Control de versiones de conjuntos de datos

Definición

El control de versiones puede referirse a diferentes significados:

• La versión TFDS API (versión PIP): tfds. version
• La versión base de datos pública, independiente de TFDS (por ejemplo Voc2007 , Voc2012). En TFDS, cada versión de conjunto de datos públicos debe implementarse como un conjunto de datos independiente:
  • Ya sea a través de configuraciones constructor : Ej voc/2007 , voc/2012
  • Ya sea como 2 conjuntos de datos independientes: Ej wmt13_translate , wmt14_translate
• La versión de código de generación de datos en TFDS ( my_dataset:1.0.0 ): Por ejemplo, si se encuentra un error en la ejecución de TFDS voc/2007 , el voc.py se actualizará código de generación ( voc/2007:1.0.0 - > voc/2007:2.0.0 ).

El resto de esta guía solo se enfoca en la última definición (versión del código del conjunto de datos en el repositorio TFDS).

Versiones admitidas

Como regla general:

• Solo se puede generar la última versión actual.
• Se pueden leer todos los conjuntos de datos generados anteriormente (nota: esto requiere conjuntos de datos generados con 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')

Semántico

Cada DatasetBuilder definido en TFDS viene con una versión, por ejemplo:

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

La versión sigue semántica de versiones 2.0.0 : MAJOR.MINOR.PATCH . El propósito de la versión es poder garantizar la reproducibilidad: cargar un conjunto de datos dado en una versión fija produce los mismos datos. Más específicamente:

• Si PATCH se incrementa versión, los datos como leído por el cliente es el mismo, aunque los datos pueden ser serializados de manera diferente en el disco, o los metadatos podrían haber cambiado. Para cualquier segmento determinado, la API de segmento devuelve el mismo conjunto de registros.
• Si MINOR se incrementa versión, los datos existentes como leído por el cliente es el mismo, pero no hay datos adicionales (características en cada registro). Para cualquier segmento determinado, la API de segmento devuelve el mismo conjunto de registros.
• Si MAJOR se incrementa versión, los datos existentes se han modificado y / o la API de corte en rodajas no necesariamente devolver el mismo conjunto de registros para una porción determinada.

Cuando se realiza un cambio de código en la biblioteca TFDS y ese cambio de código afecta la forma en que el cliente serializa y / o lee un conjunto de datos, la versión del constructor correspondiente se incrementa de acuerdo con las pautas anteriores.

Tenga en cuenta que la semántica anterior es el mejor esfuerzo, y puede haber errores no notados que afecten a un conjunto de datos mientras la versión no se incrementó. Tales errores son finalmente fijos, pero si dependen en gran medida del control de versiones, nos aconsejan que use TFDS de una versión comercial (en contraposición a HEAD ).

También tenga en cuenta que algunos conjuntos de datos tienen otro esquema de versiones independiente de la versión TFDS. Por ejemplo, las imágenes abiertas conjunto de datos tiene varias versiones, y en TFDS, los constructores correspondientes son open_images_v4 , open_images_v5 , ...

Cargando una versión específica

Al cargar un conjunto de datos o una DatasetBuilder , puede especificar la versión para su uso. Por ejemplo:

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

Si usa TFDS para una publicación, le recomendamos que:

• fijar el MAJOR componente de sólo la versión;
• anuncia qué versión del conjunto de datos se utilizó en tus resultados.

Hacerlo debería facilitarle a usted mismo, a sus lectores y revisores la reproducción de sus resultados.

BUILDER_CONFIGS y versiones

Algunos conjuntos de datos definen varios BUILDER_CONFIGS . Cuando ese es el caso, version y supported_versions se definen a sí mismos los objetos de configuración. Aparte de eso, la semántica y el uso son idénticos. Por ejemplo:

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

Versión experimental

Es posible permitir que se generen 2 versiones al mismo tiempo. Una versión predeterminada y una experimental. Por ejemplo:

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

En el código, debe asegurarse de admitir las 2 versiones:

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

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