Dieses Dokument richtet sich an Benutzer, die Abwärtskompatibilität für verschiedene Versionen von TensorFlow benötigen (entweder für Code oder Daten), und an Entwickler, die TensorFlow unter Beibehaltung der Kompatibilität ändern möchten.
Semantische Versionierung 2.0
TensorFlow folgt Semantic Versioning 2.0 ( Semver ) für seine öffentliche API. Jede Release-Version von TensorFlow hat die Form MAJOR.MINOR.PATCH
. Beispielsweise hat TensorFlow Version 1.2.3 MAJOR
Version 1, MINOR
Version 2 und PATCH
Version 3. Änderungen an jeder Nummer haben die folgende Bedeutung:
MAJOR : Möglicherweise rückwärts inkompatible Änderungen. Code und Daten, die mit einer früheren Hauptversion funktioniert haben, funktionieren nicht unbedingt mit der neuen Version. In einigen Fällen können vorhandene TensorFlow-Diagramme und -Prüfpunkte jedoch auf die neuere Version migriert werden. Weitere Informationen zur Datenkompatibilität finden Sie unter Kompatibilität von Diagrammen und Prüfpunkten .
MINOR : Abwärtskompatible Funktionen, Geschwindigkeitsverbesserungen usw. Code und Daten, die mit einer früheren Nebenversion funktioniert haben und nur von der nicht experimentellen öffentlichen API abhängen, funktionieren weiterhin unverändert. Ausführliche Informationen dazu, was die öffentliche API ist und was nicht, finden Sie unter Was wird behandelt?
PATCH : Abwärtskompatible Fehlerkorrekturen.
In Version 1.0.0 wurden beispielsweise rückwärts inkompatible Änderungen gegenüber Version 0.12.1 eingeführt. Release 1.1.1 war jedoch abwärtskompatibel mit Release 1.0.0.
Was ist abgedeckt
Nur die öffentlichen APIs von TensorFlow sind für kleinere und Patch-Versionen abwärtskompatibel. Die öffentlichen APIs bestehen aus
Alle dokumentierten Python- Funktionen und -Klassen im
tensorflow
Modul und seinen Submodulen mit Ausnahme von- Private Symbole: jede Funktion, Klasse usw., deren Name mit
_
beginnt - Experimentelle und
tf.contrib
Symbole, siehe unten für Details.
Beachten Sie, dass der Code in den
examples/
undtools/
Verzeichnissen nicht über dastensorflow
Python-Modul erreichbar ist und daher nicht von der Kompatibilitätsgarantie abgedeckt wird.Wenn ein Symbol über das
tensorflow
Python-Modul oder seine Submodule verfügbar ist, aber nicht dokumentiert ist, wird es nicht als Teil der öffentlichen API betrachtet.- Private Symbole: jede Funktion, Klasse usw., deren Name mit
Die Kompatibilitäts-API (in Python das Modul
tf.compat
). In Hauptversionen veröffentlichen wir möglicherweise Dienstprogramme und zusätzliche Endpunkte, um Benutzern den Übergang zu einer neuen Hauptversion zu erleichtern. Diese API-Symbole sind veraltet und werden nicht unterstützt (dh wir werden keine Funktionen hinzufügen und keine anderen Fehler beheben, als Schwachstellen zu beheben), sie fallen jedoch unter unsere Kompatibilitätsgarantien.Die C-API .
Die folgenden Protokollpufferdateien:
Was ist nicht abgedeckt
Einige Teile von TensorFlow können sich jederzeit rückwärts inkompatibel ändern. Diese schließen ein:
Experimentelle APIs : Um die Entwicklung zu erleichtern, befreien wir einige API-Symbole, die eindeutig als experimentell gekennzeichnet sind, von den Kompatibilitätsgarantien. Insbesondere sind folgende Punkte nicht durch Kompatibilitätsgarantien abgedeckt:
- ein beliebiges Symbol im Modul
tf.contrib
oder seinen Submodulen; jedes Symbol (Modul, Funktion, Argument, Eigenschaft, Klasse oder Konstante), dessen Name
experimental
oderExperimental
enthält; oderJedes Symbol, dessen vollständig qualifizierter Name ein Modul oder eine Klasse enthält, die selbst experimentell ist. Dies umfasst Felder und Teilmeldungen eines Protokollpuffers, der als
experimental
.
- ein beliebiges Symbol im Modul
Andere Sprachen : TensorFlow-APIs in anderen Sprachen als Python und C, z.
- C ++ (
tensorflow/cc
durch Header-Dateien intensorflow/cc
). - Java ,
- Gehen
- JavaScript
- C ++ (
Details zu zusammengesetzten Operationen: Viele öffentliche Funktionen in Python werden auf mehrere primitive Operationen im Diagramm erweitert, und diese Details sind Teil aller Diagramme, die als
GraphDef
auf der FestplatteGraphDef
. Diese Details können sich für kleinere Releases ändern. Insbesondere Regressionstests, bei denen die exakte Übereinstimmung zwischen Diagrammen überprüft wird, können bei kleineren Releases auftreten, auch wenn das Verhalten des Diagramms unverändert bleiben sollte und vorhandene Prüfpunkte weiterhin funktionieren.Numerische Gleitkommadetails : Die von ops berechneten spezifischen Gleitkommawerte können sich jederzeit ändern. Benutzer sollten sich nur auf die ungefähre Genauigkeit und numerische Stabilität verlassen, nicht auf die berechneten spezifischen Bits. Änderungen an numerischen Formeln in Neben- und Patch-Versionen sollten zu einer vergleichbaren oder verbesserten Genauigkeit führen, mit der Einschränkung, dass eine verbesserte Genauigkeit bestimmter Formeln beim maschinellen Lernen zu einer verringerten Genauigkeit für das Gesamtsystem führen kann.
Zufallszahlen: Die berechneten spezifischen Zufallszahlen können sich jederzeit ändern. Benutzer sollten sich nur auf ungefähr korrekte Verteilungen und statistische Stärke verlassen, nicht auf die spezifischen berechneten Bits. Weitere Informationen finden Sie in der Anleitung zur Generierung von Zufallszahlen .
Versionsversatz in verteiltem Tensorflow: Das Ausführen von zwei verschiedenen Versionen von TensorFlow in einem einzelnen Cluster wird nicht unterstützt. Es gibt keine Garantie für die Abwärtskompatibilität des Drahtprotokolls.
Fehler: Wir behalten uns das Recht vor, rückwärts inkompatibles Verhalten (wenn auch nicht API) zu ändern, wenn die aktuelle Implementierung eindeutig fehlerhaft ist, dh wenn sie der Dokumentation widerspricht oder wenn ein bekanntes und genau definiertes beabsichtigtes Verhalten aufgrund von Fehlern nicht ordnungsgemäß implementiert wird zu einem Fehler. Wenn beispielsweise ein Optimierer behauptet, einen bekannten Optimierungsalgorithmus zu implementieren, dieser jedoch aufgrund eines Fehlers nicht mit diesem Algorithmus übereinstimmt, wird der Optimierer behoben. Unser Fix kann Code beschädigen, der auf dem falschen Verhalten für die Konvergenz beruht. Wir werden solche Änderungen in den Versionshinweisen vermerken.
Nicht verwendete API: Wir behalten uns das Recht vor, rückwärts inkompatible Änderungen an APIs vorzunehmen, für die wir keine dokumentierten Verwendungen finden (indem wir die TensorFlow-Verwendung über die GitHub-Suche prüfen). Bevor wir solche Änderungen vornehmen, werden wir unsere Absicht bekannt geben, die Änderung auf der Announce @ Mailingliste vorzunehmen, Anweisungen zur Behebung von Brüchen (falls zutreffend) bereitzustellen und zwei Wochen warten, um unserer Community die Möglichkeit zu geben, ihr Feedback zu teilen .
Fehlerverhalten: Wir können Fehler durch fehlerfreies Verhalten ersetzen. Beispielsweise können wir eine Funktion ändern, um ein Ergebnis zu berechnen, anstatt einen Fehler auszulösen, selbst wenn dieser Fehler dokumentiert ist. Wir behalten uns außerdem das Recht vor, den Text von Fehlermeldungen zu ändern. Darüber hinaus kann sich der Fehlertyp ändern, sofern in der Dokumentation nicht der Ausnahmetyp für eine bestimmte Fehlerbedingung angegeben ist.
Kompatibilität von gespeicherten Modellen, Grafiken und Prüfpunkten
SavedModel ist das bevorzugte Serialisierungsformat für TensorFlow-Programme. SavedModels bestehen aus zwei Teilen: einem oder mehreren als GraphDefs
codierten GraphDefs
und einem GraphDefs
. Die Diagramme beschreiben den Datenfluss der auszuführenden Operationen, und Prüfpunkte enthalten die gespeicherten Tensorwerte der Variablen in einem Diagramm.
Viele TensorFlow-Benutzer erstellen SavedModels und laden sie und führen sie mit einer späteren Version von TensorFlow aus. In Übereinstimmung mit Semver können SavedModels, die mit einer Version von TensorFlow geschrieben wurden, mit einer späteren Version von TensorFlow mit derselben Hauptversion geladen und ausgewertet werden.
Wir geben zusätzliche Garantien für unterstützte SavedModels. Wir nennen ein SavedModel, das nur mit nicht veralteten, nicht experimentellen, nicht kompatiblen APIs in der TensorFlow-Hauptversion N
ein SavedModel, das in Version N
. Jedes in TensorFlow-Hauptversion N
unterstützte SavedModel kann mit TensorFlow-Hauptversion N+1
geladen und ausgeführt werden. Die zum Erstellen oder Ändern eines solchen Modells erforderlichen Funktionen sind jedoch möglicherweise nicht mehr verfügbar. Daher gilt diese Garantie nur für das nicht geänderte SavedModel.
Wir werden uns bemühen, die Abwärtskompatibilität so lange wie möglich aufrechtzuerhalten, damit die serialisierten Dateien über lange Zeiträume verwendet werden können.
GraphDef-Kompatibilität
GraphDef
werden über den GraphDef
Protokollpuffer serialisiert. Um rückwärts inkompatible Änderungen an Diagrammen zu ermöglichen, verfügt jedes GraphDef
über eine Versionsnummer, die von der TensorFlow-Version getrennt ist. Zum Beispiel hat GraphDef
Version 17 die inv
Op zugunsten von reciprocal
abgelehnt. Die Semantik ist:
Jede Version von TensorFlow unterstützt ein Intervall von
GraphDef
Versionen. Dieses Intervall ist für Patch-Releases konstant und wächst nur für kleinere Releases. DasGraphDef
Unterstützung für eineGraphDef
Version erfolgt nur für eine Hauptversion von TensorFlow (und stimmt nur mit der für SavedModels garantierten Versionsunterstützung überein).Neu erstellte Diagramme erhalten die neueste
GraphDef
Versionsnummer.Wenn eine bestimmte Version von TensorFlow die
GraphDef
Version eines Diagramms unterstützt, wird es mit demselben Verhalten geladen und ausgewertet wie die TensorFlow-Version, mit der es generiert wurde (mit Ausnahme der oben beschriebenen numerischen Gleitkommadetails und Zufallszahlen), unabhängig vom Hauptfach Version von TensorFlow. Insbesondere ein GraphDef, das mit einer Prüfpunktdatei in einer Version von TensorFlow kompatibel ist (wie dies in einem SavedModel der Fall ist), bleibt in nachfolgenden Versionen mit diesem Prüfpunkt kompatibel, solange GraphDef unterstützt wird.Beachten Sie, dass dies nur für serialisierte Diagramme in GraphDefs (und SavedModels) gilt: Code, der einen Prüfpunkt liest, kann möglicherweise keine Prüfpunkte lesen, die von demselben Code generiert wurden, auf dem eine andere Version von TensorFlow ausgeführt wird.
Wenn die
GraphDef
Obergrenze in einer (Neben-) Version auf X erhöht wird,GraphDef
es mindestens sechs Monate, bis die Untergrenze auf X erhöht wird. Beispiel (wir verwenden hier hypothetische Versionsnummern):- TensorFlow 1.2 unterstützt möglicherweise die
GraphDef
Versionen 4 bis 7. - TensorFlow 1.3 könnte
GraphDef
Version 8 hinzufügen und die Versionen 4 bis 8 unterstützen. - Mindestens sechs Monate später konnte TensorFlow 2.0.0 die Unterstützung für die Versionen 4 bis 7 einstellen und nur Version 8 belassen.
Da Hauptversionen von TensorFlow normalerweise im Abstand von mehr als 6 Monaten veröffentlicht werden, sind die oben beschriebenen Garantien für unterstützte SavedModels viel höher als die 6-Monats-Garantie für GraphDefs.
- TensorFlow 1.2 unterstützt möglicherweise die
Wenn die Unterstützung für eine GraphDef
Version eingestellt wird, werden wir versuchen, Tools zum automatischen Konvertieren von Diagrammen in eine neuere unterstützte GraphDef
Version GraphDef
.
Grafik- und Checkpoint-Kompatibilität beim Erweitern von TensorFlow
Dieser Abschnitt ist nur relevant, wenn Sie inkompatible Änderungen am GraphDef
Format GraphDef
, z. B. beim Hinzufügen von Operationen, Entfernen von Operationen oder Ändern der Funktionalität vorhandener Operationen. Der vorherige Abschnitt sollte für die meisten Benutzer ausreichen.
Abwärts- und teilweise Vorwärtskompatibilität
Unser Versionsschema hat drei Anforderungen:
- Abwärtskompatibilität zur Unterstützung des Ladens von Diagrammen und Prüfpunkten, die mit älteren Versionen von TensorFlow erstellt wurden.
- Weiterleitungskompatibilität zur Unterstützung von Szenarien, in denen der Hersteller eines Diagramms oder Prüfpunkts vor dem Verbraucher auf eine neuere Version von TensorFlow aktualisiert wird.
- Aktivieren Sie die Entwicklung von TensorFlow auf inkompatible Weise. Beispiel: Entfernen von Operationen, Hinzufügen von Attributen und Entfernen von Attributen.
Beachten Sie, dass der GraphDef
Versionsmechanismus zwar von der TensorFlow-Version getrennt ist, abwärtskompatible Änderungen am GraphDef
Format jedoch weiterhin durch die semantische Versionierung eingeschränkt werden. Dies bedeutet, dass die Funktionalität nur zwischen den MAJOR
Versionen von TensorFlow (z. B. 1.7
bis 2.0
) entfernt oder geändert werden kann. Darüber hinaus wird die Vorwärtskompatibilität in Patch-Versionen (z. B. 1.x.1
bis 1.x.2
) erzwungen.
Um Abwärts- und Vorwärtskompatibilität zu erreichen und zu wissen, wann Änderungen in Formaten erzwungen werden müssen, verfügen Diagramme und Prüfpunkte über Metadaten, die beschreiben, wann sie erstellt wurden. In den folgenden Abschnitten werden die TensorFlow-Implementierung und Richtlinien für die Entwicklung von GraphDef
Versionen beschrieben.
Unabhängige Datenversionsschemata
Es gibt verschiedene Datenversionen für Diagramme und Prüfpunkte. Die beiden Datenformate entwickeln sich unterschiedlich schnell und auch unterschiedlich schnell von TensorFlow. Beide Versionsverwaltungssysteme sind in core/public/version.h
. Jedes Mal, wenn eine neue Version hinzugefügt wird, wird der Kopfzeile eine Notiz hinzugefügt, in der die Änderungen und das Datum aufgeführt sind.
Daten, Produzenten und Konsumenten
Wir unterscheiden zwischen den folgenden Arten von Datenversionsinformationen:
- Produzenten : Binärdateien, die Daten produzieren. Produzenten haben eine Version (
producer
) und eine Mindest-Consumer-Version, mit der sie kompatibel sind (min_consumer
). - Verbraucher : Binärdateien, die Daten verbrauchen. Verbraucher haben eine Version (
consumer
) und eine Mindestproduzentenversion, mit der sie kompatibel sind (min_producer
).
Jedes versionierte Datenelement verfügt über ein VersionDef versions
, in dem der producer
, der die Daten erstellt hat, der min_consumer
, mit dem es kompatibel ist, und eine Liste der nicht zugelassenen bad_consumers
Versionen bad_consumers
werden.
Wenn ein Produzent Daten erstellt, erben die Daten standardmäßig die producer
und min_consumer
Versionen des producer
. bad_consumers
kann festgelegt werden, wenn bestimmte Consumer-Versionen bekanntermaßen Fehler enthalten und vermieden werden müssen. Ein Verbraucher kann Daten akzeptieren, wenn Folgendes zutrifft:
-
consumer
> = Datenmin_consumer
- Daten des
producer
> = Verbrauchermin_producer
-
consumer
nicht in denbad_consumers
Daten
Da sowohl Hersteller als auch Verbraucher aus derselben TensorFlow-Codebasis stammen, enthält core/public/version.h
eine Hauptdatenversion, die je nach Kontext entweder als producer
oder als consumer
behandelt wird und sowohl min_consumer
als auch min_producer
(von Herstellern bzw. Verbrauchern benötigt). . Speziell,
- Für
GraphDef
Versionen haben wirTF_GRAPH_DEF_VERSION
,TF_GRAPH_DEF_VERSION_MIN_CONSUMER
undTF_GRAPH_DEF_VERSION_MIN_PRODUCER
. - Für Checkpoint-Versionen haben wir
TF_CHECKPOINT_VERSION
,TF_CHECKPOINT_VERSION_MIN_CONSUMER
undTF_CHECKPOINT_VERSION_MIN_PRODUCER
.
Fügen Sie einer vorhandenen Operation standardmäßig ein neues Attribut hinzu
Wenn Sie die folgenden Anleitungen befolgen, erhalten Sie nur dann Vorwärtskompatibilität, wenn sich die Anzahl der Operationen nicht geändert hat:
- Wenn Vorwärtskompatibilität gewünscht wird, eingestellt
strip_default_attrs
zuTrue
, während das Modell entweder ausführenden Verwendung dertf.saved_model.SavedModelBuilder.add_meta_graph_and_variables
undtf.saved_model.SavedModelBuilder.add_meta_graph
Methoden derSavedModelBuilder
Klasse odertf.estimator.Estimator.export_saved_model
- Dadurch werden die Standardwertattribute zum Zeitpunkt der Erstellung / des Exports der Modelle entfernt. Dadurch wird sichergestellt, dass das exportierte
tf.MetaGraphDef
das neue op-Attribut nicht enthält, wenn der Standardwert verwendet wird. - Mit dieser Steuerung können veraltete Benutzer (z. B. Bereitstellen von Binärdateien, die hinter den Schulungsbinärdateien zurückbleiben) die Modelle weiterhin laden und Unterbrechungen bei der Modellbereitstellung verhindern.
Weiterentwickelte GraphDef-Versionen
In diesem Abschnitt wird erläutert, wie Sie diesen Versionsmechanismus verwenden, um verschiedene Arten von Änderungen am GraphDef
Format GraphDef
.
Fügen Sie eine Operation hinzu
Fügen Sie die neue GraphDef
gleichzeitig Verbrauchern und Herstellern hinzu und ändern Sie keine GraphDef
Versionen. Diese Art der Änderung ist automatisch abwärtskompatibel und wirkt sich nicht auf den Vorwärtskompatibilitätsplan aus, da vorhandene Herstellerskripte die neue Funktionalität nicht plötzlich verwenden.
Fügen Sie eine Operation hinzu und wechseln Sie vorhandene Python-Wrapper, um sie zu verwenden
- Implementieren Sie neue Consumer-Funktionen und
GraphDef
dieGraphDef
Version. - Wenn es möglich ist, die Wrapper dazu zu bringen, die neue Funktionalität nur in Fällen zu verwenden, die zuvor nicht funktionierten, können die Wrapper jetzt aktualisiert werden.
- Ändern Sie die Python-Wrapper, um die neue Funktionalität zu verwenden.
min_consumer
Siemin_consumer
, da Modelle, die diesemin_consumer
nicht verwenden, nicht kaputt gehen sollten.
Entfernen oder beschränken Sie die Funktionalität eines Op
- Korrigieren Sie alle Producer-Skripte (nicht TensorFlow selbst), um die gesperrte Operation oder Funktionalität nicht zu verwenden.
- Inkrementieren Sie die
GraphDef
Version und implementieren Sie neue Consumer-Funktionen, die die entfernte Operation oder Funktionalität für GraphDefs ab der neuen Version verbieten. Wenn möglich, lassen Sie TensorFlow die Produktion vonGraphDefs
mit derGraphDefs
FunktionalitätGraphDefs
.REGISTER_OP(...).Deprecated(deprecated_at_version, message)
Sie dazu dasREGISTER_OP(...).Deprecated(deprecated_at_version, message)
. - Warten Sie aus Gründen der Abwärtskompatibilität auf eine Hauptversion.
-
min_producer
min_producer von (2) auf die GraphDef-Version und entfernen Sie die Funktionalität vollständig.
Ändern Sie die Funktionalität eines Op
- Fügen Sie eine neue ähnliche Operation mit dem Namen
SomethingV2
oder eine ähnliche hinzu und führen Sie den Vorgang durch, indem Sie sie hinzufügen und vorhandene Python-Wrapper wechseln, um sie zu verwenden. Um die Vorwärtskompatibilität sicherzustellen, verwenden Sie beim Ändern der Python-Wrapper die in compatible.py vorgeschlagenen Überprüfungen. - Entfernen Sie die alte Operation (Kann aufgrund der Abwärtskompatibilität nur mit einer größeren Versionsänderung erfolgen).
-
min_consumer
, um Konsumenten mit der altenmin_consumer
auszuschließen, fügen Sie die altemin_consumer
als Alias fürSomethingV2
und führen Sie den Prozess durch, um vorhandene Python-Wrapper für die Verwendung zu wechseln. - Gehen Sie den Vorgang durch, um
SomethingV2
zu entfernen.
Verbieten Sie eine einzelne unsichere Consumer-Version
-
GraphDef
dieGraphDef
Version und fügen Sie die fehlerhafte Version für alle neuen GraphDefs zubad_consumers
hinzu. Wenn möglich, fügen Siebad_consumers
nur für GraphDefs hinzu, die eine bestimmte Operation oder ähnliches enthalten. - Wenn bestehende Verbraucher die schlechte Version haben, schieben Sie sie so schnell wie möglich heraus.