ONNX Runtime 推理排错：6 个高频报错与排查方法（附速查表）

ONNX Runtime 推理排错6 个高频报错与排查方法附速查表【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime写给跑 ONNX Runtime 推理时遇到报错的你模型加载失败、GPU 跑不起来、推理又慢又占内存这篇按三步走排查顺序一次讲清结尾附速查表直接对号入座。先看懂排查思路环境依赖 → 模型文件 → 运行时参数ONNX Runtime 的报错九成落在三段里先按顺序过一遍再进具体小节环境与依赖装的是不是当前 Python 环境、GPU 版是否装对、CUDA/cuDNN 版本是否匹配模型文件与配置算子支不支持、输入 shape 对不对、模型本身合不合法运行时参数线程数、日志级别、显存和内存占用怎么调。先确认前两步没坑再动运行时参数能少走一大半弯路。同一个模型会被分发给不同的执行提供器Execution Provider执行报错信息里通常会带上具体是 CPU 还是 CUDA先看这一句再动手。环境依赖排查版本怎么对模块为什么找不到装好了却提示 No module named onnxruntime你看到的现象pip install onnxruntime执行成功一 import 就报模块不存在。可能的原因装包用的解释器和跑代码的解释器不是同一个最常见是 venv/conda 环境没激活另一种是想要 GPU 能力却只装了 CPU 基础包。具体操作先跑pip show onnxruntime确认 Location 指向当前环境的 site-packages再跑一句python -c import onnxruntime; print(onnxruntime.__version__)验证版本。需要 CUDA 时单独安装onnxruntime-gpu它和基础包不互相替代。CUDAExecutionProvider 不可用或提示 CUDA 版本不匹配你看到的现象providers[CUDAExecutionProvider]创建 session 直接失败日志里写着 CUDA 不可用或版本不匹配。可能的原因驱动和 CUDA 版本对不上或装的 ORT 小版本要求的 CUDA/cuDNN 与本机不一致。具体操作先跑nvidia-smi看驱动和 CUDA 上限再跑python -c import onnxruntime as ort; print(ort.get_device())确认环境。对不上就按当前 ORT 版本要求的 CUDA/cuDNN 组合重装版本对照以 官方FAQ 为准。GPU 显存爆掉CUDA out of memory你看到的现象小 batch 能跑batch 一大就报CUDA out of memory进程被杀或推理挂掉。可能的原因输入 batch 或序列长度偏大开了 CUDA graph 额外占了一份额外显存。具体操作先把 batch 调小复现确认代码里enable_cuda_graph已设为False再检查输入分辨率很多显存问题最后都出在图片边长上。模型文件排查算子不支持和 shape 不匹配加载失败Node Op is not supported你看到的现象InferenceSession创建时抛错大意是某个 Node 的某个 Op 当前不支持。可能的原因模型用了较新的算子或 opset当前 ORT 版本还没覆盖模型依赖了 contrib 算子而你的构建没编进去。具体操作记下报错里的算子名和版本号到 贡献算子文档 里查归属和编译条件然后升级 ORT 到最新版或从导出源头降低 opset 重新生成模型。用了自定义算子的把算子库注册进 session 即可sess_options ort.SessionOptions() sess_options.register_custom_ops_library(./custom_ops.so) session ort.InferenceSession(model.onnx, sess_options)Shape mismatch输入张量形状对不上你看到的现象推理时报错Input tensor has shape (X) but expected (Y)或输出尺寸和预期不符。可能的原因预处理后的 shape 和模型声明不符batch 维度改了但模型没声明动态轴。具体操作先用session.get_inputs()把每个输入的期望 shape 打出来再按它reshape你的数据。多输入多输出的写法可以直接看官方测试 test_inference.cc里面有 3 输入 3 输出的完整示例。结果和导出框架对不上你看到的现象同一个模型PyTorch 和 ONNX Runtime 输出不一致数值对不齐。可能的原因不同执行提供器上的浮点误差累积模型里有非确定性算子。具体操作先用 CPUExecutionProvider 跑一遍当基准再换 CUDA 或 TensorRT 对比确认差异出在哪一段。差值在 1e-3 量级以内一般属精度容忍范围再大就要逐个算子定位了。运行时参数排查推理变慢先查哪里线程怎么限推理变慢且 CPU 占用低你看到的现象单条推理耗时远超预期top 里 CPU 却闲着一半。可能的原因线程数没配好intra_op_num_threads和inter_op_num_threads之和超过核数反而互相抢锁图优化默认级别没打开。具体操作先把两个线程数改成接近核数的组合试一轮再开性能分析定位具体是哪个算子慢opts.enable_profiling True session ort.InferenceSession(model.onnx, sess_optionsopts) session.run(None, feeds) profiling_file session.end_profiling() # 生成 json 文件生成的 json 里按节点耗时排序通常头几个节点就占掉 90% 的时间。单实例把 CPU 打满影响同机其他进程你看到的现象session.run()默认会用满整机核心旁边跑着的服务一起变卡。可能的原因OpenMP 构建下默认拉满线程session options 又没设限制。具体操作设环境变量OMP_NUM_THREADS1再在 session options 里把intra_op_num_threads设为 1、execution_mode设为顺序执行三步都能限制线程os.environ[OMP_NUM_THREADS] 1 opts ort.SessionOptions() opts.inter_op_num_threads 1 opts.execution_mode ort.ExecutionMode.ORT_SEQUENTIAL大模型推理内存占用高你看到的现象模型加载或推理时内存/显存持续爬升进程被 OOM killer 干掉。可能的原因输入尺寸过大内存模式没复用中间张量反复分配。具体操作先减小 batch 和输入尺寸确认 memory pattern 优化是开着的默认开启GPU 侧按前面显存爆掉一节处理量化支持情况以 官方FAQ 为准。排查速查表现象/报错最常见原因第一步动作No module named onnxruntime装包环境与运行环境不一致pip show onnxruntime核对 LocationCUDA 不可用/版本不匹配驱动或 CUDA/cuDNN 版本不对nvidia-smi看驱动版本CUDA out of memorybatch 过大或开了 CUDA graph调小 batch关enable_cuda_graphNode Op not supported算子或 opset 版本过新记算子名查贡献算子文档并升级 ORTShape mismatch预处理 shape 与模型声明不符用get_inputs()打印期望 shape输出与导出框架不一致跨 EP 浮点误差或非确定性算子先跑 CPU 基准再对比 GPU推理慢、CPU 占用低线程数配错调 intra/inter 线程数再开 profiling单实例打满 CPU默认拉满所有核OMP_NUM_THREADS1加顺序执行模式更多细节以 官方FAQ 为准卡住了就把报错原文和复现命令提 issue通常很快就能定位。按上面三步走一遍大部分问题都能迎刃而解。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考