计算机视觉 / 系统课时

导出 ONNX 模型

导出 ONNX 模型

本课把训练得到的 best.pt 转换为可跨框架部署的 ONNX 文件,并完成结构检查。你将明确固定尺寸与动态尺寸的区别,确认输入、输出节点是否符合预期,避免把“导出成功”误判为“模型已经可以直接上线”。

学习目标

  • 使用 YOLOv5 的 export.py 导出 ONNX 模型
  • 检查输入输出节点、张量形状和模型合法性
  • 根据部署环境选择动态尺寸、opset 与图简化参数

导出前检查

下面操作默认在 YOLOv5 项目根目录执行,并且已经获得训练权重 runs/train/exp/weights/best.pt。ONNX 的输入通常采用 BCHW 排列,即批量、通道、高度、宽度;检测模型的输出最后一维通常为 5 + 类别数,分别对应边界框、目标置信度和类别分数。

启用 --dynamic 后,导出脚本会把批量、高度、宽度等维度标记为动态轴;未启用时,模型只接受导出时确定的输入形状。当前 YOLOv5 官方导出脚本使用 onnx 作为导出类型,并为检测模型生成名为 images 的输入和 output0 的主要输出。:contentReference[oaicite:0]{index=0}

PyTorch 权重转换为 ONNX 的导出链路

执行导出

先安装导出与运行时依赖,再使用训练权重执行转换。--opset 12 兼容性较广,--simplify 会精简计算图,但不会把模型量化为 INT8。

bash
python -m pip install onnx onnxruntime onnxslim
python export.py \
  --weights runs/train/exp/weights/best.pt \
  --include onnx \
  --imgsz 640 640 \
  --batch-size 1 \
  --opset 12 \
  --dynamic \
  --simplify

预期结果

text
ONNX: export success <TIME>s, saved as runs/train/exp/weights/best.onnx
Export complete <TIME>s

日志格式会随仓库版本略有不同,但必须看到 ONNX 导出成功,并在权重同级目录生成 best.onnx。若部署端只接受固定的 1×3×640×640,应删除 --dynamic,减少运行时形状处理的不确定性。

检查输入输出节点

将下面脚本保存为 inspect_onnx.py,它会执行 ONNX 标准合法性检查、补全可推断的张量形状,并打印输入、输出和元数据。脚本中的模型路径应与实际导出位置一致。

python
from pathlib import Path

import onnx
from onnx import shape_inference

MODEL_PATH = Path("runs/train/exp/weights/best.onnx")

def read_dims(value_info: onnx.ValueInfoProto) -> list[object]:
    dims: list[object] = []
    for dim in value_info.type.tensor_type.shape.dim:
        if dim.dim_param:
            dims.append(dim.dim_param)
        elif dim.HasField("dim_value"):
            dims.append(dim.dim_value)
        else:
            dims.append("?")
    return dims

def main() -> None:
    if not MODEL_PATH.exists():
        raise FileNotFoundError(f"模型不存在:{MODEL_PATH}")

    model = onnx.load(MODEL_PATH)
    onnx.checker.check_model(model)
    inferred = shape_inference.infer_shapes(model)

    print(f"model: {MODEL_PATH.name}")
    print("check: passed")
    for item in inferred.graph.input:
        print(f"input: {item.name} {read_dims(item)}")
    for item in inferred.graph.output:
        print(f"output: {item.name} {read_dims(item)}")

    metadata_keys = sorted(item.key for item in model.metadata_props)
    print(f"metadata: {metadata_keys}")

if __name__ == "__main__":
    main()

预期输出

text
model: best.onnx
check: passed
input: images ['batch', 3, 'height', 'width']
output: output0 ['batch', 'anchors', <5+CLASS_COUNT>]
metadata: ['names', 'stride']

<5+CLASS_COUNT> 会显示为实际整数。例如自定义数据集有 3 个类别时,最后一维通常为 8。若没有使用 --dynamic,输入和输出中的动态名称会被具体数字替代。

关键边界与失败处理

动态尺寸不等于任意尺寸都适合部署。YOLOv5 通常要求输入高宽与模型步长兼容,工程上常使用 32 的倍数;部署端还必须使用与训练、验证一致的缩放、填充和归一化流程。

导出失败时按顺序检查:权重能否被当前仓库正常加载、依赖是否安装在当前 Python 环境、目标运行时是否支持所选 opset。若简化阶段失败,可先移除 --simplify 导出原始 ONNX;若运行时报告算子不支持,可降低 opset 后重新导出。

普通检测 ONNX 输出的是模型预测张量,不代表已经完成最终筛选。部署代码仍需执行置信度过滤、坐标还原和非极大值抑制,否则会看到大量重叠候选框。

本课总结

  • export.py --include onnx 可把 YOLOv5 权重转换为跨框架模型
  • 动态轴决定输入尺寸是否可变,opset 决定算子表达与运行时兼容性
  • 导出后必须检查模型合法性、节点名称和张量形状

下一课预告

下一课将使用同一输入分别运行 PyTorch 与 ONNX 模型,对比检测结果、数值误差和推理耗时,确认导出模型是否真正可用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

导出 ONNX 模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通