Złącze funkcji

Interfejs API tfds.features.FeatureConnector :

  • Definiuje strukturę, kształty, typy końcowego zestawu danych tf.data.Dataset
  • Abstrakcyjna serializacja do/z dysku.
  • Ujawnij dodatkowe metadane (np. nazwy etykiet, częstotliwość próbkowania audio,...)

Przegląd

tfds.features.FeatureConnector definiuje strukturę cech zbioru danych (w tfds.core.DatasetInfo ):

tfds.core.DatasetInfo(
    features=tfds.features.FeaturesDict({
        'image': tfds.features.Image(shape=(28, 28, 1), doc='Grayscale image'),
        'label': tfds.features.ClassLabel(
            names=['no', 'yes'],
            doc=tfds.features.Documentation(
                desc='Whether this is a picture of a cat',
                value_range='yes or no'
            ),
        ),
        'metadata': {
            'id': tf.int64,
            'timestamp': tfds.features.Scalar(
                tf.int64,
                doc='Timestamp when this picture was taken as seconds since epoch'),
            'language': tf.string,
        },
    }),
)

Funkcje można udokumentować, używając samego opisu tekstowego ( doc='description' ) lub bezpośrednio używając tfds.features.Documentation w celu zapewnienia bardziej szczegółowego opisu funkcji.

Funkcje mogą być:

Podczas generowania przykłady zostaną automatycznie serializowane przez FeatureConnector.encode_example do formatu odpowiedniego dla dysku (obecnie bufory protokołu tf.train.Example ):

yield {
    'image': '/path/to/img0.png',  # `np.array`, file bytes,... also accepted
    'label': 'yes',  # int (0-num_classes) also accepted
    'metadata': {
        'id': 43,
        'language': 'en',
    },
}

Podczas odczytu zbioru danych (np. za pomocą tfds.load ) dane są automatycznie dekodowane za pomocą FeatureConnector.decode_example . Zwrócony tf.data.Dataset będzie zgodny ze strukturą dict zdefiniowaną w tfds.core.DatasetInfo : 

ds = tfds.load(...)
ds.element_spec == {
    'image': tf.TensorSpec(shape=(28, 28, 1), tf.uint8),
    'label': tf.TensorSpec(shape=(), tf.int64),
    'metadata': {
        'id': tf.TensorSpec(shape=(), tf.int64),
        'language': tf.TensorSpec(shape=(), tf.string),
    },
}

Serializuj/deserializuj do proto

TFDS udostępnia API niskiego poziomu do serializacji/deserializacji przykładów do tf.train.Example proto.

Aby serializować dict[np.ndarray | Path | str | ...] na proto bytes , użyj features.serialize_example :

with tf.io.TFRecordWriter('path/to/file.tfrecord') as writer:
  for ex in all_exs:
    ex_bytes = features.serialize_example(data)
    f.write(ex_bytes)

Aby deserializować do bytes do tf.Tensor , użyj features.deserialize_example : 

ds = tf.data.TFRecordDataset('path/to/file.tfrecord')
ds = ds.map(features.deserialize_example)

Dostęp do metadanych

Zobacz dokument wprowadzający , aby uzyskać dostęp do metadanych funkcji (nazwy etykiet, kształt, typ,...). Przykład: 

ds, info = tfds.load(..., with_info=True)

info.features['label'].names  # ['cat', 'dog', ...]
info.features['label'].str2int('cat')  # 0

Utwórz własny tfds.features.FeatureConnector

Jeśli uważasz, że brakuje jakiejś funkcji w dostępnych funkcjach , otwórz nowe wydanie .

Aby utworzyć własny konektor funkcji, musisz dziedziczyć z tfds.features.FeatureConnector i zaimplementować metody abstrakcyjne.

  • Jeśli funkcja ma pojedynczą wartość tensora, najlepiej dziedziczyć po tfds.features.Tensor i w razie potrzeby używać super() . Przykład można znaleźć w kodzie źródłowym tfds.features.BBoxFeature .
  • Jeśli Twoja funkcja jest kontenerem wielu tensorów, najlepiej dziedziczyć z tfds.features.FeaturesDict i używać super() do automatycznego kodowania podzłączy.

Obiekt tfds.features.FeatureConnector oddziela sposób kodowania funkcji na dysku od sposobu jej prezentacji użytkownikowi. Poniżej znajduje się diagram przedstawiający warstwy abstrakcji zbioru danych oraz transformację surowych plików zbioru danych do obiektu tf.data.Dataset .

Warstwy abstrakcji DatasetBuilder

Aby utworzyć własny konektor funkcji, podklasę tfds.features.FeatureConnector i zaimplementuj metody abstrakcyjne:

  • encode_example(data) : Określa sposób kodowania danych podanych w generatorze _generate_examples() do danych zgodnych tf.train.Example . Może zwrócić pojedynczą wartość lub dict wartości.
  • decode_example(data) : Określa sposób dekodowania danych z tensora odczytanego z tf.train.Example do tensora użytkownika zwróconego przez tf.data.Dataset .
  • get_tensor_info() : Wskazuje kształt/typ tensora(ów) zwracanego przez tf.data.Dataset . Może być opcjonalny w przypadku dziedziczenia z innego tfds.features .
  • (opcjonalnie) get_serialized_info() : Jeśli informacja zwrócona przez get_tensor_info() różni się od tego, w jaki sposób dane są faktycznie zapisane na dysku, musisz nadpisać get_serialized_info() w celu dopasowania do specyfikacji tf.train.Example
  • to_json_content / from_json_content : Jest to wymagane, aby umożliwić załadowanie zestawu danych bez oryginalnego kodu źródłowego. Zobacz przykład funkcji Audio .

Aby uzyskać więcej informacji, zapoznaj się z dokumentacją tfds.features.FeatureConnector . Najlepiej też przyjrzeć się prawdziwym przykładom .