2、ONNX环境搭建：安装ONNX、ONNX Runtime、Protobuf，验证安装

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

这一章的目标很明确——把ONNX相关的工具链装好。说白了，就是装三个东西：ONNX本身、ONNX Runtime、还有Protobuf。别小看这一步，我见过太多人卡在环境上，折腾半天跑不起来，最后发现是Protobuf版本不对。

嗯，咱们一步步来。

2.1 为什么是这三件套？

先理清关系。你想想看，ONNX模型就像一个“中间格式”，它负责把不同框架（PyTorch、TensorFlow）的模型统一起来。而ONNX Runtime是专门用来跑这个格式的推理引擎。至于Protobuf，它是ONNX模型的“骨架”——模型文件本身就是用Protobuf序列化的。

我在项目中遇到过一个问题：模型导出成功了，但加载时报错“无法解析protobuf”。查了半天，发现是Protobuf版本太老，ONNX opset不兼容。从那以后，我每次搭建环境都会先确认Protobuf版本。

核心关系：

  • ONNX：模型定义与导出工具
  • ONNX Runtime：跨平台推理引擎
  • Protobuf：序列化协议，ONNX模型的底层依赖

2.2 安装前的准备

我个人习惯用Python 3.8-3.11之间的版本。太新的Python（比如3.12）有时候会遇到一些包还没适配的情况。建议用conda或者venv创建虚拟环境，别污染系统Python。

# 创建虚拟环境（推荐）
conda create -n onnx_env python=3.9
conda activate onnx_env

# 或者用 venv
python -m venv onnx_env
source onnx_env/bin/activate  # Linux/Mac
# onnx_env\Scripts\activate   # Windows

小提示：虚拟环境的名字随意，但我习惯用“onnx_env”，一看就知道是干嘛的。

2.3 安装Protobuf

先装Protobuf。为什么先装它？因为ONNX和ONNX Runtime都依赖它。顺序搞反了可能会出问题。

# 安装 Protobuf 编译器
pip install protobuf

# 验证安装
protoc --version

如果你看到类似 libprotoc 3.21.12 的输出，说明装好了。版本建议在3.20以上，我推荐3.21.x系列，比较稳定。

注意：我曾经在Windows上遇到过protoc命令找不到的情况。这是因为pip安装的protobuf只包含了Python库，没包含编译器。你需要单独下载protoc的二进制文件。去GitHub的protobuf releases页面下载对应系统的版本，解压后把路径加到环境变量里。

2.4 安装ONNX

接下来装ONNX核心库。这个简单，一行命令搞定：

pip install onnx

装完之后，咱们验证一下：

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

正常会输出类似 1.15.0 的版本号。如果报错，多半是Protobuf版本不匹配。检查一下Protobuf版本，必要时升级：

pip install --upgrade protobuf

验证ONNX核心功能：

import onnx
import onnx.helper as helper

# 创建一个简单的模型
input = helper.make_tensor_value_info('input', onnx.TensorProto.FLOAT, [1, 3, 224, 224])
output = helper.make_tensor_value_info('output', onnx.TensorProto.FLOAT, [1, 1000])

node = helper.make_node('Relu', ['input'], ['output'])
graph = helper.make_graph([node], 'test_graph', [input], [output])
model = helper.make_model(graph)

# 检查模型
onnx.checker.check_model(model)
print("模型创建成功，验证通过！")

这段代码创建了一个最简单的ONNX模型——一个ReLU层。如果运行没报错，说明ONNX安装完全OK。

2.5 安装ONNX Runtime

ONNX Runtime是咱们真正用来跑模型的东西。安装也很直接：

pip install onnxruntime

如果你有NVIDIA GPU并且想用CUDA加速，装这个：

pip install onnxruntime-gpu

我的建议：刚开始学习时，先用CPU版本。等后面章节讲到性能优化时，再切到GPU版本。省得一开始就被CUDA版本问题搞晕。

验证安装：

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

输出类似 1.17.0 就对了。咱们再跑个简单的推理测试：

import onnxruntime as ort
import numpy as np

# 创建一个简单的会话
session = ort.InferenceSession()
print("ONNX Runtime 会话创建成功！")

# 实际使用需要加载模型，这里只是验证安装
print(f"可用提供者: {ort.get_available_providers()}")

2.6 完整验证脚本

我习惯把验证步骤写成一个脚本，一键运行。这样以后换环境时也能快速确认：

"""
ONNX环境验证脚本
运行此脚本确认所有组件安装正确
"""
import sys

def check_installation():
    print("=" * 50)
    print("ONNX 环境验证")
    print("=" * 50)
    
    # 检查 Python 版本
    print(f"\n[1] Python 版本: {sys.version}")
    
    # 检查 Protobuf
    try:
        import google.protobuf
        print(f"[2] Protobuf 版本: {google.protobuf.__version__}")
    except ImportError:
        print("[2] Protobuf 未安装！")
        return False
    
    # 检查 ONNX
    try:
        import onnx
        print(f"[3] ONNX 版本: {onnx.__version__}")
        
        # 创建并验证模型
        import onnx.helper as helper
        input = helper.make_tensor_value_info('x', onnx.TensorProto.FLOAT, [1, 10])
        output = helper.make_tensor_value_info('y', onnx.TensorProto.FLOAT, [1, 5])
        node = helper.make_node('Relu', ['x'], ['y'])
        graph = helper.make_graph([node], 'test', [input], [output])
        model = helper.make_model(graph)
        onnx.checker.check_model(model)
        print("    ONNX 模型创建与验证通过！")
    except ImportError:
        print("[3] ONNX 未安装！")
        return False
    
    # 检查 ONNX Runtime
    try:
        import onnxruntime
        print(f"[4] ONNX Runtime 版本: {onnxruntime.__version__}")
        print(f"    可用提供者: {onnxruntime.get_available_providers()}")
    except ImportError:
        print("[4] ONNX Runtime 未安装！")
        return False
    
    print("\n" + "=" * 50)
    print("所有组件安装成功！环境准备就绪。")
    print("=" * 50)
    return True

if __name__ == "__main__":
    check_installation()

2.7 常见问题与避坑指南

问题 原因 解决方案
ImportError: No module named 'onnx' ONNX未安装或虚拟环境未激活 检查是否在正确的虚拟环境中，重新运行 pip install onnx
protoc: command not found Protobuf编译器未安装或不在PATH中 下载protoc二进制文件并添加到PATH，或使用conda安装：conda install -c conda-forge protobuf
ONNX Runtime报错：DLL load failed Windows下缺少VC++运行库 安装Microsoft Visual C++ Redistributable
ONNX版本与Protobuf不兼容 Protobuf版本过旧或过新 固定Protobuf版本为3.21.x：pip install protobuf==3.21.12

我曾经踩过的坑：有一次在Ubuntu服务器上装ONNX Runtime GPU版本，死活装不上。折腾了两小时，最后发现是CUDA版本不匹配。ONNX Runtime 1.17需要CUDA 11.8，而我装的是12.0。所以，装GPU版本前一定先查官方文档的CUDA版本要求。

2.8 验证结果

运行上面的验证脚本，如果看到类似下面的输出，恭喜你，环境搭建成功了：

==================================================
ONNX 环境验证
==================================================

[1] Python 版本: 3.9.18
[2] Protobuf 版本: 3.21.12
[3] ONNX 版本: 1.15.0
    ONNX 模型创建与验证通过！
[4] ONNX Runtime 版本: 1.17.0
    可用提供者: ['CPUExecutionProvider']

==================================================
所有组件安装成功！环境准备就绪。
==================================================

好，环境搭好了。下一章咱们就开始玩真的——把PyTorch模型导出成ONNX格式。到时候你会发现，前面这些准备工作有多重要。

← 上一章 📖 返回目录 下一章 →