计算机视觉 / 系统课时
导出 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}

执行导出
先安装导出与运行时依赖,再使用训练权重执行转换。--opset 12 兼容性较广,--simplify 会精简计算图,但不会把模型量化为 INT8。
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预期结果
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 标准合法性检查、补全可推断的张量形状,并打印输入、输出和元数据。脚本中的模型路径应与实际导出位置一致。
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()预期输出
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 模型,对比检测结果、数值误差和推理耗时,确认导出模型是否真正可用。