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

Compatibilidade de versão do TensorFlow

Este documento é para usuários que precisam de compatibilidade com versões anteriores em diferentes versões do TensorFlow (para código ou dados) e para desenvolvedores que desejam modificar o TensorFlow enquanto preservam a compatibilidade.

Versão semântica 2.0

O TensorFlow segue o Semantic Versioning 2.0 ( semver ) para sua API pública. Cada versão de lançamento do TensorFlow tem o formato MAJOR.MINOR.PATCH . Por exemplo, o TensorFlow versão 1.2.3 tem MAJOR versão 1, MINOR versão 2 e PATCH versão 3. As alterações em cada número têm o seguinte significado:

  • MAJOR : Alterações potencialmente incompatíveis com versões anteriores. O código e os dados que funcionavam com uma versão principal anterior não funcionarão necessariamente com a nova versão. No entanto, em alguns casos, os gráficos e pontos de verificação existentes do TensorFlow podem ser migrados para a versão mais recente; consulte Compatibilidade de gráficos e pontos de verificação para obter detalhes sobre compatibilidade de dados.

  • MENOR : recursos compatíveis com versões anteriores, melhorias de velocidade, etc. O código e os dados que funcionaram com uma versão secundária anterior e que dependem apenas da API pública não experimental continuarão a funcionar inalterados. Para obter detalhes sobre o que é e o que não é a API pública, consulte O que é abordado .

  • PATCH : Correções de bugs compatíveis com versões anteriores.

Por exemplo, a versão 1.0.0 introduziu alterações incompatíveis com versões anteriores da versão 0.12.1. No entanto, a versão 1.1.1 era compatível com a versão 1.0.0.

O que está coberto

Apenas as APIs públicas do TensorFlow são compatíveis com versões anteriores em versões menores e de patch. As APIs públicas consistem em

  • Todas as funções e classes Python documentadas no módulo tensorflow e seus submódulos, exceto para

    • Símbolos privados: qualquer função, classe, etc., cujo nome comece com _
    • Símbolos experimentais e tf.contrib , veja abaixo para detalhes.

    Observe que o código nos diretórios examples/ e tools/ não pode ser acessado por meio do módulo Python tensorflow e, portanto, não é coberto pela garantia de compatibilidade.

    Se um símbolo está disponível por meio do módulo tensorflow Python ou seus submódulos, mas não está documentado, ele não é considerado parte da API pública.

  • A API de compatibilidade (em Python, o módulo tf.compat ). Nas versões principais, podemos lançar utilitários e terminais adicionais para ajudar os usuários na transição para uma nova versão principal. Esses símbolos API estão obsoletos e não são suportados (ou seja, não adicionaremos nenhum recurso e não corrigiremos bugs a não ser para corrigir vulnerabilidades), mas eles se enquadram em nossas garantias de compatibilidade.

  • A API C.

  • Os seguintes arquivos de buffer de protocolo:

O que não está coberto

Algumas partes do TensorFlow podem mudar de maneiras incompatíveis com versões anteriores a qualquer momento. Esses incluem:

  • APIs experimentais : para facilitar o desenvolvimento, isentamos alguns símbolos de API claramente marcados como experimentais das garantias de compatibilidade. Em particular, o seguinte não é coberto por nenhuma garantia de compatibilidade:

    • qualquer símbolo no módulo tf.contrib ou seus submódulos;
    • qualquer símbolo (módulo, função, argumento, propriedade, classe ou constante) cujo nome contém experimental ou Experimental ; ou

    • qualquer símbolo cujo nome totalmente qualificado inclua um módulo ou classe que seja experimental. Isso inclui campos e submensagens de qualquer buffer de protocolo denominado experimental .

  • Outras linguagens : APIs TensorFlow em linguagens diferentes de Python e C, como:

  • Detalhes de operações compostas: muitas funções públicas em Python se expandem para várias operações primitivas no gráfico, e esses detalhes farão parte de quaisquer gráficos salvos em disco como GraphDef s. Esses detalhes podem mudar para lançamentos menores. Em particular, os testes de regressão que verificam a correspondência exata entre os gráficos provavelmente não funcionarão em versões menores, embora o comportamento do gráfico deva ser o mesmo e os pontos de verificação existentes ainda funcionem.

  • Detalhes numéricos de ponto flutuante: os valores de ponto flutuante específicos calculados por ops podem mudar a qualquer momento. Os usuários devem confiar apenas na precisão aproximada e na estabilidade numérica, não nos bits específicos computados. As alterações nas fórmulas numéricas em versões menores e de patch devem resultar em precisão comparável ou melhorada, com a ressalva de que, no aprendizado de máquina, a precisão aprimorada de fórmulas específicas pode resultar em precisão diminuída para o sistema geral.

  • Números aleatórios: os números aleatórios específicos calculados podem mudar a qualquer momento. Os usuários devem confiar apenas em distribuições aproximadamente corretas e força estatística, não nos bits específicos calculados. Consulte o guia de geração de números aleatórios para obter detalhes.

  • Desvio de versão no Tensorflow distribuído: a execução de duas versões diferentes do TensorFlow em um único cluster não é compatível. Não há garantias sobre a compatibilidade com versões anteriores do protocolo de fio.

  • Bugs: nos reservamos o direito de fazer alterações de comportamento incompatível com versões anteriores (embora não de API) se a implementação atual estiver claramente quebrada, isto é, se contradizer a documentação ou se um comportamento pretendido bem conhecido e bem definido não for implementado corretamente devido a um bug. Por exemplo, se um otimizador afirma implementar um algoritmo de otimização conhecido, mas não corresponde a esse algoritmo devido a um bug, então corrigiremos o otimizador. Nossa correção pode quebrar o código, dependendo do comportamento errado para convergência. Notaremos essas mudanças nas notas de lançamento.

  • API não utilizada: nos reservamos o direito de fazer alterações incompatíveis com versões anteriores em APIs para as quais não encontramos usos documentados (realizando auditoria de uso do TensorFlow por meio de pesquisa do GitHub). Antes de fazer qualquer alteração, anunciaremos nossa intenção de fazer a alteração na lista de e-mails announce @ , fornecendo instruções sobre como resolver quaisquer quebras (se aplicável) e esperaremos duas semanas para dar a nossa comunidade a chance de compartilhar seus comentários .

  • Comportamento de erro: podemos substituir os erros por um comportamento sem erro. Por exemplo, podemos alterar uma função para calcular um resultado em vez de gerar um erro, mesmo se esse erro for documentado. Também nos reservamos o direito de alterar o texto das mensagens de erro. Além disso, o tipo de um erro pode mudar, a menos que o tipo de exceção para uma condição de erro específica seja especificado na documentação.

Compatibilidade de SavedModels, gráficos e pontos de verificação

SavedModel é o formato de serialização preferido para usar em programas do TensorFlow. SavedModels contém duas partes: Um ou mais gráficos codificados como GraphDefs e um Checkpoint. Os gráficos descrevem o fluxo de dados de operações a serem executados e os pontos de verificação contêm os valores de tensor salvos das variáveis ​​em um gráfico.

Muitos usuários do TensorFlow criam SavedModels e os carregam e executam com uma versão posterior do TensorFlow. Em conformidade com o semver , SavedModels escritos com uma versão do TensorFlow podem ser carregados e avaliados com uma versão posterior do TensorFlow com a mesma versão principal.

Oferecemos garantias adicionais para SavedModels compatíveis . Chamamos um SavedModel que foi criado usando apenas APIs não obsoletas, não experimentais e incompatíveis na versão principal N TensorFlow de SavedModel compatível com a versão N Qualquer SavedModel compatível com a versão principal N TensorFlow pode ser carregado e executado com a versão principal N+1 TensorFlow. No entanto, a funcionalidade necessária para construir ou modificar tal modelo pode não estar mais disponível, portanto, esta garantia só se aplica ao SavedModel não modificado.

Faremos o possível para preservar a compatibilidade com versões anteriores o máximo possível, de modo que os arquivos serializados possam ser usados ​​por longos períodos de tempo.

Compatibilidade GraphDef

Os gráficos são serializados por meio do buffer de protocolo GraphDef . Para facilitar alterações incompatíveis com versões anteriores em gráficos, cada GraphDef tem um número de versão separado da versão do TensorFlow. Por exemplo, GraphDef versão 17 GraphDef obsoleto o inv op em favor do reciprocal . A semântica é:

  • Cada versão do TensorFlow oferece suporte a um intervalo de versões do GraphDef . Esse intervalo será constante nas versões de patch e aumentará apenas nas versões secundárias. A GraphDef suporte para uma versão do GraphDef ocorrerá apenas para uma versão principal do TensorFlow (e apenas alinhada com o suporte de versão garantido para SavedModels).

  • Os gráficos recém-criados recebem o número da versão GraphDef mais recente.

  • Se uma determinada versão do TensorFlow for compatível com a versão GraphDef de um gráfico, ela será carregada e avaliada com o mesmo comportamento da versão do TensorFlow usada para gerá-lo (exceto para detalhes numéricos de ponto flutuante e números aleatórios, conforme descrito acima), independentemente do principal versão do TensorFlow. Em particular, um GraphDef que é compatível com um arquivo de checkpoint em uma versão do TensorFlow (como é o caso em um SavedModel) permanecerá compatível com esse checkpoint nas versões subsequentes, desde que o GraphDef seja compatível.

    Observe que isso se aplica apenas a Graphs serializados em GraphDefs (e SavedModels): o código que lê um checkpoint pode não ser capaz de ler checkpoints gerados pelo mesmo código executando uma versão diferente do TensorFlow.

  • Se o GraphDef superior GraphDef for aumentado para X em uma versão (menor), haverá pelo menos seis meses antes que o limite inferior seja aumentado para X. Por exemplo (estamos usando números de versão hipotéticos aqui):

    • O TensorFlow 1.2 pode ser compatível com GraphDef versões 4 a 7.
    • O TensorFlow 1.3 pode adicionar o GraphDef versão 8 e oferecer suporte às versões 4 a 8.
    • Pelo menos seis meses depois, o TensorFlow 2.0.0 pode interromper o suporte para as versões 4 a 7, deixando apenas a versão 8.

    Observe que, como as versões principais do TensorFlow geralmente são publicadas com mais de 6 meses de intervalo, as garantias para SavedModels compatíveis detalhadas acima são muito mais fortes do que a garantia de 6 meses para GraphDefs.

Finalmente, quando o suporte para uma versão do GraphDef for abandonado, tentaremos fornecer ferramentas para converter automaticamente os gráficos para uma versão mais recente do GraphDef compatível.

Gráfico e compatibilidade de pontos de verificação ao estender o TensorFlow

Esta seção é relevante apenas ao fazer alterações incompatíveis no formato GraphDef , como ao adicionar ops, remover ops ou alterar a funcionalidade de ops existentes. A seção anterior deve ser suficiente para a maioria dos usuários.

Compatibilidade com versões anteriores e parciais

Nosso esquema de controle de versão tem três requisitos:

  • Compatibilidade com versões anteriores para suportar o carregamento de gráficos e pontos de verificação criados com versões anteriores do TensorFlow.
  • Compatibilidade de encaminhamento para suportar cenários em que o produtor de um gráfico ou ponto de verificação é atualizado para uma versão mais recente do TensorFlow antes do consumidor.
  • Ative o TensorFlow em evolução de maneiras incompatíveis. Por exemplo, removendo ops, adicionando atributos e removendo atributos.

Observe que, embora o mecanismo de versão do GraphDef seja separado da versão do TensorFlow, as alterações incompatíveis com GraphDef formato GraphDef ainda são restritas pelo controle de versão semântica. Isso significa que a funcionalidade só pode ser removida ou alterada entre as versões MAJOR do TensorFlow (como 1.7 a 2.0 ). Além disso, a compatibilidade com versões futuras é aplicada nas versões de patch ( 1.x.1 a 1.x.2 por exemplo).

Para obter compatibilidade com versões anteriores e futuras e saber quando forçar mudanças nos formatos, os gráficos e os pontos de verificação têm metadados que descrevem quando foram produzidos. As seções abaixo detalham a implementação do TensorFlow e as diretrizes para a evolução GraphDef versões do GraphDef .

Esquemas de versão de dados independentes

Existem diferentes versões de dados para gráficos e pontos de verificação. Os dois formatos de dados evoluem em taxas diferentes um do outro e também em taxas diferentes do TensorFlow. Ambos os sistemas de versão são definidos em core/public/version.h . Sempre que uma nova versão é adicionada, uma nota é adicionada ao cabeçalho detalhando o que mudou e a data.

Dados, produtores e consumidores

Nós distinguimos entre os seguintes tipos de informações de versão de dados:

  • produtores : binários que produzem dados. Os produtores têm uma versão ( producer ) e uma versão mínima do consumidor com a qual são compatíveis ( min_consumer ).
  • consumidores : binários que consomem dados. Os consumidores têm uma versão ( consumer ) e uma versão mínima do produtor com a qual são compatíveis ( min_producer ).

Cada parte dos dados com versão tem um campo de VersionDef versions que registra o producer que criou os dados, o min_consumer qual é compatível e uma lista de versões de bad_consumers que não são permitidas.

Por padrão, quando um produtor min_consumer alguns dados, os dados herdam as versões do producer e min_consumer do producer . bad_consumers pode ser definido se versões específicas do consumidor forem conhecidas por conter bugs e devem ser evitadas. Um consumidor pode aceitar um dado se o seguinte for verdadeiro:

  • consumer > = min_consumer de dados
  • producer de dados> = min_producer do consumidor
  • consumer não está em bad_consumers de dados

Como produtores e consumidores vêm da mesma base de código do TensorFlow, core/public/version.h contém uma versão de dados principal que é tratada como producer ou consumer dependendo do contexto e de min_consumer e min_producer (necessários para produtores e consumidores, respectivamente) . Especificamente,

  • Para GraphDef versões do GraphDef , temos TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER e TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Para versões de checkpoint, temos TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER e TF_CHECKPOINT_VERSION_MIN_PRODUCER .

Adicionar um novo atributo com padrão para uma operação existente

Seguir as orientações abaixo fornece compatibilidade com versões futuras apenas se o conjunto de operações não mudou:

  1. Se a compatibilidade para a frente é desejado, definir strip_default_attrs para True durante a exportação do modelo usando o tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables e tf.saved_model.SavedModelBuilder.add_meta_graph métodos da SavedModelBuilder classe, ou tf.estimator.Estimator.export_saved_model
  2. Isso remove os atributos de valor padrão no momento da produção / exportação dos modelos. Isso garante que o tf.MetaGraphDef exportado não contenha o novo atributo op quando o valor padrão for usado.
  3. Ter esse controle pode permitir que os consumidores desatualizados (por exemplo, binários de veiculação que ficam atrás dos binários de treinamento) continuem carregando os modelos e evitem interrupções na veiculação de modelos.

Versões evolutivas do GraphDef

Esta seção explica como usar este mecanismo de controle de versão para fazer diferentes tipos de alterações no formato GraphDef .

Adicionar uma operação

Adicione a nova op para consumidores e produtores ao mesmo tempo e não altere nenhuma versão do GraphDef . Este tipo de mudança é automaticamente compatível com versões anteriores e não afeta o plano de compatibilidade futura, uma vez que os scripts de produtor existentes não usarão repentinamente a nova funcionalidade.

Adicione um op e troque os wrappers Python existentes para usá-lo

  1. Implementar novas funcionalidades de consumidor e incrementar a versão GraphDef .
  2. Se for possível fazer com que os wrappers utilizem a nova funcionalidade apenas em casos que não funcionavam antes, os wrappers podem ser atualizados agora.
  3. Altere os wrappers Python para usar a nova funcionalidade. Não incremente min_consumer , pois os modelos que não usam esta op não devem quebrar.

Remover ou restringir a funcionalidade de uma operação

  1. Corrija todos os scripts do produtor (não o próprio TensorFlow) para não usar a operação ou funcionalidade banida.
  2. GraphDef versão do GraphDef e implemente a nova funcionalidade do consumidor que proíbe a operação ou funcionalidade removida para GraphDefs na nova versão e acima. Se possível, faça o TensorFlow parar de produzir GraphDefs com a funcionalidade banida. Para fazer isso, adicione o REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Aguarde uma versão principal para fins de compatibilidade com versões anteriores.
  4. Aumente min_producer para a versão GraphDef de (2) e remova a funcionalidade completamente.

Alterar a funcionalidade de uma operação

  1. Adicione um novo op semelhante chamado SomethingV2 ou semelhante e passe pelo processo de adicioná-lo e alternar os wrappers Python existentes para usá-lo. Para garantir a compatibilidade com versões futuras, use as verificações sugeridas em compat.py ao alterar os wrappers Python.
  2. Remova o op antigo (só pode ocorrer com uma alteração importante da versão devido à compatibilidade com versões anteriores).
  3. Aumente min_consumer para descartar consumidores com o op antigo, adicione de volta o op antigo como um alias para SomethingV2 e passe pelo processo para trocar os wrappers Python existentes para usá-lo.
  4. Siga o processo para remover o SomethingV2 .

Proibir uma única versão não segura para o consumidor

  1. GraphDef versão GraphDef e adicione a versão bad_consumers a bad_consumers para todos os novos GraphDefs. Se possível, adicione a bad_consumers apenas para GraphDefs que contenham uma determinada op ou semelhante.
  2. Se os consumidores existentes tiverem a versão ruim, tire-os o mais rápido possível.