此页面由 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.*.*')