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