資料集版本控制

定義

版本控制可能有多種含義

  • TFDS API 版本 (pip 版本)：tfds.version
  • 公開資料集版本，與 TFDS 無關 (例如 Voc2007、Voc2012)。在 TFDS 中，每個公開資料集版本都應做為獨立資料集實作
    • 透過 建立工具組態：例如 voc/2007、voc/2012
    • 或做為 2 個獨立資料集：例如 wmt13_translate、wmt14_translate
  • TFDS 中的資料集產生程式碼版本 (my_dataset:1.0.0)：例如，如果在 voc/2007 的 TFDS 實作中發現錯誤，則會更新 voc.py 產生程式碼 (voc/2007:1.0.0 -> voc/2007:2.0.0)。

本指南的其餘部分僅著重於最後一個定義 (TFDS 存放區中的資料集程式碼版本)。

支援的版本

一般規則如下

  • 僅可產生最新的目前版本。
  • 可以讀取所有先前產生的資料集 (注意：這需要使用 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')

語意

TFDS 中定義的每個 DatasetBuilder 都隨附一個版本，例如

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

此版本遵循語意化版本 2.0.0：MAJOR.MINOR.PATCH。版本的目的是能夠保證可重現性：以固定版本載入給定的資料集會產生相同的資料。更具體來說：

  • 如果 PATCH 版本遞增，則用戶端讀取的資料相同，但資料在磁碟上的序列化方式可能不同，或者中繼資料可能已變更。對於任何給定的切片，切片 API 會傳回相同的記錄集。
  • 如果 MINOR 版本遞增，則用戶端讀取的現有資料相同，但有額外資料 (每個記錄中的功能)。對於任何給定的切片，切片 API 會傳回相同的記錄集。
  • 如果 MAJOR 版本遞增，則現有資料已變更，且/或切片 API 不一定會針對給定的切片傳回相同的記錄集。

當對 TFDS 程式庫進行程式碼變更，且該程式碼變更會影響資料集的序列化和/或用戶端讀取方式時，則會根據上述準則遞增對應的建立工具版本。

請注意，上述語意是盡力而為，並且可能存在未注意到的錯誤，這些錯誤會影響資料集，但版本未遞增。此類錯誤最終會修正，但如果您非常依賴版本控制，我們建議您從已發布的版本 (而不是 HEAD) 使用 TFDS。

另請注意，某些資料集具有與 TFDS 版本無關的其他版本控制方案。例如，Open Images 資料集有多個版本，而在 TFDS 中，對應的建立工具為 open_images_v4、open_images_v5 等。

載入特定版本

載入資料集或 DatasetBuilder 時，您可以指定要使用的版本。例如：

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

如果將 TFDS 用於發佈，我們建議您

  • 僅修正版本的 MAJOR 元件;
  • 宣傳您的結果中使用的資料集版本。

這樣做應該讓您自己、讀者和審稿人更容易重現您的結果。

BUILDER_CONFIGS 和版本

某些資料集定義了多個 BUILDER_CONFIGS。在這種情況下，version 和 supported_versions 是在組態物件本身上定義的。除此之外，語意和用法都相同。例如：

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

實驗性版本

可以同時產生 2 個版本。一個預設版本和一個實驗性版本。例如：

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

在程式碼中，您需要確保支援這 2 個版本

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

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