Versionamento dei set di dati

Definizione

Il controllo delle versioni può avere significati diversi:

  • La versione dell'API TFDS (versione pip): tfds. version
  • La versione del set di dati pubblico, indipendente da TFDS (ad esempio Voc2007 , Voc2012). In TFDS ogni versione del set di dati pubblico dovrebbe essere implementata come set di dati indipendente:
    • O tramite le configurazioni del builder : ad esempio voc/2007 , voc/2012
    • O come 2 set di dati indipendenti: ad esempio wmt13_translate , wmt14_translate
  • La versione del codice di generazione del set di dati in TFDS ( my_dataset:1.0.0 ): ad esempio, se viene trovato un bug nell'implementazione TFDS di voc/2007 , il codice di generazione voc.py verrà aggiornato ( voc/2007:1.0.0 - > voc/2007:2.0.0 ).

Il resto di questa guida si concentra solo sull'ultima definizione (versione del codice del set di dati nel repository TFDS).

Versioni supportate

Come regola generale:

  • È possibile generare solo l'ultima versione corrente.
  • È possibile leggere tutti i set di dati generati in precedenza (nota: ciò richiede set di dati generati con 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')

Semantico

Ogni DatasetBuilder definito in TFDS viene fornito con una versione, ad esempio:

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 versione segue il Semantic Versioning 2.0.0 : MAJOR.MINOR.PATCH . Lo scopo della versione è quello di garantire la riproducibilità: caricare un dato set di dati in una versione fissa produce gli stessi dati. Più specificatamente:

  • Se la versione PATCH viene incrementata, i dati letti dal client sono gli stessi, anche se i dati potrebbero essere serializzati in modo diverso sul disco o i metadati potrebbero essere cambiati. Per ogni sezione specifica, l'API di sezionamento restituisce lo stesso set di record.
  • Se la versione MINOR viene incrementata, i dati esistenti letti dal client sono gli stessi, ma sono presenti dati aggiuntivi (funzionalità in ciascun record). Per ogni sezione specifica, l'API di sezionamento restituisce lo stesso set di record.
  • Se la versione MAJOR viene incrementata, i dati esistenti sono stati modificati e/o l'API di slicing non restituisce necessariamente lo stesso set di record per una determinata sezione.

Quando viene apportata una modifica al codice alla libreria TFDS e tale modifica al codice influisce sul modo in cui un set di dati viene serializzato e/o letto dal client, la versione del builder corrispondente viene incrementata in base alle linee guida sopra riportate.

Tieni presente che la semantica di cui sopra è il massimo sforzo e potrebbero esserci bug non rilevati che influiscono su un set di dati mentre la versione non è stata incrementata. Tali bug vengono eventualmente risolti, ma se fai molto affidamento sul controllo delle versioni, ti consigliamo di utilizzare TFDS da una versione rilasciata (al contrario di HEAD ).

Tieni inoltre presente che alcuni set di dati hanno un altro schema di controllo delle versioni indipendente dalla versione TFDS. Ad esempio, il set di dati Open Images ha diverse versioni e in TFDS i builder corrispondenti sono open_images_v4 , open_images_v5 , ...

Caricamento di una versione specifica

Quando si carica un set di dati o un DatasetBuilder , è possibile specificare la versione da utilizzare. Per esempio:

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.*.*')

Se utilizzi TFDS per una pubblicazione, ti consigliamo di:

  • correggere solo il componente MAJOR della versione ;
  • pubblicizzare quale versione del set di dati è stata utilizzata nei risultati.

In questo modo dovrebbe essere più semplice per te stesso, per i tuoi lettori e revisori futuri, riprodurre i tuoi risultati.

BUILDER_CONFIGS e versioni

Alcuni set di dati definiscono diversi BUILDER_CONFIGS . In tal caso, version supported_versions vengono definiti negli oggetti di configurazione stessi. A parte questo, la semantica e l'utilizzo sono identici. Per esempio: 

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.*.*')

Versione sperimentale

È possibile consentire la generazione di 2 versioni contemporaneamente. Una versione predefinita e una sperimentale. Per esempio:

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')

Nel codice, devi assicurarti di supportare le 2 versioni:

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

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