TensorFlow Version Compatibility（版本兼容性）

本文档面向需要向不同版本的TensorFlow（代码或数据）提供向后兼容性的用户，以及希望在保持兼容性的同时修改TensorFlow的开发人员。

语义版本2.0

TensorFlow遵循语义版本2.0（semver）为其公共API。TensorFlow的每个发行版本都具有这种形式MAJOR.MINOR.PATCH。例如，TensorFlow 1.2.3版本具有MAJOR版本1，MINOR版本2和PATCH版本3.每个数字的更改具有以下含义：

MAJOR：潜在的后向不兼容的变化。与以前的主要版本一起工作的代码和数据不一定适用于新版本。但是，在某些情况下，现有的TensorFlow图形和检查点可能会迁移到新版本; 有关数据兼容性的详细信息，请参阅图形和检查点的兼容性

• MINOR：向后兼容功能，速度改进等。与之前的次要版本一起工作并且仅依赖于公共API的代码和数据将继续保持不变。有关是否为公共API的详细信息，请参阅涵盖的内容。

• PATCH：向后兼容错误fixes.For例如，1.0.0版本引入了向后兼容的版本0.12.1的变化。然而，版本1.1.1 与版本1.0.0 向后兼容。涵盖的内容只有TensorFlow的公共API在跨版本和补丁版本之间向后兼容。公共API包含

• 所有记录在Python中的Python函数和类

tensorflow 模块及其子模块，除了

- functions and classes in `tf.contrib` 
- functions and classes whose names start with `_` (as these are private) Note that the code in the `examples/` and `tools/` directories is not reachable through the `tensorflow` Python module and is thus not covered by the compatibility guarantee.

如果符号通过tensorflowPython模块或其子模块可用，但没有记录，则它不被视为公共API的一部分。

• C API。

• 以下协议缓冲文件：

- [`attr_value`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/attr_value.proto)
- [`config`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/protobuf/config.proto)
- [`event`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/util/event.proto)
- [`graph`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/graph.proto)
- [`op_def`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/op_def.proto)
- [`reader_base`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/reader_base.proto)
- [`summary`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/summary.proto)
- [`tensor`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/tensor.proto)
- [`tensor_shape`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/tensor_shape.proto)
- [`types`](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/types.proto)

不包括在内：

一些API函数被明确标记为“实验性”，并且可以在次版本之间以向后不兼容的方式进行更改。这些包括：

• 实验性API：tf.contribPython中的模块及其子模块，以及C API中的任何函数或协议缓冲区中明确表示为实验性的字段。

• 其他语言：除Python和C以外的其他语言的 TensorFlow API，例如：

• C ++（通过头文件公开tensorflow/cc）。

• Java,

• Go

• 复合操作的细节： Python中的许多公共函数展开为图中的几个原始操作，这些细节将作为GraphDefs 保存到磁盘的任何图的一部分。这些细节可能会因次要版本而有所变化 特别是，检查图表之间精确匹配的回归测试可能会跨越次要版本，即使图表的行为应该保持不变并且现有检查点仍然可以工作。

• 浮点数字细节：操作计算的特定浮点值可能随时发生变化。用户应该只依靠近似精度和数值稳定性，而不是计算的特定位数。在次要版本和补丁版本中对数字公式的更改应导致准确性相当或提高，同时需要注意的是，在机器学习中，特定公式的准确性提高可能会导致整个系统的精度降低。

• 随机数：由随机操作计算出的特定随机数可能随时发生变化。用户应该只依靠大致正确的分布和统计强度，而不是计算的特定位数。但是，我们会对修补程序很少发布（或者从不）修改随机位。我们当然会记录所有这些变化。

• 分布式Tensorflow中的版本偏差：在单个群集中运行两个不同版本的TensorFlow不受支持。对于有线协议的向后兼容性没有任何保证。

• Bugs：如果当前的实现明显中断，我们保留使后向不兼容的行为（尽管不是API）发生变化的权利，也就是说，如果它与文档相矛盾，或者知名且明确定义的预期行为没有适当实现，到一个bug。例如，如果优化器声称实现了一个众所周知的优化算法，但由于错误而与该算法不匹配，那么我们将修复优化器。我们的修复可能会依靠错误的行为来破坏代码。我们会在发行说明中注意这些更改。

• 错误消息：我们保留更改错误消息文本的权利。另外，除非文档中指定了类型，否则错误的类型可能会更改。例如，记录用于引发InvalidArgument异常的函数将继续增加InvalidArgument，但人类可读的消息内容可能会更改。

图形和检查点的兼容性

你有时需要保存图形和检查点。图形描述了在训练和推断过程中要运行的操作数据流，并且检查点包含图中变量的已保存张量值。

许多TensorFlow用户将图形和训练好的模型保存到磁盘以备后期评估或进行额外培训，但最终会在更高版本上运行保存的图形或模型。在符合semver的情况下，用一个版本的TensorFlow写出的任何图形或检查点都可以使用具有相同主要版本的更高版本的TensorFlow加载和评估。但是，尽可能在主要发行版本之间保持向后兼容性，以便序列化文件可以在很长一段时间内使用。

图形通过GraphDef协议缓冲区序列化。为了促进（罕见的）向后不兼容的图形更改，每个GraphDef版本都有一个与TensorFlow版本分开的版本号。例如，GraphDef版本 17 不赞成使用inv操作 reciprocal。语义是：

• TensorFlow的每个版本都支持一段时间的GraphDef版本。这个时间间隔在修补程序版本中将保持不变，并且只会在次要版本中增长。GraphDef只有TensorFlow的主要版本才会支持。

• 新创建的图形会分配最新的GraphDef版本号。

• 如果给定版本的TensorFlow支持GraphDef图形的版本，则无论TensorFlow的主版本如何，它都将加载和评估，其行为与用于生成它的TensorFlow版本（浮点数字细节和随机数除外）相同。特别是，所有检查点文件都是兼容的。

• 如果在（次要）版本中GraphDef 上限 增加到X，那么在下限 增加到X 之前至少有六个月。例如（我们在这里使用假设版本号）：

- TensorFlow 1.2 might support `GraphDef` versions 4 to 7.
- TensorFlow 1.3 could add `GraphDef` version 8 and support versions 4 to 8.
- At least six months later, TensorFlow 2.0.0 could drop support for versions 4 to 7, leaving version 8 only.

最后，当GraphDef版本支持被删除时，我们将尝试提供自动将图转换为支持GraphDef版本的更新的工具。

扩展TensorFlow时的图形和检查点兼容性

本节只与在对GraphDef格式进行不兼容的更改时（例如添加操作，删除操作或更改现有操作的功能）有关。上一节应该足以满足大多数用户的需求。

后向和部分向前兼容

我们的版本控制计划有三个要求：

• 向后兼容性，支持加载使用旧版TensorFlow创建的图形和检查点。

• 向前兼容性支持图形或检查点的生产者在使用者之前升级到更新版本的TensorFlow的场景。

• 以不兼容的方式启用渐进的TensorFlow。例如，删除操作，添加属性和删除属性。

请注意，尽管GraphDef版本机制与TensorFlow版本分开，但对GraphDef格式的向后不兼容更改仍受Semantic Versioning限制。这意味着功能只能被移除或在MAJOR之间变化TensorFlow的版本（如1.7到2.0）。此外，前向兼容性是补丁版本内执行（1.x.1至1.x.2例如）。

为了实现向前和向后兼容性，并知道何时执行格式更改，图形和检查点具有描述它们何时生成的元数据。下面的部分详细介绍了TensorFlow实现和不断发展的GraphDef版本的指导原则。

独立的数据版本方案

图形和检查点有不同的数据版本。这两种数据格式的演变速度不同，而且速度也不同于TensorFlow。两个版本控制系统都在core/public/version.h中定义。每当添加新版本时，都会在标题中添加注释，详细说明更改的内容和日期。

数据，生产者和消费者

我们区分以下几种数据版本信息： 生产者：生成数据的二进制文件。生产者具有producer与（min_consumer __）兼容的版本和最低消费者版本。 消费者：消耗数据的二进制文件。消费者拥有consumer与（min_producer）兼容的版本（）和最低生产者版本。

每个版本化的数据都有一个VersionDef versions字段，用于记录producer数据的创建，min_consumer兼容的数据以及bad_consumers不允许的版本列表。

默认情况下，当生产者创建一些数据时，数据会继承生产者producer和min_consumer版本。bad_consumers可以设置，如果特定的消费者版本已知包含错误，必须避免。如果满足以下条件，消费者可以接受一段数据：

• consumer >= data's min_consumer

• data's producer >= consumer's min_producer

• consumer not in data's bad_consumers

由于生产者和消费者都来自同一个TensorFlow代码库，因此它core/public/version.h包含一个主要数据版本，该版本被视为producer或consumer取决于上下文以及两者min_consumer和min_producer（分别由生产者和消费者所需）。特别地，

• 对于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。

不断发展的GraphDef版本

本节介绍如何使用此版本控制机制对GraphDef格式进行不同类型的更改。

添加一个操作

同时向消费者和生产者添加新的作品，并且不要更改任何GraphDef版本。这种类型的更改会自动向后兼容，并且不会影响兼容性计划，因为现有生产者脚本不会突然使用新功能。

添加一个操作并切换现有的Python包装来使用它

1. 实现新的消费者功能并增加GraphDef版本。

1. 如果仅在以前无法使用的情况下才能使包装程序使用新功能，则可以立即更新包装程序。

1. 更改Python包装以使用新功能。不要增加min_consumer，因为不使用此操作的模型不应该中断。

删除或限制操作的功能

1. 修复所有生产者脚本（不是TensorFlow本身）不使用禁止的操作或功能。

1. 增加GraphDef版本并实现新的使用者功能，以便在新版本及更高版本中禁用已删除的操作或GraphDefs功能。如果可能，使TensorFlow停止生产GraphDefs与禁止的功能。为此，请添加REGISTER_OP(...).Deprecated(deprecated_at_version, message)。

1. 为了向后兼容，等待主要版本。

1. 增加min_producer从（2）GraphDef版本和完全删除的功能。

更改操作的功能

1. 添加一个新的类似的操作系统命名SomethingV2或类似，并通过添加它并切换现有的Python包装器来使用它，如果需要向前兼容性可能需要三周时间。

1. 删除旧的操作系统（由于向后兼容性，只能进行主版本更改）。

1. 通过增加min_consumer旧操作排除消费者，增加旧操作作为SomethingV2别名，并通过该过程切换现有的Python包装来使用它。

1. 通过该过程删除SomethingV2。

禁止单个不安全的消费者版本

1. 凹凸的GraphDef版本，并添加不良版本bad_consumers为所有新GraphDefs。如果可能，只为包含特定操作或类似操作的GraphDef 添加bad_consumers。