数据集版本控制

定义

版本控制可以指不同的含义

  • TFDS API 版本（pip 版本）：tfds.version
  • 公共数据集版本，独立于 TFDS（例如 Voc2007、Voc2012）。在 TFDS 中，每个公共数据集版本都应作为独立的数据集实现
    • 通过 构建器配置：例如 voc/2007、voc/2012
    • 或作为 2 个独立的数据集：例如 wmt13_translate、wmt14_translate
  • TFDS 中的数据集生成代码版本（my_dataset:1.0.0）：例如，如果在 TFDS 实现的 voc/2007 中发现错误，则 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 库进行代码更改，并且该代码更改影响数据集的序列化方式和/或客户端读取方式时，将根据上述指南递增相应的构建器版本。

请注意，上述语义是尽力而为，在版本未递增时，可能存在影响数据集的未发现错误。此类错误最终会被修复，但如果您严重依赖版本控制，建议您使用发布版本的 TFDS（而不是 HEAD）。

另请注意，某些数据集具有独立于 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:
      ...