คุณสมบัติตัวเชื่อมต่อ

tfds.features.FeatureConnector API:

  • กำหนดโครงสร้าง รูปร่าง dtypes ของ tf.data.Dataset สุดท้าย
  • บทคัดย่อการซีเรียลไลซ์ไปยัง/จากดิสก์
  • เปิดเผยข้อมูลเมตาเพิ่มเติม (เช่น ชื่อป้ายกำกับ อัตราตัวอย่างเสียง...)

ภาพรวม

tfds.features.FeatureConnector กำหนดโครงสร้างคุณสมบัติชุดข้อมูล (ใน 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,
        },
    }),
)

คุณลักษณะต่างๆ สามารถจัดทำเป็นเอกสารได้โดยใช้เพียงคำอธิบายที่เป็นข้อความ ( doc='description' ) หรือโดยการใช้ tfds.features.Documentation โดยตรงเพื่อให้คำอธิบายคุณลักษณะที่มีรายละเอียดมากขึ้น

คุณสมบัติสามารถ:

  • ค่าสเกลาร์: tf.bool , tf.string , tf.float32 ,... เมื่อคุณต้องการบันทึกคุณลักษณะ คุณยังสามารถใช้ tfds.features.Scalar(tf.int64, doc='description')
  • tfds.features.Audio , tfds.features.Video ,... (ดู รายการ คุณสมบัติที่มี)
  • dict คุณสมบัติที่ซ้อนกัน: {'metadata': {'image': Image(), 'description': tf.string} } ,...
  • ซ้อนกัน tfds.features.Sequence : Sequence({'image': ..., 'id': ...}) , Sequence(Sequence(tf.int64)) ,...

ในระหว่างการสร้าง ตัวอย่างจะถูกทำให้เป็นอนุกรมโดยอัตโนมัติโดย FeatureConnector.encode_example เป็นรูปแบบที่เหมาะกับดิสก์ (ปัจจุบันคือ 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',
    },
}

เมื่ออ่านชุดข้อมูล (เช่นด้วย tfds.load ) ข้อมูลจะถูกถอดรหัสโดยอัตโนมัติด้วย FeatureConnector.decode_example tf.data.Dataset ที่ส่งคืนจะตรงกับโครงสร้าง dict ที่กำหนดใน 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),
    },
}

ทำให้เป็นอนุกรม/ดีซีเรียลไลซ์เป็นโปรโต

TFDS เปิดเผย API ระดับต่ำเพื่อทำให้ตัวอย่างเป็นอนุกรม/ดีซีเรียลไลซ์ไปยัง tf.train.Example proto

หากต้องการซีเรียลไลซ์ dict[np.ndarray | Path | str | ...] ถึง proto bytes ให้ใช้ 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)

หากต้องการดีซีเรียลไลซ์เป็นโปรโต bytes เป็น tf.Tensor ให้ใช้ features.deserialize_example :

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

เข้าถึงข้อมูลเมตา

ดู เอกสารแนะนำ เพื่อเข้าถึงข้อมูลเมตาของฟีเจอร์ (ชื่อป้ายกำกับ รูปร่าง dtype,...) ตัวอย่าง:

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

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

สร้าง tfds.features.FeatureConnector ของคุณเอง

หากคุณเชื่อว่ามีคุณลักษณะหายไปจาก คุณลักษณะที่มีอยู่ โปรดเปิด ประเด็นใหม่

หากต้องการสร้างตัวเชื่อมต่อฟีเจอร์ของคุณเอง คุณจะต้องสืบทอดจาก tfds.features.FeatureConnector และนำเมธอด abstract ไปใช้

  • หากฟีเจอร์ของคุณเป็นค่าเทนเซอร์เดียว ทางที่ดีที่สุดคือรับค่าจาก tfds.features.Tensor และใช้ super() เมื่อจำเป็น ดูตัวอย่างซอร์สโค้ด tfds.features.BBoxFeature
  • หากฟีเจอร์ของคุณเป็นคอนเทนเนอร์ที่มีเทนเซอร์หลายตัว ทางที่ดีที่สุดคือสืบทอดจาก tfds.features.FeaturesDict และใช้ super() เพื่อเข้ารหัสตัวเชื่อมต่อย่อยโดยอัตโนมัติ

ออบเจ็กต์ tfds.features.FeatureConnector จะสรุปวิธีการเข้ารหัสคุณลักษณะบนดิสก์จากวิธีการนำเสนอต่อผู้ใช้ ด้านล่างนี้เป็นแผนภาพที่แสดงเลเยอร์นามธรรมของชุดข้อมูลและการแปลงจากไฟล์ชุดข้อมูลดิบไปเป็นออบเจ็กต์ tf.data.Dataset

เลเยอร์นามธรรมของ DatasetBuilder

หากต้องการสร้างตัวเชื่อมต่อฟีเจอร์ของคุณเอง ให้คลาสย่อย tfds.features.FeatureConnector และใช้เมธอด abstract:

  • encode_example(data) : กำหนดวิธีการเข้ารหัสข้อมูลที่กำหนดในเครื่องกำเนิดไฟฟ้า _generate_examples() ลงในข้อมูลที่เข้ากันได้กับ tf.train.Example สามารถส่งคืนค่าเดียวหรือ dict ของค่าได้
  • decode_example(data) : กำหนดวิธีถอดรหัสข้อมูลจากเทนเซอร์ที่อ่านจาก tf.train.Example ลงในเทนเซอร์ผู้ใช้ที่ส่งคืนโดย tf.data.Dataset
  • get_tensor_info() : ระบุรูปร่าง/dtype ของเทนเซอร์ที่ส่งคืนโดย tf.data.Dataset อาจเป็นทางเลือกหากสืบทอดมาจาก tfds.features อื่น
  • (เป็นทางเลือก) get_serialized_info() : หากข้อมูลที่ส่งคืนโดย get_tensor_info() แตกต่างจากวิธีการเขียนข้อมูลบนดิสก์จริง ๆ คุณจะต้องเขียนทับ get_serialized_info() เพื่อให้ตรงกับข้อกำหนดของ tf.train.Example
  • to_json_content / from_json_content : สิ่งนี้จำเป็นเพื่อให้ชุดข้อมูลของคุณสามารถโหลดได้โดยไม่ต้องใช้ซอร์สโค้ดต้นฉบับ ดูตัวอย่าง คุณสมบัติเสียง

สำหรับข้อมูลเพิ่มเติม โปรดดูที่เอกสารประกอบ tfds.features.FeatureConnector นอกจากนี้ เป็นการดีที่สุดที่จะดู ตัวอย่างจริง ด้วย