FeatureConnector

API tfds.features.FeatureConnector :

• ساختار، اشکال، 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),
    },
}

Serialize/deserialize to proto

TFDS یک API سطح پایین را برای سریال‌سازی/عدم سریال‌سازی نمونه‌ها در پروتو tf.train.Example نشان می‌دهد.

برای سریال 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)

برای deserialize کردن پروتو bytes به tf.Tensor ، از features.deserialize_example استفاده کنید:

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

دسترسی به ابرداده

برای دسترسی به فراداده ویژگی ها (نام برچسب، شکل، نوع d و...) به سند مقدمه مراجعه کنید. مثال:

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 را نشان می دهد.

برای ایجاد رابط ویژگی خود، tfds.features.FeatureConnector را زیر کلاس قرار داده و متدهای انتزاعی را پیاده سازی کنید:

• encode_example(data) : نحوه کدگذاری داده های داده شده در ژنراتور _generate_examples() در داده های سازگار با tf.train.Example تعریف می کند. می تواند یک مقدار واحد یا یک dict از مقادیر را برگرداند.
• decode_example(data) : نحوه رمزگشایی داده ها از تانسور خوانده شده از tf.train.Example را به تانسور کاربر که توسط tf.data.Dataset بازگردانده شده است، تعریف می کند.
• get_tensor_info() : شکل/dنوع تانسور(های) بازگردانده شده توسط 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 بیندازید. همچنین بهتر است به نمونه های واقعی نگاه کنید.