ONNX 版本控制

本文档描述了 ONNX 版本控制的规则。MUST、SHOULD 等词语的使用与 RFC2119 保持一致。

版本控制原则

ONNX 定义了三类实体的版本控制策略和机制

  • 中间表示 (IR) 规范，它是图和操作符的抽象模型以及表示它们的具体格式。这些始终原子地进行版本控制，并被称为 IR 版本。

  • 给定 ONNX 图可能引用的操作符规范。我们将其称为 操作符版本。

  • 一个已定义/已训练的模型，它根据特定操作符定义了一个特定图。我们将其称为 模型版本。

所有这三种实体类型的版本控制是独立且基本不相关的。IR 规范的演变速度与操作符规范不同（通常更慢）。模型版本完全独立于其他两个版本。

仅强制要求 IR 版本和操作符版本的版本管理特定策略。对于模型版本控制，它们仅是建议。对于模型版本控制，ONNX 用户和系统可以遵循任何有意义的本地习俗；但是，为了方便管理共享的 ONNX 模型集合，他们应该遵守模型版本控制下描述的策略。

新的 IR 和操作符版本作为 ONNX 发布 的一部分发布，它们有自己的版本控制方案。发布版本控制方案不作为标准本身的一部分进行描述。它在 ONNX 发布管理文档 中讨论。

语义版本控制还是简单数字？

ONNX 版本控制系统允许简单的单调递增数字或 语义版本控制 (SemVer)。对于 IR 和操作符集，版本控制基于简单数字。对于模型，ONNX 不要求任何方案，但建议一组共享约定。

通过检查最重要的四个字节，可以清楚地知道模型使用了哪种版本控制方案，使用语义版本控制时必须非零，使用简单数字时必须为零。换句话说，当使用 SemVer 时，MAJOR 或 MINOR 数字中至少有一个必须非零。

SemVer、文件和消费者

对于模型和发布版本控制，ONNX 建立在 SemVer 2.0.0 定义的原则和语法之上。在本文档中，我们使用与 SemVer 2.0.0 一致的术语 破坏性更改、非破坏性更改 和 补丁。

由于 ONNX 模型是序列化文件（而不是 API），因此有必要阐明序列化模型与消费该模型的一段软件之间的关系。粗略地说，序列化模型扮演着 API 被调用者 的角色，而序列化模型的消费者扮演着 API 调用者 的角色。

ONNX 版本控制原则基于 健壮性原则：“对你所做的事情要保守，对你从别人那里接受的东西要自由”。

  1. 给定 ONNX 模型的生产者（以及 ONNX 规范本身）必须严格遵守本规范中定义的关于破坏性与非破坏性更改的规则。

  2. 给定 ONNX 模型的消费者应该消费更新的 ONNX 文件，前提是新 ONNX 文件的 IR 版本、引用的操作符版本或模型版本没有破坏性更改（这意味着两个 ONNX 文件之间的 MAJOR 版本号没有改变）。

  3. 给定 ONNX 模型的消费者可以消费更新的 ONNX 文件，前提是新 ONNX 文件的 IR 版本、引用的操作符版本或模型版本存在一个或多个破坏性更改。

在 protobuf 中序列化 SemVer 版本号

为了效率，ONNX 将 MAJOR、MINOR 和 PATCH 值序列化为位打包的 64 位整数；最重要的两个字节是 MAJOR 组件，接下来的两个最重要的字节是 MINOR 组件，最不重要的四个字节是 PATCH 组件。

例如，1.2.345 表示为 0x0001000200000159。

预发布和构建元数据不存储在模型中。

IR 版本控制

IR 格式使用简单数字进行版本控制，这些数字必须单调递增。对 ONNX 规范的格式或语义进行破坏性更改需要增加版本。对 IR 格式进行非破坏性更改不需要更改版本号。

注意：破坏性更改包括那些不改变序列化二进制格式，但仍然会破坏使用写入或读取它的库的软件的更改。例如，更改消息属性的拼写会导致访问该属性的代码中断。

IR 格式遵循 proto3 规范的 更新消息类型 部分中定义的版本控制指南。

作为一般原则，实现应该在面对缺少字段时保持健壮。但是，为了确保基本的互操作性，消息字段的子集将被标记为给定 IR 版本的必需字段，并且所有生产者必须正确设置这些字段。必需字段必须始终用注释标记

// This field MUST be present for this version of the IR.

例如，ModelProto.ir_version 属性必须存在于每个模型中。ONNX 检查器 (onnx/checker.py) 将强制执行这些规则。

由于协议缓冲区消息定义（.proto / .proto3 文件）预计将由多个独立开发人员使用，因此对这些定义的更改不应破坏依赖于生成的语言绑定（例如，更改现有字段的类型）的代码。

操作符版本控制

IR 可以独立于操作符集发展。操作符表示给定操作的签名和语义。操作符是抽象接口，因为它们不暗示特定的实现；相反，它们只是模型作者和模型可能执行的实现之间的契约。

给定操作符由一个三元组标识：(domain, op_type, since_version)，在散文中写为 domain.op_type:since_version（例如，com.acme.FastConv:3）。since_version 是引入该操作符的操作符集的版本。破坏性操作符更改包括

  • 添加/删除/重命名属性。这甚至包括添加新可选属性的情况，其中省略该属性将意味着默认值，产生与以前的操作符版本相同的语义。

  • 添加/删除/重新排序输入或输出。

  • 添加/删除输入和输出支持的类型，以及更改属性使用的类型。

  • 支持新行为，即使现有参数签名 otherwise 相同（例如，在 Mean 操作符中隐式支持张量广播）。

以下不是破坏性更改

  • 澄清规范模糊性以匹配主流实现实践。

操作符或函数的语义更改必须在新的操作符中引入，该操作符必须在新的 操作符集 中引入。

实际上，这意味着 ONNX 存储库中的 BC 破坏性更改要求贡献者遵循以下步骤

  1. 增加 DomainToVersionRange 中的最大版本。

  2. 将旧操作符模式复制到 old.cc 文件。

  3. 将 SinceVersion 标识符更新为步骤 (1) 中的新最大版本。

  4. 在相应的 operator_sets 头文件中注册新操作符。

  5. 向 convert.h 添加版本适配器，以便版本转换器可以将旧版本的操作符升级到新版本。这可以是 CompatibleAdapter，以防遵循旧模式的操作符在新模式下仍然有效（通常如此）。

  6. 也可以向 convert.h 添加一个版本适配器，用于将新操作符降级到旧版本，但这不是强制性的。

节点如何绑定到操作符声明是严格定义的，并且旨在本着健壮性原则的保守条款的精神，提高 ONNX 实现的模型兼容性。

ONNX 实现如何将操作符声明绑定到特定实现超出了本规范的范围。ONNX 实现可以本着健壮性原则的自由条款的精神，选择引入更复杂的操作符声明/实现绑定模式。

操作符集

ONNX 使用操作符集将不可变操作符规范分组在一起。操作符集表示一个特定版本的域，由一对 (domain, version) 指示。这表示属于指定域且具有指定版本（称为 opset_version）的所有操作符的集合。当给定操作符集的清单因添加、删除或包含操作符的语义更改而发生变化时，其版本必须增加。

模型在 ModelProto.opset_import 中声明它们需要哪些操作符集，作为 (domain, opset_version) 对的列表。空字符串 (“”) 域表示作为 ONNX 规范一部分定义的操作符；其他域对应于其他供应商的操作符集（这意味着它们可用于为 ONNX 提供供应商特定的扩展）。给定模型指定的运算符集的并集必须为模型图中的每个节点提供兼容的运算符声明。

示例

本节不具有规范性，仅供参考。

给定以下操作符集

操作符集

操作符

注释

1

{A}

A 引入

2

{A, B}

B 引入

3

{A’, B, C}

A 更新（到 A'），C 引入

4

{B, C’}

A 删除，C 更新（到 C'）

给定操作符集的操作符将具有以下 since_version 值

Operator

操作符集 1

操作符集 2

操作符集 3

操作符集 4

A

1

1

3

-

B

-

2

2

2

C

-

-

3

4

注释

  • 与先前操作符集版本相比，新增或更新的值以 粗体 显示。

模型版本控制

本规范的这一部分不具有规范性。它仅概述了一组推荐实践。

模型作者和应用程序/系统可以选择忽略模型版本控制机制和策略规则。对于将在开发人员、团队或组织之间共享的模型，模型作者和应用程序/系统应该遵守以下版本策略

签名更改

  1. 对 ModelProto.graph.GraphProto.input 或 .output 的破坏性更改必须增加 ModelProto.model_version 的 MAJOR 版本。破坏性更改包括

    • 对输入或输出的语义进行破坏性更改（例如，将输入张量所需内容从彩色图像更改为黑白图像）。

    • 将输入或输出的声明类型更改为不兼容的类型（例如，tensor(int)->tensor(string)）。

    • 添加没有有意义或指定默认值的新输入。回想一下，输入的默认值在初始化程序列表中指定。

    • 删除没有有意义或指定默认值的现有输出。

  2. 对 ModelProto.graph.GraphProto.input 或 .output 的非破坏性更改必须增加 ModelProto.model_version 的 MINOR 版本。非破坏性更改包括

    • 将输入或输出的声明类型更改为兼容/扩展类型（例如，tensor(int32)->tensor(int64)、tensor(float16)->tensor(float32)）。

    • 添加具有有意义或指定默认值的新输入。

    • 添加仅在存在旧版本图中不可能存在的输入时（通常通过存在新输入或允许以前无效的输入值）触发的新行为。

精度或性能变化

显著影响精度或性能但未改变模型输入或输出的更改，应增加 ModelProto.model_version 的 PATCH 版本。

已发布版本

ONNX 版本

IR 版本

Opset 版本 ai.onnx

Opset 版本 ai.onnx.ml

Opset 版本 ai.onnx.training

1.0

3

1

1

-

1.1

3

5

1

-

1.1.2

3

6

1

-

1.2

3

7

1

-

1.3

3

8

1

-

1.4.1

4

9

1

-

1.5.0

5

10

1

-

1.6.0

6

11

2

-

1.7.0

7

12

2

1

1.8.0

7

13

2

1

1.8.1

7

13

2

1

1.9.0

7

14

2

1

1.10.0

8

15

2

1

1.10.1

8

15

2

1

1.10.2

8

15

2

1

1.11.0

8

16

3

1

1.12.0

8

17

3

1

1.13.0

8

18

3

1

1.13.1

8

18

3

1

1.14.0

9

19

3

1

1.14.1

9

19

3

1

1.15.0

9

20

4

1

1.16.0

10

21

5

1

1.16.1

10

21

5

1

1.16.2

10

21

5

1

1.17.0

10

22

5

1

1.18.0

11

23

5

1

1.19.0

12

24

5

1

1.19.1

12

24

5

1

1.20.0

13

25

5

1

上述表格的编程可访问版本可在 此处 找到。有限的版本号信息也保存在 version.h 和 schema.h 中。每当发布新版本 ONNX 时，请更新所有这些文件。