简介适用于Windows x64平台的ONNX Runtime 1.23.2 CPU版本预编译包面向需要在Windows环境中部署或调用ONNX模型的开发者和机器学习爱好者解决特定版本安装包在官网难以找到或下载缓慢的问题提供开箱即用的备份资源。压缩包内共26个文件以14个头文件为主完整覆盖C、C等多种调用接口配套2个动态链接库和2个导入库方便程序编译与运行时链接另外包含2个调试符号文件、多份说明文档以及版本号、提交标识和许可证文件便于使用者核对版本来源、使用权限和进行本地调试。整个资源包大小约74.51MB结构清晰解压后可直接集成到Visual Studio等开发环境快速进行ONNX模型加载与CPU推理验证无需额外配置繁琐的依赖项。目前已有76人浏览学习适合作离线安装或紧急恢复备件帮助节省检索下载时间更快搭建本地推理环境。1. onnxruntime-win-x64-1.23.2.zip 是什么一次解压把 ONNX 推理环境装进项目目录onnxruntime-win-x64-1.23.2.zip 这个压缩包是我在 Windows 上做 ONNX 模型部署时最常拿到的最小运行时。它是 ONNX Runtime 官方发布的 Windows x64 预编译二进制解压后就能被 C 或 Python 程序直接加载不依赖安装器也不往系统里写注册表。很多人下它不是为了省事而是生产环境要求手动管理依赖pip 装出来的动态库版本不可控安装目录也不允许被随便覆盖。这篇笔记面向要在 Windows x64 上集成 ONNX 推理的开发者从拆包验货、C/Python 两种接入方式到现场排查和调参一次讲透。2. 拆开这个 zip 前先弄明白onnxruntime 的发布物和 1.23.2 的含义onnxruntime 在 Windows 上的发布形态不止 zip 一种。pip 用户最常遇到的是 wheel装完就能在 Python 里 importVisual Studio 项目常用 NuGet 包工程文件里加一行引用就行。zip 在两者之外反而更适合手动控制依赖的场景它没有安装逻辑解压出来的 DLL 和头文件放哪个目录完全由你决定。离线内网、安装包集成、要固定 DLL 版本的交付项目都是 zip 的主场。1.23.2 这个版本号拆开看1 是主版本23 是功能版本2 是补丁号。官方在 1.x 系列里保持接口兼容从 1.20 迁到 1.23 时源码基本不用动但 1.20 起 provider 共享库被拆分这个变化会直接影响你的分发方式后面的避坑章会专门讲。在动手写代码之前先花两分钟把包内容、版本来源摸清楚能省掉后面一多半的玄学排错。2.1 包内文件清单onnxruntime.dll、provider 共享库与头文件各管什么打开压缩包前先对齐一下里面大约有什么。官方发布的 Windows x64 zip 里常见的组成是头文件、导入库和若干动态库。include 目录下是 API 声明lib 目录下是导入库动态库里的核心是 onnxruntime.dll所有推理入口都从它出来。1.20 之后的版本还会带一个 onnxruntime_providers_shared.dllCPUExecutionProvider 的算子执行逻辑有一部分在它里面所以拷贝分发时它不是可选项。文件作用分发给目标机器include/onnxruntime_cxx_api.hC API 声明编译期需要否lib/onnxruntime.lib导入库链接期需要否onnxruntime.dll核心推理引擎运行期必须是onnxruntime_providers_shared.dllprovider 共享支撑库运行期必须是LICENSE开源许可证与第三方声明打包时建议带上拿到 zip 后我习惯先“验货”再开工。解压到一个固定目录比如C:\libs\onnxruntime_1.23.2然后用 PowerShell 确认 DLL 的文件版本真的是 1.23.2而不是被重新打包过的同名文件。cd C:\libs\onnxruntime_1.23.2 Get-ChildItem -Recurse -Filter *.dll | ForEach-Object { $_.VersionInfo | Select-Object FileName, FileVersion, ProductVersion }VersionInfo 里的 FileVersion 是 Release 构建自带的版本资源应该显示 1.23.2。如果读取结果是 0.0.0.0 或读取失败说明文件被二次处理过可能是压缩工具重写过也可能是分发链路动过手脚。这种包就算能解压也建议换官方来源重新下载否则后面排错时版本对不上非常被动。这里顺带说一句为什么不建议把 DLL 直接丢进C:\Windows\System32。System32 是全局搜索路径一旦旧版本 DLL 被别的软件覆盖所有依赖它的程序同时遭殃。集成现场遇到这种“黑匣子”问题排查成本很高。项目目录隔离才是可控的做法编译期用 include 和 lib运行期把 DLL 放在 exe 同目录或独立子目录互不污染。2.2 版本号与构建类型CPU 版和 DirectML 版怎么选win-x64 的 zip 从执行提供程序上分成普通 CPU 版和 DirectML 版。名字不带 dml 字样的通常是 CPU 版只依赖 CPUExecutionProvider带 dml 字样的包里会多出 DirectML.dll可以把推理任务调度到支持 DirectX 12 的显卡上。选型先给一个简单判据目标机器有没有现成的 CUDA 环境没有就不要碰 GPU 执念直接用 CPU 版。DirectML 在 Windows 上确实不需要 CUDA但它要求显卡驱动较新而且首次推理有 shader 编译延迟。模型很小或推理频率很低时这个一次性延迟可能比 CPU 推理耗时还大模型是大卷积网络且持续推理时DML 的收益才值得付出这套复杂度。常见做法是先 CPU 版跑通正确性和精度再按需切换 providerAPI 层只是 provider 名字不同。还有一类发布物是 NuGet 包。NuGet 包和 zip 里的内容其实是同构的只是按包管理器的目录约定重新排布。项目本身在用 NuGet 时没必要额外下 zip但离线环境里 NuGet 源不通zip 就成了后悔药解压后手动引用绕开包管理器。这也是我会在本地长期保留一个解压好的常用版本的原因升级时另建目录不影响已有工程。3. 用 C API 在本地跑通最小推理解压、编译、运行的完整命令C 和 C 是这个 zip 最直接的使用方式。PyTorch 训练完导出的 ONNX 模型在 Windows 桌面软件里用 C 推理这是很常见的落地路径。这一章从目录落位开始给一个能直接编译运行的最小示例附带 MSVC 命令行参数说明。3.1 环境准备与目录落位把 zip 解压到干净路径。Windows 10 以上系统自带 tar 命令能解 zip不需要额外装工具。目录名带上版本号这是血泪经验见过太多人把 DLL 直接扔在下载目录三个月后自己都分不清哪个是哪个。mkdir C:\libs tar -xf onnxruntime-win-x64-1.23.2.zip -C C:\libs ren C:\libs\onnxruntime-win-x64-1.23.2 onnxruntime_1.23.2 dir C:\libs\onnxruntime_1.23.2\include\onnxruntime_cxx_api.h dir C:\libs\onnxruntime_1.23.2\lib\onnxruntime.lib解压后如果找不到include或lib目录说明拿到的是精简发布版只带 DLL 不带开发文件那 C 编译没法做需要补头文件和导入库。确认关键文件在位后编译期只需要两个路径头文件目录和导入库目录运行期需要的是 DLL 目录。这里不设置全局 PATH。每个项目在自己的编译脚本里显式引用这个目录比全局环境变量可靠得多。原因很简单PATH 里的 DLL 对系统里所有进程可见别的软件如果带了个旧版 onnxruntime.dll你的程序启动时按搜索顺序可能先加载到那个旧版排查起来极其隐蔽。3.2 最小示例代码与 MSVC 编译参数下面这段代码按 1.23 的 C API 写法完成加载模型、构造输入、推理、读输出四步没有多余逻辑。#include onnxruntime_cxx_api.h #include vector #include iostream int main() { // 日志级别设 WARNING避免每次推理在控制台刷大量信息 Ort::Env env(ORT_LOGGING_LEVEL_WARNING, onnx-demo); // 会话选项线程数和图优化是影响性能的两个关键参数 Ort::SessionOptions opts; opts.SetIntraOpNumThreads(4); opts.SetGraphOptimizationLevel(ORT_ENABLE_ALL); // 加载模型路径支持宽字符 Ort::Session session(env, Lmodel.onnx, opts); // 假设模型输入是 1x3x224x224 的 float 张量 std::vectorint64_t shape{1, 3, 224, 224}; std::vectorfloat input_data(1 * 3 * 224 * 224, 0.5f); // 创建 CPU 内存上的输入张量 auto mem_info Ort::MemoryInfo::CreateCpu(OrtArenaAllocator, OrtMemTypeDefault); Ort::Value input_tensor Ort::Value::CreateTensorfloat( mem_info, input_data.data(), input_data.size(), shape.data(), shape.size()); // 输入输出节点名要和导出的模型一致可以用 Netron 打开模型查看 const char* input_names[] {input}; const char* output_names[] {output}; Ort::RunOptions run_opts; auto outputs session.Run(run_opts, input_names, input_tensor, 1, output_names, 1); // 取第一个输出张量的首个元素验证推理通路是通的 const float* result outputs[0].GetTensorDatafloat(); std::cout first output value: result[0] std::endl; return 0; }编译命令在 Visual Studio 的 x64 Native Tools 命令行里执行。/EHsc是 C 异常处理/std:c17指定标准/I指向头文件目录/link后面的onnxruntime.lib是导入库——它只包含符号表实际实现在 onnxruntime.dll 里。cl /nologo /EHsc /std:c17 ^ /I C:\libs\onnxruntime_1.23.2\include ^ demo.cpp ^ /link C:\libs\onnxruntime_1.23.2\lib\onnxruntime.lib ^ /OUT:demo.exe set PATHC:\libs\onnxruntime_1.23.2\lib;%PATH% demo.exe运行前把 DLL 目录临时加进 PATH这是开发机上的做法。正式交付时不依赖 PATH直接把 onnxruntime.dll 和 onnxruntime_providers_shared.dll 复制到 exe 同目录程序启动时 Windows 会优先从 exe 所在目录找 DLL。编译出来的 demo.exe 本身很小体积大头在 DLL 上所以分发时整目录打包是常见做法。代码里的关键参数给一个建议表方便对照调整参数建议值说明SetIntraOpNumThreads与 CPU 物理核数相当不是越大越好内存带宽不够时线程增加反而变慢ORT_ENABLE_ALL上线前开启做算子融合等图优化能明显降延迟ORT_LOGGING_LEVEL_WARNING生产环境日志级别开 INFO 会在循环推理时拖慢速度如果你用的是 CMake思路完全一样include_directories指向 includetarget_link_libraries指向onnxruntime.lib的完整路径运行时保证 DLL 在 exe 同目录即可。4. Python 侧复用这个 zip两种 DLL 投喂方式与离线包制作Python 用户通常直接pip install onnxruntime但有些场景必须手动管理 DLL内网机器装不了包或者项目要求 Python 包和推理运行时严格同版本。这种情况下zip 里的 DLL 可以和 Python 包配合使用。原理是onnxruntime 的 Python 扩展底层加载的动态库就是同名同 ABI 的 onnxruntime.dll版本对齐时互相替换是安全的。4.1 方式一os.add_dll_directory 指向 zip 解压目录Python 3.8 之后Windows 上加载 DLL 的搜索逻辑变了不再默认把任意目录纳入搜索路径。os.add_dll_directory是官方给的补救入口可以让 onnxruntime 的 C 扩展在 import 时找到你指定的 DLL。import os import ctypes import onnxruntime # 必须在 import onnxruntime 之前执行 dll_dir rC:\libs\onnxruntime_1.23.2\lib os.add_dll_directory(dll_dir) # 如果当前环境还没装 onnxruntime 包可以用 ctypes 预加载验证 DLL 可用 ctypes.CDLL(os.path.join(dll_dir, onnxruntime.dll)) sess onnxruntime.InferenceSession( model.onnx, providers[CPUExecutionProvider], ) print(sess.get_providers())这段脚本适合开发机上临时指定 DLL 目录不动 site-packages随时可以切回 pip 版本。注意调用顺序os.add_dll_directory必须在import onnxruntime之前执行因为 onnxruntime 的 C 扩展在 import 时就要加载依赖的动态库顺序反了就不生效。如果dll_dir里同时存在多个版本的 onnxruntime.dll搜索顺序以 add 的先后为准先加入的优先。调试阶段建议只把 zip 解压目录加进去避免和系统 PATH 里的旧版 DLL 互相干扰。4.2 方式二复制 DLL 进 site-packages做成离线发布目录离线目标机器上装不了 pip 包时可以直接把 DLL 复制进已经装好的 onnxruntime 包目录覆盖同名文件。前提是 pip 包的版本和 zip 版本一致都是 1.23.2。用 PowerShell 完成整个操作# 找到当前 Python 的 onnxruntime 包目录 python -c import onnxruntime, os; print(os.path.dirname(onnxruntime.__file__)) # 通常输出 C:\Python312\Lib\site-packages\onnxruntime\capi # 把 zip 里的 DLL 复制过去覆盖 copy C:\libs\onnxruntime_1.23.2\lib\onnxruntime.dll C:\Python312\Lib\site-packages\onnxruntime\capi\ copy C:\libs\onnxruntime_1.23.2\lib\onnxruntime_providers_shared.dll C:\Python312\Lib\site-packages\onnxruntime\capi\这种做法的意义在于离线内网机器不需要联网装包目录拷贝完就能跑。更彻底的离线方案是用 Python 官方 embeddable 版本解压后没有 pip但 onnxruntime 的 DLL 可以被 ctypes 直接加载推理脚本先ctypes.CDLL(onnxruntime.dll)再调用 C API连 site-packages 都不用碰。这个方案体积最小适合做进安装包。不管哪种方式有一条原则不要破不要用全局环境变量 PATH 来暴露这个 DLL 目录。全局 PATH 会让所有进程看到这份 onnxruntime.dll和项目里其他依赖产生隐式冲突排错成本比省下的那点配置功夫高得多。5. 集成 onnxruntime-win-x64 的常见问题排查5 个现场翻车记录这一章记录的坑来自实际集成现场每条按现象、原因、解决三个层次展开。前四条在 Windows 上最常见最后一条是架构选型问题一次说清。5.1 0xc000007b别先怀疑架构先查 VC 运行库现象是编译链接都过了双击 exe 直接弹“应用程序无法正常启动 0xc000007b”。这个错误码在 x64 程序里最常见的诱因不是 CPU 架构而是缺少 Visual C 运行库。onnxruntime 官方二进制依赖较新的 vcruntime140.dll 和 msvcp140.dllWindows 7 或精简版 Windows Server 上默认不带。先给目标机器安装 microsoft visual c 2015-2022 redistributable (x64)。急着验证的话可以把 vcruntime140.dll、msvcp140.dll 临时复制到 exe 同目录程序先跑起来再说。如果装完还报错在 VS 的 x64 Native Tools 命令行里跑dumpbin /dependents demo.exe看列出的 DLL 哪个不在目标系统里再逐个补。这里最容易翻车的是把 x86 版运行库装了x64 版没装。查错时先确认目标机器系统目录下 System32 里有没有 64 位的 ucrtbase.dll。看到 0xc000007b 就认定是“32 位和 64 位混了”方向对了一半但真正缺的往往是运行库而非 CPU 位数。5.2 import onnxruntime 报 DLL load failed进程位数和 DLL 搜索路径现象是pip install onnxruntime成功但import onnxruntime的瞬间抛 DLL load failed堆栈指向某个 pyd 文件。两种常见原因一是 Python 解释器本身是 32 位pip 解析到了 x86 的 wheel二是系统 PATH 里存在旧版 onnxruntime.dllPython 启动时按 DLL 搜索顺序先加载了它。先确认 Python 位数命令行跑python -c import struct; print(struct.calcsize(P)*8)输出 64 才对。如果输出 32换 64 位 Python 重装包。位数没问题后用os.add_dll_directory指向 zip 解压目录并提前用 ctypes 加载一次 onnxruntime.dll强制把搜索路径修正到你指定的位置。调这个坑时很容易被 pyd 的报错文件名带偏以为是包损坏反复重装。实际上 pyd 只是入口它依赖的 onnxruntime.dll 没找到才是根因。先查进程位数再查 DLL 搜索路径顺序不要反。5.3 推理结果和导出框架对不上输入节点名、形状与归一化现象是同一个输入PyTorch 里输出正常换到 onnxruntime 后结果不对甚至全 0 或 NaN。多数情况下问题不在推理引擎而在输入侧。onnxruntime 按字符串匹配输入节点名名字写错时可能直接报错也可能命中意料之外的节点输入 shape 不匹配时某些算子老版本里不做严格校验悄悄广播结果就歪了。排查时先打印会话的输入输出元信息一项项核对sess onnxruntime.InferenceSession(model.onnx, providers[CPUExecutionProvider]) for inp in sess.get_inputs(): print(inp.name, inp.shape, inp.type) for out in sess.get_outputs(): print(out.name, out.shape, out.type)核对这三点节点名和你的推理代码里传的字符串是否一致shape 是否为模型要求的 NCHW 布局type 是否为 float32。另外导出模型前把模型切到 eval 模式并冻结 BatchNorm固定 batch size 再导出不要一上来就用 dynamic axes。先固定维度调通正确性再考虑动态输入能省掉一半的模型侧排查时间。5.4 目标机器缺 onnxruntime_providers_shared.dll分发时别省文件现象是开发机跑得好好的打包发给目标机器运行时报“找不到 onnxruntime_providers_shared.dll”但 onnxruntime.dll 明明在同目录。原因是 1.20 之后官方把 provider 的逻辑拆到了共享库里onnxruntime.dll 只是入口层真正的算子执行路径在共享库里。只拷主 DLL 不够。解决方法是把解压目录里的 DLL 全部一起分发。程序里最好在启动阶段主动指定 DLL 目录思路是用 GetModuleFileName 取到 exe 所在路径拼出 onnxruntime 子目录后调用 SetDllDirectory 指向它。别依赖系统 PATH正式交付时目标机器的 PATH 你控制不了。如果安装包是拿 WiX 或 Inno Setup 做的把 lib 目录整目录带进去就行。5.5 x64 包拿到 ARM 平台架构不匹配没有玄学可讲现象是拿到 win-x64 包的人偶尔想在鲲鹏920 这类 ARM 服务器上复用程序能启动但创建 session 时直接崩。原因没有悬念x64 的机器码在 arm64 上根本没有对应执行环境。Windows 的模拟层可以启动进程但 onnxruntime 内部的指令集调度不会按模拟层来。解决思路只有一个按目标架构换包。Linux 环境用 Linux arm64 的 tar.gzWindows ARM 用 win-arm64 版本。注意这不只是换一个 DLL 的事Python 扩展同样需要重新编译成 arm64 的 pyd所以 ARM 适配要当作一次独立交付来做而不是替换文件。架构不匹配这类问题的排查顺序也很固定先看进程架构再看 DLL 架构不要在运行逻辑里浪费时间。6. 把 CPU 推理的时延再压一截线程数、图优化与稳定测速模型能跑通只是开始上线前把参数调到合理区间差距可能有三倍。这一章给三个必调参数和一个可靠测速方法。6.1 SessionOptions 里值得调的三个参数Python 侧直接改 SessionOptionsC 侧对应同一个对象参数名一致。import onnxruntime as ort so ort.SessionOptions() # 算子内部并行线程数按物理核数设置后续用实测校准 so.intra_op_num_threads 4 # 图优化等级上线前拉满 so.graph_optimization_level ort.GraphOptimizationLevel.ORT_ENABLE_ALL # 内存模式打开允许复用工作区减少反复分配开销 so.enable_mem_pattern True sess ort.InferenceSession( model.onnx, sess_optionsso, providers[CPUExecutionProvider], )intra_op_num_threads控制单个算子内部的并行度这是 CPU 推理最敏感的参数。拉满并不总是最好内存带宽不够时线程增加反而互相等待。graph_optimization_level默认是 ORT_ENABLE_BASIC上线前改成 ORT_ENABLE_ALL算子融合和常量折叠会带来明显收益但改完后要跑一遍回归集确认输出误差在可接受范围。enable_mem_pattern对频繁调用的场景收益明显极端内存紧张时才考虑关掉。6.2 验证提速热身、中位数与稳定的计时窗改完参数后怎么确认真的快了直接跑一次看耗时是看不出效果的。onnnxruntime 第一次推理有初始化开销arena 内存分配器也需要几轮预热才能稳定。import time import numpy as np # 构造与线上一致的输入 x np.random.rand(1, 3, 224, 224).astype(np.float32) # 先跑 10 次热身让内存池和缓存策略稳定下来 for _ in range(10): sess.run(None, {input: x}) # 正式计时取 30 次的中位数而不是平均值 costs [] for _ in range(30): t0 time.perf_counter() sess.run(None, {input: x}) costs.append(time.perf_counter() - t0) costs.sort() median_ms costs[len(costs) // 2] * 1000 print(fmedian latency: {median_ms:.2f} ms)为什么取中位数而不是平均值冷启动延迟和系统调度抖动会把平均拉高中位数更能反映稳定状态。同步看 CPU 占用率如果线程数已经超过物理核数CPU 占用还跑不满说明瓶颈在内存带宽或单线程算子这时加线程数没有意义。我自己的习惯是每次调参只改一个变量跑完上面这段脚本再改下一个。线程数从 1 开始往上扫每个档位记录中位数画一条曲线看拐点。这个习惯帮我避免过很多次“一次改三个参数不知道是哪个生效”的尴尬。希望帮到你。本文还有配套的精品资源点击获取