Wersjonowanie zbiorów danych

Definicja

Wersjonowanie może odnosić się do innego znaczenia:

  • Wersja API TFDS (wersja pip): tfds. version
  • Wersja publicznego zbioru danych, niezależna od TFDS (np. Voc2007 , Voc2012). W TFDS każda wersja publicznego zbioru danych powinna być zaimplementowana jako niezależny zbiór danych:
    • Albo poprzez konfiguracje konstruktora : np. voc/2007 , voc/2012
    • Albo jako 2 niezależne zestawy danych: np. wmt13_translate , wmt14_translate
  • Wersja kodu generowania zestawu danych w TFDS ( my_dataset:1.0.0 ): Na przykład, jeśli zostanie znaleziony błąd w implementacji TFDS voc/2007 , kod generowania voc.py zostanie zaktualizowany ( voc/2007:1.0.0 - > voc/2007:2.0.0 ).

Pozostała część tego przewodnika skupia się wyłącznie na ostatniej definicji (wersja kodu zbioru danych w repozytorium TFDS).

Obsługiwane wersje

Co do zasady:

  • Można wygenerować tylko ostatnią aktualną wersję.
  • Można odczytać cały wcześniej wygenerowany zbiór danych (uwaga: wymaga to zbiorów danych wygenerowanych za pomocą 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')

Semantyczny

Każdy DatasetBuilder zdefiniowany w TFDS ma wersję, na przykład:

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',
  }

Wersja jest zgodna z wersją Semantic 2.0.0 : MAJOR.MINOR.PATCH . Celem wersji jest zapewnienie powtarzalności: załadowanie danego zbioru danych w ustalonej wersji daje te same dane. Dokładniej:

  • Jeśli wersja PATCH zostanie zwiększona, dane odczytane przez klienta będą takie same, chociaż dane mogą być serializowane inaczej na dysku lub metadane mogły ulec zmianie. Dla dowolnego wycinka interfejs API krojenia zwraca ten sam zestaw rekordów.
  • W przypadku inkrementacji wersji MINOR istniejące dane odczytywane przez klienta pozostają takie same, ale występują dodatkowe dane (cechy w każdym rekordzie). Dla dowolnego wycinka interfejs API krojenia zwraca ten sam zestaw rekordów.
  • Jeśli wersja MAJOR zostanie zwiększona, istniejące dane zostaną zmienione i/lub interfejs API krojenia niekoniecznie zwróci ten sam zestaw rekordów dla danego wycinka.

Kiedy w bibliotece TFDS zostanie dokonana zmiana kodu, która wpłynie na sposób serializacji i/lub odczytu zbioru danych przez klienta, wówczas odpowiednia wersja konstruktora zostanie zwiększona zgodnie z powyższymi wytycznymi.

Należy pamiętać, że powyższa semantyka jest najlepszym rozwiązaniem i mogą wystąpić niezauważone błędy wpływające na zestaw danych, gdy wersja nie została zwiększona. Takie błędy są ostatecznie naprawiane, ale jeśli w dużym stopniu polegasz na wersjonowaniu, radzimy używać TFDS z wydanej wersji (w przeciwieństwie do HEAD ).

Należy również pamiętać, że niektóre zbiory danych mają inny schemat wersjonowania niezależny od wersji TFDS. Na przykład zbiór danych Open Images ma kilka wersji, a w TFDS odpowiednimi kreatorami są open_images_v4 , open_images_v5 , ...

Ładowanie określonej wersji

Podczas ładowania zestawu danych lub DatasetBuilder możesz określić wersję, która ma być używana. Na przykład:

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

Jeśli używasz TFDS do publikacji, radzimy:

  • napraw tylko MAJOR komponent wersji ;
  • reklamuj, która wersja zbioru danych została wykorzystana w wynikach.

Powinno to ułatwić Tobie, czytelnikom i recenzentom odtworzenie wyników.

BUILDER_CONFIGS i wersje

Niektóre zestawy danych definiują kilka BUILDER_CONFIGS . W takim przypadku version i supported_versions są zdefiniowane w samych obiektach konfiguracyjnych. Poza tym semantyka i użycie są identyczne. Na przykład: 

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

Wersja eksperymentalna

Istnieje możliwość jednoczesnego wygenerowania 2 wersji. Jedna wersja domyślna i jedna wersja eksperymentalna. Na przykład:

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

W kodzie musisz upewnić się, że obsługuje 2 wersje:

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

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