【Python实战】Windows系统下ONNX Runtime环境搭建：从CPU到GPU推理的完整配置指南

1. 为什么需要ONNX Runtime环境？

在深度学习模型部署的过程中，我们经常会遇到一个头疼的问题：训练环境和部署环境不一致。比如你在PyTorch或者TensorFlow里训练好的模型，想要放到Windows服务器上运行，这时候ONNX Runtime就能派上大用场了。

ONNX（Open Neural Network Exchange）就像是一个万能翻译器，它能把不同框架训练出来的模型转换成统一的格式。而ONNX Runtime则是专门用来运行这些ONNX模型的引擎，相当于一个高性能的"执行器"。我去年在部署一个图像识别项目时就深有体会，当时客户要求必须在Windows Server上运行，多亏了ONNX Runtime才解决了框架兼容性问题。

这个环境最大的优势在于它的跨平台性。不管你是用CPU还是GPU，Windows还是Linux，它都能很好地支持。特别是对于Windows平台的开发者来说，ONNX Runtime提供了完整的Python API，用起来就像调用普通Python库一样简单。而且它还能自动调用CUDA进行GPU加速，我在实际测试中发现，同样的模型用GPU版本推理，速度能提升5-8倍。

2. 准备工作：搭建基础Python环境

2.1 Python版本选择

在开始之前，我们需要确保Python环境配置正确。根据我的经验，ONNX Runtime对Python 3.6-3.9的支持最好。太老的版本可能会有兼容性问题，太新的版本又可能遇到一些依赖冲突。我建议使用Python 3.8，这个版本在Windows上的稳定性最好。

你可以通过命令行检查当前Python版本：

python --version

如果还没有安装Python，可以直接从官网下载安装包。记得勾选"Add Python to PATH"选项，这样后面用起来会方便很多。

2.2 升级pip工具

很多安装问题其实都出在pip版本太老上。我建议先升级pip到最新版，这样可以避免很多依赖冲突。升级命令很简单：

python -m pip install --upgrade pip

这里有个小技巧：如果你在国内，可能会遇到下载慢的问题。可以临时使用清华镜像源来加速：

python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple

升级完成后，建议再运行一次pip --version确认版本号。我遇到过不少案例都是因为pip版本问题导致后续安装失败，所以这一步千万别偷懒。

3. 安装ONNX和CPU版ONNX Runtime

3.1 安装ONNX核心库

ONNX库是处理模型转换的基础，我们先来安装它。虽然ONNX Runtime运行模型时不一定需要这个库，但如果你要做模型转换或者查看模型信息，ONNX库是必不可少的。

安装命令如下：

pip install onnx -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，可以通过简单的Python代码测试是否安装成功：

import onnx print(onnx.__version__)

这里有个常见问题：可能会遇到protobuf版本冲突。如果安装过程中报错，可以尝试先卸载旧版本：

pip uninstall protobuf pip install protobuf==3.20.0

3.2 安装ONNX Runtime CPU版本

CPU版本是ONNX Runtime的基础版本，即使你后面要使用GPU加速，也建议先安装CPU版本测试基本功能。

安装命令：

pip install onnxruntime -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，我们可以写个简单的测试脚本：

import onnxruntime as ort sess = ort.InferenceSession("model.onnx") # 替换成你的模型路径 print("ONNX Runtime CPU版本运行正常！")

如果你还没有现成的ONNX模型，可以用ONNX官方提供的测试模型：

import onnx from onnx import helper from onnx import TensorProto # 创建一个简单的模型 node = helper.make_node("Add", inputs=["X", "Y"], outputs=["Z"]) graph = helper.make_graph( [node], "test", [ helper.make_tensor_value_info("X", TensorProto.FLOAT, [1]), helper.make_tensor_value_info("Y", TensorProto.FLOAT, [1]), ], [helper.make_tensor_value_info("Z", TensorProto.FLOAT, [1])], ) model = helper.make_model(graph) # 保存模型 onnx.save(model, "test_model.onnx") # 测试运行 sess = ort.InferenceSession("test_model.onnx") result = sess.run(None, {"X": [1.0], "Y": [2.0]}) print(result) # 应该输出[array([3.], dtype=float32)]

4. 配置GPU加速环境

4.1 检查CUDA和cuDNN环境

要使用ONNX Runtime的GPU版本，首先得确保你的Windows系统已经安装了正确的CUDA和cuDNN。这是最容易出问题的环节，我见过太多开发者在这里栽跟头。

首先检查CUDA版本：

nvcc --version

ONNX Runtime 1.11版本需要CUDA 11.4，而最新版可能支持更新的CUDA。如果没安装CUDA，需要先去NVIDIA官网下载安装包。安装时建议选择"自定义安装"，只安装必要的组件。

接下来是cuDNN，这个需要手动安装。下载对应版本的cuDNN后，把bin、include、lib目录下的文件复制到CUDA安装目录下对应的文件夹里。

4.2 安装ONNX Runtime GPU版本

确认CUDA环境没问题后，就可以安装GPU版本了：

pip install onnxruntime-gpu -i https://pypi.tuna.tsinghua.edu.cn/simple

这里有个重要细节：ONNX Runtime GPU版本的版本号必须和CUDA版本匹配。比如如果你用的是CUDA 11.4，那么应该安装：

pip install onnxruntime-gpu==1.11.0

安装完成后，我们可以修改之前的测试代码来检查GPU是否正常工作：

import onnxruntime as ort # 创建GPU会话 providers = ['CUDAExecutionProvider', 'CPUExecutionProvider'] sess = ort.InferenceSession("model.onnx", providers=providers) # 检查使用的provider print(sess.get_providers())

如果输出中包含'CUDAExecutionProvider'，说明GPU加速已经启用。我在实际项目中发现，有时候虽然安装了GPU版本，但默认还是会用CPU运行，这时候就需要像上面代码那样显式指定provider。

4.3 性能对比测试

为了直观展示GPU加速的效果，我们可以做个简单的性能对比：

import time import numpy as np import onnxruntime as ort # 准备测试数据 input_data = np.random.rand(1, 3, 224, 224).astype(np.float32) # CPU测试 cpu_sess = ort.InferenceSession("model.onnx", providers=['CPUExecutionProvider']) start = time.time() for _ in range(100): cpu_sess.run(None, {'input': input_data}) print(f"CPU平均耗时: {(time.time()-start)/100:.4f}秒") # GPU测试 gpu_sess = ort.InferenceSession("model.onnx", providers=['CUDAExecutionProvider']) start = time.time() for _ in range(100): gpu_sess.run(None, {'input': input_data}) print(f"GPU平均耗时: {(time.time()-start)/100:.4f}秒")

在我的RTX 3080上测试一个ResNet50模型，CPU平均耗时约0.15秒，而GPU只要0.02秒，性能提升非常明显。

5. 常见问题排查与优化技巧

5.1 版本兼容性问题

ONNX Runtime的版本兼容性是个大坑，我总结了几点经验：

1. ONNX Runtime版本要和CUDA版本严格匹配
2. Python版本最好在3.6-3.9之间
3. protobuf版本建议用3.20.x

如果遇到奇怪的报错，可以尝试创建一个干净的虚拟环境：

python -m venv onnx_env .\onnx_env\Scripts\activate pip install --upgrade pip

5.2 内存不足问题

GPU推理时可能会遇到内存不足的情况，这时候可以尝试：

1. 减小batch size
2. 使用ORT_ENABLE_ALL环境变量启用内存优化：

import os os.environ["ORT_ENABLE_ALL"] = "1"

5.3 多线程优化

ONNX Runtime支持多线程推理，可以通过设置线程数来优化性能：

options = ort.SessionOptions() options.intra_op_num_threads = 4 options.inter_op_num_threads = 4 sess = ort.InferenceSession("model.onnx", options)

对于CPU推理，线程数设置为物理核心数效果最好；而GPU推理时，适当减少线程数反而可能提升性能。

5.4 模型优化技巧

ONNX Runtime提供了一些模型优化工具，可以显著提升推理速度：

from onnxruntime.transformers import optimizer optimized_model = optimizer.optimize_model( "model.onnx", model_type='bert', # 根据模型类型选择 num_heads=12, # 模型参数 hidden_size=768 ) optimized_model.save_model_to_file("optimized_model.onnx")

我在一个NLP项目中使用优化后的模型，推理速度提升了近3倍。