Ta strona została przetłumaczona przez Cloud Translation API.
Switch to English

Wersjonowanie zbiorów danych

Semantyczny

Każdy DatasetBuilder zdefiniowany w TFDS jest dostarczany z wersją, na przykład:

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

Wersja jest zgodna z Semantic Versioning 2.0.0 : MAJOR.MINOR.PATCH . Celem tej wersji jest zapewnienie powtarzalności: załadowanie danego zestawu danych do ustalonej wersji daje te same dane. Dokładniej:

  • Jeśli wersja PATCH jest zwiększana, dane odczytywane przez klienta są takie same, chociaż dane mogą być serializowane na dysku inaczej lub metadane mogły ulec zmianie. Dla dowolnego wycinka API do wycinania zwraca ten sam zestaw rekordów.
  • Jeśli wersja MINOR jest zwiększana, istniejące dane odczytane przez klienta są takie same, ale są dodatkowe dane (cechy w każdym rekordzie). Dla dowolnego wycinka API do wycinania zwraca ten sam zestaw rekordów.
  • Jeśli wersja MAJOR jest zwiększana, istniejące dane zostały zmienione i / lub interfejs API do wycinania niekoniecznie zwraca ten sam zestaw rekordów dla danego wycinka.

Gdy w bibliotece TFDS zostanie wprowadzona zmiana kodu, która wpływa na sposób serializacji i / lub odczytu zestawu danych przez klienta, odpowiednia wersja programu budującego jest zwiększana zgodnie z powyższymi wskazówkami.

Zauważ, ż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 zostaną ostatecznie naprawione, 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ż zauważyć, że niektóre zbiory danych mają inny schemat wersjonowania niezależny od wersji TFDS. Na przykład zestaw danych Open Images ma kilka wersji, aw TFDS odpowiednie konstruktory to open_images_v4 , open_images_v5 , ...

Obsługiwane wersje

DatasetBuilder może obsługiwać kilka wersji, które mogą być wyższe lub niższe niż wersja kanoniczna. Na przykład:

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

Decyzja o dalszym wspieraniu starszej wersji jest podejmowana indywidualnie dla każdego przypadku, głównie na podstawie popularności zbioru danych i wersji. Ostatecznie dążymy do obsługi ograniczonej liczby wersji na zbiór danych, najlepiej jednej. W powyższym przykładzie widzimy, że wersja 2.0.0 nie jest już obsługiwana, jako identyczna z 2.0.1 z punktu widzenia czytelnika.

Obsługiwane wersje o numerze wyższym niż numer kanoniczny są uważane za eksperymentalne i mogą być uszkodzone. Jednak ostatecznie staną się kanoniczne.

Wersja może określać tfds_version_to_prepare . Oznacza to, że ta wersja zestawu danych może być używana tylko z aktualną wersją kodu TFDS, jeśli została już przygotowana przez starszą wersję kodu, ale nie można jej przygotować. Wartość tfds_version_to_prepare określa ostatnią znaną wersję TFDS, której można użyć do pobrania i przygotowania zestawu danych w tej wersji.

Ładowanie określonej wersji

Podczas ładowania zestawu danych lub elementu DatasetBuilder można określić wersję do użycia. 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:

  • naprawić tylko MAJOR składnik wersji ;
  • reklamuj, która wersja zbioru danych została użyta w Twoich wynikach.

Powinno to ułatwić Tobie w przyszłości, Twoim czytelnikom i recenzentom odtworzenie wyników.

Eksperymenty

Aby stopniowo wprowadzać zmiany w TFDS, które mają wpływ na wiele twórców zestawów danych, wprowadziliśmy pojęcie eksperymentów. Po pierwszym wprowadzeniu eksperyment jest domyślnie wyłączony, ale określone wersje zestawu danych mogą zdecydować o jego włączeniu. Zazwyczaj będzie to wykonywane na początku w „przyszłych” wersjach (które nie są jeszcze kanoniczne). Na przykład:

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

Gdy eksperyment zostanie zweryfikowany, aby działał zgodnie z oczekiwaniami, zostanie rozszerzony na wszystkie lub większość zbiorów danych, w którym to momencie można go włączyć domyślnie, a powyższa definicja będzie wtedy wyglądać następująco:

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

Gdy eksperyment zostanie wykorzystany we wszystkich wersjach zbioru danych (nie ma już wersji zbioru danych określającej {experiment: False} ), można go usunąć.

Eksperymenty i ich opis są zdefiniowane w core/utils/version.py .

BUILDER_CONFIGS i wersje

Niektóre BUILDER_CONFIGS danych definiują kilka BUILDER_CONFIGS . W takim przypadku version i supported_versions są definiowane 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.*.*')