第2章 ONNX环境搭建

第2章：ONNX环境搭建：安装ONNX、ONNX Runtime、Protobuf编译器，验证环境是否可用

说实话，很多同学刚开始学ONNX，第一步就被环境搭建给卡住了。我当年也是，装个Protobuf折腾了一下午，版本不对、路径不对、Python环境冲突……各种问题轮番上阵。所以这一章，咱们就把这些坑提前填上。

环境搭建说白了就三件事：装ONNX、装ONNX Runtime、装Protobuf编译器。然后跑个demo验证一下，确保整个链路是通的。咱们一步步来。

2.1 准备工作：Python虚拟环境

我个人习惯，做任何AI项目之前，先建一个干净的虚拟环境。为什么？你想想看，你电脑上可能同时有TensorFlow 1.x和2.x，PyTorch 1.8和1.12，这些库的依赖经常打架。虚拟环境就是给每个项目一个独立的小房间，互不干扰。

小提示： 我建议用conda或者venv都行。我个人更偏爱conda，因为它在Windows上对Protobuf的二进制包支持更好。

# 创建虚拟环境（Python 3.8 - 3.11 都行，我推荐3.9）
conda create -n onnx_env python=3.9

# 激活环境
conda activate onnx_env

嗯，这里要注意：Python版本别太新也别太旧。3.12刚出来时，ONNX的某些依赖还没适配，我踩过这个坑。

2.2 安装ONNX核心库

ONNX本身是一个模型格式标准，它的Python包主要负责模型的导出、导入和结构操作。安装很简单：

pip install onnx

装完之后，你可以验证一下版本：

python -c "import onnx; print(onnx.__version__)"

如果正常输出版本号，比如 1.16.0，那就说明装好了。我曾经遇到过一次，装完报错说找不到 onnx.proto，后来发现是Protobuf版本不兼容。别急，咱们后面会专门讲Protobuf。

2.3 安装ONNX Runtime

ONNX Runtime是微软开源的推理引擎。说白了，它就是用来跑ONNX模型的。你导出模型之后，总得找个地方跑起来对吧？ONNX Runtime就是干这个的。

pip install onnxruntime

如果你有GPU，想用CUDA加速，那就装GPU版本：

pip install onnxruntime-gpu

注意： GPU版本对CUDA和cuDNN的版本有严格要求。我建议先装CPU版本把流程跑通，再考虑GPU加速。否则光配CUDA环境就能让你怀疑人生。

验证安装：

python -c "import onnxruntime; print(onnxruntime.__version__)"

2.4 安装Protobuf编译器

这个可能是最容易被忽略的一环。Protobuf（Protocol Buffers）是Google的一种数据序列化协议。ONNX模型文件本质上就是一个Protobuf序列化后的二进制文件。所以你要解析ONNX模型，就得有Protobuf编译器。

安装方式分两种：

方式一：用pip安装（推荐）

pip install protobuf

这种方式装的是Python版的Protobuf运行时库。对于大部分场景，这就够了。

方式二：安装protoc编译器（高级用法）

如果你需要从 .proto 文件生成Python代码，或者想查看ONNX的原始proto定义，那就需要装 protoc 命令行工具。

Windows： 去GitHub的 protobuf/releases 页面下载 protoc-x.x.x-win64.zip，解压后把 bin 目录加到环境变量PATH里。
Linux/Mac： apt install protobuf-compiler 或 brew install protobuf

验证protoc是否装好：

protoc --version

输出类似 libprotoc 3.21.12 就对了。

  避坑指南： 我曾经遇到过pip装的protobuf版本和protoc版本不一致，导致解析模型时出现奇怪的字段缺失错误。建议两者版本尽量对齐，比如都用3.21.x系列。

2.5 验证环境是否可用

环境都装好了，咱们写个简单的脚本验证一下。这个脚本会创建一个最简单的ONNX模型，然后用ONNX Runtime跑一次推理。

import onnx
import onnxruntime
import numpy as np

# 1. 创建一个简单的ONNX模型（一个加法运算）
# 定义输入和输出
X = onnx.helper.make_tensor_value_info('X', onnx.TensorProto.FLOAT, [1, 3])
Y = onnx.helper.make_tensor_value_info('Y', onnx.TensorProto.FLOAT, [1, 3])

# 定义节点：Add运算
node = onnx.helper.make_node(
    'Add',
    inputs=['X', 'Y'],
    outputs=['Z']
)

# 构建图
graph = onnx.helper.make_graph(
    [node],
    'test_graph',
    [X, Y],
    [onnx.helper.make_tensor_value_info('Z', onnx.TensorProto.FLOAT, [1, 3])]
)

# 构建模型
model = onnx.helper.make_model(graph)

# 检查模型是否合法
onnx.checker.check_model(model)
print("✅ 模型创建成功，结构合法！")

# 2. 用ONNX Runtime跑推理
session = onnxruntime.InferenceSession(model.SerializeToString())

# 准备输入数据
input_X = np.array([[1.0, 2.0, 3.0]], dtype=np.float32)
input_Y = np.array([[4.0, 5.0, 6.0]], dtype=np.float32)

# 运行推理
outputs = session.run(None, {'X': input_X, 'Y': input_Y})
print(f"✅ 推理结果：{outputs[0]}")
# 预期输出：[[5.0, 7.0, 9.0]]

如果一切顺利，你会看到两行绿色的勾勾。第一行表示模型创建和校验通过，第二行表示推理成功，结果正确。

小技巧： 如果你在运行 onnx.checker.check_model 时遇到错误，别慌。最常见的错误是输入输出类型不匹配，或者节点名称重复。仔细看错误信息，它通常会告诉你具体是哪一行出了问题。

2.6 常见问题与解决方案

我整理了几个我在项目中遇到过的典型问题，供你参考：

问题现象	可能原因	解决方案
安装onnx时提示 `ERROR: Could not build wheels for onnx`	缺少C++编译工具，或者Python版本不兼容	安装Visual Studio Build Tools（Windows）或 `build-essential`（Linux）；或者换用Python 3.9
运行 `onnx.checker.check_model` 报 `ValueError: ...`	模型结构有误，比如输入输出维度不匹配	检查 `make_tensor_value_info` 中的shape是否与节点运算一致
ONNX Runtime推理时提示 `Fail to load model`	模型文件损坏，或者ONNX Runtime版本与ONNX版本不兼容	升级/降级ONNX Runtime：`pip install onnxruntime==1.15.0`
protobuf报错 `TypeError: Descriptors cannot not be created directly`	protobuf版本过高（4.x）与ONNX不兼容	降级protobuf：`pip install protobuf==3.20.3`

重要提醒： protobuf 4.x 和 ONNX 的兼容性问题，是我见过最多人踩的坑。如果你用的是较新的protobuf，建议强制降到3.20.x。命令：pip install protobuf==3.20.3

2.7 本章小结

到这，你的ONNX开发环境就搭好了。咱们回顾一下：

建了一个干净的Python虚拟环境
装了ONNX核心库（负责模型构建和校验）
装了ONNX Runtime（负责模型推理）
装了Protobuf编译器（负责模型序列化/反序列化）
跑了一个完整的demo，从创建模型到推理输出

下一章，咱们会深入ONNX模型的结构，看看一个 .onnx 文件里面到底长什么样。你会惊讶地发现，它其实就是一个结构清晰的「计算图」——节点、边、属性，清清楚楚。

嗯，环境搭好了，后面的事情就好办了。咱们下章见。

📚 课程目录