FeatureConnecteur

L'API tfds.features.FeatureConnector :

• Définit la structure, les formes et les types du tf.data.Dataset final
• Sérialisation abstraite vers/depuis le disque.
• Exposer des métadonnées supplémentaires (par exemple, noms d'étiquettes, fréquence d'échantillonnage audio,...)

Aperçu

tfds.features.FeatureConnector définit la structure des fonctionnalités de l'ensemble de données (dans 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,
        },
    }),
)

Les fonctionnalités peuvent être documentées soit en utilisant simplement une description textuelle ( doc='description' ), soit en utilisant directement tfds.features.Documentation pour fournir une description plus détaillée des fonctionnalités.

Les fonctionnalités peuvent être :

• Valeurs scalaires : tf.bool , tf.string , tf.float32 ,... Lorsque vous souhaitez documenter la fonctionnalité, vous pouvez également utiliser tfds.features.Scalar(tf.int64, doc='description') .
• tfds.features.Audio , tfds.features.Video ,... (voir la liste des fonctionnalités disponibles)
• dict imbriqué de fonctionnalités : {'metadata': {'image': Image(), 'description': tf.string} } ,...
• tfds.features.Sequence imbriqué : Sequence({'image': ..., 'id': ...}) , Sequence(Sequence(tf.int64)) ,...

Lors de la génération, les exemples seront automatiquement sérialisés par FeatureConnector.encode_example dans un format adapté au disque (actuellement les tampons de protocole 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',
    },
}

Lors de la lecture de l'ensemble de données (par exemple avec tfds.load ), les données sont automatiquement décodées avec FeatureConnector.decode_example . Le tf.data.Dataset renvoyé correspondra à la structure dict définie dans 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),
    },
}

Sérialiser/désérialiser en prototype

TFDS expose une API de bas niveau pour sérialiser/désérialiser les exemples dans le proto tf.train.Example .

Pour sérialiser dict[np.ndarray | Path | str | ...] en proto bytes , utilisez 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)

Pour désérialiser en proto bytes vers tf.Tensor , utilisez features.deserialize_example :

ds = tf.data.TFRecordDataset('path/to/file.tfrecord')
ds = ds.map(features.deserialize_example)

Accéder aux métadonnées

Voir la documentation d'introduction pour accéder aux métadonnées des fonctionnalités (noms d'étiquettes, forme, type,...). Exemple:

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

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

Créez votre propre tfds.features.FeatureConnector

Si vous pensez qu'une fonctionnalité manque parmi les fonctionnalités disponibles , veuillez ouvrir un nouveau numéro .

Pour créer votre propre connecteur de fonctionnalités, vous devez hériter de tfds.features.FeatureConnector et implémenter les méthodes abstraites.

• Si votre fonctionnalité est une valeur de tenseur unique, il est préférable d'hériter de tfds.features.Tensor et d'utiliser super() si nécessaire. Voir le code source tfds.features.BBoxFeature pour un exemple.
• Si votre fonctionnalité est un conteneur de plusieurs tenseurs, il est préférable d'hériter de tfds.features.FeaturesDict et d'utiliser le super() pour encoder automatiquement les sous-connecteurs.

L'objet tfds.features.FeatureConnector fait abstraction de la façon dont la fonctionnalité est codée sur le disque de la façon dont elle est présentée à l'utilisateur. Vous trouverez ci-dessous un diagramme montrant les couches d'abstraction de l'ensemble de données et la transformation des fichiers de l'ensemble de données bruts en l'objet tf.data.Dataset .

Pour créer votre propre connecteur de fonctionnalités, sous-classez tfds.features.FeatureConnector et implémentez les méthodes abstraites :

• encode_example(data) : Définit comment encoder les données fournies dans le générateur _generate_examples() en données compatibles tf.train.Example . Peut renvoyer une valeur unique ou un dict de valeurs.
• decode_example(data) : Définit comment décoder les données du tenseur lu depuis tf.train.Example en tenseur utilisateur renvoyé par tf.data.Dataset .
• get_tensor_info() : Indique la forme/le type du ou des tenseurs renvoyés par tf.data.Dataset . Peut être facultatif en cas d'héritage d'un autre tfds.features .
• (facultatif) get_serialized_info() : Si les informations renvoyées par get_tensor_info() sont différentes de la façon dont les données sont réellement écrites sur le disque, vous devez alors écraser get_serialized_info() pour correspondre aux spécifications de tf.train.Example
• to_json_content / from_json_content : ceci est requis pour permettre à votre ensemble de données d'être chargé sans le code source d'origine. Voir Fonctionnalité audio pour un exemple.

Pour plus d'informations, consultez la documentation tfds.features.FeatureConnector . Il est également préférable de regarder des exemples réels .