此页面由 Cloud Translation API 翻译。
Switch to English

TensorFlow版本兼容性

本文档适用于需要在不同版本的TensorFlow(代码或数据)之间向后兼容的用户,以及希望在保留兼容性的同时修改TensorFlow的开发人员。

语义版本2.0

TensorFlow的公共API遵循语义版本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符号和tf.contrib符号,请参见下文以了解详细信息。

    请注意, examples/tools/目录中的代码无法通过tensorflow Python模块访问,因此不被兼容性保证所涵盖。

    如果符号可以通过tensorflow Python模块或其子模块使用,但未记录在文档中,则该符号被视为公共API的一部分。

  • 兼容性API(在Python中为tf.compat模块)。在主要版本中,我们可能会发布实用程序和其他终结点,以帮助用户过渡到新的主要版本。这些API符号已被弃用,不受支持(即,我们将不会添加任何功能,并且除了修复漏洞之外,我们不会修复其他漏洞),但是它们确实属于我们的兼容性保证。

  • C API

  • 以下协议缓冲区文件:

什么包括

TensorFlow的某些部分随时可能以向后不兼容的方式更改。这些包括:

  • 实验性API :为了促进开发,我们从兼容性保证中排除了一些明确标记为实验性的API符号。特别是,以下内容不包含在任何兼容性保证中:

    • tf.contrib模块或其子模块中的任何符号;
    • 名称包含experimentalExperimental任何符号(模块,函数,参数,属性,类或常量);要么

    • 具有完全限定名称的任何符号包括本身是实验性的模块或类。这包括称为experimental的任何协议缓冲区的字段和子消息。

  • 其他语言 :使用Python和C以外的其他语言的 TensorFlow API,例如:

  • 组合操作的详细信息: Python中的许多公共功能都扩展为图形中的多个原始操作,这些详细信息将作为GraphDef保存到磁盘的任何图形的一部分。对于次要发行版,这些详细信息可能会更改。尤其是,检查图之间是否完全匹配的回归测试很可能会跨次要发布而中断,即使图的行为应保持不变并且现有检查点仍将起作用。

  • 浮点数值详细信息: ops计算的特定浮点值可能随时更改。用户应仅依赖于近似精度和数值稳定性,而不依赖于所计算的特定位。次要版本和补丁版本中数字公式的更改应导致可比较或更高的准确性,但需要注意的是,在机器学习中,特定公式的准确性可能会降低整个系统的准确性。

  • 随机数:计算出的特定随机数可能随时更改。用户应仅依靠近似正确的分布和统计强度,而不是所计算的特定位。有关详细信息,请参见随机数生成指南。

  • 分布式Tensorflow中的版本偏斜:不支持在单个集群中运行TensorFlow的两个不同版本。不能保证有线协议的向后兼容性。

  • 错误:如果当前的实现明显被破坏,即,如果它与文档相矛盾,或者由于适当地实现了众所周知的定义明确的预期行为,则我们保留更改向后不兼容行为(尽管不是API)的权利一个错误。例如,如果优化器声称要实现众所周知的优化算法,但由于错误而与该算法不匹配,那么我们将修复该优化器。我们的修复程序可能会依靠错误的行为来破坏代码来收敛。我们将在发行说明中记录此类更改。

  • 未使用的API:我们保留对未发现使用记录的API进行向后不兼容更改的权利(通过GitHub搜索对TensorFlow使用情况进行审核)。在进行任何此类更改之前,我们将在announce @邮件列表中宣布我们打算进行更改,并提供有关如何解决任何破损的说明(如果适用),并等待两周,以便我们的社区有机会分享他们的反馈意见。

  • 错误行为:我们可以将错误替换为非错误行为。例如,即使记录了错误,我们也可以更改函数以计算结果而不是引发错误。我们也保留更改错误消息文本的权利。此外,错误的类型可能会更改,除非在文档中指定了特定错误情况的异常类型。

SavedModel,图形和检查点的兼容性

SavedModel是在TensorFlow程序中使用的首选序列化格式。 SavedModels包含两个部分:一个或多个编码为GraphDefs图形和一个Checkpoint。图形描述了要运行的操作的数据流,检查点包含图形中变量的已保存张量值。

许多TensorFlow用户创建SavedModels,并在更高版本的TensorFlow中加载并执行它们。为了符合semver的要求 ,可以使用具有相同主要版本的TensorFlow的更高版本加载和评估使用TensorFlow的一个版本编写的SavedModels

我们为受支持的 SavedModels提供其他保证。我们将TensorFlow主版本N 使用未弃用,非实验,不兼容的API创建的SavedModel称为版本N支持SavedModel 。 TensorFlow主版本N支持的任何SavedModel均可使用TensorFlow主版本N+1加载和执行。但是,构建或修改此类模型所需的功能可能不再可用,因此,此保证仅适用于未修改的SavedModel。

我们将努力保持尽可能的向后兼容性,以便序列化的文件可以长时间使用。

GraphDef兼容性

图形通过GraphDef协议缓冲区进行序列化。为了促进图形的向后不兼容更改,每个GraphDef的版本号都与TensorFlow版本分开。例如, GraphDef版本17不赞成使用inv op,而建议使用reciprocal 。语义是:

  • 每个TensorFlow版本都支持一定间隔的GraphDef版本。此间隔在补丁程序发行版中将是恒定的,并且只会在次要发行版中增大。仅在主要版本的TensorFlow中放弃对GraphDef版本的支持(并且仅与对SavedModels保证的版本支持保持一致)。

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

  • 如果给定版本的TensorFlow支持图的GraphDef版本,则它将加载和评估其行为与用于生成它的TensorFlow版本相同(除了上面概述的浮点数字详细信息和随机数),无论其主要版本的TensorFlow。特别是,只要支持GraphDef,与TensorFlow的一个版本中的检查点文件兼容的GraphDef(例如SavedModel中的情况)将在后续版本中与该检查点兼容。

    请注意,这仅适用于GraphDefs(和SavedModels)中的序列化Graph:读取检查点的代码可能无法读取由运行不同版本的TensorFlow的同一代码生成的检查点。

  • 如果GraphDef 上限在次要版本中增加到X,则至少要等六个月才能将下限增加到X。例如(我们在这里使用假设的版本号):

    • TensorFlow 1.2可能支持GraphDef版本4至7。
    • TensorFlow 1.3可以添加GraphDef版本8并支持版本4至8。
    • 至少六个月后,TensorFlow 2.0.0可能会放弃对版本4至7的支持,仅保留版本8。

    请注意,由于TensorFlow的主要版本通常分开发布超过6个月,因此上面详述的对SavedModels支持的保证比对GraphDefs的6个月保证要强得多。

最后,当放弃对GraphDef版本的支持时,我们将尝试提供用于将图自动转换为较新支持的GraphDef版本的工具。

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

仅当对GraphDef格式进行不兼容的更改(例如添加操作,删除操作或更改现有操作的功能)时,此部分才有意义。上一部分对于大多数用户来说就足够了。

向后和部分向前兼容性

我们的版本控制方案具有三个要求:

  • 向后兼容以支持加载使用旧版TensorFlow创建的图形和检查点。
  • 前向兼容性以支持在使用者之前将图形或检查点的生成器升级到TensorFlow的较新版本的方案。
  • 以不兼容的方式启用不断发展的TensorFlow。例如,删除操作,添加属性和删除属性。

请注意,虽然GraphDef版本机制与TensorFlow版本是分开的,但是对GraphDef格式的向后不兼容更改仍受语义版本限制。这意味着只能在TensorFlow的MAJOR版本之间(例如1.72.0 )删除或更改功能。此外,在修补程序版本(例如1.x.11.x.2 )中强制实施向前兼容性。

为了实现向后和向前的兼容性并知道何时实施格式更改,图形和检查点具有描述何时生成的元数据。以下各节详细介绍了TensorFlow实施以及有关GraphDef版本发展的GraphDef

独立的数据版本方案

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

数据,生产者和消费者

我们区分以下几种数据版本信息:

  • 生产者 :产生数据的二进制文件。生产者具有一个与其兼容的版本( producer )和一个最低使用者版本( min_consumer )。
  • 消费者 :使用数据的二进制文件。使用者具有min_producer兼容的版本( consumer )和最低生产者版本( min_producer )。

每个版本化数据都有一个VersionDef versions字段,该字段记录producer数据的min_consumer ,与之兼容的bad_consumers以及不允许的bad_consumers版本列表。

默认情况下,当生产者生成一些数据时,数据将继承生产者的producer版本和min_consumer版本。如果已知特定使用者版本包含错误并且可以避免,则可以设置bad_consumers 。如果满足以下所有条件,则消费者可以接受一条数据:

  • consumer > =数据的min_consumer
  • 数据的producer > =消费者的min_producer
  • consumer不在数据的bad_consumers

由于生产者和消费者都来自同一TensorFlow代码库,因此core/public/version.h包含一个主数据版本,根据上下文以及min_consumermin_producer (分别由生产者和消费者需要)将其视为producerconsumer 。 。特别,

  • 对于GraphDef版本,我们有TF_GRAPH_DEF_VERSIONTF_GRAPH_DEF_VERSION_MIN_CONSUMERTF_GRAPH_DEF_VERSION_MIN_PRODUCER
  • 对于检查点版本,我们有TF_CHECKPOINT_VERSIONTF_CHECKPOINT_VERSION_MIN_CONSUMERTF_CHECKPOINT_VERSION_MIN_PRODUCER

将新属性默认添加到现有操作中

仅在操作集未更改的情况下,遵循以下指导即可为您提供向前兼容性:

  1. 如果前向兼容性是期望的,设置strip_default_attrsTrue ,而使用任一个导出模型tf.saved_model.SavedModelBuilder.add_meta_graph_and_variablestf.saved_model.SavedModelBuilder.add_meta_graph所述的方法SavedModelBuilder类,或tf.estimator.Estimator.export_saved_model
  2. 在生成/导出模型时,这会剥去默认值属性。使用默认值时,这可以确保导出的tf.MetaGraphDef不包含新的op属性。
  3. 拥有此控件可以使过时的使用者(例如,服务二进制文件落后于训练二进制文件)继续加载模型并防止模型服务中断。

不断发展的GraphDef版本

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

添加操作

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

添加操作并切换现有的Python包装器以使用它

  1. 实现新的使用者功能并增加GraphDef版本。
  2. 如果可以使包装器仅在以前不起作用的情况下使用新功能,则可以立即更新包装器。
  3. 更改Python包装器以使用新功能。不要增加min_consumer ,因为不使用此op的模型不会min_consumer

删除或限制操作的功能

  1. 修复所有生产者脚本(不是TensorFlow本身)以不使用禁止的操作或功能。
  2. 增加GraphDef版本并实现新的使用者功能,该功能禁止在新版本及更高版本上删除GraphDef的操作或功能。如果可能的话,使TensorFlow停止产生具有禁止功能的GraphDefs 。为此,添加REGISTER_OP(...).Deprecated(deprecated_at_version, message)
  3. 等待主要版本以实现向后兼容。
  4. min_producer从(2)增加到GraphDef版本,并完全删除功能。

更改操作的功能

  1. 添加一个名为SomethingV2或类似版本的新类似操作,并完成添加过程以及切换现有Python包装程序以使用它的过程。为了确保向前兼容, 在更改Python包装器时使用compat.py中建议的检查方法。
  2. 删除旧的操作(由于向后兼容,只能进行主要版本更改)。
  3. 增加min_consumer可以排除使用旧操作的消费者,将旧操作重新添加为SomethingV2的别名,并完成切换现有Python包装程序以使用它的过程。
  4. 完成删除SomethingV2的过程。

禁止使用一个不安全的消费者版本

  1. 撞击GraphDef版本,并添加不良版本bad_consumers所有新GraphDefs。如果可能,仅对包含某些操作或类似操作的GraphDef添加到bad_consumers
  2. 如果现有使用者使用的版本不正确,请尽快将其推出。