Özellik Bağlayıcı

tfds.features.FeatureConnector API'si:

  • Nihai tf.data.Dataset yapısını, şekillerini ve türlerini tanımlar.
  • Diske/diskten serileştirmeyi soyutlayın.
  • Ek meta verileri açığa çıkarın (örn. etiket adları, ses örnekleme hızı,...)

Genel Bakış

tfds.features.FeatureConnector veri kümesi özellikleri yapısını tanımlar ( tfds.core.DatasetInfo içinde):

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,
        },
    }),
)

Özellikler, yalnızca metinsel bir açıklama ( doc='description' ) kullanılarak veya daha ayrıntılı bir özellik açıklaması sağlamak için doğrudan tfds.features.Documentation kullanılarak belgelenebilir.

Özellikler şunlar olabilir:

Oluşturma sırasında örnekler, FeatureConnector.encode_example tarafından diske uygun bir formatta (şu anda tf.train.Example protokol arabellekleri) otomatik olarak serileştirilecektir:

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',
    },
}

Veri kümesi okunurken (örn. tfds.load ile), verilerin kodu, FeatureConnector.decode_example ile otomatik olarak çözülür. Döndürülen tf.data.Dataset tfds.core.DatasetInfo içinde tanımlanan dict yapısıyla eşleşecektir: 

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),
    },
}

Protokole serileştirme/seri durumdan çıkarma

TFDS, örnekleri tf.train.Example protokolüne serileştirmek/seri durumdan çıkarmak için düşük seviyeli bir API sunar.

dict[np.ndarray | Path | str | ...] bytes proto etmek için, features.serialize_example kullanın:

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)

tf.Tensor protokol bytes seri durumdan çıkarmak için, features.deserialize_example kullanın: 

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

Meta verilere erişme

Özelliklerin meta verilerine (etiket adları, şekil, dtype,...) erişmek için giriş belgesine bakın. Örnek: 

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

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

Kendi tfds.features.FeatureConnector oluşturun

Mevcut özellikler arasında bir özelliğin eksik olduğunu düşünüyorsanız lütfen yeni bir konu açın.

Kendi özellik bağlayıcınızı oluşturmak için tfds.features.FeatureConnector miras almanız ve soyut yöntemleri uygulamanız gerekir.

  • Özelliğiniz tek bir tensör değeriyse, en iyisi tfds.features.Tensor miras almak ve gerektiğinde super() işlevini kullanmaktır. Örnek için tfds.features.BBoxFeature kaynak koduna bakın.
  • Özelliğiniz birden fazla tensörden oluşan bir kapsa, en iyisi tfds.features.FeaturesDict miras almak ve alt bağlayıcıları otomatik olarak kodlamak için super() işlevini kullanmaktır.

tfds.features.FeatureConnector nesnesi, özelliğin diskte nasıl kodlandığını kullanıcıya nasıl sunulduğundan soyutlar. Aşağıda veri kümesinin soyutlama katmanlarını ve ham veri kümesi dosyalarından tf.data.Dataset nesnesine dönüşümü gösteren bir diyagram bulunmaktadır.

DatasetBuilder soyutlama katmanları

Kendi özellik bağlayıcınızı oluşturmak için tfds.features.FeatureConnector alt sınıfını oluşturun ve soyut yöntemleri uygulayın:

  • encode_example(data) : _generate_examples() oluşturucusunda verilen verilerin tf.train.Example uyumlu verilere nasıl kodlanacağını tanımlar. Tek bir değer veya bir değerler dict döndürebilir.
  • decode_example(data) : tf.train.Example öğesinden okunan tensördeki verilerin kodunun tf.data.Dataset tarafından döndürülen kullanıcı tensörüne nasıl çözüleceğini tanımlar.
  • get_tensor_info() : tf.data.Dataset tarafından döndürülen tensörlerin şeklini/dtipini gösterir. Başka bir tfds.features öğesinden devralınıyorsa isteğe bağlı olabilir.
  • (isteğe bağlı olarak) get_serialized_info() : get_tensor_info() tarafından döndürülen bilgi, verilerin gerçekte diske yazılma şeklinden farklıysa, tf.train.Example özellikleriyle eşleşmesi için get_serialized_info() nun üzerine yazmanız gerekir.
  • to_json_content / from_json_content : Veri kümenizin orijinal kaynak kodu olmadan yüklenmesine izin vermek için bu gereklidir. Örnek için Ses özelliğine bakın.

Daha fazla bilgi için tfds.features.FeatureConnector belgelerine bakın. Gerçek örneklere bakmak da en iyisidir.