Conector de funciones

La API tfds.features.FeatureConnector :

• Define la estructura, formas y tipos del tf.data.Dataset final.
• Resumen de serialización ausente hacia/desde el disco.
• Exponer metadatos adicionales (por ejemplo, nombres de etiquetas, frecuencia de muestreo de audio,...)

Descripció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 características se pueden documentar usando solo una descripción textual ( doc='description' ) o usando tfds.features.Documentation directamente para proporcionar una descripción de característica más detallada.

Las características pueden ser:

• Valores escalares: tf.bool , tf.string , tf.float32 ,... Cuando desee documentar la característica, también puede usar tfds.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} } ,...
• tfds.features.Sequence anidado: 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, buffers de protocolo 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',
    },
}

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 dict definida en 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),
    },
}

Serializar/deserializar a proto

TFDS expone una API de bajo nivel para serializar/deserializar ejemplos en el proto tf.train.Example .

Para serializar dict[np.ndarray | Path | str | ...] para 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 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, forma, tipo,...). Ejemplo:

ds, info = tfds.load(..., with_info=True)

info.features['label'].names  # ['cat', 'dog', ...]
info.features['label'].str2int('cat')  # 0

Crea tu propio tfds.features.FeatureConnector

Si cree que falta una función entre las funciones 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 usar super() cuando sea necesario. Consulte el código fuente tfds.features.BBoxFeature para ver un ejemplo.
• Si su característica es un contenedor de múltiples tensores, es mejor heredar de tfds.features.FeaturesDict y usar super() para codificar automáticamente los subconectores.

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 funciones, subclase 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 con tf.train.Example . Puede devolver un valor único o un dict de valores.
• decode_example(data) : define cómo decodificar los datos del tensor leído de tf.train.Example en el tensor de usuario devuelto por tf.data.Dataset .
• get_tensor_info() : Indica la forma/tipo de los tensores devueltos por tf.data.Dataset . Puede ser opcional si se hereda de otro tfds.features .
• (opcionalmente) get_serialized_info() : si la información devuelta por get_tensor_info() es diferente de cómo se escriben realmente los datos en el disco, entonces necesita sobrescribir get_serialized_info() para que coincida con las especificaciones de tf.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.

Nota: asegúrese de probar sus conectores de funciones con self.assertFeature y tfds.testing.FeatureExpectationItem . Eche un vistazo a los ejemplos de prueba :

Para obtener más información, consulte la documentación de tfds.features.FeatureConnector . También es mejor mirar ejemplos reales .