第2章环境准备

第2章：环境准备——安装ONNX、ONNX Runtime、Protobuf以及相关依赖库

好，咱们正式开始动手了。

这一章，说白了就是搭积木。你得先把ONNX这套工具链装好，后面才能玩得转。我记得自己刚入坑ONNX那会儿，光装个Protobuf就折腾了一下午，版本不对、路径冲突、Python binding死活找不到……嗯，这些坑我今天都帮你填上。

2.1 核心依赖一览

先搞清楚我们要装什么。ONNX生态里，这几个东西是绕不开的：

组件	作用	我建议的版本
ONNX	模型格式标准，负责序列化/反序列化	≥1.12.0
ONNX Runtime	推理引擎，跑模型用的	≥1.15.0
Protobuf	序列化库，ONNX的底层依赖	3.20.x（别用4.x！）
numpy	数据处理，几乎必装	≥1.21.0

⚠️ 避坑指南： 我曾经因为装了Protobuf 4.x，结果ONNX死活加载不了模型，报错信息还特别隐晦。后来查了半天才发现是Protobuf版本不兼容。所以，Protobuf请锁定3.20.x，别手贱升到4.x。

2.2 安装ONNX

最简单的方式，用pip一把梭：

pip install onnx==1.12.0

如果你在墙内，速度慢得想砸电脑，可以加个国内镜像：

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

装完之后，验证一下：

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

能正常输出版本号，说明ONNX装好了。我个人习惯每次装完都跑一下这行命令，心里踏实。

2.3 安装ONNX Runtime

ONNX Runtime分CPU版和GPU版。怎么选？

CPU版： 通用，兼容性好，适合开发和调试。
GPU版： 需要CUDA和cuDNN，推理速度快很多。

CPU版安装：

pip install onnxruntime==1.15.0

GPU版安装（前提是你已经装好了CUDA 11.x和cuDNN 8.x）：

pip install onnxruntime-gpu==1.15.0

💡 小提示： 如果你不确定自己该装哪个，先装CPU版。等后面跑通了，再换GPU版也不迟。我在项目里经常这么干——先用CPU版调通流程，再切到GPU版压性能。

验证安装：

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

2.4 安装Protobuf

这个有点特殊。ONNX依赖Protobuf来做序列化，但Protobuf的Python包和C++库是两回事。

Python版安装：

pip install protobuf==3.20.3

C++版安装（Linux/macOS）：

# Ubuntu/Debian
sudo apt-get install protobuf-compiler libprotobuf-dev

# macOS
brew install protobuf

Windows用户呢？我个人建议直接用Python版就够了，除非你要从源码编译ONNX。大多数场景下，Python版的Protobuf完全够用。

    🔑 关键点： 装完Protobuf后，检查一下版本是否匹配：

    protoc --version  # 看C++版版本号

    python -c "import google.protobuf; print(google.protobuf.__version__)"  # 看Python版版本号

2.5 安装其他依赖库

除了上面三个核心组件，你还需要一些辅助库。我列个清单：

pip install numpy==1.21.0
pip install onnxconverter-common==1.9.0
pip install onnxoptimizer==0.3.0
pip install onnxruntime-tools==1.7.0  # 可选，用于模型优化

为什么要装 onnxoptimizer？你想想看，模型导出后往往有冗余算子，用这个工具可以剪枝、融合，让推理更快。我在一个OCR项目里，用optimizer把模型体积从200MB压缩到了150MB，推理速度提升了30%。

2.6 验证环境是否就绪

全部装完后，跑一个完整的验证脚本：

import onnx
import onnxruntime
import numpy as np

# 1. 创建一个简单的ONNX模型
# 这里用ONNX的helper API构建一个加法运算
import onnx.helper as helper
import onnx.numpy_helper as numpy_helper

# 定义输入
X = helper.make_tensor_value_info('X', onnx.TensorProto.FLOAT, [1, 3])
Y = helper.make_tensor_value_info('Y', onnx.TensorProto.FLOAT, [1, 3])

# 定义节点（加法）
node = helper.make_node('Add', inputs=['X', 'Y'], outputs=['Z'])

# 定义图
graph = helper.make_graph([node], 'add_graph', [X, Y], [helper.make_tensor_value_info('Z', onnx.TensorProto.FLOAT, [1, 3])])

# 定义模型
model = helper.make_model(graph, producer_name='test')

# 保存模型
onnx.save(model, 'test_add.onnx')
print("✅ ONNX模型创建并保存成功")

# 2. 用ONNX Runtime推理
session = onnxruntime.InferenceSession('test_add.onnx')
input_data = np.array([[1.0, 2.0, 3.0]], dtype=np.float32)
output = session.run(None, {'X': input_data, 'Y': input_data})
print(f"✅ 推理结果: {output[0]}")

# 3. 清理
import os
os.remove('test_add.onnx')
print("✅ 环境验证通过！")

如果这段代码能跑通，恭喜你，环境已经准备好了。如果报错，别慌——大概率是Protobuf版本问题，或者某个包没装全。回头检查一下上面的步骤。

⚠️ 常见报错及解决：

ImportError: No module named 'onnx' → 没装ONNX，或者装在了不同的Python环境里。
RuntimeError: Protobuf version mismatch → 你装了Protobuf 4.x，降级到3.20.x。
onnxruntime.capi.onnxruntime_pybind11_state.Fail → 模型文件损坏或版本不兼容，检查ONNX和ORT版本。

2.7 我的个人建议

最后，分享几个小习惯：

用虚拟环境： 我每个项目都建一个独立的conda环境或venv，避免包冲突。命令：conda create -n onnx_env python=3.9
记录版本号： 装完所有包后，跑 pip freeze > requirements.txt，方便以后复现。
别用最新版： 最新版往往有坑。我一般等新版本发布后一个月再升级，让社区先踩踩雷。

好了，环境准备就到这里。下一章，我们开始真正动手——把PyTorch模型导出成ONNX格式。到时候你会发现，前面这些准备工作有多值得。

📚 课程目录