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} } ,...
• Nested 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 .

לסדרת 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)

כדי לבצע deserialize ל-proto 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 .

כדי ליצור מחבר תכונה משלך, תת-סיווג 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 . עדיף גם להסתכל על דוגמאות אמיתיות .