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.

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