Versionnement des ensembles de données

Définition

La gestion des versions peut avoir différentes significations :

  • La version de l'API TFDS (version pip) : tfds. version
  • La version de l'ensemble de données public, indépendante de TFDS (par exemple Voc2007 , Voc2012). Dans TFDS, chaque version d'ensemble de données public doit être implémentée en tant qu'ensemble de données indépendant :
    • Soit via les configurations du constructeur : Par exemple voc/2007 , voc/2012
    • Soit sous forme de 2 jeux de données indépendants : Par exemple wmt13_translate , wmt14_translate
  • La version du code de génération de l'ensemble de données dans TFDS ( my_dataset:1.0.0 ) : Par exemple, si un bug est trouvé dans l'implémentation TFDS de voc/2007 , le code de génération voc.py sera mis à jour ( voc/2007:1.0.0 - > voc/2007:2.0.0 ).

Le reste de ce guide se concentre uniquement sur la dernière définition (version du code du jeu de données dans le référentiel TFDS).

Versions prises en charge

En règle générale :

  • Seule la dernière version actuelle peut être générée.
  • Tous les ensembles de données générés précédemment peuvent être lus (remarque : cela nécessite des ensembles de données générés avec TFDS 4+). 
builder = tfds.builder('my_dataset')
builder.info.version  # Current version is: '2.0.0'

# download and load the last available version (2.0.0)
ds = tfds.load('my_dataset')

# Explicitly load a previous version (only works if
# `~/tensorflow_datasets/my_dataset/1.0.0/` already exists)
ds = tfds.load('my_dataset:1.0.0')

Sémantique

Chaque DatasetBuilder défini dans TFDS est livré avec une version, par exemple :

class MNIST(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version('2.0.0')
  RELEASE_NOTES = {
      '1.0.0': 'Initial release',
      '2.0.0': 'Update dead download url',
  }

La version suit Semantic Versioning 2.0.0 : MAJOR.MINOR.PATCH . Le but de la version est de pouvoir garantir la reproductibilité : charger un jeu de données donné dans une version fixe donne les mêmes données. Plus précisément :

  • Si la version PATCH est incrémentée, les données lues par le client sont les mêmes, bien que les données puissent être sérialisées différemment sur le disque ou que les métadonnées puissent avoir changé. Pour une tranche donnée, l'API de découpage renvoie le même ensemble d'enregistrements.
  • Si la version MINOR est incrémentée, les données existantes telles que lues par le client sont les mêmes, mais il existe des données supplémentaires (caractéristiques dans chaque enregistrement). Pour une tranche donnée, l'API de découpage renvoie le même ensemble d'enregistrements.
  • Si la version MAJOR est incrémentée, les données existantes ont été modifiées et/ou l'API de découpage ne renvoie pas nécessairement le même ensemble d'enregistrements pour une tranche donnée.

Lorsqu'une modification de code est apportée à la bibliothèque TFDS et que cette modification de code a un impact sur la manière dont un ensemble de données est sérialisé et/ou lu par le client, la version du générateur correspondante est incrémentée conformément aux directives ci-dessus.

Notez que la sémantique ci-dessus est un effort optimal et qu'il peut y avoir des bogues inaperçus affectant un ensemble de données alors que la version n'a pas été incrémentée. De tels bugs sont finalement corrigés, mais si vous comptez beaucoup sur le versioning, nous vous conseillons d'utiliser TFDS à partir d'une version publiée (par opposition à HEAD ).

Notez également que certains ensembles de données ont un autre schéma de version indépendant de la version TFDS. Par exemple, l'ensemble de données Open Images a plusieurs versions, et dans TFDS, les générateurs correspondants sont open_images_v4 , open_images_v5 , ...

Chargement d'une version spécifique

Lors du chargement d'un jeu de données ou d'un DatasetBuilder , vous pouvez spécifier la version à utiliser. Par exemple:

tfds.load('imagenet2012:2.0.1')
tfds.builder('imagenet2012:2.0.1')

tfds.load('imagenet2012:2.0.0')  # Error: unsupported version.

# Resolves to 3.0.0 for now, but would resolve to 3.1.1 if when added.
tfds.load('imagenet2012:3.*.*')

Si vous utilisez TFDS pour une publication, nous vous conseillons de :

  • corriger le composant MAJOR de la version uniquement ;
  • annoncez quelle version de l’ensemble de données a été utilisée dans vos résultats.

Cela devrait permettre à votre futur moi, à vos lecteurs et à vos critiques de reproduire plus facilement vos résultats.

BUILDER_CONFIGS et versions

Certains ensembles de données définissent plusieurs BUILDER_CONFIGS . Lorsque tel est le cas, version et supported_versions sont définies sur les objets de configuration eux-mêmes. En dehors de cela, la sémantique et l’utilisation sont identiques. Par exemple:

class OpenImagesV4(tfds.core.GeneratorBasedBuilder):

  BUILDER_CONFIGS = [
      OpenImagesV4Config(
          name='original',
          version=tfds.core.Version('0.2.0'),
          supported_versions=[
            tfds.core.Version('1.0.0', "Major change in data"),
          ],
          description='Images at their original resolution and quality.'),
      ...
  ]

tfds.load('open_images_v4/original:1.*.*')

Version expérimentale

Il est possible de permettre de générer 2 versions en même temps. Une version par défaut et une version expérimentale. Par exemple:

class MNIST(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version("1.0.0")  # Default version
  SUPPORTED_VERSIONS = [
      tfds.core.Version("2.0.0"),  # Experimental version
  ]


# Download and load default version 1.0.0
builder = tfds.builder('mnist')

#  Download and load experimental version 2.0.0
builder = tfds.builder('mnist', version='experimental_latest')

Dans le code, vous devez vous assurer de supporter les 2 versions :

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

  def _generate_examples(self, path):
    if self.info.version >= '2.0.0':
      ...
    else:
      ...