📚 课程目录第4章环境搭建与工具准备

4. 环境搭建与工具准备：安装ONNX Runtime、Python环境、性能分析工具

4.1 核心原理：为什么环境准备决定调优成败

ONNX Runtime（简称ORT）是一个跨平台推理引擎，其性能表现高度依赖构建配置、执行后端和硬件指令集。同一个ONNX模型，在不同环境下可能产生数倍甚至数十倍的推理延迟差异。调优工作本质上是在“模型结构—硬件特性—运行时配置”三者之间寻找最优匹配，因此环境搭建不是一次性安装，而是建立一套可复现、可观测、可对比的基准实验平台。

环境准备的核心目标有三个：

可复现性：固定Python版本、ORT版本、依赖库版本，确保每次实验的基线一致。
可观测性：安装profiling工具，能够捕获算子级耗时、内存分配、CPU/GPU利用率等关键指标。
可对比性：支持在同一模型上切换不同执行提供程序（CPU、CUDA、TensorRT）和不同优化级别，快速评估收益。

版本锁定建议：生产环境务必使用 requirements.txt 或 conda-lock 锁定所有依赖版本。ONNX Runtime的版本更新频繁，不同版本对算子融合策略、图优化逻辑均有差异，版本漂移会让调优结论失真。

4.2 方法流程：从零搭建可调优的实验环境

推荐使用 conda 创建独立Python环境，避免系统级Python被污染。以下步骤在Ubuntu 20.04/22.04 + CUDA 11.8环境下验证通过，Windows/macOS用户需调整CUDA相关部分。

步骤一：创建Python虚拟环境

# 创建Python 3.10环境（ORT对3.10支持最稳定）
conda create -n ort_env python=3.10 -y
conda activate ort_env

# 安装基础依赖
pip install --upgrade pip
pip install numpy onnx psutil py-spy

步骤二：安装ONNX Runtime

根据硬件选择安装包。CPU版本直接使用PyPI源，GPU版本需匹配CUDA版本。

# CPU版本（所有机器可用）
pip install onnxruntime

# GPU版本（CUDA 11.8 + cuDNN 8.x）
pip install onnxruntime-gpu

# 验证安装
python -c "import onnxruntime as ort; print(ort.__version__); print(ort.get_available_providers())"
# 期望输出: ['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider']

常见坑：onnxruntime-gpu 与 onnxruntime 不能共存于同一环境。若已安装CPU版，需先 pip uninstall onnxruntime 再安装GPU版。另外，CUDA、cuDNN、TensorRT版本必须与ORT官方文档中的兼容矩阵严格对应，否则运行时会报“Failed to create CUDAExecutionProvider”。

步骤三：安装性能分析工具链

# ORT自带profiling功能（无需额外安装）
# 通过SessionOptions启用即可

# Perfetto - 系统级性能追踪（用于分析CPU调度、GPU活动）
pip install perfetto

# 可选：安装onnx模型可视化工具
pip install netron

# 验证Perfetto可用
python -c "import perfetto; print('Perfetto OK')"

步骤四：编写环境自检脚本

每次开始调优前，运行以下脚本确认环境健康：

import onnxruntime as ort
import psutil, platform, time

print(f"Python: {platform.python_version()}")
print(f"ORT: {ort.__version__}")
print(f"Providers: {ort.get_available_providers()}")
print(f"CPU: {platform.processor()}, 物理核: {psutil.cpu_count(logical=False)}")

# 简单推理测试
import numpy as np
sess = ort.InferenceSession(
    "model.onnx",
    providers=['CPUExecutionProvider'],
    sess_options=ort.SessionOptions()
)
x = np.random.rand(1, 3, 224, 224).astype(np.float32)
start = time.time()
for _ in range(10):
    sess.run(None, {"input": x})
print(f"平均推理耗时: {(time.time()-start)/10*1000:.2f} ms")

4.3 案例：一次典型的环境配置与Profiling验证

假设我们有一个ResNet50的ONNX模型，目标是在GPU服务器上达到5ms以内的推理延迟。以下是完整的环境配置与验证流程：

配置项	推荐值	说明
Python版本	3.10.12	兼容性最佳
onnxruntime-gpu	1.17.1	匹配CUDA 11.8
CUDA / cuDNN	11.8 / 8.6	严格遵循兼容矩阵
TensorRT	8.6.1	可选，可提升约20%
线程数	intra_op=4	根据CPU核数调整
优化级别	ORT_ENABLE_ALL	开启所有图优化

启用Profiling并分析输出：

import onnxruntime as ort

so = ort.SessionOptions()
so.enable_profiling = True  # 开启profiling
so.profile_file_prefix = "resnet50_run"  # 输出文件前缀
so.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
so.intra_op_num_threads = 4

sess = ort.InferenceSession(
    "resnet50.onnx",
    sess_options=so,
    providers=['CUDAExecutionProvider', 'CPUExecutionProvider']
)

# 执行推理...
output = sess.run(None, {"input": input_tensor})

# 结束后生成文件: resnet50_run_*.json
# 使用Perfetto UI (ui.perfetto.dev) 打开该JSON文件

在Perfetto时间线中，我们可以清晰看到每个算子的耗时分布。若发现Conv算子耗时占比超过60%，说明模型计算密集，可考虑TensorRT加速；若发现Memcpy频繁出现，则需优化数据预处理管线，减少CPU-GPU拷贝。

4.4 误区与复盘：环境搭建中的典型陷阱

误区一：盲目使用最新版本
最新版ORT可能引入新的算子融合规则，导致与生产环境的旧版行为不一致。调优结论必须基于固定版本，升级版本后需重新验证所有基准数据。

误区二：忽略CPU指令集差异
同一台机器上，Python的pip install onnxruntime默认下载的是兼容性版本，未启用AVX-512指令集。若CPU支持AVX-512，应从源码编译或下载特定wheel包，可获得15%-30%的性能提升。

  复盘建议：每次调优实验前，运行环境自检脚本并将输出保存为日志文件。建议使用dvc或mlflow记录每次实验的：环境版本、模型文件哈希、输入数据特征、profiling文件路径。这样当性能出现回退时，可以快速定位是代码变更还是环境漂移导致。

最后，务必验证Profiling数据的可靠性。ONNX Runtime的Profiling默认记录每个算子的start_time和duration，但GPU异步执行时，时间戳可能不准确。建议在关键实验中同时使用torch.profiler或Nsight Systems交叉验证，确保分析结论可信。