Cette page a été traduite par l'API Cloud Translation.
Switch to English

Gestion des versions des ensembles de données

Sémantique

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

class MNIST(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version("1.0.0")

La version suit Semantic Versioning 2.0.0 : MAJOR.MINOR.PATCH . Le but de la version est de pouvoir garantir la reproductibilité: le chargement d'un ensemble de données donné à une version fixe produit les mêmes données. Plus précisement:

  • Si la version de 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 les métadonnées peuvent 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 y a 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 façon dont un ensemble de données est sérialisé et / ou lu par le client, la version de générateur correspondante est incrémentée selon les directives ci-dessus.

Notez que la sémantique ci-dessus est le meilleur effort, et il peut y avoir des bogues non remarqués affectant un ensemble de données alors que la version n'était pas incrémentée. Ces bogues sont finalement corrigés, mais si vous comptez beaucoup sur le contrôle de version, 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 versionnage indépendant de la version TFDS. Par exemple, le jeu de données Open Images a plusieurs versions, et dans TFDS, les générateurs correspondants sont open_images_v4 , open_images_v5 , ...

Versions prises en charge

Un DatasetBuilder peut prendre en charge plusieurs versions, qui peuvent être à la fois supérieures ou inférieures à la version canonique. Par exemple:

class Imagenet2012(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version('2.0.1', 'Encoding fix. No changes from user POV')
  SUPPORTED_VERSIONS = [
      tfds.core.Version('3.0.0', 'S3: tensorflow.org/datasets/splits'),
      tfds.core.Version('1.0.0'),
      tfds.core.Version('0.0.9', tfds_version_to_prepare="v1.0.0"),
  ]

Le choix de continuer à prendre en charge une version plus ancienne se fait au cas par cas, principalement en fonction de la popularité de l'ensemble de données et de la version. Finalement, nous visons à ne prendre en charge qu'un nombre limité de versions par ensemble de données, idéalement une. Dans l'exemple ci-dessus, nous pouvons voir que la version 2.0.0 n'est plus supportée, comme identique à 2.0.1 du point de vue du lecteur.

Les versions prises en charge avec un nombre supérieur au numéro de version canonique sont considérées comme expérimentales et peuvent être endommagées. Ils finiront cependant par devenir canoniques.

Une version peut spécifier tfds_version_to_prepare . Cela signifie que cette version de l'ensemble de données ne peut être utilisée avec la version actuelle du code TFDS que si elle a déjà été préparée par une version plus ancienne du code, mais ne peut pas être préparée. La valeur de tfds_version_to_prepare spécifie la dernière version connue de TFDS qui peut être utilisée pour télécharger et préparer l'ensemble de données dans cette version.

Chargement d'une version spécifique

Lors du chargement d'un ensemble 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 ;
  • annoncer 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 critiques de reproduire plus facilement vos résultats.

Expériences

Pour déployer progressivement les changements de TFDS qui impactent de nombreux constructeurs de jeux de données, nous avons introduit la notion d'expérimentation. Lors de sa première introduction, une expérience est désactivée par défaut, mais des versions spécifiques de l'ensemble de données peuvent décider de l'activer. Cela sera généralement fait sur les versions "futures" (pas encore canoniques) dans un premier temps. Par exemple:

class MNIST(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version("1.0.0")
  SUPPORTED_VERSIONS = [
      tfds.core.Version("2.0.0", "EXP1: Opt-in for experiment 1",
                        experiments={tfds.core.Experiment.EXP1: True}),
  ]

Une fois qu'une expérience a été vérifiée pour fonctionner comme prévu, elle sera étendue à tous ou à la plupart des ensembles de données, à quel point elle peut être activée par défaut, et la définition ci-dessus ressemblerait alors à:

class MNIST(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version("1.0.0",
                              experiments={tfds.core.Experiment.EXP1: False})
  SUPPORTED_VERSIONS = [
      tfds.core.Version("2.0.0", "EXP1: Opt-in for experiment 1"),
  ]

Une fois qu'un test est utilisé dans toutes les versions des ensembles de données (il ne reste plus de version de l'ensemble de données spécifiant {experiment: False} ), le test peut être supprimé.

Les expériences et leur description sont définies dans core/utils/version.py .

BUILDER_CONFIGS et versions

Certains ensembles de données définissent plusieurs BUILDER_CONFIGS . Lorsque tel est le cas, la version et supported_versions sont définis sur la configuration des objets eux - mêmes. À part 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.*.*')