Управление версиями наборов данных

Определение

Версионирование может иметь разное значение:

  • Версия API TFDS (версия 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')

Семантический

Каждый DatasetBuilder определенный в TFDS, имеет версию, например:

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

Версия соответствует Semantic Versioning 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.*.*')

Экспериментальная версия

Можно разрешить создание двух версий одновременно. Одна версия по умолчанию и одна экспериментальная версия. Например:

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

В коде необходимо убедиться в поддержке двух версий:

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

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