2. 环境搭建：Python环境配置、安装onnxruntime、numpy、opencv等依赖库

2.1 核心原理：为什么环境搭建是ONNX模型调用的“地基”

ONNX（Open Neural Network Exchange）本身是一个中间表示格式，它并不直接执行推理计算。当我们拿到一个 .onnx 文件时，真正负责加载模型、执行算子运算的是推理引擎——在本课程中即 onnxruntime。而 numpy 负责处理输入输出的多维数组（Tensor），opencv-python 则承担图像解码、缩放、颜色空间转换等预处理任务。三者协作关系如下：

  • onnxruntime：解析模型结构，调用底层CPU/GPU算子库完成前向计算，输出结果Tensor。
  • numpy：提供 ndarray 数据结构，作为模型输入输出的载体，并支持维度变换、归一化等数学运算。
  • opencv-python：读取图片为BGR格式的numpy数组，执行resize、cvtColor等操作，将原始图像转换为模型期望的输入张量。

如果环境版本不匹配（例如Python 3.12搭配过旧的onnxruntime），会出现 DLL load failed 或 No module named 'onnxruntime' 等错误。因此，搭建一个干净、版本可控的Python虚拟环境是后续所有案例能够稳定复现的前提。

版本选择建议：本课程统一采用 Python 3.10，该版本对onnxruntime、opencv-python的二进制wheel支持最全面，且兼容PyTorch/TensorFlow导出模型。若使用Python 3.12+，部分旧版onnxruntime可能无法安装。
ONNX模型Python调用环境依赖关系 原始输入 图像 / 文本 / 数值 预处理 opencv-python · 图像解码 · resize / 归一化 · BGR→RGB转换 numpy ndarray 形状: [1,3,H,W] dtype: float32 onnxruntime InferenceSession 加载 .onnx 模型 执行算子计算 推理结果 分类概率 / 检测框 / 特征 model.onnx 模型文件（磁盘） 环境搭建 = 安装上述三个库 + 保证版本兼容 + 验证导入成功

2.2 方法流程：从零搭建可复现的Python推理环境

推荐使用 venv 或 conda 创建独立虚拟环境，避免污染系统级Python。以下以 venv 为例，演示完整流程：

  1. 创建虚拟环境（在项目根目录执行）
python -m venv onnx_env
# 激活环境（Windows）
onnx_env\Scripts\activate
# 激活环境（Linux/macOS）
source onnx_env/bin/activate
  1. 升级pip并安装核心依赖
python -m pip install --upgrade pip
pip install onnxruntime numpy opencv-python
  1. 验证安装是否成功
python -c "import onnxruntime, numpy, cv2; print('onnxruntime', onnxruntime.__version__); print('numpy', numpy.__version__); print('opencv', cv2.__version__)"

预期输出类似：

onnxruntime 1.17.1
numpy 1.26.4
opencv 4.9.0.80
补充安装（按需）：若需GPU加速，可安装 onnxruntime-gpu 替代 onnxruntime，并确保本机已安装CUDA和cuDNN。CPU版本足以运行本课程全部案例。

2.3 案例/场景：图像分类模型的最小调用骨架

环境搭建完成后，我们用一个最小案例验证“图像→numpy→onnxruntime→结果”的完整链路。假设已有一个ResNet50导出的 resnet50.onnx 模型文件：

import cv2
import numpy as np
import onnxruntime as ort

# 1. 读取并预处理图像
img = cv2.imread("cat.jpg")
img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
img = cv2.resize(img, (224, 224))
img = img.astype(np.float32) / 255.0
# 归一化（ImageNet标准）
mean = np.array([0.485, 0.456, 0.406], dtype=np.float32)
std = np.array([0.229, 0.224, 0.225], dtype=np.float32)
img = (img - mean) / std
# 调整维度为 [1, 3, 224, 224]
input_tensor = np.transpose(img, (2, 0, 1))[None, ...]

# 2. 创建推理会话
session = ort.InferenceSession("resnet50.onnx", providers=["CPUExecutionProvider"])

# 3. 获取输入输出名称
input_name = session.get_inputs()[0].name
output_name = session.get_outputs()[0].name

# 4. 执行推理
result = session.run([output_name], {input_name: input_tensor})
pred = np.argmax(result[0])
print(f"预测类别索引: {pred}")

这段代码验证了三个关键点：opencv正确读取图像、numpy完成维度变换与归一化、onnxruntime成功加载模型并输出结果。如果环境有问题，错误会在这四步中暴露。

2.4 常见误区与排障复盘

误区/错误 可能原因 解决方案
ModuleNotFoundError: No module named 'onnxruntime' 未激活虚拟环境，或pip安装到了其他Python 执行 where python 检查当前解释器路径；确认激活了正确的venv
DLL load failed while importing onnxruntime Python版本过新（3.12+）或缺少VC++运行库 降级到Python 3.10；安装“Visual C++ Redistributable”
cv2.imread 返回 None 图像路径错误或包含中文路径 使用绝对路径；将图像放在纯英文目录下
输入维度不匹配报错 忘记增加batch维度，或通道顺序错误 打印 session.get_inputs()[0].shape 确认期望形状
GPU版本安装后仍使用CPU 未安装CUDA/cuDNN，或providers未指定 检查 onnxruntime.get_available_providers()，确认包含 CUDAExecutionProvider
重要提醒：不要使用 pip install onnxruntime 和 pip install onnxruntime-gpu 混装。两者会互相覆盖，导致不可预知的运行时错误。若需切换，请先卸载旧版本再安装新版本。

2.5 环境验证清单（快速自检）

完成安装后，建议按以下清单逐项确认，确保后续章节案例不会因环境问题中断：

  • ✅ python --version 显示 3.10.x
  • ✅ pip list 中能看到 onnxruntime、numpy、opencv-python 三个包
  • ✅ 能成功导入三个库且打印版本号
  • ✅ 使用一张测试图片运行2.3节代码，得到预测结果
  • ✅ 确认 onnxruntime.get_available_providers() 包含预期执行提供程序
← 上一章 📖 返回目录 下一章 →