ONNX 发布¶
ONNX 项目今后计划大致每四个月发布一次。我们遵循 Semver 版本控制方法,并将作为一个社区,根据每次发布的情况决定是进行主要版本发布还是次要版本发布。
准备工作¶
确定新发布的版本号 (X.Y.Z)
在 Slack 发布频道讨论 (https://lfaifoundation.slack.com/archives/C018VGGJUGK)
对于 (v.X.Y.Z),如果发布版本是 1.16.0,
X=1, Y=16, Z=0
新的分支将是
rel-1.16.0
符合此格式的分支会自动应用分支保护规则。
新的标签将是
v1.16.0
在发布物流 Wiki 中为该发布创建新页面
创建发布分支¶
在
main
分支,在创建发布分支之前在 version.h 中更新
LAST_RELEASE_VERSION
。设置为 X.Y.Z,这与您当前正在创建的发布分支相同。
切出发布分支后,
main
中的VERSION_NUMBER
将增加到下一个未来版本。
确保 ONNX proto 文件、Versioning.md、schema.h、helper.py 和 helper_test.py 中的发布版本、IR 版本、ai.onnx opset 版本、ai.onnx.ml opset 版本以及 ai.onnx.training opset 版本对于新发布是正确的。
创建一个发布分支
从 分支 中点击“New branch”并选择
main
作为 Source。确保新分支上的所有测试都通过。
切出发布分支后
创建 PR 将
main
中的 VERSION_NUMBER 文件设置为下一个未来版本X.Y+1.0
。创建 PR 将新发布分支中的
VERSION_NUMBER
文件设置为X.Y.Zrc1
。例如,1.16.0 的第一个发布候选版本将是
1.16.0rc1
更新
onnx/defs/operator_sets.h
和onnx/defs/schema.h
中 ai.onnx 域的 opset 版本,以供未来算子添加和更改使用。例如,这个示例 PR。
将发布候选版本上传到 TestPyPI¶
重要
**等待** 设置发布分支
VERSION_NUMBER
的 PR 合并并构建完成后再继续。要将文件推送到 TestPyPI 或 PyPI,如果尚未安装
twine
,请安装它:pip install twine
当
twine
命令提示输入密码时,请使用 API token。您的密码将无法使用。注意:TestPyPI 和 PyPI 是独立的账户,因此请根据您上传的位置确保使用正确的账户。
与 PyPI 类似,一个发布版本只能推送到 TestPyPI **一次**。
要更新已推送的文件,您必须增加
VERSION_NUMBER
,重新构建,并推送新的 X.Y.Zrc2 等。要测试推送命令,您可以使用 docker 或 podman 创建一个本地 pypi 服务器
启动服务器
docker run --rm -it --platform linux/amd64 -p 80:8080 pypiserver/pypiserver:latest run -a . -P .
这将启动一个不需要认证的本地 pypiserver(任何用户/密码都可以使用)。
容器不保存状态。停止并再次启动它将允许您多次推送同一版本。
推送文件
wheels:
twine upload --repository-url http://127.0.0.1:80 --verbose -u fake -p fake *.whl
源码包:
twine upload --repository-url http://127.0.0.1:80 --verbose -u fake -p fake dist/*
从您的测试服务器拉取并安装
pip uninstall -y onnx && pip install --index-url http://127.0.0.1:80/simple/ --pre onnx
推送 Wheels
从 ONNX Github Actions 中收集发布候选版本的 wheel 文件。
ONNX GitHub Action
找到发布分支的运行
或者通过点击“Run workflow”,选择发布分支,点击“Run Workflow”来启动运行
点击已完成的运行,滚动到底部找到“Artifacts”部分,点击“wheels”下载文件
解压 wheels.zip 文件,并将其内容合并到一个文件夹中
手动将生成的 wheels 上传到 TestPyPI:
twine upload --repository testpypi --verbose -u <YOUR_TESTPYPI_USER> <extracted_wheel.zip_folder>/*.whl
。在推送文件之前,ONNX 项目的当前所有者需要授予您访问权限。
项目名称和版本内置在文件中。
源码分发包
确保所有 git 子模块已更新
git submodule update --init
确保 git 工作区是干净的 –
运行
git clean -nxd
确保不存在以下自动生成的头文件。
onnx/onnx-operators.pb.cc
onnx/onnx-operator.pb.h
onnx/onnx.pb.cc
onnx/onnx.pb.h
如果它们存在,运行
git clean -ixd
并从本地分支中删除这些文件
生成源码分发文件:
python -m build --sdist
如果尚未安装
build
包,运行pip install build
。
将源码分发文件上传到 TestPyPI:
twine upload --repository testpypi --verbose -u <YOUR_TESTPYPI_USER> dist/*
注意
在推送文件之前,ONNX 项目的当前所有者需要授予您访问权限。
项目名称和版本内置在文件中。
确认 TestPyPI 包可以安装
Wheel 安装:
pip uninstall -y onnx && pip install -i https://test.pypi.org/simple/ --pre onnx
假设您的环境有预构建的 wheel 包可用,否则将开始源码安装。
源码安装:
pip uninstall -y onnx && pip install -i https://test.pypi.org/simple --no-binary onnx --pre onnx
包验证¶
测试 ONNX 本身
测试 PyPI 包安装在各种 Python 版本、Protobuf 版本和平台的不同组合下的情况。
安装 TestPyPI 包后,在发布分支中运行
pytest
。Python 版本:适用于该发布的 Python 版本。
Protobuf 版本:发布时的最新 protobuf 版本 + 上一个发布使用的 protobuf 版本
合作伙伴验证
使用 onnxruntime 包进行测试
使用已安装的 onnxruntime 包运行 test_with_ort.py 中的测试脚本。
脚本使用 onnxruntime 函数如
InferenceSession
和InferenceSession.run
在某些示例 ONNX 模型上测试 ONNX 函数如load
、checker.check_model
和shape_inference.infer_shapes
。
为外部仓库创建 Issue
在转换器仓库中创建 GitHub issue,向他们提供包链接,并让他们有机会在发布公开之前测试该版本。
https://github.com/microsoft/onnxruntime
注意:他们的仓库中有一个 How_To_Update_ONNX_Dev_Notes 文件,其中记录了如何拉取新的 ONNX 发布。
如果发现问题,bug 应在 onnx
main
分支中修复,然后 cherry-pick 到发布分支。与报告者跟进,确保问题已解决(并在新的 rc 版本中验证)或推迟到新发布。
正式发布¶
在此之前必须完成验证步骤!这是关键点。
git 标签一旦发布就不应更改
一旦推送到 PyPI,就无法更新该发布。必须创建一个新的发布来代替。
设置最终版本号¶
创建 PR 从新发布分支中的
VERSION_NUMBER
文件中移除 “rcX
” 后缀。
创建发布标签¶
上传到正式 PyPI¶
注意:¶
一旦包上传到 PyPI,**您无法在同一 PyPI 实例上覆盖它**。
**在上传到 PyPI 之前,请确保 TestPyPI 上的一切都正常**
PyPI 的登录信息、密码和 API token 与 TestPyPI 是分开的,但过程相同。ONNX PyPI 所有者需要授予访问权限等。
按照上面将发布候选版本上传到 TestPyPI 中的 **Wheels** 和 **源码分发包** 步骤进行,并做如下更改
在您的 PyPI 账户(**API tokens** 部分)中创建一个 onnx 范围的新 API token 用于上传 onnx wheel 包。
推送该发布的 wheel 包和源码包后,移除创建的 token。
上传时,从 twine 命令中移除
--repository testpypi
。验证上传时,从 pip 命令中移除
-i https://test.pypi.org/simple/
和--pre
。
PyPI 发布后¶
公告
Slack
在 onnx-release 和 onnx-general 频道发布。
通过电子邮件列表通知 ONNX 合作伙伴
ONNX 新闻发布
更新 news.json,参见 示例 news.json PR
使用新的 ONNX 版本更新 conda-forge 包
ONNX 的 Conda 构建通过 conda-forge/onnx-feedstock 进行,该仓库运行用于构建包并将其上传到 conda-forge 的基础设施。
发布在 https://github.com/onnx/onnx/releases 可用后,
regro-cf-autotick-bot
应会自动创建 PR。如果自动 PR 构建失败
fork conda-forge/onnx-feedstock 到您的个人仓库
基于自动 PR 分支创建一个个人分支
解决构建问题
基于您的分支提交一个替代 PR
如果自动 PR 未创建,您需要手动提交一个 PR
注意:使用发布页面 https://github.com/onnx/onnx/releases 中该发布 tar.gz 文件的 sha256 哈希值 (
sha256sum onnx-X.Y.Z.tar.gz
)。
合并到 main 分支
如果直接在发布分支中进行了紧急更改,请将发布分支合并回 main 分支。
如果合并到发布分支(切出后)的所有 PR 都是从 main 分支 cherry-pick 的,则合并 PR 将显示为空,此步骤不需要。
移除 PyPI 上的旧 onnx-weekly 包
移除 PyPI 上针对刚刚发布的版本的所有onnx-weekly 包,以节省空间。
步骤
-
这是一个与 onnx 发布分开的项目,因此您可能需要向所有者请求访问权限
点击目标包 -> 选项 -> 删除。
-
移除 PyPI 上的旧发布候选包
移除 PyPI 上至少早于上一个发布版本指定时间的onnx 发布候选包,以节省空间。
步骤
-
这是一个与 onnx 发布分开的项目,因此您可能需要向所有者请求访问权限
点击目标包 -> 选项 -> 删除。
-