Esta página foi traduzida pela API Cloud Translation.
Switch to English

Versão de conjuntos de dados

Semântica

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

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

A versão segue o Semantic Versioning 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 gera 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 maneira diferente no disco ou os metadados possam ter sido alterados. Para qualquer fatia, a API de faturamento retorna o mesmo conjunto de registros.
  • Se a versão MINOR for incrementada, os dados existentes, conforme lidos pelo cliente, são os mesmos, mas há dados adicionais (recursos em cada registro). Para qualquer fatia, a API de faturamento 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 impacto 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 erros não percebidos afetando um conjunto de dados enquanto a versão não foi incrementada. Esses erros são eventualmente corrigidos, mas se você confiar muito no controle de versão, recomendamos que você use o TFDS de uma versão lançada (em oposição ao HEAD ).

Observe também que alguns conjuntos de dados têm outro esquema de versão 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 , ...

Versões suportadas

Um DatasetBuilder pode suportar várias versões, que podem ser superiores ou inferiores à versão canônica. Por exemplo:

 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"),
  ]
 

A escolha de continuar suportando uma versão mais antiga é feita caso a caso, principalmente com base na popularidade do conjunto de dados e da versão. Eventualmente, nosso objetivo é oferecer suporte apenas a um número limitado de versões por conjunto de dados, idealmente uma. No exemplo acima, podemos ver que a versão 2.0.0 não é mais suportada, como idêntica à 2.0.1 da perspectiva do leitor.

As versões suportadas com um número maior que o número da versão canônica são consideradas experimentais e podem estar com problemas. No entanto, acabarão por se tornar canônicos.

Uma versão pode especificar tfds_version_to_prepare . Isso significa que esta versão do conjunto de dados só pode ser usada com a versão atual do código TFDS se já tiver sido preparada por uma versão mais antiga do código, mas não puder ser preparada. O valor de tfds_version_to_prepare especifica a última versão conhecida do TFDS, que pode ser usada para baixar e preparar o conjunto de dados nesta versão.

Carregando uma versão específica

Ao carregar um conjunto de dados ou um 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 você usar o TFDS para uma publicação, recomendamos que você:

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

Fazer isso deve facilitar a reprodução de seus resultados, de seus leitores e revisores.

Experiências

Para implementar gradualmente as mudanças no TFDS que afetam muitos criadores de conjuntos de dados, introduzimos a noção de experimentos. Quando introduzida pela primeira vez, um experimento é desativado por padrão, mas versões específicas do conjunto de dados podem decidir ativá-lo. Isso normalmente será feito em versões "futuras" (ainda não feitas canônicas) a princípio. Por exemplo:

 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}),
  ]
 

Depois que uma experiência é verificada para funcionar conforme o esperado, ela será estendida para todos ou para a maioria dos conjuntos de dados; nesse momento, ela poderá ser ativada por padrão e a definição acima será semelhante a:

 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"),
  ]
 

Depois que uma experiência é usada em todas as versões de conjuntos de dados (não há versão do conjunto de dados especificando {experiment: False} ), a experiência pode ser excluída.

As experiências e suas descrições são definidas em core/utils/version.py .

BUILDER_CONFIGS e versões

Alguns conjuntos de dados definem vários BUILDER_CONFIGS . Quando esse for 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.*.*')