2、环境搭建与工具链：Python环境准备、ONNX核心库安装、onnxruntime安装、Netron可视化工具、protobuf兼容性问题

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

环境搭建这事，说简单也简单，说坑也多。我见过不少同学，模型都写好了，结果卡在装包上，一卡就是半天。说白了，ONNX 的工具链并不复杂，但版本之间的「爱恨情仇」你得心里有数。

2.1 Python 环境准备

我个人习惯用 conda 来管理环境。为什么？因为干净、好隔离。你想想看，一个项目一套环境，互不干扰，多省心。

conda create -n onnx_env python=3.9
conda activate onnx_env

Python 版本我建议选 3.8 到 3.11 之间。3.12 虽然新，但有些 ONNX 生态的包还没完全跟上。我在项目中吃过这个亏，当时图新鲜上了 3.12，结果某个算子库死活装不上，最后乖乖退回 3.10。

2.2 ONNX 核心库安装

ONNX 核心库，就是 onnx 这个包。它负责模型的序列化、反序列化，还有图结构的操作。

pip install onnx

装完之后，你可以快速验证一下：

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

如果能正常输出版本号，说明装好了。嗯，这里要注意，ONNX 的版本和 protobuf 的版本是绑定的。我后面会专门讲这个坑。

2.3 onnxruntime 安装

onnxruntime 是推理引擎，也是咱们落地的核心。它分 CPU 版和 GPU 版，安装命令不一样。

CPU 版本：

pip install onnxruntime

GPU 版本：

pip install onnxruntime-gpu

GPU 版需要 CUDA 和 cuDNN 的支持。我建议用 CUDA 11.8 + cuDNN 8.6 这个组合，兼容性最好。你可以用下面这段代码验证 GPU 是否生效：

import onnxruntime as ort
print(ort.get_device())

如果输出是 GPU，那就对了。

2.4 Netron 可视化工具

Netron 是我最常用的模型可视化工具。它支持 ONNX、TensorFlow、PyTorch 等多种格式。说白了，它就是模型界的「看图软件」。

安装方式有两种：

• 在线版： 打开 netron.app，直接把模型文件拖进去就行。
• 本地版： 用 pip 安装，适合离线环境。

pip install netron
netron your_model.onnx

我个人习惯用本地版。为什么？因为模型文件有时候很大，上传到网页不太安全，尤其是公司内部的模型。

Netron 能帮你看到什么？

• 模型的输入输出节点名称和形状
• 每一层的算子类型和参数
• 模型的整体拓扑结构

我在项目中经常用它来排查模型结构对不对。比如有一次，模型导出后推理结果全是错的，我用 Netron 一看，发现某个算子的输入顺序搞反了。嗯，这种问题光看代码很难发现，但可视化一下就一目了然。

2.5 protobuf 兼容性问题

这个坑，我估计每个做 ONNX 部署的人都踩过。

ONNX 底层依赖 protobuf 来序列化模型。protobuf 的版本如果不对，你会遇到各种莫名其妙的错误，比如：

google.protobuf.message.DecodeError: Error parsing message

为什么会这样？因为 ONNX 的每个版本都绑定了特定范围的 protobuf 版本。你装了一个太新或太旧的 protobuf，解析模型时就会出问题。

我给大家一个参考表：

ONNX 版本	推荐的 protobuf 版本
1.12.x	3.20.x
1.13.x	3.20.x
1.14.x	3.20.x 或 3.21.x
1.15.x	3.20.x 或 3.21.x
1.16.x	4.21.x 或 3.20.x

安装命令：

pip install protobuf==3.20.3

我曾经在一个项目里，因为 protobuf 版本不对，模型加载时直接崩了。排查了整整一个下午，最后发现是 conda 自动帮我升级了 protobuf。从那以后，我每次装 ONNX 环境，第一件事就是先锁死 protobuf 版本。

2.6 完整环境安装脚本

为了方便，我整理了一个一键安装脚本。你直接复制到终端里跑就行：

conda create -n onnx_env python=3.9 -y
conda activate onnx_env

pip install protobuf==3.20.3
pip install onnx==1.14.0
pip install onnxruntime==1.15.0
pip install netron

# 验证安装
python -c "import onnx; print('ONNX:', onnx.__version__)"
python -c "import onnxruntime; print('ORT:', onnxruntime.__version__)"
python -c "import netron; print('Netron installed')"

跑完之后，如果所有版本都能正常打印，那你的环境就准备好了。

好了，环境搭好了，下一章咱们就开始讲怎么把模型转成 ONNX 格式。那才是真正的重头戏。