2、环境搭建：安装ONNX Runtime、配置Python与C++环境、验证安装
好，咱们正式开始动手了。
这一章说白了就是「把枪擦亮」。环境搭不好，后面所有代码都跑不起来。我见过太多同学卡在安装这一步，其实没那么玄乎，跟着我一步步来就行。
2.1 安装ONNX Runtime——选对版本很重要
ONNX Runtime 是微软开源的推理引擎。你想想看，ONNX 模型只是个中间格式，真正要跑起来，得靠它来加速。
我个人习惯用 pip 安装，简单直接。但这里有个坑——版本一定要跟你的 ONNX 模型匹配。我曾经有一次图省事装了最新版，结果模型死活加载不了，查了半天才发现是 opset 版本不兼容。
⚠️ 版本匹配原则：
- ONNX 1.12 对应 ONNX Runtime 1.12.x
- ONNX 1.13 对应 ONNX Runtime 1.13.x
- 如果模型是用旧版导出的，建议用 1.10 或 1.11 稳定版
安装命令很简单：
# CPU 版本（最常用）
pip install onnxruntime
# GPU 版本（需要 CUDA 环境）
pip install onnxruntime-gpu
# 指定版本（推荐）
pip install onnxruntime==1.15.1
💡 我的建议： 刚开始学，先用 CPU 版本。GPU 版本坑更多，CUDA、cuDNN 版本一不对就报错。等后面章节我们专门讲 GPU 加速时再换。
2.2 配置Python环境——虚拟环境是必须的
嗯，这里要注意。千万别直接在系统 Python 里装。我刚开始做项目时就是图省事，结果不同项目依赖打架，搞得我重装了三次系统。
用 conda 或者 venv 都行。我个人偏爱 conda，因为它还能管理 CUDA 版本。
# 创建虚拟环境
conda create -n onnx_env python=3.9
# 激活环境
conda activate onnx_env
# 安装核心依赖
pip install numpy protobuf onnx onnxruntime
# 可选：安装可视化工具
pip install netron # 用来查看模型结构为什么用 Python 3.9？因为它是目前 ONNX 生态支持最稳定的版本。3.10 以上有些库还没完全适配，你想想看，何必给自己找麻烦呢？
2.3 配置C++环境——给性能党准备的
Python 适合快速验证，但真要上生产环境，C++ 才是王道。我去年给一个工业视觉项目做部署，Python 推理要 30ms，换成 C++ 直接压到 8ms。差距就是这么大。
C++ 安装分三步：
- 下载预编译库：去 GitHub Releases 下载对应系统的包
- 解压到本地：比如
C:\onnxruntime-win-x64-1.15.1 - 配置 CMakeLists.txt
# CMakeLists.txt 示例
cmake_minimum_required(VERSION 3.10)
project(OnnxDemo)
set(ONNX_RUNTIME_DIR "C:/onnxruntime-win-x64-1.15.1")
include_directories(${ONNX_RUNTIME_DIR}/include)
link_directories(${ONNX_RUNTIME_DIR}/lib)
add_executable(demo main.cpp)
target_link_libraries(demo onnxruntime)
⚠️ 注意： Windows 下记得把
onnxruntime.dll 放到可执行文件同目录，或者加到系统 PATH 里。我当初忘了这一步，报错「找不到 dll」，折腾了半小时才发现。
2.4 验证安装——跑一个最小示例
环境搭好了，得验证一下能不能用。写个最简单的代码，加载一个 ONNX 模型做推理。
先准备一个测试模型。如果你手头没有，可以用 ONNX 官方提供的：
# 下载测试模型
wget https://github.com/onnx/models/raw/main/vision/classification/squeezenet/model/squeezenet1.0-8.onnx然后写 Python 验证脚本：
import onnxruntime as ort
import numpy as np
# 检查可用后端
print("可用后端:", ort.get_available_providers())
# 加载模型
session = ort.InferenceSession("squeezenet1.0-8.onnx")
# 获取输入输出信息
input_name = session.get_inputs()[0].name
output_name = session.get_outputs()[0].name
print(f"输入: {input_name}, 形状: {session.get_inputs()[0].shape}")
print(f"输出: {output_name}, 形状: {session.get_outputs()[0].shape}")
# 构造随机输入（模拟一张图片）
dummy_input = np.random.randn(1, 3, 224, 224).astype(np.float32)
# 推理
result = session.run([output_name], {input_name: dummy_input})
print("推理成功！输出形状:", result[0].shape)如果输出类似下面这样，说明环境没问题：
可用后端: ['CPUExecutionProvider']
输入: data_0, 形状: [1, 3, 224, 224]
输出: softmaxout_1, 形状: [1, 1000, 1, 1]
推理成功！输出形状: (1, 1000, 1, 1)
✅ 验证清单：
- Python 能正常 import onnxruntime
- 能加载 .onnx 文件
- 能执行推理并返回结果
- 没有 dll 或 so 文件缺失错误
2.5 常见问题与避坑指南
我整理了几个高频问题，都是我在项目里踩过的坑：
| 问题 | 原因 | 解决方案 |
|---|---|---|
| ImportError: No module named 'onnxruntime' | 没安装或装错环境 | 检查当前 Python 环境，用 pip list | grep onnx 确认 |
| RuntimeError: Dll load failed | Windows 下缺少 VC++ 运行库 | 安装 Visual C++ Redistributable 2015-2022 |
| Segmentation fault (core dumped) | 模型 opset 版本不兼容 | 降级或升级 ONNX Runtime 版本 |
| ONNX Runtime only supports 64-bit | 用了 32 位 Python | 换成 64 位 Python 3.8+ |
💡 我的经验： 如果遇到「找不到 Provider」的错误，八成是 GPU 版本没装对。先切回 CPU 版本跑通流程，再回头折腾 GPU 加速。别一上来就挑战高难度。
好了，环境搭完，咱们就可以正式开始玩模型了。下一章我会带你写第一个完整的推理程序，从加载模型到输出结果，一条龙走通。
记住：环境搭得好，后面没烦恼。花点时间把这一步做扎实，后面你会感谢自己的。