La API tfds.features.FeatureConnector
:
- Define la estructura, formas, tipos de
tf.data.Dataset
final - Abstraiga la serialización hacia/desde el disco.
- Exponer metadatos adicionales (por ejemplo, nombres de etiquetas, frecuencia de muestreo de audio,...)
Visión general
tfds.features.FeatureConnector
define la estructura de características del conjunto de datos (en 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,
},
}),
)
Las funciones se pueden documentar usando solo una descripción textual ( doc='description'
) o usando tfds.features.Documentation
directamente para proporcionar una descripción más detallada de la función.
Las características pueden ser:
- Valores escalares:
tf.bool
,tf.string
,tf.float32
,... Cuando desee documentar la característica, también puede usartfds.features.Scalar(tf.int64, doc='description')
. -
tfds.features.Audio
,tfds.features.Video
,... (consulte la lista de funciones disponibles) -
dict
anidado de características:{'metadata': {'image': Image(), 'description': tf.string} }
,... - Anidado
tfds.features.Sequence
:Sequence({'image': ..., 'id': ...})
,Sequence(Sequence(tf.int64))
,...
Durante la generación, FeatureConnector.encode_example
serializará automáticamente los ejemplos en un formato adecuado para el disco (actualmente tf.train.Example
protocol buffers):
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',
},
}
Al leer el conjunto de datos (por ejemplo, con tfds.load
), los datos se decodifican automáticamente con FeatureConnector.decode_example
. El tf.data.Dataset
devuelto coincidirá con la estructura tfds.core.DatasetInfo
dict
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),
},
}
Serializar/deserializar a proto
TFDS expone una API de bajo nivel para serializar/deserializar ejemplos en tf.train.Example
proto.
Para serializar dict[np.ndarray | Path | str | ...]
a proto bytes
, use 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)
Para deserializar a proto bytes
a tf.Tensor
, use features.deserialize_example
:
ds = tf.data.TFRecordDataset('path/to/file.tfrecord')
ds = ds.map(features.deserialize_example)
Acceder a metadatos
Consulte el documento de introducción para acceder a los metadatos de las funciones (nombres de etiquetas, formas, tipos de d...). Ejemplo:
ds, info = tfds.load(..., with_info=True)
info.features['label'].names # ['cat', 'dog', ...]
info.features['label'].str2int('cat') # 0
Cree su propio tfds.features.FeatureConnector
Si cree que falta una característica de las características disponibles , abra una nueva edición .
Para crear su propio conector de funciones, debe heredar de tfds.features.FeatureConnector
e implementar los métodos abstractos.
- Si su característica es un valor de tensor único, es mejor heredar de
tfds.features.Tensor
y usarsuper()
cuando sea necesario. Consulte el código fuente detfds.features.BBoxFeature
para ver un ejemplo. - Si su función es un contenedor de múltiples tensores, es mejor heredar de
tfds.features.FeaturesDict
y usarsuper()
para codificar subconectores automáticamente.
El objeto tfds.features.FeatureConnector
abstrae cómo se codifica la característica en el disco de cómo se presenta al usuario. A continuación se muestra un diagrama que muestra las capas de abstracción del conjunto de datos y la transformación de los archivos del conjunto de datos sin procesar al objeto tf.data.Dataset
.
Para crear su propio conector de características, subclasifique tfds.features.FeatureConnector
e implemente los métodos abstractos:
-
encode_example(data)
: Define cómo codificar los datos proporcionados en el generador_generate_examples()
en datos compatibles contf.train.Example
. Puede devolver un solo valor o undict
de valores. -
decode_example(data)
: Define cómo decodificar los datos del tensor leído detf.train.Example
en el tensor de usuario devuelto portf.data.Dataset
. -
get_tensor_info()
: indica la forma/tipo de tensor devuelto portf.data.Dataset
. Puede ser opcional si se hereda de otrotfds.features
. - (opcionalmente)
get_serialized_info()
: si la información devuelta porget_tensor_info()
es diferente de cómo se escriben realmente los datos en el disco, entonces debe sobrescribirget_serialized_info()
para que coincida con las especificaciones detf.train.Example
-
to_json_content
/from_json_content
: esto es necesario para permitir que su conjunto de datos se cargue sin el código fuente original. Consulte la función de audio para ver un ejemplo.
Para obtener más información, consulte la documentación de tfds.features.FeatureConnector
. También es mejor mirar ejemplos reales .