Conector de funciones

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 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} } ,...
• 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 usar super() cuando sea necesario. Consulte el código fuente de tfds.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 usar super() 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 con tf.train.Example . Puede devolver un solo valor 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 tensor devuelto 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 debe 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 de tfds.features.FeatureConnector . También es mejor mirar ejemplos reales .