Versionamento de conjuntos de dados

Definição

O versionamento pode referir-se a diferentes significados:

  • A versão da API TFDS (versão pip): tfds. version
  • A versão do conjunto de dados público, independente do TFDS (por exemplo, Voc2007 , Voc2012). No TFDS, cada versão do conjunto de dados público deve ser implementada como um conjunto de dados independente:
    • Através das configurações do construtor : por exemplo, voc/2007 , voc/2012
    • Como 2 conjuntos de dados independentes: por exemplo, wmt13_translate , wmt14_translate
  • A versão do código de geração do conjunto de dados no TFDS ( my_dataset:1.0.0 ): Por exemplo, se um bug for encontrado na implementação TFDS de voc/2007 , o código de geração voc.py será atualizado ( voc/2007:1.0.0 - > voc/2007:2.0.0 ).

O restante deste guia concentra-se apenas na última definição (versão do código do conjunto de dados no repositório TFDS).

Versões suportadas

Como regra geral:

  • Somente a última versão atual pode ser gerada.
  • Todos os conjuntos de dados gerados anteriormente podem ser lidos (nota: isso requer conjuntos de dados gerados com 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ântica

Cada DatasetBuilder definido no TFDS vem com uma versão, por exemplo:

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

A versão segue o Versionamento Semântico 2.0.0 : MAJOR.MINOR.PATCH . O objetivo da versão é garantir a reprodutibilidade: carregar um determinado conjunto de dados em uma versão fixa produz os mesmos dados. Mais especificamente:

  • Se a versão PATCH for incrementada, os dados lidos pelo cliente serão os mesmos, embora os dados possam ser serializados de forma diferente no disco ou os metadados possam ter sido alterados. Para qualquer fatia, a API de fatiamento retorna o mesmo conjunto de registros.
  • Se a versão MINOR for incrementada, os dados existentes lidos pelo cliente são os mesmos, mas há dados adicionais (recursos em cada registro). Para qualquer fatia, a API de fatiamento retorna o mesmo conjunto de registros.
  • Se a versão MAJOR for incrementada, os dados existentes foram alterados e/ou a API de fatiamento não retorna necessariamente o mesmo conjunto de registros para uma determinada fatia.

Quando uma alteração de código é feita na biblioteca TFDS e essa alteração de código afeta a maneira como um conjunto de dados está sendo serializado e/ou lido pelo cliente, a versão do construtor correspondente é incrementada de acordo com as diretrizes acima.

Observe que a semântica acima é o melhor esforço e pode haver bugs despercebidos afetando um conjunto de dados enquanto a versão não foi incrementada. Esses bugs são eventualmente corrigidos, mas se você depende muito do controle de versão, recomendamos usar o TFDS de uma versão lançada (em vez de HEAD ).

Observe também que alguns conjuntos de dados possuem outro esquema de versionamento independente da versão do TFDS. Por exemplo, o conjunto de dados Open Images possui várias versões e, no TFDS, os construtores correspondentes são open_images_v4 , open_images_v5 , ...

Carregando uma versão específica

Ao carregar um conjunto de dados ou DatasetBuilder , você pode especificar a versão a ser usada. Por exemplo:

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

Se estiver usando o TFDS para uma publicação, recomendamos:

  • corrija apenas o componente MAJOR da versão ;
  • anuncie qual versão do conjunto de dados foi usada em seus resultados.

Isso tornará mais fácil para você, seus leitores e revisores, reproduzir seus resultados no futuro.

BUILDER_CONFIGS e versões

Alguns conjuntos de dados definem vários BUILDER_CONFIGS . Quando for esse o caso, version e supported_versions são definidos nos próprios objetos de configuração. Fora isso, a semântica e o uso são idênticos. Por exemplo: 

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

Versão experimental

É possível permitir a geração de 2 versões ao mesmo tempo. Uma versão padrão e uma versão experimental. Por exemplo:

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

No código, você precisa ter suporte para as 2 versões:

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

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