3. 环境搭建

在正式进入模型导出与图优化之前，环境搭建是决定后续所有实验能否顺利复现的第一道关卡。很多初学者在导出ONNX时遇到的“算子不支持”“opset版本冲突”“Runtime加载失败”等问题，根源往往不在模型本身，而在于依赖版本之间的错配。本节将围绕ONNX、ONNX Runtime、PyTorch/TensorFlow三大依赖，讲清安装逻辑、版本兼容性检查方法，以及如何用最小代价验证环境是否可用。

一、核心原理：为什么版本兼容性是关键

ONNX本身只是一个中间表示格式，它由三部分组成：ONNX规范（opset）、导出器（Exporter）和运行时（Runtime）。PyTorch或TensorFlow负责把训练好的模型翻译成ONNX图，ONNX Runtime负责加载并执行这张图。三者之间通过opset版本建立契约：导出器生成的opset版本，必须被Runtime支持；Runtime支持的算子集，又必须覆盖模型中实际用到的算子。

因此，环境搭建的本质不是“把包装上”，而是建立一条版本可追溯、算子可覆盖、执行可验证的链路。如果只关注安装成功，而忽略版本矩阵，后续图优化阶段会出现大量难以定位的报错。

二、方法流程：三步完成可复现环境搭建

推荐使用虚拟环境隔离依赖，避免与系统Python或其他项目冲突。以下流程以PyTorch导出为例，TensorFlow用户可将导出部分替换为tf2onnx。

1. 创建并激活虚拟环境：使用conda或venv均可，建议Python 3.9～3.11，这是当前ONNX生态兼容性最好的区间。
2. 安装核心依赖：按“框架→ONNX→Runtime”的顺序安装，便于观察版本解析结果。
3. 执行兼容性检查：用一段最小脚本验证导出、校验、推理三个环节是否全部通过。

# 1. 创建虚拟环境
conda create -n onnx-lab python=3.10 -y
conda activate onnx-lab

# 2. 安装依赖（示例版本，可按需调整）
pip install torch==2.1.0 torchvision==0.16.0
pip install onnx==1.15.0
pip install onnxruntime==1.16.3
pip install numpy==1.24.4

# 3. 查看版本
python -c "import torch, onnx, onnxruntime, numpy; \
print('torch', torch.__version__); \
print('onnx', onnx.__version__); \
print('onnxruntime', onnxruntime.__version__); \
print('numpy', numpy.__version__)"

安装完成后，建议立即运行下面的最小验证脚本。它同时完成导出、结构校验和推理执行，是判断环境是否可用的“金标准”。

import torch, onnx, onnxruntime as ort
import numpy as np

class TinyNet(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = torch.nn.Linear(4, 2)
    def forward(self, x):
        return self.fc(x)

model = TinyNet().eval()
dummy = torch.randn(1, 4)

torch.onnx.export(
    model, dummy, "tiny.onnx",
    input_names=["input"], output_names=["output"],
    opset_version=17, dynamic_axes={"input": {0: "batch"}}
)

# 结构校验
onnx.checker.check_model("tiny.onnx")
print("ONNX 模型结构校验通过")

# 推理验证
sess = ort.InferenceSession("tiny.onnx", providers=["CPUExecutionProvider"])
out = sess.run(None, {"input": dummy.numpy()})[0]
print("Runtime 推理输出形状:", out.shape)

三、版本兼容性对照与检查清单

下表给出常见组合的参考区间。实际项目中应以官方发布说明为准，但该表可作为快速排查的起点。

四、案例场景与常见误区复盘

场景：某团队在PyTorch 2.2上导出opset=18的模型，但服务器安装的是ONNX Runtime 1.14，加载时直接报“Unsupported model IR version”。原因在于Runtime 1.14最高支持IR version 8，而opset 18对应更高IR版本。解决方案是降低导出opset至17，或升级Runtime。

误区一：只装onnx，不装onnxruntime。onnx包只提供格式定义和校验工具，真正执行推理需要onnxruntime。两者职责不同，缺一不可。

误区二：忽略NumPy 2.x的ABI变化。部分旧版ONNX Runtime在NumPy 2.x下会出现导入错误，建议锁定1.26以下版本。

误区三：导出成功即认为环境可用。导出只证明图能生成，不代表Runtime能加载、能执行、能数值对齐。必须走完“导出→校验→推理→对比”四步。