Konektor Fitur

API tfds.features.FeatureConnector :

  • Mendefinisikan struktur, bentuk, tipe tf.data.Dataset akhir
  • Abstrak serialisasi ke/dari disk.
  • Paparkan metadata tambahan (misalnya nama label, laju sampel audio,...)

Ringkasan

tfds.features.FeatureConnector mendefinisikan struktur fitur kumpulan data (dalam 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,
        },
    }),
)

Fitur dapat didokumentasikan hanya dengan menggunakan deskripsi tekstual ( doc='description' ) atau dengan menggunakan tfds.features.Documentation secara langsung untuk memberikan deskripsi fitur yang lebih detail.

Fiturnya bisa berupa:

Selama pembuatan, contoh akan secara otomatis diserialkan oleh FeatureConnector.encode_example ke dalam format yang sesuai untuk disk (saat ini buffer protokol 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',
    },
}

Saat membaca kumpulan data (misalnya dengan tfds.load ), data secara otomatis didekodekan dengan FeatureConnector.decode_example . tf.data.Dataset yang dikembalikan akan cocok dengan struktur dict yang ditentukan dalam 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),
    },
}

Serialisasi/deserialisasi ke proto

TFDS mengekspos API tingkat rendah untuk membuat serialisasi/deserialisasi contoh ke proto tf.train.Example .

Untuk membuat serial dict[np.ndarray | Path | str | ...] untuk proto bytes , gunakan 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)

Untuk melakukan deserialize ke proto bytes ke tf.Tensor , gunakan features.deserialize_example : 

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

Akses metadata

Lihat dokumen pendahuluan untuk mengakses metadata fitur (nama label, bentuk, tipe d,...). Contoh: 

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

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

Buat tfds.features.FeatureConnector Anda sendiri

Jika Anda yakin ada fitur yang hilang dari fitur yang tersedia , silakan buka terbitan baru .

Untuk membuat konektor fitur Anda sendiri, Anda perlu mewarisi dari tfds.features.FeatureConnector dan mengimplementasikan metode abstrak.

  • Jika fitur Anda adalah nilai tensor tunggal, sebaiknya mewarisi dari tfds.features.Tensor dan menggunakan super() bila diperlukan. Lihat kode sumber tfds.features.BBoxFeature sebagai contoh.
  • Jika fitur Anda merupakan wadah yang terdiri dari beberapa tensor, sebaiknya turunkan dari tfds.features.FeaturesDict dan gunakan super() untuk mengkodekan subkonektor secara otomatis.

Objek tfds.features.FeatureConnector mengabstraksi bagaimana fitur dikodekan pada disk dan bagaimana fitur tersebut disajikan kepada pengguna. Di bawah ini adalah diagram yang menunjukkan lapisan abstraksi kumpulan data dan transformasi dari file kumpulan data mentah ke objek tf.data.Dataset .

Lapisan abstraksi DatasetBuilder

Untuk membuat konektor fitur Anda sendiri, subkelas tfds.features.FeatureConnector dan terapkan metode abstrak:

  • encode_example(data) : Mendefinisikan cara menyandikan data yang diberikan di generator _generate_examples() menjadi data yang kompatibel dengan tf.train.Example . Dapat mengembalikan nilai tunggal, atau dict nilai.
  • decode_example(data) : Mendefinisikan cara mendekode data dari tensor yang dibaca dari tf.train.Example menjadi tensor pengguna yang dikembalikan oleh tf.data.Dataset .
  • get_tensor_info() : Menunjukkan bentuk/tipe tensor yang dikembalikan oleh tf.data.Dataset . Mungkin opsional jika mewarisi dari tfds.features lain.
  • (opsional) get_serialized_info() : Jika info yang dikembalikan oleh get_tensor_info() berbeda dari cara data sebenarnya ditulis pada disk, maka Anda perlu menimpa get_serialized_info() agar sesuai dengan spesifikasi tf.train.Example
  • to_json_content / from_json_content : Ini diperlukan agar kumpulan data Anda dapat dimuat tanpa kode sumber asli. Lihat fitur Audio sebagai contoh.

Untuk info lebih lanjut, lihat dokumentasi tfds.features.FeatureConnector . Sebaiknya lihat juga contoh nyata .