Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

Controllo delle versioni dei set di dati

Semantico

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

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

La versione segue Semantic Versioning 2.0.0 : MAJOR.MINOR.PATCH . Lo scopo della versione è di essere in grado di garantire la riproducibilità: il caricamento di un determinato set di dati in una versione fissa produce gli stessi dati. Più specificamente:

  • 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 dato slice, l'API slicing restituisce lo stesso set di record.
  • Se la versione MINOR viene incrementata, i dati esistenti letti dal client sono gli stessi, ma ci sono dati aggiuntivi (funzionalità in ciascun record). Per ogni dato slice, l'API slicing restituisce lo stesso set di record.
  • Se la versione MAJOR viene incrementata, i dati esistenti sono stati modificati e / o l'API slicing non restituisce necessariamente lo stesso set di record per una determinata sezione.

Quando viene apportata una modifica del codice alla libreria TFDS e tale modifica del 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.

Si noti che la semantica sopra è lo sforzo migliore e potrebbero esserci dei bug non notati che incidono su un set di dati mentre la versione non è stata incrementata. Tali bug vengono infine corretti, ma se si fa molto affidamento sul controllo delle versioni, si consiglia di utilizzare TFDS da una versione rilasciata (al contrario di HEAD ).

Si noti inoltre 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 costruttori corrispondenti sono open_images_v4 , open_images_v5 , ...

Versioni supportate

Un DatasetBuilder può supportare diverse versioni, che possono essere sia superiori che inferiori rispetto alla versione canonica. Per esempio:

 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"),
  ]
 

La scelta di continuare a supportare una versione precedente viene fatta caso per caso, principalmente in base alla popolarità del set di dati e della versione. Alla fine, miriamo a supportare solo un numero limitato di versioni per set di dati, idealmente una. Nell'esempio sopra, possiamo vedere che la versione 2.0.0 non è più supportata, come identica a 2.0.1 dal punto di vista del lettore.

Le versioni supportate con un numero maggiore rispetto al numero di versione canonico sono considerate sperimentali e potrebbero essere interrotte. Saranno comunque resi canonici.

Una versione può specificare tfds_version_to_prepare . Ciò significa che questa versione del set di dati può essere utilizzata con la versione corrente del codice TFDS se è già stata preparata da una versione precedente del codice, ma non può essere preparata. Il valore di tfds_version_to_prepare specifica l'ultima versione nota di TFDS che può essere utilizzata per scaricare e preparare il set di dati in questa versione.

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 si utilizza TFDS per una pubblicazione, si consiglia di:

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

Ciò dovrebbe rendere più semplice per te, i tuoi lettori e revisori futuri riprodurre i tuoi risultati.

esperimenti

Per implementare gradualmente i cambiamenti nel TFDS che stanno influenzando molti costruttori di set di dati, abbiamo introdotto il concetto di esperimenti. Quando viene introdotto per la prima volta, un esperimento è disabilitato per impostazione predefinita, ma versioni specifiche del set di dati possono decidere di abilitarlo. In genere questo verrà fatto inizialmente su versioni "future" (non ancora rese canoniche). Per esempio:

 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}),
  ]
 

Una volta verificato che l'esperimento funziona come previsto, verrà esteso a tutti o alla maggior parte dei set di dati, a quel punto può essere abilitato per impostazione predefinita e la definizione sopra sarà quindi simile a:

 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"),
  ]
 

Una volta che un esperimento viene utilizzato in tutte le versioni del set di dati (non è rimasta alcuna versione del set di dati che specifichi {experiment: False} ), l'esperimento può essere eliminato.

Gli esperimenti e la loro descrizione sono definiti in core/utils/version.py .

BUILDER_CONFIGS e versioni

Alcuni set di dati definiscono diversi BUILDER_CONFIGS . Quando questo è il caso, version e supported_versions sono definite sui config stessi oggetti. Oltre a ciò, 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.*.*')