 ONNX 子模塊完整指南：從依賴安裝到文檔與測(cè)試同步)
ONNX Runtime 升級(jí) ONNX 子模塊完整指南從依賴安裝到文檔與測(cè)試同步【免費(fèi)下載鏈接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator項(xiàng)目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime導(dǎo)讀本文面向 ONNX Runtime 的開發(fā)者系統(tǒng)梳理在 ONNX Runtime 倉(cāng)庫(kù)中升級(jí) ONNXONNX 規(guī)范與算子定義到新版本/新提交的完整操作流程。全文圍繞三條主線展開C 依賴的兩種安裝路徑cmake/deps.txt下載構(gòu)建與 vcpkg 包管理的同步更新、自動(dòng)生成文檔算子內(nèi)核表、WebGL 算子表與 Pythonrequirements.txt的再生成、以及升級(jí)后測(cè)試用例與優(yōu)化器的配套更新。讀完本文你將掌握一次可交付的 ONNX 版本升級(jí)從改代碼到過(guò) CI 的每一步實(shí)操細(xì)節(jié)。本文內(nèi)容以 docs/How_To_Update_ONNX_Dev_Notes.md 為骨架并結(jié)合當(dāng)前倉(cāng)庫(kù)中 cmake/deps.txt、cmake/vcpkg-ports/onnx/portfile.cmake、cmake/patches/onnx/onnx.patch、tools/python/gen_opkernel_doc.py、tools/python/find_optimizer_opset_version_updates_required.py 等文件進(jìn)行源碼級(jí)印證。一、升級(jí)前的總覽ONNX 依賴的兩條安裝路徑ONNX Runtime 目前支持兩種方式安裝 ONNX 的 C 依賴二者均受 CI 覆蓋cmake/deps.txt下載構(gòu)建路徑在 cmake/deps.txt 中以名稱;URL;SHA1的 CSV 行描述所有第三方依賴構(gòu)建時(shí)由 CMake 下載源碼包并編譯。vcpkg 包管理路徑通過(guò) cmake/vcpkg-ports/onnx/portfile.cmake 等端口文件把 ONNX 作為 vcpkg 包安裝。官方建議在 Windows 機(jī)器上測(cè)試 vcpkg 路徑。以當(dāng)前倉(cāng)庫(kù)為例cmake/deps.txt 中 ONNX 被固定為v1.22.0發(fā)布版onnx;https://github.com/onnx/onnx/archive/refs/tags/v1.22.0.zip;2b2cd58ac7a26df5371266149e0c76776330cdf1其注釋還記錄了一次典型的“純版本升級(jí)”經(jīng)驗(yàn)從 rc2 到最終版僅涉及 CI workflow 與VERSION_NUMBER的改動(dòng)算子 schema、opset 與測(cè)試數(shù)據(jù)均無(wú)變化因此可直接升級(jí)。這說(shuō)明升級(jí)前先比對(duì)目標(biāo)版本與當(dāng)前版本之間onnx/defs、opset 與 testdata 的差異可以顯著降低后續(xù)工作量。二、更新 ONNX 子模塊SubmoduleONNX Runtime 通過(guò) git submodule 引用 ONNX 源碼掛在cmake/external/onnx下。升級(jí)的第一步是把子模塊切到目標(biāo)提交。文檔強(qiáng)調(diào)用 commit id 比用分支更精確可追溯、可復(fù)現(xiàn)。cd cmake/external/onnx git remote update git reset --hard commit_id cd .. git add onnx將commit_id替換為你的目標(biāo)提交如果不確定具體提交可以使用origin/main例如git reset --hard origin/main。執(zhí)行完成后父?jìng)}庫(kù)記錄下子模塊的新指針git add onnx使該變更進(jìn)入暫存區(qū)。三、更新 cmake/deps.txt 下載路徑當(dāng)采用 deps.txt 下載構(gòu)建路徑時(shí)需要同步更新下載源與校驗(yàn)值更新 cmake/deps.txt把 ONNX 行的 zip 下載鏈接與 SHA1 改為新版本對(duì)應(yīng)的值。文件頭部注釋說(shuō)明了校驗(yàn)值的生成方式Linux 下運(yùn)行sha1sumPowerShell 下可用(Get-FileHash -Algorithm SHA1 filename).Hash.ToLower()。文檔同時(shí)給出一個(gè)取巧技巧先用錯(cuò)誤的 SHA 構(gòu)建ORT 會(huì)在報(bào)錯(cuò)信息中直接告訴你期望的 SHA。檢查 cmake/patches/onnx/onnx.patch確認(rèn) patch 中的 diff 是否已在最新的 ONNX 版本中被上游解決被解決的部分應(yīng)移除。當(dāng)前倉(cāng)庫(kù)的 patch 內(nèi)容反映了兩個(gè)典型的 ORT 側(cè)需求為 ONNX 的CMakeLists.txt增加ONNX_MINIMAL_BUILD選項(xiàng)使 WebAssembly/最小化構(gòu)建只需data_type_utils.cc與生成的 protobuf 源碼跳過(guò)完整算子/schema 源碼去掉GroupNormalization算子 ver18 schema 上的Deprecate()標(biāo)記保證 ORT 對(duì)該算子的兼容性。 可見該 patch 是 ORT 與上游 ONNX 行為差異的“粘合層”每次升級(jí)都必須重新評(píng)估。從源碼構(gòu)建 ONNXRUNTIME 驗(yàn)證文檔給出的示例構(gòu)建命令CUDA 12.6 環(huán)境、構(gòu)建 wheel、并行編譯、跳過(guò)測(cè)試./build.sh --config RelWithDebInfo --use_cuda --cuda_home /usr/local/cuda-12.6/ --cudnn_home /usr/local/cuda-12.6/ --build_wheel --parallel --skip_tests如果構(gòu)建失敗屬于 ONNX 自身的問(wèn)題修改/補(bǔ)充onnx.patch屬于 ORT 適配問(wèn)題則直接修改 ORT 側(cè)代碼。四、更新 cmake/vcpkg-ports 端口采用 vcpkg 路徑時(shí)需要維護(hù) cmake/vcpkg-ports/onnx/ 目錄下的端口文件步驟如下同步 cmake/vcpkg-ports/onnx/binskim.patch文檔要求將其內(nèi)容與 cmake/patches/onnx/onnx.patch 保持一致——即 deps.txt 路徑的補(bǔ)丁與 vcpkg 路徑的補(bǔ)丁同源同步避免兩條安裝路徑行為分叉。重新 diff 其余 patchcmake/vcpkg-ports/onnx/ 下除 binskim.patch 外的其他補(bǔ)丁如fix-cmakelists.patch、fix-dependency-protobuf.patch是 vcpkg 倉(cāng)庫(kù)構(gòu)建 ONNX 所必需/創(chuàng)建的升級(jí)后需要重新運(yùn)行 diff 確認(rèn)這些補(bǔ)丁仍能干凈地應(yīng)用到新版 ONNX 上。這一點(diǎn)可從 portfile.cmake 的PATCHES段得到印證vcpkg_from_github( OUT_SOURCE_PATH SOURCE_PATH REPO onnx/onnx REF v1.22.0 SHA512 13fafff073a8e0bcf67fd06195da979c3c6273b3f5fdd25f5e5c39ad6af20eefe107f13dc73d52b6021e986d87401e46121e00bba8fbd09f098334e34f78462f PATCHES fix-cmakelists.patch fix-dependency-protobuf.patch binskim.patch )更新 cmake/vcpkg-ports/onnx/portfile.cmake將REF改為新 commit id 或 tag將SHA512改為新源碼包的校驗(yàn)值。同樣可用“故意填錯(cuò) SHA512 觸發(fā)構(gòu)建報(bào)錯(cuò)、ORT 提示期望值”的辦法獲取正確哈希。portfile.cmake中其余邏輯展示了 vcpkg 端口的關(guān)鍵約束可作為修改時(shí)的背景知識(shí)vcpkg_check_linkage(ONLY_STATIC_LIBRARY)僅支持靜態(tài)庫(kù)鏈接通過(guò)find_program(PROTOC ...)定位 protobuf 自帶的protoc并分別透?jìng)鱋NNX_CUSTOM_PROTOC_EXECUTABLE與Protobuf_PROTOC_EXECUTABLE根據(jù) protobuf 庫(kù)文件名后綴判斷ONNX_USE_PROTOBUF_SHARED_LIBS取值配置ONNX_MLON、關(guān)閉測(cè)試與 benchmark并清理安裝目錄中 ORT 不需要的include/onnx/defs/*、onnx/reference等子目錄以縮減包體積。上傳包按 vcpkg 倉(cāng)庫(kù)內(nèi)部文檔說(shuō)明上傳新包也可直接用 Terrapin 工具上傳 ONNX 包需要 SHA512示例命令如下C:\local\Terrapin\TerrapinRetrievalTool.exe -b https://vcpkg.storage.devpackages.microsoft.io/artifacts/ -a true -u Environment -p onnx源碼tar.gz地址 -s SHA512 -d 本地下載臨時(shí)文件路徑從源碼構(gòu)建驗(yàn)證與 deps.txt 路徑類似文檔給出的 vcpkg 構(gòu)建示例僅多出--use_vcpkg開關(guān)./build.sh --config RelWithDebInfo --use_cuda --cuda_home /usr/local/cuda-12.6/ --cudnn_home /usr/local/cuda-12.6/ --build_wheel --parallel --skip_tests --use_vcpkg五、更新 ONNX 相關(guān)自動(dòng)生成文檔ONNX 版本升級(jí)會(huì)改變可用的算子集合因此需要重新生成兩類自動(dòng)文檔并更新 Pythonrequirements.txt。5.1 重新生成 ONNX kernels 文檔OperatorKernels.md推薦直接從 CIAzureDevOps 發(fā)布的 Artifacts下載 CI 生成好的 markdown 上傳更新若希望本地生成則執(zhí)行# 在 onnxruntime 倉(cāng)庫(kù)根目錄下 python tools/python/gen_opkernel_doc.py --output_path docs/OperatorKernels.md從源碼看tools/python/gen_opkernel_doc.py 實(shí)際調(diào)用 Python 綁定的rtpy.get_all_operator_schema()與rtpy.get_all_opkernel_def()遍歷當(dāng)前構(gòu)建中注冊(cè)的全部算子 schema 與內(nèi)核定義按 Execution Provider 分組輸出表格并支持--providers按 EP 名過(guò)濾大小寫不敏感會(huì)自動(dòng)補(bǔ)齊ExecutionProvider后綴與--plugin-ep按NAME:PATH注冊(cè)插件 EP 并納入其內(nèi)核兩個(gè)可選參數(shù)。因此該命令必須基于升級(jí)后重新構(gòu)建的 ONNXRUNTIME運(yùn)行才能反映新 ONNX 版本的實(shí)際算子支持情況。文檔頭部也明確標(biāo)注了“由腳本自動(dòng)生成、請(qǐng)勿手工修改”。5.2 重新生成 WebGL 算子文檔webgl-operators.mdjs/web/docs/webgl-operators.md 由 js/web/script/generate-webgl-operator-md.ts 生成需要先在 JS 兩級(jí)目錄安裝依賴再構(gòu)建文檔# 在父級(jí) JS 目錄安裝依賴 cd /path/to/onnxruntime/js npm install # 在 web 目錄安裝依賴 cd /path/to/onnxruntime/js/web npm install # 構(gòu)建文檔 npm run build:doc5.3 更新 Python requirements.txt將以下文件中的 ONNX 版本號(hào)更新為新版本如onnx1.16.0若從源碼構(gòu)建則使用 commit hash 形式的 git 依賴如githttp://github.com/onnx/onnx.gittargetonnxcommithash#eggonnxonnxruntime/test/python/requirements.txttools/ci_build/github/linux/docker/scripts/requirements.txttools/ci_build/github/linux/docker/scripts/manylinux/requirements.txttools/ci_build/github/linux/python/requirements.txt當(dāng)前倉(cāng)庫(kù)的實(shí)際狀態(tài)可作參照上述文件均固定為onnx1.22.0另有 tools/ci_build/github/linux/docker/scripts/lort/requirements.txt 等 CI 輔助文件同樣固定該版本。文檔還提醒運(yùn)行g(shù)it grep -rn onnx1 .檢查是否還有其他位置引用了舊的 ONNX 版本號(hào)發(fā)現(xiàn)后一并更新必要時(shí)同步更新本文檔即 docs/How_To_Update_ONNX_Dev_Notes.md 本身。六、附加注意事項(xiàng)從代碼到 CI 的全鏈路檢查升級(jí) ONNX 不止改依賴還需處理以下連鎖影響重新生成 OnnxMl.cs如果cmake/external/onnx/onnx/*.in.proto有任何變更需要重新生成 C# 側(cè)OnnxMl.cs——構(gòu)建 NuGet 包--build_nuget相關(guān)流程會(huì)自動(dòng)完成這一步。部署新測(cè)試數(shù)據(jù)若從發(fā)布 tag 升級(jí)到新 commit需要聯(lián)系維護(hù)者文檔中為 ChangmingGitHub 名snnn把新測(cè)試數(shù)據(jù)連同其他測(cè)試模型部署到 CI 構(gòu)建機(jī)確保測(cè)試覆蓋每一個(gè) ONNX opset。提交 PR 并手動(dòng)排隊(duì)打包流水線PR 提交后需要手動(dòng)為分支的每一個(gè)打包流水線排隊(duì)構(gòu)建。WebAssembly CI 的文檔過(guò)期檢查如果 WebAssembly CI 流水線在 “Check out of dated documents” 階段失敗說(shuō)明 WebGL 算子支持文檔過(guò)期需要確保已安裝 Node.js參見 js/README.md 的 Prerequisites按 js/README.md 的 Build 章節(jié)安裝依賴按 Generating Document 章節(jié)更新文檔并將docs/operators.md的變更提交入庫(kù)。處理新增測(cè)試的失敗新版 ONNX 通常會(huì)帶來(lái)新測(cè)試可能觸發(fā)失敗此時(shí)需要更新onnxruntime/test/onnx/main.cconnxruntime/test/providers/cpu/model_tests.cccsharp/test/Microsoft.ML.OnnxRuntime.Tests.NetCoreApp/InferenceTest.netcore.csonnxruntime/test/testdata/onnx_backend_test_series_filters.jsonconnxruntime/test/testdata/onnx_backend_test_series_overrides.jsonc其中兩個(gè) JSONC 文件是 ONNX backend 測(cè)試系列的過(guò)濾器決定哪些用例被跳過(guò)與覆蓋項(xiàng)決定哪些用例的結(jié)果被覆蓋新算子/新 opset 加入后往往需要在這里增刪條目。檢查涉及變更算子的優(yōu)化器如果某個(gè)算子發(fā)生了變化涉及該算子的圖優(yōu)化器可能需要同步更新 opset 版本支持。運(yùn)行python tools/python/find_optimizer_opset_version_updates_required.py -o onnxruntime倉(cāng)庫(kù)根目錄從 tools/python/find_optimizer_opset_version_updates_required.py 源碼看該腳本會(huì)從onnxruntime/core/optimizer下所有.cc/.h中解析graph_utils::IsSupportedOptypeVersionAndDomain調(diào)用解析出每個(gè)優(yōu)化器聲稱支持的算子 opset 上限同時(shí)從 ORT 內(nèi)核注冊(cè)文件onnxruntime/contrib_ops/cpu/cpu_contrib_kernels.cc、onnxruntime/contrib_ops/cuda/cuda_contrib_kernels.cc與 ONNX 頭文件cmake/external/onnx/onnx/defs/operator_sets.h、operator_sets_ml.h提取每個(gè)算子的最新 opset兩者比對(duì)后輸出Newer opset found for ...類警告。將該腳本輸出與當(dāng)前 main 分支的輸出做對(duì)比檢查是否出現(xiàn)新的警告若有新警告聯(lián)系對(duì)應(yīng)優(yōu)化器的負(fù)責(zé)人通?？醋罱l(shuí)修改了相關(guān)文件或向 “ONNX Runtime Shared Core” 郵件列表求助。七、總結(jié)一次 ONNX 升級(jí)的完整清單將上述步驟收攏為可執(zhí)行的檢查清單階段關(guān)鍵動(dòng)作涉及倉(cāng)庫(kù)文件子模塊切換到目標(biāo) commit 并提交指針cmake/external/onnxsubmoduledeps.txt 路徑更新下載 URL SHA1評(píng)估 onnx.patch源碼構(gòu)建驗(yàn)證cmake/deps.txt、cmake/patches/onnx/onnx.patchvcpkg 路徑同步 binskim.patch重跑其余 patch diff更新 REF SHA512上傳包--use_vcpkg構(gòu)建驗(yàn)證cmake/vcpkg-ports/onnx/、portfile.cmake自動(dòng)文檔重新生成 OperatorKernels.md、webgl-operators.mdtools/python/gen_opkernel_doc.py、js/web/script/generate-webgl-operator-md.tsPython 依賴統(tǒng)一更新各 requirements.txt 并git grep查漏onnxruntime/test/python/requirements.txt 等測(cè)試與優(yōu)化器更新 backend 測(cè)試過(guò)濾器/覆蓋項(xiàng)運(yùn)行 optimizer 腳本排查onnx_backend_test_series_filters.jsonc、find_optimizer_opset_version_updates_required.py收尾重新生成 OnnxMl.csproto 變更時(shí)、部署測(cè)試數(shù)據(jù)、PR 后手動(dòng)排隊(duì) CINuGet 構(gòu)建流程、CI 打包流水線按照這份清單逐項(xiàng)推進(jìn)即可保證 ONNX 升級(jí)在依賴一致性、文檔時(shí)效性、測(cè)試覆蓋性與優(yōu)化器正確性四個(gè)維度同時(shí)達(dá)標(biāo)順利通過(guò)各條 CI 流水線。【免費(fèi)下載鏈接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator項(xiàng)目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 ONNX Runtime 升級(jí) ONNX 子模塊完整指南：從依賴安裝到文檔與測(cè)試同步
ONNX Runtime 升級(jí) ONNX 子模塊完整指南從依賴安裝到文檔與測(cè)試同步【免費(fèi)下載鏈接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator項(xiàng)目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime導(dǎo)讀本文面向 ONNX Runtime 的開發(fā)者系統(tǒng)梳理在 ONNX Runtime 倉(cāng)庫(kù)中升級(jí) ONNXONNX 規(guī)范與算子定義到新版本/新提交的完整操作流程。全文圍繞三條主線展開C 依賴的兩種安裝路徑cmake/deps.txt下載構(gòu)建與 vcpkg 包管理的同步更新、自動(dòng)生成文檔算子內(nèi)核表、WebGL 算子表與 Pythonrequirements.txt的再生成、以及升級(jí)后測(cè)試用例與優(yōu)化器的配套更新。讀完本文你將掌握一次可交付的 ONNX 版本升級(jí)從改代碼到過(guò) CI 的每一步實(shí)操細(xì)節(jié)。本文內(nèi)容以 docs/How_To_Update_ONNX_Dev_Notes.md 為骨架并結(jié)合當(dāng)前倉(cāng)庫(kù)中 cmake/deps.txt、cmake/vcpkg-ports/onnx/portfile.cmake、cmake/patches/onnx/onnx.patch、tools/python/gen_opkernel_doc.py、tools/python/find_optimizer_opset_version_updates_required.py 等文件進(jìn)行源碼級(jí)印證。一、升級(jí)前的總覽ONNX 依賴的兩條安裝路徑ONNX Runtime 目前支持兩種方式安裝 ONNX 的 C 依賴二者均受 CI 覆蓋cmake/deps.txt下載構(gòu)建路徑在 cmake/deps.txt 中以名稱;URL;SHA1的 CSV 行描述所有第三方依賴構(gòu)建時(shí)由 CMake 下載源碼包并編譯。vcpkg 包管理路徑通過(guò) cmake/vcpkg-ports/onnx/portfile.cmake 等端口文件把 ONNX 作為 vcpkg 包安裝。官方建議在 Windows 機(jī)器上測(cè)試 vcpkg 路徑。以當(dāng)前倉(cāng)庫(kù)為例cmake/deps.txt 中 ONNX 被固定為v1.22.0發(fā)布版onnx;https://github.com/onnx/onnx/archive/refs/tags/v1.22.0.zip;2b2cd58ac7a26df5371266149e0c76776330cdf1其注釋還記錄了一次典型的“純版本升級(jí)”經(jīng)驗(yàn)從 rc2 到最終版僅涉及 CI workflow 與VERSION_NUMBER的改動(dòng)算子 schema、opset 與測(cè)試數(shù)據(jù)均無(wú)變化因此可直接升級(jí)。這說(shuō)明升級(jí)前先比對(duì)目標(biāo)版本與當(dāng)前版本之間onnx/defs、opset 與 testdata 的差異可以顯著降低后續(xù)工作量。二、更新 ONNX 子模塊SubmoduleONNX Runtime 通過(guò) git submodule 引用 ONNX 源碼掛在cmake/external/onnx下。升級(jí)的第一步是把子模塊切到目標(biāo)提交。文檔強(qiáng)調(diào)用 commit id 比用分支更精確可追溯、可復(fù)現(xiàn)。cd cmake/external/onnx git remote update git reset --hard commit_id cd .. git add onnx將commit_id替換為你的目標(biāo)提交如果不確定具體提交可以使用origin/main例如git reset --hard origin/main。執(zhí)行完成后父?jìng)}庫(kù)記錄下子模塊的新指針git add onnx使該變更進(jìn)入暫存區(qū)。三、更新 cmake/deps.txt 下載路徑當(dāng)采用 deps.txt 下載構(gòu)建路徑時(shí)需要同步更新下載源與校驗(yàn)值更新 cmake/deps.txt把 ONNX 行的 zip 下載鏈接與 SHA1 改為新版本對(duì)應(yīng)的值。文件頭部注釋說(shuō)明了校驗(yàn)值的生成方式Linux 下運(yùn)行sha1sumPowerShell 下可用(Get-FileHash -Algorithm SHA1 filename).Hash.ToLower()。文檔同時(shí)給出一個(gè)取巧技巧先用錯(cuò)誤的 SHA 構(gòu)建ORT 會(huì)在報(bào)錯(cuò)信息中直接告訴你期望的 SHA。檢查 cmake/patches/onnx/onnx.patch確認(rèn) patch 中的 diff 是否已在最新的 ONNX 版本中被上游解決被解決的部分應(yīng)移除。當(dāng)前倉(cāng)庫(kù)的 patch 內(nèi)容反映了兩個(gè)典型的 ORT 側(cè)需求為 ONNX 的CMakeLists.txt增加ONNX_MINIMAL_BUILD選項(xiàng)使 WebAssembly/最小化構(gòu)建只需data_type_utils.cc與生成的 protobuf 源碼跳過(guò)完整算子/schema 源碼去掉GroupNormalization算子 ver18 schema 上的Deprecate()標(biāo)記保證 ORT 對(duì)該算子的兼容性。 可見該 patch 是 ORT 與上游 ONNX 行為差異的“粘合層”每次升級(jí)都必須重新評(píng)估。從源碼構(gòu)建 ONNXRUNTIME 驗(yàn)證文檔給出的示例構(gòu)建命令CUDA 12.6 環(huán)境、構(gòu)建 wheel、并行編譯、跳過(guò)測(cè)試./build.sh --config RelWithDebInfo --use_cuda --cuda_home /usr/local/cuda-12.6/ --cudnn_home /usr/local/cuda-12.6/ --build_wheel --parallel --skip_tests如果構(gòu)建失敗屬于 ONNX 自身的問(wèn)題修改/補(bǔ)充onnx.patch屬于 ORT 適配問(wèn)題則直接修改 ORT 側(cè)代碼。四、更新 cmake/vcpkg-ports 端口采用 vcpkg 路徑時(shí)需要維護(hù) cmake/vcpkg-ports/onnx/ 目錄下的端口文件步驟如下同步 cmake/vcpkg-ports/onnx/binskim.patch文檔要求將其內(nèi)容與 cmake/patches/onnx/onnx.patch 保持一致——即 deps.txt 路徑的補(bǔ)丁與 vcpkg 路徑的補(bǔ)丁同源同步避免兩條安裝路徑行為分叉。重新 diff 其余 patchcmake/vcpkg-ports/onnx/ 下除 binskim.patch 外的其他補(bǔ)丁如fix-cmakelists.patch、fix-dependency-protobuf.patch是 vcpkg 倉(cāng)庫(kù)構(gòu)建 ONNX 所必需/創(chuàng)建的升級(jí)后需要重新運(yùn)行 diff 確認(rèn)這些補(bǔ)丁仍能干凈地應(yīng)用到新版 ONNX 上。這一點(diǎn)可從 portfile.cmake 的PATCHES段得到印證vcpkg_from_github( OUT_SOURCE_PATH SOURCE_PATH REPO onnx/onnx REF v1.22.0 SHA512 13fafff073a8e0bcf67fd06195da979c3c6273b3f5fdd25f5e5c39ad6af20eefe107f13dc73d52b6021e986d87401e46121e00bba8fbd09f098334e34f78462f PATCHES fix-cmakelists.patch fix-dependency-protobuf.patch binskim.patch )更新 cmake/vcpkg-ports/onnx/portfile.cmake將REF改為新 commit id 或 tag將SHA512改為新源碼包的校驗(yàn)值。同樣可用“故意填錯(cuò) SHA512 觸發(fā)構(gòu)建報(bào)錯(cuò)、ORT 提示期望值”的辦法獲取正確哈希。portfile.cmake中其余邏輯展示了 vcpkg 端口的關(guān)鍵約束可作為修改時(shí)的背景知識(shí)vcpkg_check_linkage(ONLY_STATIC_LIBRARY)僅支持靜態(tài)庫(kù)鏈接通過(guò)find_program(PROTOC ...)定位 protobuf 自帶的protoc并分別透?jìng)鱋NNX_CUSTOM_PROTOC_EXECUTABLE與Protobuf_PROTOC_EXECUTABLE根據(jù) protobuf 庫(kù)文件名后綴判斷ONNX_USE_PROTOBUF_SHARED_LIBS取值配置ONNX_MLON、關(guān)閉測(cè)試與 benchmark并清理安裝目錄中 ORT 不需要的include/onnx/defs/*、onnx/reference等子目錄以縮減包體積。上傳包按 vcpkg 倉(cāng)庫(kù)內(nèi)部文檔說(shuō)明上傳新包也可直接用 Terrapin 工具上傳 ONNX 包需要 SHA512示例命令如下C:\local\Terrapin\TerrapinRetrievalTool.exe -b https://vcpkg.storage.devpackages.microsoft.io/artifacts/ -a true -u Environment -p onnx源碼tar.gz地址 -s SHA512 -d 本地下載臨時(shí)文件路徑從源碼構(gòu)建驗(yàn)證與 deps.txt 路徑類似文檔給出的 vcpkg 構(gòu)建示例僅多出--use_vcpkg開關(guān)./build.sh --config RelWithDebInfo --use_cuda --cuda_home /usr/local/cuda-12.6/ --cudnn_home /usr/local/cuda-12.6/ --build_wheel --parallel --skip_tests --use_vcpkg五、更新 ONNX 相關(guān)自動(dòng)生成文檔ONNX 版本升級(jí)會(huì)改變可用的算子集合因此需要重新生成兩類自動(dòng)文檔并更新 Pythonrequirements.txt。5.1 重新生成 ONNX kernels 文檔OperatorKernels.md推薦直接從 CIAzureDevOps 發(fā)布的 Artifacts下載 CI 生成好的 markdown 上傳更新若希望本地生成則執(zhí)行# 在 onnxruntime 倉(cāng)庫(kù)根目錄下 python tools/python/gen_opkernel_doc.py --output_path docs/OperatorKernels.md從源碼看tools/python/gen_opkernel_doc.py 實(shí)際調(diào)用 Python 綁定的rtpy.get_all_operator_schema()與rtpy.get_all_opkernel_def()遍歷當(dāng)前構(gòu)建中注冊(cè)的全部算子 schema 與內(nèi)核定義按 Execution Provider 分組輸出表格并支持--providers按 EP 名過(guò)濾大小寫不敏感會(huì)自動(dòng)補(bǔ)齊ExecutionProvider后綴與--plugin-ep按NAME:PATH注冊(cè)插件 EP 并納入其內(nèi)核兩個(gè)可選參數(shù)。因此該命令必須基于升級(jí)后重新構(gòu)建的 ONNXRUNTIME運(yùn)行才能反映新 ONNX 版本的實(shí)際算子支持情況。文檔頭部也明確標(biāo)注了“由腳本自動(dòng)生成、請(qǐng)勿手工修改”。5.2 重新生成 WebGL 算子文檔webgl-operators.mdjs/web/docs/webgl-operators.md 由 js/web/script/generate-webgl-operator-md.ts 生成需要先在 JS 兩級(jí)目錄安裝依賴再構(gòu)建文檔# 在父級(jí) JS 目錄安裝依賴 cd /path/to/onnxruntime/js npm install # 在 web 目錄安裝依賴 cd /path/to/onnxruntime/js/web npm install # 構(gòu)建文檔 npm run build:doc5.3 更新 Python requirements.txt將以下文件中的 ONNX 版本號(hào)更新為新版本如onnx1.16.0若從源碼構(gòu)建則使用 commit hash 形式的 git 依賴如githttp://github.com/onnx/onnx.gittargetonnxcommithash#eggonnxonnxruntime/test/python/requirements.txttools/ci_build/github/linux/docker/scripts/requirements.txttools/ci_build/github/linux/docker/scripts/manylinux/requirements.txttools/ci_build/github/linux/python/requirements.txt當(dāng)前倉(cāng)庫(kù)的實(shí)際狀態(tài)可作參照上述文件均固定為onnx1.22.0另有 tools/ci_build/github/linux/docker/scripts/lort/requirements.txt 等 CI 輔助文件同樣固定該版本。文檔還提醒運(yùn)行g(shù)it grep -rn onnx1 .檢查是否還有其他位置引用了舊的 ONNX 版本號(hào)發(fā)現(xiàn)后一并更新必要時(shí)同步更新本文檔即 docs/How_To_Update_ONNX_Dev_Notes.md 本身。六、附加注意事項(xiàng)從代碼到 CI 的全鏈路檢查升級(jí) ONNX 不止改依賴還需處理以下連鎖影響重新生成 OnnxMl.cs如果cmake/external/onnx/onnx/*.in.proto有任何變更需要重新生成 C# 側(cè)OnnxMl.cs——構(gòu)建 NuGet 包--build_nuget相關(guān)流程會(huì)自動(dòng)完成這一步。部署新測(cè)試數(shù)據(jù)若從發(fā)布 tag 升級(jí)到新 commit需要聯(lián)系維護(hù)者文檔中為 ChangmingGitHub 名snnn把新測(cè)試數(shù)據(jù)連同其他測(cè)試模型部署到 CI 構(gòu)建機(jī)確保測(cè)試覆蓋每一個(gè) ONNX opset。提交 PR 并手動(dòng)排隊(duì)打包流水線PR 提交后需要手動(dòng)為分支的每一個(gè)打包流水線排隊(duì)構(gòu)建。WebAssembly CI 的文檔過(guò)期檢查如果 WebAssembly CI 流水線在 “Check out of dated documents” 階段失敗說(shuō)明 WebGL 算子支持文檔過(guò)期需要確保已安裝 Node.js參見 js/README.md 的 Prerequisites按 js/README.md 的 Build 章節(jié)安裝依賴按 Generating Document 章節(jié)更新文檔并將docs/operators.md的變更提交入庫(kù)。處理新增測(cè)試的失敗新版 ONNX 通常會(huì)帶來(lái)新測(cè)試可能觸發(fā)失敗此時(shí)需要更新onnxruntime/test/onnx/main.cconnxruntime/test/providers/cpu/model_tests.cccsharp/test/Microsoft.ML.OnnxRuntime.Tests.NetCoreApp/InferenceTest.netcore.csonnxruntime/test/testdata/onnx_backend_test_series_filters.jsonconnxruntime/test/testdata/onnx_backend_test_series_overrides.jsonc其中兩個(gè) JSONC 文件是 ONNX backend 測(cè)試系列的過(guò)濾器決定哪些用例被跳過(guò)與覆蓋項(xiàng)決定哪些用例的結(jié)果被覆蓋新算子/新 opset 加入后往往需要在這里增刪條目。檢查涉及變更算子的優(yōu)化器如果某個(gè)算子發(fā)生了變化涉及該算子的圖優(yōu)化器可能需要同步更新 opset 版本支持。運(yùn)行python tools/python/find_optimizer_opset_version_updates_required.py -o onnxruntime倉(cāng)庫(kù)根目錄從 tools/python/find_optimizer_opset_version_updates_required.py 源碼看該腳本會(huì)從onnxruntime/core/optimizer下所有.cc/.h中解析graph_utils::IsSupportedOptypeVersionAndDomain調(diào)用解析出每個(gè)優(yōu)化器聲稱支持的算子 opset 上限同時(shí)從 ORT 內(nèi)核注冊(cè)文件onnxruntime/contrib_ops/cpu/cpu_contrib_kernels.cc、onnxruntime/contrib_ops/cuda/cuda_contrib_kernels.cc與 ONNX 頭文件cmake/external/onnx/onnx/defs/operator_sets.h、operator_sets_ml.h提取每個(gè)算子的最新 opset兩者比對(duì)后輸出Newer opset found for ...類警告。將該腳本輸出與當(dāng)前 main 分支的輸出做對(duì)比檢查是否出現(xiàn)新的警告若有新警告聯(lián)系對(duì)應(yīng)優(yōu)化器的負(fù)責(zé)人通?？醋罱l(shuí)修改了相關(guān)文件或向 “ONNX Runtime Shared Core” 郵件列表求助。七、總結(jié)一次 ONNX 升級(jí)的完整清單將上述步驟收攏為可執(zhí)行的檢查清單階段關(guān)鍵動(dòng)作涉及倉(cāng)庫(kù)文件子模塊切換到目標(biāo) commit 并提交指針cmake/external/onnxsubmoduledeps.txt 路徑更新下載 URL SHA1評(píng)估 onnx.patch源碼構(gòu)建驗(yàn)證cmake/deps.txt、cmake/patches/onnx/onnx.patchvcpkg 路徑同步 binskim.patch重跑其余 patch diff更新 REF SHA512上傳包--use_vcpkg構(gòu)建驗(yàn)證cmake/vcpkg-ports/onnx/、portfile.cmake自動(dòng)文檔重新生成 OperatorKernels.md、webgl-operators.mdtools/python/gen_opkernel_doc.py、js/web/script/generate-webgl-operator-md.tsPython 依賴統(tǒng)一更新各 requirements.txt 并git grep查漏onnxruntime/test/python/requirements.txt 等測(cè)試與優(yōu)化器更新 backend 測(cè)試過(guò)濾器/覆蓋項(xiàng)運(yùn)行 optimizer 腳本排查onnx_backend_test_series_filters.jsonc、find_optimizer_opset_version_updates_required.py收尾重新生成 OnnxMl.csproto 變更時(shí)、部署測(cè)試數(shù)據(jù)、PR 后手動(dòng)排隊(duì) CINuGet 構(gòu)建流程、CI 打包流水線按照這份清單逐項(xiàng)推進(jìn)即可保證 ONNX 升級(jí)在依賴一致性、文檔時(shí)效性、測(cè)試覆蓋性與優(yōu)化器正確性四個(gè)維度同時(shí)達(dá)標(biāo)順利通過(guò)各條 CI 流水線。【免費(fèi)下載鏈接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator項(xiàng)目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考