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

จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

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 protocol buffers):

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 | ...] เพื่อโปรโต 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 และใช้วิธีนามธรรม

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

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

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

ในการสร้างตัวเชื่อมต่อคุณลักษณะของคุณเอง คลาสย่อย tfds.features.FeatureConnector และใช้วิธีนามธรรม:

  • 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 ทางที่ดีควรดู ตัวอย่างจริง ด้วย