Compatibilità della versione di TensorFlow

Questo documento è per gli utenti che necessitano della retrocompatibilità tra diverse versioni di TensorFlow (per codice o dati) e per gli sviluppatori che desiderano modificare TensorFlow preservando la compatibilità.

Versionamento semantico 2.0

Tensorflow segue Semantic Versioning 2.0 ( semver ) per la sua API pubblica. Ogni versione di tensorflow ha la forma MAJOR.MINOR.PATCH . Ad esempio, tensorflow versione 1.2.3 ha MAJOR versione 1, MINOR versione 2, e PATCH versione 3. Modifiche a ogni numero hanno il seguente significato:

  • MAGGIORE: potenzialmente modifiche all'indietro incompatibili. Il codice e i dati che funzionavano con una versione principale precedente non funzioneranno necessariamente con la nuova versione. Tuttavia, in alcuni casi i grafici e i checkpoint TensorFlow esistenti potrebbero essere migrabili alla versione più recente; vedere Compatibilità grafici e punti di controllo per dettagli sulla compatibilità dei dati.

  • MINOR: all'indietro funzioni compatibili, miglioramenti di velocità, ecc codice ei dati che hanno lavorato con una versione precedente minore e che dipende solo dalla API pubblica non sperimentale continuerà a lavorare invariato. Per i dettagli su ciò che è e non è l'API pubbliche, vedere cosa è coperto .

  • PATCH: correzioni di bug Compatibile all'indietro.

Ad esempio, il rilascio 1.0.0 ha introdotto modifiche all'indietro incompatibili dal rilascio 0.12.1. Tuttavia, il rilascio 1.1.1 è compatibile con la versione 1.0.0.

Cosa è coperto

Solo le API pubbliche di TensorFlow sono retrocompatibili nelle versioni minori e patch. Le API pubbliche sono costituite da

  • Tutte le documentati Python funzioni e le classi nel tensorflow modulo e dei relativi moduli, eccetto per

    • Simboli privati: ogni funzione, di classe, ecc, il cui nome iniziare con _
    • Sperimentale e tf.contrib simboli, vedi sotto per i dettagli.

    Si noti che il codice negli examples/ e tools/ directory non è raggiungibile attraverso il tensorflow modulo Python e non è quindi coperto dalla garanzia compatibilità.

    Se un simbolo è disponibile attraverso il tensorflow modulo Python o dei suoi moduli, ma non è documentato, allora non è considerata parte della API pubblica.

  • L'API compatibilità (in Python, il tf.compat modulo). Nelle versioni principali, potremmo rilasciare utilità ed endpoint aggiuntivi per aiutare gli utenti nella transizione a una nuova versione principale. Questi simboli API sono deprecati e non supportati (cioè, non aggiungeremo alcuna funzionalità e non correggeremo bug se non per correggere vulnerabilità), ma rientrano nelle nostre garanzie di compatibilità.

  • Il C API .

  • I seguenti file di buffer di protocollo:

Ciò che non è coperto

Alcune parti di TensorFlow possono cambiare in modi incompatibili con le versioni precedenti in qualsiasi momento. Questi includono:

  • API sperimentali: Per facilitare lo sviluppo, abbiamo esentare alcuni simboli API chiaramente contrassegnati come sperimentale garanzie di compatibilità. In particolare, non sono coperti da alcuna garanzia di compatibilità:

    • qualsiasi simbolo nel tf.contrib modulo o dei suoi sottomoduli;
    • qualsiasi simbolo (modulo, funzione, argomento, struttura, classe, o costante) il cui nome contiene experimental o Experimental ; o
    • qualsiasi simbolo il cui nome completo include un modulo o una classe che è di per sé sperimentale. Questo include campi e sottomessaggi di qualsiasi tampone protocollo chiamato experimental .

  • Altre lingue: API tensorflow in lingue diverse Python e C, come ad esempio:

  • Dettagli della OPS compositi: Molte funzioni pubbliche in Python espandono per più OP primitive nel grafico, e questi dettagli saranno parte di qualsiasi grafico salvati su disco come GraphDef s. Questi dettagli possono cambiare per le versioni minori. In particolare, è probabile che i test di regressione che verificano la corrispondenza esatta tra i grafici si rompano in versioni minori, anche se il comportamento del grafico dovrebbe essere invariato e i checkpoint esistenti continueranno a funzionare.

  • Floating point dettagli numerici: I valori in virgola mobile specifici calcolati da op può cambiare in qualsiasi momento. Gli utenti dovrebbero fare affidamento solo sulla precisione approssimativa e sulla stabilità numerica, non sui bit specifici calcolati. Le modifiche alle formule numeriche nelle versioni minori e di patch dovrebbero comportare una precisione comparabile o migliorata, con l'avvertenza che nell'apprendimento automatico una maggiore precisione di formule specifiche può comportare una minore precisione per il sistema complessivo.

  • Numeri casuali: i numeri casuali specifici calcolati possono cambiare in qualsiasi momento. Gli utenti dovrebbero fare affidamento solo su distribuzioni e forza statistica approssimativamente corrette, non sui bit specifici calcolati. Vedere la generazione di numeri casuali guida per i dettagli.

  • Versione inclinare in distribuita tensorflow: Esecuzione di due versioni differenti di tensorflow in un unico cluster non è supportato. Non ci sono garanzie sulla retrocompatibilità del protocollo wire.

  • Bugs: Ci riserviamo il diritto di apportare comportamento all'indietro incompatibili (anche se non API) cambia se l'implementazione attuale è chiaramente rotto, che è, se contraddice la documentazione o se un noto e comportamento previsto ben definito non è correttamente implementato a causa a un bug. Ad esempio, se un ottimizzatore afferma di implementare un algoritmo di ottimizzazione noto ma non corrisponde a tale algoritmo a causa di un bug, allora ripareremo l'ottimizzatore. La nostra correzione potrebbe interrompere il codice basandosi sul comportamento sbagliato per la convergenza. Annoteremo tali modifiche nelle note di rilascio.

  • API non utilizzato: Ci riserviamo il diritto di apportare modifiche a ritroso incompatibili alle API per i quali non troviamo usi documentati (eseguendo controllo di utilizzo tensorflow tramite GitHub di ricerca). Prima di effettuare tali modifiche, noi annunciare la nostra intenzione di rendere la modifica sul annunciare @ mailing list , con le istruzioni per come affrontare eventuali rotture (se applicabile), e attendere due settimane per dare alla nostra comunità la possibilità di condividere il loro feedback .

  • Il comportamento di errore: Si può sostituire gli errori con un comportamento non-errore. Ad esempio, possiamo modificare una funzione per calcolare un risultato invece di generare un errore, anche se tale errore è documentato. Ci riserviamo inoltre il diritto di modificare il testo dei messaggi di errore. Inoltre, il tipo di un errore può cambiare a meno che il tipo di eccezione per una specifica condizione di errore non sia specificato nella documentazione.

Compatibilità di SavedModels, grafici e checkpoint

SavedModel è il formato di serializzazione preferito da utilizzare nei programmi TensorFlow. SavedModels contengono due parti: una o più grafici codificati come GraphDefs e un punto di controllo. I grafici descrivono il flusso di dati delle operazioni da eseguire e i checkpoint contengono i valori di tensore salvati delle variabili in un grafico.

Molti utenti di TensorFlow creano modelli salvati e li caricano ed eseguono con una versione successiva di TensorFlow. In conformità a semver , SavedModels scritti con una versione di tensorflow possono essere caricati e valutati con una versione successiva di tensorflow con la stessa major release.

Facciamo garanzie supplementari per SavedModels supportati. Chiamiamo un SavedModel che è stato creato utilizzando solo non obsoleto, non sperimentale, API non compatibilità in tensorflow versione principale N un SavedModel supportata nella versione N . Qualsiasi SavedModel supportato in tensorflow versione principale N può essere caricato ed eseguito con tensorflow importante versione N+1 . Tuttavia, la funzionalità richiesta per creare o modificare tale modello potrebbe non essere più disponibile, quindi questa garanzia si applica solo al modello salvato non modificato.

Cercheremo di preservare la compatibilità con le versioni precedenti il ​​più a lungo possibile, in modo che i file serializzati siano utilizzabili per lunghi periodi di tempo.

Compatibilità GraphDef

Grafici vengono serializzati tramite il GraphDef buffer del protocollo. Per facilitare modifiche all'indietro incompatibili ai grafici, ogni GraphDef ha un numero di versione separata dalla versione tensorflow. Ad esempio, GraphDef versione 17 deprecato l' inv op a favore della reciprocal . La semantica è:

  • Ogni versione di tensorflow supporta un intervallo di GraphDef versioni. Questo intervallo sarà costante tra le versioni delle patch e aumenterà solo tra le versioni minori. Rimozione del supporto per un GraphDef versione sarà occur solo per un release di tensorflow (e solo aligned con il supporto della versione garantito per SavedModels).

  • Grafici appena creati vengono assegnati l'ultima GraphDef numero di versione.

  • Se una data versione di tensorflow sostiene la GraphDef versione di un grafico, caricherà e valutare con lo stesso comportamento della versione tensorflow usato per generare (eccetto per floating point numerica dettagli e numeri casuali come descritto sopra), indipendentemente dalla maggiore versione di TensorFlow. In particolare, un GraphDef che è compatibile con un file di checkpoint in una versione di TensorFlow (come nel caso di un SavedModel) rimarrà compatibile con quel checkpoint nelle versioni successive, purché GraphDef sia supportato.

    Si noti che questo vale solo per i grafici serializzati in GraphDefs (e SavedModels): codice che legge un checkpoint potrebbe non essere in grado di leggere i punti di controllo generati dallo stesso codice in esecuzione una versione diversa di tensorflow.

  • Se il GraphDef limite superiore è aumentato a X in un rilascio (minore), ci saranno almeno sei mesi prima che il limite inferiore è aumentato a X. Per esempio (stiamo usando ipotetici numeri di versione qui):

    • Tensorflow 1.2 potrebbe supportare GraphDef versioni da 4 a 7.
    • Tensorflow 1.3 potrebbe aggiungere GraphDef versione 8 e supporta le versioni da 4 a 8.
    • Almeno sei mesi dopo, TensorFlow 2.0.0 potrebbe abbandonare il supporto per le versioni dalla 4 alla 7, lasciando solo la versione 8.

    Si noti che poiché le versioni principali di TensorFlow vengono generalmente pubblicate a più di 6 mesi di distanza, le garanzie per i SavedModel supportati descritte sopra sono molto più forti della garanzia di 6 mesi per GraphDefs.

Infine, quando il supporto per una GraphDef versione è caduto, si cercherà di fornire strumenti per la conversione automaticamente grafici per una più recente supportato GraphDef versione.

Compatibilità di grafici e checkpoint durante l'estensione di TensorFlow

Questa sezione è rilevante solo quando si apportano modifiche incompatibili al GraphDef formato, ad esempio quando si aggiungono ops, rimuovendo ops, o cambiare la funzionalità di OPS esistenti. La sezione precedente dovrebbe essere sufficiente per la maggior parte degli utenti.

Compatibilità all'indietro e parziale in avanti

Il nostro schema di versionamento ha tre requisiti:

  • Backward compatibilità per supportare i grafici di carico e posti di blocco creato con versioni precedenti di tensorflow.
  • Compatibilità in avanti per scenari di supporto in cui il produttore di un grafico o di checkpoint viene aggiornato a una nuova versione di tensorflow prima che il consumatore.
  • Abilita TensorFlow in evoluzione in modi incompatibili. Ad esempio, rimozione di operazioni, aggiunta di attributi e rimozione di attributi.

Si noti che mentre la GraphDef meccanismo di versione è separata dalla versione tensorflow, modifiche all'indietro incompatibili al GraphDef formato sono ancora limitati da Semantic Versioning. Questa funzionalità mezzi può essere rimosso o modificato soltanto tra MAJOR versioni tensorflow (ad esempio 1.7 a 2.0 ). Inoltre, la compatibilità in avanti viene applicato all'interno di rilasci di patch ( 1.x.1 per 1.x.2 per esempio).

Per ottenere la compatibilità con le versioni precedenti e successive e per sapere quando applicare modifiche ai formati, i grafici e i checkpoint hanno metadati che descrivono quando sono stati prodotti. Le sezioni che seguono dettaglio l'attuazione tensorflow e linee guida per evoluzione GraphDef versioni.

Schemi di versione dati indipendenti

Esistono diverse versioni di dati per grafici e checkpoint. I due formati di dati si evolvono a velocità diverse l'una dall'altra e anche a velocità diverse da TensorFlow. Entrambi i sistemi di versioning sono definiti nel core/public/version.h . Ogni volta che viene aggiunta una nuova versione, viene aggiunta una nota all'intestazione con i dettagli su cosa è cambiato e la data.

Dati, produttori e consumatori

Distinguiamo tra i seguenti tipi di informazioni sulla versione dei dati:

  • produttori: i binari che producono dati. I produttori hanno una versione ( producer ) e una versione minima di consumo che siano compatibili con ( min_consumer ).
  • consumatori: binari che utilizzano i dati. I consumatori hanno una versione ( consumer ) e una versione minima produttore che siano compatibili con la ( min_producer ).

Ogni pezzo di dati versionati ha un VersionDef versions settore che registra il producer che ha reso i dati, l' min_consumer che sia compatibile con, e un elenco di bad_consumers versioni che vengono annullato.

Per impostazione predefinita, quando un produttore fa alcuni dati, i dati eredita del produttore producer e min_consumer versioni. bad_consumers possono essere impostati se le versioni specifiche di consumatori sono noti per contenere bug e devono essere evitati. Un consumatore può accettare un dato se le seguenti condizioni sono tutte vere:

  • consumer > = di dati min_consumer
  • di dati producer > = consumatore min_producer
  • consumer non in di Data bad_consumers

Poiché i produttori ei consumatori vengono dalla stessa base di codice tensorflow, core/public/version.h contiene una versione di dati principale che è considerato sia producer o consumer seconda del contesto ed entrambi min_consumer e min_producer (necessaria ai produttori e consumatori, rispettivamente) . Nello specifico,

  • Per GraphDef versioni, abbiamo TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER e TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Per le versioni checkpoint, abbiamo TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER e TF_CHECKPOINT_VERSION_MIN_PRODUCER .

Aggiungi un nuovo attributo di default a un'operazione esistente

Seguendo la guida di seguito si ottiene la compatibilità in avanti solo se il set di operazioni non è cambiato:

  1. Se compatibilità avanti si desidera, impostare strip_default_attrs a True durante l'esportazione del modello utilizzando i tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables e tf.saved_model.SavedModelBuilder.add_meta_graph metodi della SavedModelBuilder classe, o tf.estimator.Estimator.export_saved_model
  2. Questo elimina gli attributi di valore di default al momento della produzione/esportazione dei modelli. Questo fa in modo che la esportato tf.MetaGraphDef non contiene il nuovo op-attributo quando viene utilizzato il valore predefinito.
  3. Avere questo controllo potrebbe consentire ai consumatori obsoleti (ad esempio, che servono file binari in ritardo rispetto ai file binari di addestramento) di continuare a caricare i modelli e prevenire interruzioni nella gestione dei modelli.

Versioni GraphDef in evoluzione

Questa sezione spiega come utilizzare questo meccanismo di controllo delle versioni per fare diversi tipi di modifiche al GraphDef formato.

Aggiungi un'operazione

Aggiungere il nuovo op sia per i consumatori e produttori allo stesso tempo, e non modificare le GraphDef versioni. Questo tipo di modifica è automaticamente compatibile con le versioni precedenti e non influisce sul piano di compatibilità in avanti poiché gli script producer esistenti non utilizzeranno improvvisamente la nuova funzionalità.

Aggiungi un'operazione e cambia i wrapper Python esistenti per usarlo

  1. Implementare nuove funzionalità dei consumatori e incrementare il GraphDef versione.
  2. Se è possibile fare in modo che i wrapper utilizzino la nuova funzionalità solo nei casi che prima non funzionavano, i wrapper possono essere aggiornati ora.
  3. Modifica i wrapper Python per utilizzare la nuova funzionalità. Non incremento min_consumer , poiché i modelli che non utilizzano questa op non dovrebbe rompersi.

Rimuovere o limitare la funzionalità di un'operazione

  1. Correggi tutti gli script del produttore (non TensorFlow stesso) per non utilizzare l'operazione o la funzionalità vietata.
  2. Incrementare la GraphDef versione ed implementare nuove funzionalità di consumo che i divieti op rimosso o funzionalità per GraphDefs alla nuova versione e sopra. Se possibile, fare tensorflow smettono di produrre GraphDefs con la funzionalità vietato. Per fare ciò, aggiungere il REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Attendi una versione principale per motivi di compatibilità con le versioni precedenti.
  4. Aumentare min_producer alla versione GraphDef da (2) e rimuovere la funzionalità del tutto.

Modificare la funzionalità di un'operazione

  1. Aggiungere un nuovo op simile chiamato SomethingV2 o simili e passare attraverso il processo di aggiunta e il passaggio wrapper Python esistenti per usarlo. Per garantire un utilizzo compatibilità in avanti i controlli suggeriti in compat.py quando si cambiano i wrapper Python.
  2. Rimuovere la vecchia operazione (può avvenire solo con una modifica importante della versione a causa della compatibilità con le versioni precedenti).
  3. Aumentare min_consumer per escludere i consumatori con il vecchio op, aggiungere di nuovo il vecchio op come alias per SomethingV2 , e passare attraverso il processo di passare wrapper Python esistenti per usarlo.
  4. Passare attraverso il processo per rimuovere SomethingV2 .

Bandire una singola versione consumer non sicura

  1. Bump la GraphDef versione e aggiungere la versione cattiva per bad_consumers per tutti i nuovi GraphDefs. Se possibile, aggiungere alla bad_consumers solo per GraphDefs che contengono un certo op o simili.
  2. Se i consumatori esistenti hanno la versione non valida, eliminali il prima possibile.