本頁面由 Cloud Translation API 翻譯而成。
Switch to English

數據集版本控制

語義的

TFDS中定義的每個DatasetBuilder都有一個版本,例如:

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

該版本遵循語義版本2.0.0MAJOR.MINOR.PATCH 。版本的目的是為了保證可重複性:以固定版本加載給定的數據集會產生相同的數據。進一步來說:

  • 如果增加PATCH版本,則客戶端讀取的數據是相同的,儘管數據在磁盤上的序列化可能不同,或者元數據可能已更改。對於任何給定的切片,切片API返回相同的記錄集。
  • 如果MINOR版本增加,則客戶端讀取的現有數據是相同的,但是還有其他數據(每條記錄中的功能)。對於任何給定的切片,切片API返回相同的記錄集。
  • 如果增加MAJOR版本,則現有數據已更改,並且/或者切片API不一定會為給定切片返回相同的記錄集。

當對TFDS庫進行代碼更改並且該代碼更改影響客戶端對數據集進行序列化和/或讀取的方式時,則根據上述準則增加相應的構建器版本。

請注意,上述語義是盡力而為的,當版本未遞增時,可能會出現一些未被注意的錯誤影響數據集。此類錯誤最終得以修復,但是如果您嚴重依賴版本控制,我們建議您使用已發布版本(而不是HEAD )中的TFDS。

還要注意,某些數據集具有獨立於TFDS版本的另一版本控制方案。例如,“打開圖像”數據集具有多個版本,在TFDS中,相應的構建器是open_images_v4open_images_v5 ,...

支持的版本

DatasetBuilder可以支持多個版本,這些版本可以高於或低於規範版本。例如:

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

繼續支持較舊版本的選擇取決於具體情況,這主要是基於數據集和版本的普及程度。最終,我們的目標是每個數據集僅支持有限數量的版本,最好是一個。在上面的示例中,我們可以看到不再支持2.0.0版本,從讀者的角度來看,該版本與2.0.1相同。

具有比規範版本號更高的數字的受支持版本被認為是實驗性的,並且可能被破壞。但是,它們最終將被規範化。

一個版本可以指定tfds_version_to_prepare 。這意味著該數據集版本只能與舊版本的TFDS代碼一起使用,但只能由當前版本的TFDS代碼使用。 tfds_version_to_prepare的值指定TFDS的最新已知版本,該版本可用於下載和準備該版本的數據集。

加載特定版本

加載數據集或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組件 ;
  • 公佈結果中使用了哪個版本的數據集。

這樣做應該使您將來的自己,讀者和審閱者更容易重現您的結果。

實驗

為了逐步推出影響許多數據集構建器的TFDS中的更改,我們引入了實驗的概念。首次引入實驗時,默認情況下它是禁用的,但是特定的數據集版本可以決定啟用它。首先,通常會在“未來”版本(尚不規範)上完成此操作。例如:

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

驗證實驗可以正常工作後,它將擴展到所有或大多數數據集,此時可以默認啟用它,並且上面的定義如下所示:

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

一旦在所有數據集版本上使用了實驗(沒有剩餘的數據集版本指定{experiment: False} ),就可以刪除該實驗。

實驗及其描述在core/utils/version.py中定義。

BUILDER_CONFIGS和版本

一些數據集定義了幾個BUILDER_CONFIGS 。在這種情況下, versionsupported_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.*.*')