Kompatibilität der TensorFlow-Version

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/ und tools/ Verzeichnissen nicht über das tensorflow 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.

  • 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 oder Experimental enthält; oder

    • Jedes 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 .

  • Andere Sprachen : TensorFlow-APIs in anderen Sprachen als Python und C, z.

  • 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 Festplatte GraphDef . 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. Das GraphDef Unterstützung für eine GraphDef 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.

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 > = Daten min_consumer
  • Daten des producer > = Verbraucher min_producer
  • consumer nicht in den bad_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 wir TF_GRAPH_DEF_VERSION , TF_GRAPH_DEF_VERSION_MIN_CONSUMER und TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
  • Für Checkpoint-Versionen haben wir TF_CHECKPOINT_VERSION , TF_CHECKPOINT_VERSION_MIN_CONSUMER und TF_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:

  1. Wenn Vorwärtskompatibilität gewünscht wird, eingestellt strip_default_attrs zu True , während das Modell entweder ausführenden Verwendung der tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables und tf.saved_model.SavedModelBuilder.add_meta_graph Methoden der SavedModelBuilder Klasse oder tf.estimator.Estimator.export_saved_model
  2. 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.
  3. 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

  1. Implementieren Sie neue Consumer-Funktionen und GraphDef die GraphDef Version.
  2. 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.
  3. Ändern Sie die Python-Wrapper, um die neue Funktionalität zu verwenden. min_consumer Sie min_consumer , da Modelle, die diese min_consumer nicht verwenden, nicht kaputt gehen sollten.

Entfernen oder beschränken Sie die Funktionalität eines Op

  1. Korrigieren Sie alle Producer-Skripte (nicht TensorFlow selbst), um die gesperrte Operation oder Funktionalität nicht zu verwenden.
  2. 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 von GraphDefs mit der GraphDefs Funktionalität GraphDefs . REGISTER_OP(...).Deprecated(deprecated_at_version, message) Sie dazu das REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. Warten Sie aus Gründen der Abwärtskompatibilität auf eine Hauptversion.
  4. 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

  1. 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.
  2. Entfernen Sie die alte Operation (Kann aufgrund der Abwärtskompatibilität nur mit einer größeren Versionsänderung erfolgen).
  3. min_consumer , um Konsumenten mit der alten min_consumer auszuschließen, fügen Sie die alte min_consumer als Alias ​​für SomethingV2 und führen Sie den Prozess durch, um vorhandene Python-Wrapper für die Verwendung zu wechseln.
  4. Gehen Sie den Vorgang durch, um SomethingV2 zu entfernen.

Verbieten Sie eine einzelne unsichere Consumer-Version

  1. GraphDef die GraphDef Version und fügen Sie die fehlerhafte Version für alle neuen GraphDefs zu bad_consumers hinzu. Wenn möglich, fügen Sie bad_consumers nur für GraphDefs hinzu, die eine bestimmte Operation oder ähnliches enthalten.
  2. Wenn bestehende Verbraucher die schlechte Version haben, schieben Sie sie so schnell wie möglich heraus.