Эта страница переведена с помощью Cloud Translation API.
Switch to English

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

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

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

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

Версия соответствует семантическому управлению версиями 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 может поддерживать несколько версий, которые могут быть как выше, так и ниже канонической версии. Например:

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_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 . В этом случае 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.*.*')