Compatibilidade de versão do TensorFlow

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Este documento é para usuários que precisam de compatibilidade com versões anteriores em diferentes versões do TensorFlow (seja para código ou dados) e para desenvolvedores que desejam modificar o TensorFlow preservando 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, 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:

  • PRINCIPAL : Alterações potencialmente incompatíveis com versões anteriores. O código e os dados que funcionaram 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 migráveis ​​para a versão mais recente; consulte Compatibilidade de gráficos e pontos de verificação para obter detalhes sobre compatibilidade de dados.

  • MINOR : 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 é coberto .

  • 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

Somente as APIs públicas do TensorFlow são compatíveis com as versões secundárias 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 estiver disponível por meio do módulo tensorflow do Python ou de seus submódulos, mas não estiver documentado, ele não será 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 endpoints adicionais para ajudar os usuários na transição para uma nova versão principal. Esses símbolos de API são obsoletos e não têm suporte (ou seja, não adicionaremos nenhum recurso e não corrigiremos bugs além de 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 forma incompatível 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, não estão cobertos 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 contenha 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 chamado experimental .
  • Outras linguagens : APIs do 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 versões menores. Em particular, os testes de regressão que verificam a correspondência exata entre os gráficos provavelmente serão interrompidos em versões menores, mesmo que o comportamento do gráfico deva permanecer inalterado e os pontos de verificação existentes ainda funcionem.

  • Detalhes numéricos de ponto flutuante: os valores específicos de ponto flutuante 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 secundárias e de patch devem resultar em precisão comparável ou aprimorada, com a ressalva de que, no aprendizado de máquina, a precisão aprimorada de fórmulas específicas pode resultar em precisão reduzida 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 computados. Consulte o guia de geração de números aleatórios para obter detalhes.

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

  • Bugs: Reservamo-nos o direito de fazer alterações de comportamento incompatível com versões anteriores (embora não API) se a implementação atual estiver claramente quebrada, ou seja, 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, corrigiremos o otimizador. Nossa correção pode quebrar o código dependendo do comportamento errado para convergência. Observaremos tais mudanças nas notas de lançamento.

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

  • Comportamento de erro: podemos substituir erros por comportamento sem erro. Por exemplo, podemos alterar uma função para calcular um resultado em vez de gerar um erro, mesmo que esse erro esteja documentado. Também nos reservamos o direito de alterar o texto das mensagens de erro. Além disso, o tipo de 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 TensorFlow. SavedModels contém duas partes: um ou mais gráficos codificados como GraphDefs e um ponto de verificação. Os gráficos descrevem o fluxo de dados das operações a serem executadas 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 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 suportados . Chamamos um SavedModel que foi criado usando apenas APIs não obsoletas, não experimentais e não compatíveis na versão principal N do TensorFlow de SavedModel com suporte na versão N . Qualquer SavedModel compatível com o TensorFlow versão principal N pode ser carregado e executado com o TensorFlow versão principal N+1 . No entanto, a funcionalidade necessária para construir ou modificar tal modelo pode não estar mais disponível, então esta garantia só se aplica ao SavedModel não modificado.

Faremos o possível para preservar a compatibilidade com versões anteriores o maior tempo possível, para 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 do 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 preteriu 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 entre os lançamentos de patch e aumentará apenas entre os lançamentos secundários. A eliminação do suporte para uma versão do GraphDef ocorrerá apenas para uma versão principal do TensorFlow (e alinhada apenas com o suporte à versão garantido para SavedModels).

  • Gráficos recém-criados recebem o número de 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 das principais versão do TensorFlow. Em particular, um GraphDef compatível com um arquivo de ponto de verificação em uma versão do TensorFlow (como é o caso de um SavedModel) permanecerá compatível com esse ponto de verificação nas versões subsequentes, desde que o GraphDef seja compatível.

    Observe que isso se aplica apenas a gráficos serializados em GraphDefs (e SavedModels): o código que lê um ponto de verificação pode não ser capaz de ler pontos de verificação gerados pelo mesmo código executando uma versão diferente do TensorFlow.

  • Se o limite superior do GraphDef for aumentado para X em uma versão (secundária), 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 oferecer suporte às versões 4 a 7 do GraphDef .
    • O TensorFlow 1.3 pode adicionar GraphDef versão 8 e oferecer suporte às versões 4 a 8.
    • Pelo menos seis meses depois, o TensorFlow 2.0.0 poderia retirar 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.

Por fim, quando o suporte para uma versão do GraphDef for descartado, tentaremos fornecer ferramentas para converter gráficos automaticamente em uma versão mais recente do GraphDef com suporte.

Compatibilidade de gráficos e 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 versionamento tem três requisitos:

  • Compatibilidade com versões anteriores para oferecer suporte a gráficos de carregamento e pontos de verificação criados com versões mais antigas do TensorFlow.
  • Compatibilidade avançada para oferecer suporte a 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.
  • Habilite a evolução do TensorFlow de maneiras incompatíveis. Por exemplo, remover operações, adicionar atributos e remover atributos.

Observe que, embora o mecanismo de versão do GraphDef seja separado da versão do TensorFlow, as alterações incompatíveis com versões anteriores no formato GraphDef ainda são restritas pelo controle de versão semântico. Isso significa que a funcionalidade só pode ser removida ou alterada entre as MAJOR versões do TensorFlow (como 1.7 a 2.0 ). Além disso, a compatibilidade futura é 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 impor alterações nos formatos, gráficos e 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 das 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 entre si 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

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 versionados tem um campo de VersionDef versions que registra o producer que criou os dados, o min_consumer com o qual é compatível e uma lista de versões de bad_consumers que não são permitidas.

Por padrão, quando um produtor cria alguns dados, os dados herdam as versões producer e min_consumer do produtor. bad_consumers pode ser definido se versões específicas do consumidor contêm 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 min_consumer e min_producer (necessários para produtores e consumidores, respectivamente) . Especificamente,

  • Para versões GraphDef , temos TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER e TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Para versões de ponto de verificação, temos TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER e TF_CHECKPOINT_VERSION_MIN_PRODUCER .

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

Seguir a orientação abaixo oferece compatibilidade futura apenas se o conjunto de operações não tiver sido alterado:

  1. Se a compatibilidade futura for desejada, defina strip_default_attrs como True ao exportar o modelo usando os métodos tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables e tf.saved_model.SavedModelBuilder.add_meta_graph da classe SavedModelBuilder 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 operacional quando o valor padrão for usado.
  3. Ter esse controle pode permitir que os consumidores desatualizados (por exemplo, servindo binários que ficam atrás dos binários de treinamento) continuem carregando os modelos e evitem interrupções no serviço do modelo.

Evolução das versões do GraphDef

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

Adicionar uma operação

Adicione a nova opção para consumidores e produtores ao mesmo tempo e não altere nenhuma versão do GraphDef . Esse tipo de alteração é automaticamente compatível com versões anteriores e não afeta o plano de compatibilidade futura, pois 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. Implemente a nova funcionalidade do consumidor e incremente a versão do GraphDef .
  2. Se for possível fazer com que os wrappers usem a nova funcionalidade apenas em casos que não funcionavam antes, os wrappers podem ser atualizados agora.
  3. Altere os wrappers do Python para usar a nova funcionalidade. Não incremente min_consumer , pois models que não usam esta operação 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. Aumente a versão do GraphDef e implemente a nova funcionalidade do consumidor que bane 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 proibida. 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 totalmente a funcionalidade.

Alterar a funcionalidade de uma operação

  1. Adicione uma nova operação semelhante chamada SomethingV2 ou similar e siga o processo de adicioná-la e alternar os wrappers Python existentes para usá-la. Para garantir a compatibilidade futura, use as verificações sugeridas em compat.py ao alterar os wrappers do Python.
  2. Remova a operação antiga (só pode ocorrer com uma alteração de versão principal devido à compatibilidade com versões anteriores).
  3. Aumente min_consumer para descartar os consumidores com o antigo op, adicione de volta o antigo op como um alias para SomethingV2 e siga o processo para alternar os wrappers existentes do Python para usá-lo.
  4. Siga o processo para remover o SomethingV2 .

Proibir uma única versão insegura para o consumidor

  1. Aumente a versão do GraphDef e adicione a versão ruim a bad_consumers para todos os novos GraphDefs. Se possível, adicione a bad_consumers apenas para GraphDefs que contenham um determinado op ou similar.
  2. Se os consumidores existentes tiverem a versão ruim, elimine-os o mais rápido possível.