ONNX基础：格式介绍、模型结构解析与常用工具生态

在正式进入量化压缩案例之前，必须先建立对 ONNX 的扎实认知。ONNX（Open Neural Network Exchange）是一个开放式的模型表示标准，它的核心价值在于：让模型在不同框架之间自由流转，同时为推理优化（包括量化）提供统一的操作入口。理解 ONNX 的底层结构，是后续所有压缩操作的前提。

2.1 ONNX 格式本质：Protobuf 与序列化

ONNX 文件（通常以 .onnx 结尾）本质上是一个使用 Protocol Buffers（Protobuf） 序列化后的二进制文件。Protobuf 是一种高效、与语言无关的结构化数据序列化机制，它定义了数据的字段类型、嵌套关系和重复规则。ONNX 规范通过 onnx.proto 文件定义了模型、图、节点、张量等核心数据结构。

这种设计带来了三个关键特性：

  • 跨语言/跨框架：任何支持 Protobuf 的语言（C++、Python、Java 等）都能解析 ONNX 文件。
  • 紧凑高效：二进制格式比 JSON/文本格式体积更小，解析速度更快，适合存储和传输。
  • 版本可控：ONNX 自带 ir_version 和 opset_import 字段，确保不同版本间的兼容性。

一个 ONNX 文件的顶层结构可以用下面的简化示意表示：

ModelProto
├── ir_version: 8                     # IR 版本号
├── producer_name: "pytorch"          # 导出框架
├── graph: GraphProto                 # 计算图主体
│   ├── node: [NodeProto, ...]        # 算子节点列表
│   ├── initializer: [TensorProto,...]# 初始权重（常量）
│   ├── input: [ValueInfoProto, ...]  # 图输入
│   ├── output: [ValueInfoProto, ...] # 图输出
│   └── value_info: [...]             # 中间张量形状信息
└── opset_import: [OperatorSetIdProto] # 算子集版本
关键认知：ONNX 文件不是“可执行程序”，而是一份静态计算图描述。它只描述“做什么运算、数据从哪来、到哪去”，真正的执行由各推理引擎（如 ONNX Runtime、TensorRT）完成。

2.2 模型结构核心要素解析

要有效操作 ONNX 模型，必须理解图中四个核心要素：Node（节点）、Initializer（初始化器）、ValueInfo（值信息）和 Graph（图）。下面通过一个典型的卷积神经网络片段来解析它们的关系。

input [1,3,224,224] Conv kernel: 3x3 stride: 2 padding: 1 initializer conv.weight [64,3,3,3] conv_out [1,64,112,112] Relu 激活 MaxPool kernel: 2x2 stride: 2 output [1,64,56,56] GraphProto 边界 Node（算子） Initializer（权重常量） ValueInfo（张量元数据）

上图展示了一个典型的 ONNX 子图。可以看到：Node 是计算单元（Conv、Relu、MaxPool），它们通过有向边连接；Initializer 是权重常量（如 conv.weight），它们不经过输入端口，而是直接“注入”到节点中；ValueInfo 描述了张量的形状和数据类型，这些信息对量化时确定每个张量的取值范围至关重要。

在 Python 中，我们可以用 onnx 库轻松解析模型结构：

import onnx

# 加载模型
model = onnx.load("resnet18.onnx")
graph = model.graph

# 打印图输入/输出
print("Inputs:", [(i.name, [d.dim_value for d in i.type.tensor_type.shape.dim]) for i in graph.input])
print("Outputs:", [(o.name, [d.dim_value for d in o.type.tensor_type.shape.dim]) for o in graph.output])

# 统计节点类型
from collections import Counter
op_types = Counter(node.op_type for node in graph.node)
print("算子统计:", dict(op_types))

# 查看初始权重
for init in graph.initializer[:3]:
    print(f"权重: {init.name}, 形状: {list(init.dims)}, 数据类型: {init.data_type}")

2.3 常用工具链与生态全景

ONNX 的价值不仅在于格式本身，更在于围绕它建立的庞大工具生态。下表列出了后续量化压缩工作中最常用的工具：

工具/库 核心用途 在量化压缩中的角色
onnx 模型加载、保存、结构修改 基础操作库，所有流程的起点
onnxruntime 高性能推理引擎 验证量化前后精度、性能差异
onnxconverter-common 量化公共工具 提供量化参数计算的基础函数
onnxoptimizer 图优化（算子融合、常量折叠） 量化前精简图结构，减少冗余节点
onnxruntime.quantization 官方量化工具 支持静态/动态量化、QDQ 格式导出
Netron 可视化模型结构 直观检查量化后图结构是否正确
polygraphy 模型调试与精度比对（NVIDIA） 逐层比对量化前后误差来源

这些工具形成了典型的工作流闭环：先用 onnx 加载并分析模型，用 onnxoptimizer 做预处理，再用 onnxruntime.quantization 执行量化，最后用 onnxruntime 做精度和性能验证。如果发现问题，可以用 Netron 可视化检查，或借助 polygraphy 定位到具体出错层。

2.4 典型场景：PyTorch → ONNX → 推理引擎

一个最常见的生产链路是：PyTorch 训练 → 导出 ONNX → ONNX Runtime/TensorRT 部署。导出时需注意以下要点：

import torch
import torchvision.models as models

model = models.resnet18(pretrained=True)
model.eval()

# 构造示例输入（batch=1, 3通道, 224x224）
dummy_input = torch.randn(1, 3, 224, 224)

# 导出 ONNX
torch.onnx.export(
    model,                      # 模型
    dummy_input,                # 示例输入
    "resnet18.onnx",            # 输出路径
    input_names=["input"],      # 输入名
    output_names=["output"],    # 输出名
    dynamic_axes={              # 动态维度（可选）
        "input": {0: "batch_size"},
        "output": {0: "batch_size"}
    },
    opset_version=17,           # 算子集版本
    do_constant_folding=True    # 常量折叠
)
print("导出成功！")
常见误区：导出 ONNX 时盲目设置 dynamic_axes 会导致后续量化困难。动态轴会阻止某些算子融合，且量化校准需要固定形状的张量。如果部署时 batch size 固定为 1，建议先导出静态形状模型，待量化完成后再考虑动态化。

2.5 复盘：ONNX 结构认知对量化的意义

理解 ONNX 结构对后续量化工作有直接的指导意义：

  • Initializer 是权重量化的目标：量化主要修改 initializer 中的浮点权重为整数表示。
  • ValueInfo 中的形状信息决定校准数据格式：量化校准需要知道每个中间张量的形状，以准备匹配的输入数据。
  • Node 类型决定量化策略：Conv、MatMul 等算子对量化敏感，而 Relu、MaxPool 等通常可以无损量化。
  • opset 版本影响量化算子支持：QDQ（Quantize-Dequantize）格式需要 opset 13 以上，动态量化需要 opset 11 以上。
← 上一章 📖 返回目录 下一章 →