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)

כדי לבצע דה-סריאליזציה ל-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 .

שכבות הפשטה של 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 . עדיף גם להסתכל על דוגמאות אמיתיות .