موصل المميزات

واجهة برمجة التطبيقات 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),
    },
}

تسلسل/إلغاء التسلسل إلى بروتو

يعرض TFDS واجهة برمجة تطبيقات منخفضة المستوى لإجراء تسلسل/إلغاء تسلسل الأمثلة إلى 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() : يشير إلى شكل/نوع الموتر (الموترات) الذي يتم إرجاعه بواسطة 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 . من الأفضل أيضًا إلقاء نظرة على أمثلة حقيقية .