3、环境准备：安装PyTorch、ONNX、onnxruntime、onnxoptimizer等工具，配置Python环境与验证安装

在开始ONNX模型转换之前，搭建一个干净、可复现的Python环境是决定后续工作效率的关键。许多初学者在模型导出时遇到“算子不支持”或“动态维度报错”，根源往往不是模型代码本身，而是工具链版本不匹配或安装顺序混乱。本章将系统讲解从Python虚拟环境创建、核心依赖安装到安装验证的完整闭环，并针对CPU与GPU环境、Windows与Linux平台的差异给出可操作的解决方案。

3.1 环境规划与Python虚拟环境配置

ONNX转换工具链涉及多个Python包，它们之间存在复杂的依赖关系。直接使用系统全局Python环境安装，极易出现包版本冲突，且不同项目间的隔离性无法保证。因此，第一步是创建独立的虚拟环境。推荐使用Anaconda或Miniconda管理环境，它不仅支持Python版本切换，还能方便地管理CUDA相关的依赖。

创建虚拟环境的操作流程如下：

# 创建Python 3.10环境，命名为onnx_env
conda create -n onnx_env python=3.10 -y

# 激活环境
conda activate onnx_env

# 确认Python版本
python --version

激活环境后，所有后续安装操作都应在此虚拟环境中进行。使用conda activate而非source activate，确保在Windows和Linux下行为一致。若网络环境受限，可配置清华或阿里云的conda镜像源加速下载。

3.2 核心工具链安装：PyTorch、ONNX、onnxruntime与onnxoptimizer

安装顺序遵循“底层依赖优先”原则。PyTorch是模型来源框架，ONNX是中间表示格式，onnxruntime是推理引擎，onnxoptimizer是优化工具。建议按以下顺序依次安装，避免依赖解析冲突。

3.2.1 安装PyTorch

PyTorch的安装命令因硬件平台而异。对于仅需CPU推理的学习环境，直接使用pip安装CPU版本即可；若需GPU加速，则需根据CUDA版本选择对应的安装源。

# CPU版本（适用于所有平台，体积小，安装快）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# GPU版本（以CUDA 11.8为例）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

3.2.2 安装ONNX与onnxruntime

ONNX是模型转换的目标格式，onnxruntime是执行ONNX模型的推理引擎。两者独立安装，但版本需保持兼容。onnxruntime提供CPU、GPU、DirectML等多种执行提供程序，学习阶段安装CPU版本即可。

# 安装ONNX标准库
pip install onnx

# 安装onnxruntime（CPU版本）
pip install onnxruntime

# 如需GPU加速推理，可安装onnxruntime-gpu
# pip install onnxruntime-gpu

安装完成后，可通过以下命令验证ONNX与onnxruntime的版本兼容性：

python -c "import onnx; print('ONNX version:', onnx.__version__)"
python -c "import onnxruntime; print('ORT version:', onnxruntime.__version__)"

3.2.3 安装onnxoptimizer

onnxoptimizer是一个用于ONNX模型计算图优化的工具库，支持常量折叠、节点融合、冗余消除等优化操作。它并非onnxruntime的强制依赖，但建议安装，以便在模型导出后对计算图进行精简。

# 通过pip直接安装
pip install onnxoptimizer

# 若安装失败（部分平台无预编译wheel），可尝试源码安装
git clone https://github.com/onnx/optimizer.git
cd optimizer
pip install -e .

3.3 安装验证与常见排障

安装完成后，必须进行系统性的功能验证，而不仅仅是检查版本号。一个完整的验证流程应包含：导入测试、基础张量转换测试、简单模型导出测试和onnxruntime推理测试。以下是一个标准验证脚本：

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

# 1. 验证PyTorch可用
x = torch.randn(1, 3, 224, 224)
print("PyTorch tensor shape:", x.shape)

# 2. 定义一个简单的线性模型并导出
class SimpleModel(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = torch.nn.Linear(10, 5)
    def forward(self, x):
        return self.fc(x)

model = SimpleModel()
dummy_input = torch.randn(1, 10)
torch.onnx.export(model, dummy_input, "test_model.onnx",
                  input_names=["input"], output_names=["output"],
                  opset_version=17)
print("ONNX export successful")

# 3. 验证ONNX模型加载
onnx_model = onnx.load("test_model.onnx")
onnx.checker.check_model(onnx_model)
print("ONNX model check passed")

# 4. 验证onnxruntime推理
ort_session = ort.InferenceSession("test_model.onnx")
ort_inputs = {ort_session.get_inputs()[0].name: dummy_input.numpy()}
ort_outputs = ort_session.run(None, ort_inputs)
print("ONNX Runtime output shape:", ort_outputs[0].shape)

若上述脚本全部执行成功，说明环境配置正确。若在某一环节报错，可参考下表进行针对性排查：

3.4 实战场景：从零搭建一个可复用的ONNX开发环境

以一个实际项目为例：某团队需要将PyTorch训练的ResNet18图像分类模型部署到Jetson Nano边缘设备。团队最初在各自电脑上独立安装环境，结果出现三种不同的PyTorch版本和两种ONNX版本，导致模型导出后部分算子不兼容。最终通过统一环境配置解决了问题。

具体操作步骤如下：

1. 制定环境规范：统一使用Python 3.10、PyTorch 2.1.0（CPU版）、ONNX 1.16.0、onnxruntime 1.17.0、onnxoptimizer 0.3.13。
2. 编写requirements.txt：锁定所有依赖包的精确版本号，确保可复现。
3. 使用conda创建环境：执行conda create -n onnx_env python=3.10，然后逐项安装。
4. 编写自动化验证脚本：将3.3节的验证脚本保存为verify_env.py，每次环境变更后运行一次。
5. 记录环境快照：使用conda list --export > environment.yml保存完整依赖列表。

该团队通过此流程，将环境搭建时间从平均2小时缩短至15分钟，且模型导出成功率从70%提升至98%。关键经验是：版本锁定比追求最新版本更重要，尤其是在团队协作和边缘部署场景中。

3.5 常见误区与总结复盘

在环境准备阶段，以下误区最容易导致后续转换失败：