O Google I/O é um embrulho! Fique por dentro das sessões do TensorFlow Ver sessões

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

TensorFlow segue Semântica Versioning 2,0 ( semver ) para a sua API pública. Cada versão de lançamento do TensorFlow tem a forma 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. Mudanças a cada número têm o seguinte significado:

  • MAJOR: Potencialmente mudanças para trás incompatíveis. 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 migráveis ​​para a versão mais recente; veja Compatibilidade de gráficos e postos de controle para obter detalhes sobre a compatibilidade dos dados.

  • Menor: Para trás funções compatíveis, melhorias de velocidade, etc. Código e dados que trabalharam com uma versão secundária anterior e que depende apenas da API pública não-experimental vai continuar a trabalhar inalterado. Para mais detalhes sobre o que é e não é a API pública, consulte O que é coberto .

  • PATCH: correções de bugs para trás compatível.

Por exemplo, a libertação 1.0.0 introduzidas alterações para trás incompatíveis de libertação 0.12.1. No entanto, a liberação 1.1.1 foi compatível com 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

  • Todos os documentados Python funções e classes no tensorflow módulo e seus submódulos, exceto para

    • Símbolos particulares: qualquer função, classe, etc., cujo nome comece com _
    • Experimental e tf.contrib símbolos, ver abaixo para mais detalhes.

    Note que o código nos examples/ e tools/ diretórios não está acessível através do tensorflow módulo Python e, portanto, não é coberto pela garantia de compatibilidade.

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

  • A API compatibilidade (no pitão, a tf.compat módulo). 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.

  • O API C .

  • Os seguintes arquivos de buffer de protocolo:

O que não é 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, nós isentar alguns símbolos da API claramente marcados como experimental das garantias de compatibilidade. Em particular, os itens a seguir não são cobertos por nenhuma garantia de compatibilidade:

    • qualquer símbolo no tf.contrib módulo 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. Isto inclui campos e submessages de qualquer tampão chamado protocolo experimental .
  • Outros idiomas: APIs TensorFlow em outros do que Python e C linguagens, como:

  • Detalhes de ops compostas: Muitas funções públicas em Python expandir para várias ops primitivas no gráfico, e esses detalhes vão fazer parte de quaisquer gráficos salvos no 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 serão interrompidos em versões menores, embora o comportamento do gráfico deva ser o mesmo e os pontos de verificação existentes ainda funcionem.

  • Floating Point detalhes numéricos: Os valores de ponto flutuante específicos calculados pela ops podem mudar a qualquer momento. Os usuários devem confiar apenas na precisão aproximada e 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 todo o sistema.

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

  • Versão enviesar em distribuída Tensorflow: Executar duas versões diferentes do TensorFlow em um único cluster não é suportado. Não há garantias sobre a compatibilidade com versões anteriores do protocolo de conexão.

  • Bugs: Reservamo-nos o direito de fazer comportamento trás incompatíveis (embora não API) muda se a implementação atual é claramente quebrado, isto é, se ela contradiz a documentação ou se um bem conhecido e comportamento pretendido bem definida não for devidamente implementada 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 utilizados: Reservamo-nos o direito de fazer alterações para trás incompatíveis a APIs para o qual não encontramos usos documentados (através da realização de auditoria de uso TensorFlow através de pesquisa GitHub). Antes de fazer tais alterações, vamos anunciar nossa intenção de fazer a mudança na lista de discussão anunciar @ , fornecendo instruções sobre como abordar quaisquer quebras (se aplicável), e esperar por duas semanas para dar nossa comunidade a oportunidade de compartilhar seus comentários .

  • Comportamento de erro: Podemos substituir erros com comportamento não-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 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 conter duas partes: uma ou mais gráficos codificados como GraphDefs e um ponto de verificação. 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 semver , SavedModels escritas com uma versão de TensorFlow pode ser carregado e avaliada com uma versão posterior do TensorFlow com a mesma versão principal.

Nós fazemos garantias adicionais para SavedModels suportados. Chamamos um SavedModel que foi criada utilizando apenas, não experimental, APIs não-compatibilidade no TensorFlow versão não preterido grande N um SavedModel suportado na versão N . Qualquer SavedModel suportado em TensorFlow versão principal N pode ser carregado e executado com grande TensorFlow versão N+1 . No entanto, a funcionalidade necessária para construir ou modificar tal modelo pode não estar mais disponível, portanto, esta garantia se aplica apenas 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 em série através do GraphDef tampão protocolo. Para facilitar as mudanças para trás incompatíveis para gráficos, cada GraphDef tem um número de versão separada da versão TensorFlow. Por exemplo, GraphDef versão 17 obsoleto o inv op em favor da reciprocal . A semântica é:

  • Cada versão do TensorFlow suporta um intervalo de GraphDef versões. Esse intervalo será constante nas versões de patch e aumentará apenas nas versões secundárias. Remoção do suporte para um GraphDef versão só ocorrerá para uma maior libertação de TensorFlow (e apenas alinhada com o apoio versão garantida para SavedModels).

  • Gráficos recém-criados são atribuídos a mais recente GraphDef número da versão.

  • Se uma determinada versão de TensorFlow suporta o GraphDef versão de um gráfico, que irá carregar e avaliar com o mesmo comportamento que a versão TensorFlow utilizados para gerá-lo (excepto para flutuante detalhes do ponto numérico e números aleatórios, conforme descrito acima), independentemente da grande versão do TensorFlow. Em particular, um GraphDef que é compatível com um arquivo de ponto de verificação em uma versão do TensorFlow (como é o caso em um SavedModel) permanecerá compatível com esse ponto de verificação nas versões subsequentes, desde que o GraphDef seja compatível.

    Note que isso se aplica apenas aos gráficos serializados em GraphDefs (e SavedModels): Código que lê um posto de controle pode não ser capaz de ler checkpoints gerados pelo mesmo código executando uma versão diferente do TensorFlow.

  • Se o GraphDef limite superior é aumentada para X em um (menor) de lançamento, haverá, pelo menos, seis meses antes do limite inferior é aumentada para X. Por exemplo (estamos usando números de versão hipotéticos aqui):

    • TensorFlow 1.2 pode apoiar GraphDef versões 4-7.
    • TensorFlow 1.3 poderia adicionar GraphDef versão 8 e suporte versões 4-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 principais versões 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 um GraphDef versão cair, vamos tentar fornecer ferramentas para converter automaticamente gráficos para a mais recente suportado GraphDef versão.

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

Esta secção é relevante apenas quando fazendo alterações incompatíveis para a GraphDef formato, tal como quando a adição de OPS, removendo OPS, ou alterando 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 gráficos e postos de controle de carga criados com versões mais antigas do TensorFlow.
  • Compatibilidade para a frente a cenários de suporte, onde o produtor de um gráfico ou ponto de verificação é atualizado para uma versão mais recente do TensorFlow antes de o consumidor.
  • Ative o TensorFlow em evolução de maneiras incompatíveis. Por exemplo, remover operações, adicionar atributos e remover atributos.

Note-se que enquanto o GraphDef mecanismo versão é separado a partir da versão TensorFlow, alterações para trás incompatíveis para a GraphDef formato são ainda restringido por semântica de versão. Esta funcionalidade meios só pode ser removida ou mudado entre MAJOR versões de TensorFlow (tal como 1.7 para 2.0 ). Além disso, a compatibilidade é imposta para a frente dentro de lança patch ( 1.x.1 para 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 pontos de verificação têm metadados que descrevem quando foram produzidos. As seções abaixo detalham a implementação TensorFlow e diretrizes para a evolução GraphDef versões.

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 controle de versão são definidos no 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 de que eles são compatíveis com ( min_consumer ).
  • consumidores: binários que consomem dados. Os consumidores têm uma versão ( consumer ) e uma versão produtor mínimo que eles são compatíveis com ( min_producer ).

Cada pedaço de dados sob controle de versão tem um VersionDef versions campo que registra o producer que fez a dados, o min_consumer que é compatível com, e uma lista de bad_consumers versões que não são permitidos.

Por padrão, quando um produtor faz alguns dados, os dados herda do produtor producer e min_consumer versões. bad_consumers pode ser definido se versões específicas de consumo são conhecidos por conterem erros e deve ser evitado. Um consumidor pode aceitar um dado se o seguinte for verdadeiro:

  • consumer > = dos dados min_consumer
  • de dados producer > = consumidor min_producer
  • consumer não no dos dados bad_consumers

Uma vez que ambos os produtores e consumidores vêm da mesma base de código TensorFlow, core/public/version.h contém uma versão de dados principal, que é tratado como qualquer producer ou consumer dependendo do contexto e ambos min_consumer e min_producer (necessária aos produtores e consumidores, respectivamente) . Especificamente,

  • Para GraphDef versões, 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 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 exportado tf.MetaGraphDef não contém o novo op-atributo quando o valor padrão é 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 ao GraphDef formato.

Adicionar uma operação

Adicione o novo op para os consumidores e produtores, ao mesmo tempo, e não alterar qualquer GraphDef versões. 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 do consumidor e incrementar o GraphDef versão.
  2. Se for possível fazer com que os invólucros utilizem a nova funcionalidade apenas em casos que não funcionavam antes, os invólucros podem ser atualizados agora.
  3. Altere os wrappers Python para usar a nova funcionalidade. Não incremento min_consumer , desde modelos que não utilizam esta op não deve quebrar.

Remover ou restringir a funcionalidade de uma operação

  1. Corrija todos os scripts do produtor (não o TensorFlow em si) para não usar a operação ou funcionalidade banida.
  2. Incrementar o GraphDef versão e implementar novas funcionalidades do consumidor que proíbe a op removido ou funcionalidade para GraphDefs na nova versão e acima. Se possível, faça TensorFlow produzir parada GraphDefs com a funcionalidade banido. 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. Aumentar min_producer para a versão GraphDef a partir de (2) e remover a funcionalidade inteiramente.

Alterar a funcionalidade de uma operação

  1. Adicionar um novo op semelhante chamado SomethingV2 ou similar e passar pelo processo de adicionar-lo e mudar wrappers Python existentes para usá-lo. Para garantir o uso compatibilidade para a frente as verificações sugeridas em compat.py quando mudar os invólucros Python.
  2. Remova o op antigo (só pode ocorrer com uma alteração importante da versão devido à compatibilidade com versões anteriores).
  3. Aumentar min_consumer para afastar os consumidores com o velho op, adicionar novamente o velho op como um alias para SomethingV2 , e passar pelo processo de mudar wrappers Python existentes para usá-lo.
  4. Passar pelo processo para remover SomethingV2 .

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

  1. Colisão do GraphDef versão e adicione a versão ruim de bad_consumers para todos os novos GraphDefs. Se possível, adicione a bad_consumers apenas para GraphDefs que contêm uma certa op ou similar.
  2. Se os consumidores existentes tiverem a versão ruim, elimine-os o mais rápido possível.