Compatibilità della versione di TensorFlow

Questo documento è rivolto agli utenti che necessitano della compatibilità con le versioni precedenti di diverse versioni di TensorFlow (sia per il codice che per i dati) e per gli sviluppatori che desiderano modificare TensorFlow preservando la compatibilità.

Controllo delle versioni semantico 2.0

TensorFlow segue Semantic Versioning 2.0 ( semver ) per la sua API pubblica. Ogni versione di rilascio di TensorFlow ha il formato MAJOR.MINOR.PATCH . Ad esempio, TensorFlow versione 1.2.3 ha la versione MAJOR 1, la versione MINOR 2 e la versione PATCH 3. Le modifiche a ciascun numero hanno il seguente significato:

MAJOR : modifiche potenzialmente incompatibili all'indietro. 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 ei checkpoint TensorFlow esistenti possono essere migrabili alla versione più recente; vedere Compatibilità di grafici e punti di controllo per dettagli sulla compatibilità dei dati.
MINORE : funzionalità retrocompatibili, miglioramenti della velocità, ecc. Il codice e i dati che funzionavano con una versione minore precedente e che dipendono solo dall'API pubblica non sperimentale continueranno a funzionare invariati. Per dettagli su cosa è e cosa non è l'API pubblica, vedere Cosa è coperto .
PATCH : correzioni di bug compatibili con le versioni precedenti.

Ad esempio, la versione 1.0.0 ha introdotto modifiche incompatibili all'indietro dalla versione 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 tra versioni secondarie e patch. Le API pubbliche sono costituite da

Tutte le funzioni e classi Python documentate nel modulo tensorflow e nei suoi sottomoduli, ad eccezione di
- Simboli privati: qualsiasi funzione, classe, ecc., Il cui nome inizia con _
- Simboli sperimentali e tf.contrib , vedi sotto per i dettagli.
Notare che il codice negli examples/ e negli tools/ directory non è raggiungibile tramite il modulo tensorflow Python e quindi non è coperto dalla garanzia di 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 di compatibilità (in Python, il modulo tf.compat ). Nelle versioni principali, potremmo rilasciare utilità ed endpoint aggiuntivi per aiutare gli utenti con il passaggio a una nuova versione principale. Questi simboli API sono deprecati e non supportati (ad esempio, non aggiungeremo alcuna funzionalità e non correggeremo bug oltre a correggere le vulnerabilità), ma rientrano nelle nostre garanzie di compatibilità.
L' API C.
I seguenti file di buffer del protocollo:
- attr_value
- config
- event
- graph
- op_def
- reader_base
- summary
- tensor
- tensor_shape
- types

Cosa non è coperto

Alcune parti di TensorFlow possono cambiare in modi incompatibili all'indietro in qualsiasi momento. Questi includono:

API sperimentali : per facilitare lo sviluppo, esentiamo alcuni simboli API chiaramente contrassegnati come sperimentali dalle garanzie di compatibilità. In particolare, non sono coperti da alcuna garanzia di compatibilità:
- qualsiasi simbolo nel modulo tf.contrib o nei suoi sottomoduli;
- qualsiasi simbolo (modulo, funzione, argomento, proprietà, classe o costante) il cui nome contiene experimental o Experimental ; o
- qualsiasi simbolo il cui nome completo include un modulo o una classe che è a sua volta sperimentale. Ciò include campi e sottomessaggi di qualsiasi buffer di protocollo chiamato experimental .
Altre lingue : API TensorFlow in linguaggi diversi da Python e C, come:
- C ++ (esposto tramite file di intestazione in tensorflow/cc ).
- Java ,
- Partire
- JavaScript
Dettagli delle operazioni composite: molte funzioni pubbliche in Python si espandono a diverse operazioni primitive nel grafo, e questi dettagli faranno parte di qualsiasi grafico salvato su disco come GraphDef . Questi dettagli possono cambiare per le versioni minori. In particolare, è probabile che i test di regressione che controllano la corrispondenza esatta tra i grafici si interrompano tra le versioni minori, anche se il comportamento del grafico dovrebbe essere invariato ei checkpoint esistenti continueranno a funzionare.
Dettagli numerici in virgola mobile: i valori in virgola mobile specifici calcolati dagli operatori possono 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 paragonabile o migliorata, con l'avvertenza che nell'apprendimento automatico una maggiore precisione di formule specifiche può comportare una diminuzione dell'accuratezza per il sistema generale.
Numeri casuali: i numeri casuali specifici calcolati possono cambiare in qualsiasi momento. Gli utenti dovrebbero fare affidamento solo su distribuzioni approssimativamente corrette e forza statistica, non su bit specifici calcolati. Vedere la guida alla generazione di numeri casuali per i dettagli.
Inclinazione della versione in Tensorflow distribuito: l' esecuzione di due diverse versioni di TensorFlow in un singolo cluster non è supportata. Non ci sono garanzie sulla retrocompatibilità del protocollo cablato.
Bug: ci riserviamo il diritto di apportare modifiche al comportamento incompatibile all'indietro (sebbene non all'API) se l'implementazione corrente è chiaramente rotta, cioè se contraddice la documentazione o se un comportamento previsto ben noto e ben definito non è implementato correttamente a causa a un bug. Ad esempio, se un ottimizzatore afferma di implementare un noto algoritmo di ottimizzazione ma non corrisponde a tale algoritmo a causa di un bug, allora correggeremo l'ottimizzatore. La nostra correzione potrebbe interrompere il codice che si basa sul comportamento sbagliato per la convergenza. Noteremo tali modifiche nelle note di rilascio.
API inutilizzate: ci riserviamo il diritto di apportare modifiche incompatibili all'indietro alle API per le quali non troviamo utilizzi documentati (eseguendo il controllo dell'utilizzo di TensorFlow tramite la ricerca GitHub). Prima di apportare tali modifiche, annunceremo la nostra intenzione di apportare la modifica sulla mailing list annunci @ , fornendo istruzioni su come affrontare eventuali rotture (se applicabile) e attendere due settimane per dare alla nostra comunità la possibilità di condividere il proprio feedback .
Comportamento in caso di errore: possiamo sostituire gli errori con un comportamento non di 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 errore può cambiare a meno che il tipo di eccezione per una condizione di errore specifica non sia specificato nella documentazione.

Compatibilità di SavedModels, grafici e checkpoint

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

Molti utenti di TensorFlow creano SavedModels, li caricano ed eseguono con una versione successiva di TensorFlow. In conformità con semver , i SavedModels scritti con una versione di TensorFlow possono essere caricati e valutati con una versione successiva di TensorFlow con la stessa versione principale.

Offriamo garanzie aggiuntive per i SavedModels supportati . Chiamiamo un SavedModel che è stato creato utilizzando solo API non obsolete, non sperimentali e non compatibili nella versione principale di TensorFlow N un SavedModel supportato nella versione N Qualsiasi SavedModel supportato nella versione principale di TensorFlow N può essere caricato ed eseguito con la versione principale di TensorFlow N+1 . Tuttavia, la funzionalità richiesta per costruire o modificare tale modello potrebbe non essere più disponibile, quindi questa garanzia si applica solo al SavedModel non modificato.

Cercheremo di preservare la retrocompatibilità il più a lungo possibile, in modo che i file serializzati siano utilizzabili per lunghi periodi di tempo.

Compatibilità GraphDef

I grafici vengono serializzati tramite il buffer del protocollo GraphDef . Per facilitare le modifiche incompatibili all'indietro ai grafici, ogni GraphDef ha un numero di versione separato dalla versione di TensorFlow. Ad esempio, GraphDef versione 17 deprecato inv op a favore di reciprocal . La semantica sono:

Ogni versione di TensorFlow supporta un intervallo di versioni di GraphDef . Questo intervallo sarà costante tra i rilasci di patch e crescerà solo tra i rilasci minori. L' GraphDef supporto per una versione di GraphDef si verificherà solo per una versione principale di TensorFlow (e sarà allineata solo con il supporto della versione garantito per SavedModels).
Ai grafici appena creati viene assegnato l'ultimo numero di versione di GraphDef .
Se una data versione di TensorFlow supporta la versione GraphDef di un grafico, verrà caricata e valutata con lo stesso comportamento della versione TensorFlow utilizzata per generarlo (ad eccezione dei dettagli numerici in virgola mobile e dei numeri casuali come descritto sopra), indipendentemente dal principale versione di TensorFlow. In particolare, un GraphDef 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, fintanto che GraphDef è supportato.
Tieni presente che questo si applica solo ai grafici serializzati in GraphDefs (e SavedModels): il codice che legge un checkpoint potrebbe non essere in grado di leggere i checkpoint generati dallo stesso codice che esegue una versione diversa di TensorFlow.
Se il GraphDef superiore di GraphDef viene aumentato a X in una versione (minore), ci saranno almeno sei mesi prima che il limite inferiore venga aumentato a X. Ad esempio (qui stiamo usando numeri di versione ipotetici):
- TensorFlow 1.2 potrebbe supportare GraphDef versioni da 4 a 7.
- TensorFlow 1.3 potrebbe aggiungere GraphDef versione 8 e supportare le versioni da 4 a 8.
- Almeno sei mesi dopo, TensorFlow 2.0.0 potrebbe abbandonare il supporto per le versioni da 4 a 7, lasciando solo la versione 8.
Tieni presente che, poiché le versioni principali di TensorFlow vengono solitamente 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 versione di GraphDef viene abbandonato, GraphDef di fornire strumenti per convertire automaticamente i grafici in una versione di GraphDef più recente supportata.

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

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

Compatibilità con le versioni precedenti e parziale in avanti

Il nostro schema di controllo delle versioni ha tre requisiti:

Compatibilità con le versioni precedenti per supportare il caricamento di grafici e checkpoint creati con versioni precedenti di TensorFlow.
Compatibilità in avanti per supportare scenari in cui il produttore di un grafico o di un checkpoint viene aggiornato a una versione più recente di TensorFlow prima del consumatore.
Abilita l'evoluzione di TensorFlow in modi incompatibili. Ad esempio, rimuovere operazioni, aggiungere attributi e rimuovere attributi.

Si noti che mentre il meccanismo della versione di GraphDef è separato dalla versione di TensorFlow, le modifiche incompatibili all'indietro al formato GraphDef sono ancora limitate dal controllo delle versioni semantico. Ciò significa che la funzionalità può essere rimossa o modificata solo tra le versioni MAJOR di TensorFlow (come dalla 1.7 alla 2.0 ). Inoltre, la compatibilità con le versioni successive viene applicata nelle versioni Patch (da 1.x.1 a 1.x.2 ad esempio).

Per ottenere la compatibilità con le versioni precedenti e successive e per sapere quando applicare le modifiche a formati, grafici e punti di controllo dispongono di metadati che descrivono quando sono stati prodotti. Le sezioni seguenti GraphDef dettaglio l'implementazione di TensorFlow e le linee guida per l'evoluzione GraphDef versioni di GraphDef .

Schemi di versione dei dati indipendenti

Esistono diverse versioni dei dati per grafici e punti di controllo. 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 controllo delle versioni sono definiti in core/public/version.h . Ogni volta che viene aggiunta una nuova versione, viene aggiunta una nota all'intestazione che specifica cosa è cambiato e la data.

Dati, produttori e consumatori

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

produttori : binari che producono dati. I produttori hanno una versione ( producer ) e una versione consumer minima con cui sono compatibili ( min_consumer ).
consumatori : binari che consumano dati. I consumatori hanno una versione ( consumer ) e una versione minima del produttore con cui sono compatibili ( min_producer ).

Ogni parte di dati con versione ha un campo VersionDef versions che registra il producer che ha creato i dati, il min_consumer cui è compatibile e un elenco di versioni bad_consumers che non sono consentite.

Per impostazione predefinita, quando un produttore crea alcuni dati, i dati ereditano le versioni producer e min_consumer del producer . bad_consumers può essere impostato se è noto che specifiche versioni consumer contengono bug e devono essere evitate. Un consumatore può accettare un dato se le seguenti condizioni sono vere:

consumer > = min_consumer
data's producer > = consumer min_producer
consumer non in bad_consumers di dati

Poiché sia i produttori che i consumatori provengono dalla stessa base di codice TensorFlow, core/public/version.h contiene una versione dei dati principale che viene trattata come producer o consumer seconda del contesto e sia min_consumer che min_producer (necessari rispettivamente ai produttori e ai consumatori) . In particolare,

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

Aggiungi un nuovo attributo predefinito a un'operazione esistente

Seguendo la guida di seguito si ottiene la compatibilità con le versioni successive solo se il set di operazioni non è cambiato:

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
Ciò elimina gli attributi con valore predefinito al momento della produzione / esportazione dei modelli. Ciò assicura che il tf.MetaGraphDef esportato non contenga il nuovo attributo op quando viene utilizzato il valore predefinito.
Avere questo controllo potrebbe consentire ai consumatori obsoleti (ad esempio, che servono file binari in ritardo rispetto ai binari di addestramento) di continuare a caricare i modelli e prevenire interruzioni nell'elaborazione dei modelli.

Versioni in evoluzione di GraphDef

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

Aggiungi un op

Aggiungi la nuova opzione sia ai consumatori che ai produttori contemporaneamente e non modificare alcuna versione di GraphDef . Questo tipo di modifica è automaticamente compatibile con le versioni precedenti e non influisce sul piano di compatibilità futura poiché gli script del produttore esistenti non utilizzeranno improvvisamente la nuova funzionalità.

Aggiungi un op e cambia i wrapper Python esistenti per usarlo

Implementa nuove funzionalità consumer e incrementa la versione GraphDef .
Se è possibile fare in modo che i wrapper utilizzino la nuova funzionalità solo in casi che prima non funzionavano, i wrapper possono essere aggiornati ora.
Cambia i wrapper Python per utilizzare la nuova funzionalità. Non incrementare min_consumer , poiché i modelli che non utilizzano questa operazione non dovrebbero rompersi.

Rimuovere o limitare la funzionalità di un op

Correggi tutti gli script del produttore (non TensorFlow stesso) per non utilizzare l'operazione o la funzionalità vietate.
Incrementa la versione di GraphDef e implementa nuove funzionalità consumer che vietano l'operazione o la funzionalità rimossa per GraphDefs alla nuova versione e successive. Se possibile, fare in modo che TensorFlow interrompa la produzione di GraphDefs con la funzionalità vietata. Per fare ciò, aggiungi REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
Attendi una versione principale per motivi di compatibilità con le versioni precedenti.
Aumenta min_producer alla versione GraphDef da (2) e rimuovi completamente la funzionalità.

Cambia la funzionalità di un op

Aggiungi una nuova operazione simile denominata SomethingV2 o simile e segui il processo di aggiunta e cambia i wrapper Python esistenti per usarlo. Per garantire la compatibilità con le versioni successive, utilizzare i controlli suggeriti in compat.py quando si cambiano i wrapper Python.
Rimuovere il vecchio op (può avvenire solo con una modifica della versione principale a causa della compatibilità con le versioni precedenti).
Aumenta min_consumer per escludere i consumatori con il vecchio op, aggiungi di nuovo il vecchio op come alias per SomethingV2 e min_consumer il processo per cambiare i wrapper Python esistenti per usarlo.
Segui il processo per rimuovere SomethingV2 .

Vieta una singola versione consumer non sicura

Bump la versione di GraphDef e aggiungi la versione non bad_consumers a bad_consumers per tutti i nuovi GraphDef. Se possibile, aggiungi a bad_consumers solo per GraphDefs che contengono un certo op o simili.
Se i consumatori esistenti hanno la versione non valida, eliminarli il prima possibile.