このドキュメントは、TensorFlowのさまざまなバージョン(コードまたはデータのいずれか)間で下位互換性が必要なユーザー、および互換性を維持しながらTensorFlowを変更したい開発者を対象としています。
セマンティックバージョニング2.0
TensorFlowは、パブリックAPIのSemantic Versioning 2.0( semver )に従います。 TensorFlowの各リリースバージョンの形式はMAJOR.MINOR.PATCH
です。たとえば、TensorFlowバージョン1.2.3には、 MAJOR
バージョン1、 MINOR
バージョン2、およびPATCH
バージョン3があります。各番号への変更には、次の意味があります。
メジャー:潜在的に後方互換性のない変更。以前のメジャーリリースで機能したコードとデータは、必ずしも新しいリリースで機能するとは限りません。ただし、場合によっては、既存のTensorFlowグラフとチェックポイントが新しいリリースに移行できる可能性があります。データの互換性の詳細については、グラフとチェックポイントの互換性を参照してください。
MINOR:以前のマイナーリリースと協力し、そのまま作業を継続します非実験パブリックAPIにのみ依存して下位互換性機能、速度の向上などのコードとデータ。パブリックAPIとは何か、およびパブリックAPIではないものの詳細については、「対象となるもの」を参照してください。
パッチ:下位互換性のあるバグ修正。
たとえば、リリース1.0.0では、リリース0.12.1からの下位互換性のない変更が導入されました。ただし、リリース1.1.1はリリース1.0.0と下位互換性がありました。
カバーされるもの
TensorFlowのパブリックAPIのみが、マイナーバージョンとパッチバージョン間で下位互換性があります。パブリックAPIはで構成されています
tensorflow
モジュールとそのサブモジュール内のすべての文書化されたPython関数とクラス(以下を除く)- プライベートシンボル:名前が
_
始まる関数、クラスなど。 - 実験的および
tf.contrib
シンボル。詳細については、以下を参照してください。
examples/
およびtools/
ディレクトリのコードは、tensorflow
Pythonモジュールを介して到達できないため、互換性保証の対象外であることに注意してください。シンボルが
tensorflow
モジュールまたはそのサブモジュールを介して利用可能であるが、文書化されていない場合、そのシンボルはパブリックAPIの一部とは見なされません。- プライベートシンボル:名前が
互換性API(Pythonでは
tf.compat
モジュール)。メジャーバージョンでは、ユーザーが新しいメジャーバージョンに移行するのに役立つユーティリティと追加のエンドポイントをリリースする場合があります。これらのAPIシンボルは非推奨であり、サポートされていません(つまり、機能を追加せず、脆弱性を修正する以外のバグを修正しません)が、互換性の保証に該当します。CAPI 。
次のプロトコルバッファファイル:
カバーされていないもの
TensorFlowの一部は、いつでも後方互換性のない方法で変更される可能性があります。これらには以下が含まれます:
実験的なAPI :開発を容易にするために、互換性の保証から実験的なものとして明確にマークされた一部のAPIシンボルを除外します。特に、以下は互換性保証の対象外です。
-
tf.contrib
モジュールまたはそのサブモジュール内の任意のシンボル。 名前に
experimental
またはExperimental
が含まれるシンボル(モジュール、関数、引数、プロパティ、クラス、または定数)。または完全修飾名に、それ自体が実験的なモジュールまたはクラスが含まれているシンボル。これは、フィールドと呼ばれる任意のプロトコルバッファのサブメッセージが含ま
experimental
。
-
その他の言語:PythonおよびC以外の言語のTensorFlow API(次のようなもの)。
- C ++ (
tensorflow/cc
ヘッダーファイルを介して公開)。 - Java 、
- 行く
- JavaScript
- C ++ (
複合操作の詳細: Pythonの多くのパブリック関数は、グラフ内のいくつかのプリミティブ操作に拡張されます。これらの詳細は、
GraphDef
としてディスクに保存されるグラフの一部になります。これらの詳細は、マイナーリリースで変更される可能性があります。特に、グラフの動作は変更されておらず、既存のチェックポイントは引き続き機能しますが、グラフ間の正確な一致をチェックする回帰テストは、マイナーリリース間で中断する可能性があります。浮動小数点の数値の詳細: opsによって計算される特定の浮動小数点値は、いつでも変更される可能性があります。ユーザーは、計算された特定のビットではなく、おおよその精度と数値安定性のみに依存する必要があります。マイナーリリースおよびパッチリリースで数式を変更すると、同等または改善された精度が得られるはずですが、機械学習では、特定の公式の精度が向上すると、システム全体の精度が低下する可能性があることに注意してください。
乱数:計算される特定の乱数はいつでも変更される可能性があります。ユーザーは、計算された特定のビットではなく、ほぼ正しい分布と統計的強度のみに依存する必要があります。詳細については、乱数生成ガイドを参照してください。
分散Tensorflowのバージョンスキュー:単一のクラスターで2つの異なるバージョンのTensorFlowを実行することはサポートされていません。ワイヤープロトコルの下位互換性についての保証はありません。
バグ:現在の実装が明らかに壊れている場合、つまり、ドキュメントと矛盾している場合、またはよく知られていて明確に定義された意図された動作が適切に実装されていない場合、後方互換性のない動作(APIではない)を変更する権利を留保しますバグに。たとえば、オプティマイザーがよく知られた最適化アルゴリズムを実装していると主張しているが、バグのためにそのアルゴリズムと一致しない場合、オプティマイザーを修正します。私たちの修正は、収束のための間違った動作に依存するコードを壊す可能性があります。このような変更については、リリースノートに記載されています。
未使用のAPI:文書化された使用法が見つからないAPIに後方互換性のない変更を加える権利を留保します(GitHub検索を介してTensorFlowの使用状況の監査を実行することにより)。このような変更を行う前に、 announce @メーリングリストで変更を行う意向を発表し、破損に対処する方法(該当する場合)を説明し、2週間待ってコミュニティにフィードバックを共有する機会を提供します。
エラー動作:エラーをエラー以外の動作に置き換える場合があります。たとえば、エラーが文書化されている場合でも、エラーを発生させる代わりに結果を計算するように関数を変更する場合があります。また、エラーメッセージのテキストを変更する権利を留保します。さらに、特定のエラー条件の例外タイプがドキュメントで指定されていない限り、エラーのタイプは変更される可能性があります。
SavedModels、グラフ、チェックポイントの互換性
SavedModelは、TensorFlowプログラムで使用するのに推奨されるシリアル化形式です。 SavedModelsには、 GraphDefs
としてエンコードされた1つ以上のグラフとCheckpointの2つの部分が含まれています。グラフは、実行されるopsのデータフローを記述し、チェックポイントには、グラフ内の変数の保存されたテンソル値が含まれます。
多くのTensorFlowユーザーは、SavedModelsを作成し、TensorFlowの新しいリリースでそれらをロードして実行します。 semverに準拠して、1つのバージョンのTensorFlowで記述されたSavedModelsをロードして、同じメジャーリリースの新しいバージョンのTensorFlowで評価できます。
サポートされているSavedModelに対して追加の保証を行います。 TensorFlowメジャーバージョンN
で非推奨ではない非実験的で非互換性のAPIのみを使用して作成されたSavedModelを、バージョンN
サポートされているSavedModelと呼びます。どれSavedModelがTensorFlowメジャーバージョンでサポートされているN
TensorFlowメジャーバージョンをロードして実行することができますN+1
。ただし、このようなモデルの構築または変更に必要な機能は使用できなくなる可能性があるため、この保証は変更されていないSavedModelにのみ適用されます。
シリアル化されたファイルを長期間使用できるように、下位互換性を可能な限り維持するように努めます。
GraphDefの互換性
グラフは、 GraphDef
プロトコルバッファを介してGraphDef
ます。グラフへの後方互換性のない変更を容易にするために、各GraphDef
はTensorFlowバージョンとは別のバージョン番号があります。例えば、 GraphDef
バージョン17は、非推奨inv
の賛成でOP reciprocal
。セマンティクスは次のとおりです。
TensorFlowの各バージョンは、
GraphDef
バージョンの間隔をGraphDef
ます。この間隔はパッチリリース間で一定であり、マイナーリリース間でのみ増加します。GraphDef
バージョンのサポートのGraphDef
は、GraphDef
のメジャーリリースでのみ発生します(SavedModelsで保証されているバージョンサポートとのみ一致します)。新しく作成されたグラフには、最新の
GraphDef
バージョン番号が割り当てられます。特定のバージョンのTensorFlowがグラフの
GraphDef
バージョンをサポートしている場合、メジャーに関係なく、グラフの生成に使用されたTensorFlowバージョンと同じ動作でロードおよび評価されます(浮動小数点の数値の詳細と乱数を除く)。 TensorFlowのバージョン。特に、TensorFlowの1つのバージョン(SavedModelの場合など)のチェックポイントファイルと互換性のあるGraphDefは、GraphDefがサポートされている限り、後続のバージョンのそのチェックポイントとの互換性を維持します。チェックポイントを読み取るコードはTensorFlowの異なるバージョンを実行して、同じコードによって生成されたチェックポイントを読み取ることができないかもしれない:これはGraphDefs(及びSavedModels)でシリアライズグラフに適用されることに留意されたいです。
場合
GraphDef
上限は(マイナー)リリースではXに増加している下限前に、少なくとも6ヶ月があるだろう例えばXに増加している(ここでは仮想的なバージョン番号を使用しています):- TensorFlow 1.2は、
GraphDef
バージョンGraphDef
サポートする可能性があります。 - TensorFlow 1.3は、
GraphDef
バージョン8を追加し、バージョン4から8をサポートする可能性があります。 - 少なくとも6か月後、TensorFlow 2.0.0はバージョン4から7のサポートを終了し、バージョン8のみを残す可能性があります。
TensorFlowのメジャーバージョンは通常6か月以上離れて公開されるため、上記でサポートされているSavedModelの保証は、GraphDefの6か月の保証よりもはるかに強力であることに注意してください。
- TensorFlow 1.2は、
最後に、 GraphDef
バージョンのサポートが終了した場合、グラフを新しいサポートされているGraphDef
バージョンに自動的に変換するためのツールの提供を試みます。
TensorFlowを拡張する際のグラフとチェックポイントの互換性
このセクションは、opsの追加、opsの削除、既存のopsの機能の変更など、 GraphDef
形式に互換性のない変更を加える場合にのみ関係します。ほとんどのユーザーにとって、前のセクションで十分です。
後方互換性と部分前方互換性
私たちのバージョン管理スキームには3つの要件があります。
- 古いバージョンのTensorFlowで作成されたグラフとチェックポイントの読み込みをサポートするための下位互換性。
- グラフまたはチェックポイントのプロデューサーがコンシューマーの前に新しいバージョンのTensorFlowにアップグレードされるシナリオをサポートするための上位互換性。
- 互換性のない方法で進化するTensorFlowを有効にします。たとえば、opsの削除、属性の追加、属性の削除などです。
GraphDef
バージョンのメカニズムはGraphDef
バージョンとは別のものですが、 GraphDef
形式への後方互換性のない変更は、セマンティックバージョニングによって制限されていることに注意してください。つまり、機能はTensorFlowのMAJOR
バージョン( 1.7
から2.0
)間でのみ削除または変更できます。さらに、パッチリリース内で上位互換性が適用されます( 1.x.1
、 1.x.2
から1.x.2
)。
下位互換性と上位互換性を実現し、フォーマットの変更をいつ実施するかを知るために、グラフとチェックポイントには、それらがいつ作成されたかを説明するメタデータがあります。以下のセクションでは、TensorFlowの実装とGraphDef
バージョンを進化させるためのガイドラインについて詳しく説明します。
独立したデータバージョンスキーム
グラフとチェックポイントにはさまざまなデータバージョンがあります。 2つのデータ形式は、互いに異なる速度で、またTensorFlowからも異なる速度で進化します。両方のバージョン管理システムは、 core/public/version.h
定義されています。新しいバージョンが追加されるたびに、変更内容と日付の詳細がヘッダーに追加されます。
データ、プロデューサー、およびコンシューマー
次の種類のデータバージョン情報を区別します。
- プロデューサー:データを生成するバイナリ。プロデューサーには、互換性のあるバージョン(
producer
)と最小コンシューマーバージョン(min_consumer
)があります。 - コンシューマー:データを消費するバイナリ。コンシューマーには、互換性のあるバージョン(
consumer
)と最小プロデューサーバージョン(min_producer
)があります。
バージョン管理されたデータの各部分には、データを作成したproducer
、互換性のあるmin_consumer
、および許可されていないbad_consumers
バージョンのリストを記録するVersionDef versions
フィールドがあります。
デフォルトでは、プロデューサーがデータを作成すると、そのデータはプロデューサーのproducer
とmin_consumer
バージョンをmin_consumer
ます。 bad_consumers
は、特定のコンシューマーバージョンにバグが含まれていることがわかっているため、回避する必要がある場合に設定できます。以下がすべて当てはまる場合、消費者はデータを受け入れることができます。
-
consumer
> =データのmin_consumer
- データの
producer
> =コンシューマーのmin_producer
- データの
bad_consumers
ないconsumer
プロデューサーとコンシューマーの両方が同じTensorFlowコードベースからのものであるため、 core/public/version.h
は、コンテキストとmin_consumer
とmin_producer
両方(それぞれプロデューサーとコンシューマーが必要)に応じてproducer
またはconsumer
として扱われるメインデータバージョンが含まれます。 。具体的には、
-
GraphDef
バージョンの場合、TF_GRAPH_DEF_VERSION
、TF_GRAPH_DEF_VERSION_MIN_CONSUMER
、およびTF_GRAPH_DEF_VERSION_MIN_PRODUCER
ます。 - チェックポイントバージョンの場合、
TF_CHECKPOINT_VERSION
、TF_CHECKPOINT_VERSION_MIN_CONSUMER
、およびTF_CHECKPOINT_VERSION_MIN_PRODUCER
ます。
デフォルトの新しい属性を既存の操作に追加します
以下のガイダンスに従うと、opsのセットが変更されていない場合にのみ上位互換性が得られます。
- 上位互換性が必要な場合は、
SavedModelBuilder
クラスのtf.saved_model.SavedModelBuilder.add_meta_graph_and_variables
およびtf.saved_model.SavedModelBuilder.add_meta_graph
メソッド、またはtf.estimator.Estimator.export_saved_model
を使用してモデルをエクスポートするときに、strip_default_attrs
をTrue
に設定します。 - これにより、モデルの作成/エクスポート時にデフォルト値の属性が削除されます。これにより、デフォルト値が使用されている場合、エクスポートされた
tf.MetaGraphDef
に新しいop属性が含まれないようになります。 - この制御を使用すると、古いコンシューマー(たとえば、トレーニングバイナリより遅れているバイナリの提供)がモデルの読み込みを継続し、モデルの提供の中断を防ぐことができます。
進化するGraphDefバージョン
このセクションでは、このバージョン管理メカニズムを使用して、 GraphDef
形式にさまざまなタイプの変更を加える方法について説明します。
操作を追加する
新しいopをコンシューマーとプロデューサーの両方に同時に追加し、 GraphDef
バージョンを変更しないでください。このタイプの変更は自動的に下位互換性があり、既存のプロデューサースクリプトが突然新しい機能を使用しないため、上位互換性計画には影響しません。
opを追加し、既存のPythonラッパーを切り替えて使用します
- 新しいコンシューマー機能を実装し、
GraphDef
バージョンをインクリメントします。 - 以前は機能しなかった場合にのみラッパーに新しい機能を使用させることができる場合は、ラッパーを今すぐ更新できます。
- 新しい機能を使用するようにPythonラッパーを変更します。この操作を使用しないモデルは壊れてはならないため、
min_consumer
インクリメントしないでください。
オペレーションの機能を削除または制限する
- 禁止されている操作や機能を使用しないように、すべてのプロデューサースクリプト(TensorFlow自体ではない)を修正します。
-
GraphDef
バージョンをインクリメントし、新しいバージョン以降でGraphDefsの削除された操作または機能を禁止する新しいコンシューマー機能を実装します。可能であれば、TensorFlowストップ生産作るGraphDefs
禁止機能を。これを行うには、REGISTER_OP(...).Deprecated(deprecated_at_version, message)
追加しREGISTER_OP(...).Deprecated(deprecated_at_version, message)
。 - 下位互換性のためにメジャーリリースを待ちます。
-
min_producer
を(2)からGraphDefバージョンに増やし、機能を完全に削除します。
オペレーションの機能を変更する
SomethingV2
などの名前の新しい同様の操作を追加し、それを追加して既存のPythonラッパーを切り替えて使用するプロセスを実行します。上位互換性を確保するには、Pythonラッパーを変更するときにcompat.pyで提案されているチェックを使用します。- 古い操作を削除します(下位互換性のため、メジャーバージョンを変更した場合にのみ実行できます)。
-
min_consumer
を増やして、古いopを持つコンシューマーを除外し、SomethingV2
エイリアスとして古いopを追加し直し、既存のPythonラッパーを切り替えて使用するようにします。 -
SomethingV2
を削除するプロセスを実行します。
安全でない単一の消費者向けバージョンを禁止する
GraphDef
バージョンをバンプし、すべての新しいGraphDefのbad_consumers
不良バージョンを追加します。可能であれば、特定のopなどを含むbad_consumers
のみbad_consumers
に追加します。- 既存の消費者が悪いバージョンを持っている場合は、できるだけ早くそれらを押し出します。