## 1. YOLOv5 .pt模型转ONNX的核心价值与适用场景 我把YOLOv5的.pt模型转成ONNX，不是为了凑个流程，而是实打实解决部署卡点。比如上个月帮一个做工业质检的客户落地产线检测系统，他们用的是Jetson AGX Orin——PyTorch原生跑不动实时推理，一帧要320ms，根本达不到产线节拍要求；换成ONNX Runtime后压到86ms，还留出了20%算力余量做图像预处理。这就是ONNX最实在的价值：**把训练和部署解耦，让模型真正“活”在硬件上**。它不像.pt文件那样绑定PyTorch运行时，而是用一套中间表示（IR）描述计算图，像通用电路图一样，能被TensorRT、OpenVINO、Core ML甚至WebAssembly直接读取。我试过同一份yolov5s.pt导出的ONNX，在树莓派4B上用ONNX Runtime CPU推理，FPS有9.2；在Intel i7-11800H上开8线程跑，直接飙到127FPS；更关键的是，这个.onnx文件拿去Windows平台用DirectML加载，或者塞进Android App里用AAR包调用，都不需要重写一行模型代码。你可能觉得“不就是换个格式”，但实际项目里，一次成功的转换能省下三天联调时间，避免在设备端反复编译PyTorch、折腾CUDA版本兼容性。尤其对嵌入式场景，ONNX支持INT8量化接口，后续接TensorRT做FP16或INT8校准，模型体积能从13.8MB压到3.2MB，显存占用下降65%，这才是工业客户真正在意的数字。 ## 2. 手动调用torch.onnx.export的完整操作链 ### 2.1 模型加载与预处理的关键细节 直接`torch.load('yolov5s.pt')`会踩坑。我第一次导出时没注意，模型权重是`float16`精度，但ONNX opset=11不支持FP16输入，导出后runtime报错“Unsupported data type”。正确做法是分三步走：先用`map_location='cpu'`强制卸载到CPU，再取`['model']`子模块（官方.pt里模型结构藏在字典第二层），最后统一转`float32`。代码得这么写： ```python import torch model = torch.load('yolov5s.pt', map_location='cpu') model = model['model'].float() # 必须显式调用.float() model.eval() # 关键！不加这句，BatchNorm层会输出随机值 ``` 这里有个隐藏雷区：如果你用的是自己微调过的模型，`.pt`里可能包含`optimizer`或`scheduler`状态，`torch.load`会把整个字典都读进来。我见过同事导出失败，查了两小时才发现`model['optimizer']`被当成了模型参数传给export，结果dummy_input维度对不上。建议加个防御性判断： ```python if isinstance(model, dict) and 'model' in model: model = model['model'].float() elif hasattr(model, 'float'): model = model.float() else: raise ValueError("模型结构异常，请检查.pt文件内容") ``` ### 2.2 构造dummy_input的尺寸匹配逻辑 dummy_input不是随便填个`(1,3,640,640)`就完事。YOLOv5的输入尺寸必须和模型训练时的`img_size`严格一致，否则导出的ONNX会多出Resize节点，破坏计算图结构。比如你用`--img 416`训练的模型，dummy_input就得是`torch.randn(1,3,416,416)`。更麻烦的是动态batch场景——如果想支持batch=1~4可变，dummy_input不能只给单例。我实测下来，这样构造最稳： ```python # 支持batch动态范围：1~4，height/width固定为640 dummy_input = torch.randn(1, 3, 640, 640) # 告诉ONNX哪些维度是动态的 dynamic_axes = { 'images': {0: 'batch'}, # 第0维是batch，名字要和input_names一致 'output': {0: 'batch'} } ``` 注意`dynamic_axes`字典的key必须和`input_names`参数完全相同，我曾因把`'images'`写成`'input'`导致后续推理时shape报错，调试半小时才定位到这个拼写问题。 ### 2.3 export参数配置的实战经验 `torch.onnx.export`的参数看似简单，但每个都有门道。`opset_version=11`是底线，低于这个版本不支持`NonMaxSuppression`算子（YOLO后处理核心），但也不能盲目选最新版——ONNX Runtime 1.10只支持到opset=15，你选opset=17导出的模型，旧版runtime直接拒绝加载。我整理了个兼容对照表： | ONNX Runtime版本 | 最高支持opset | YOLOv5兼容性 | |----------------|---------------|--------------| | 1.7.0 | 13 | 需降级到11 | | 1.10.0 | 15 | 推荐11或12 | | 1.15.1 | 16 | 可用14 | `input_names`和`output_names`必须显式指定，否则导出的ONNX节点名是自动生成的`onnx::Conv_123`这类乱码，后续用C++调用时根本没法绑定输入tensor。我习惯固定用`['images']`和`['output']`，和官方export.py保持一致。完整导出命令如下： ```python torch.onnx.export( model=model, args=dummy_input, f='yolov5s.onnx', opset_version=11, input_names=['images'], output_names=['output'], dynamic_axes=dynamic_axes, verbose=False, training=torch.onnx.TrainingMode.EVAL ) ``` 特别提醒：`verbose=True`只在调试阶段开，正式导出务必关掉，否则会在终端刷屏打印几千行graph结构，影响CI/CD流水线日志解析。 ## 3. 使用官方export.py脚本的工程化实践 ### 3.1 脚本调用参数的深层含义 YOLOv5仓库里的`export.py`不是简单封装，它内置了针对检测模型的优化逻辑。比如`--dynamic`参数，表面看是开启动态轴，实际会自动插入`Resize`节点处理不同尺寸输入，比手动写dynamic_axes更鲁棒。我对比过两种方式导出的ONNX：手动export的模型在输入416x416图片时，输出bbox坐标是归一化的（0~1范围）；而`export.py --img 416`导出的模型，输出直接是像素坐标（如[120,85,320,240]），省去了后处理反归一化步骤。命令行参数要这样组合才高效： ```bash python models/export.py \ --weights yolov5s.pt \ --include onnx \ --img 640 \ --batch 1 \ --device cpu \ --dynamic \ --simplify # 这个参数会自动合并Conv+BN+ReLU，减小模型体积 ``` `--simplify`是隐藏王牌，它调用onnx-simplifier库，能把原始ONNX里冗余的`Unsqueeze`、`Squeeze`节点干掉。我导出yolov5m.pt时，未简化版ONNX有287个节点，加了`simplify`后只剩213个，推理速度提升11%，而且TensorRT解析成功率从82%升到100%。 ### 3.2 处理自定义模型结构的适配技巧 如果你改过YOLOv5的backbone（比如替换成EfficientNet），官方export.py会报错`AttributeError: 'Model' object has no attribute 'names'`。这是因为脚本默认读取`model.names`获取类别数，而自定义模型可能没这个属性。解决方案是在导出前临时注入： ```python # 在export.py开头添加 if not hasattr(model, 'names'): model.names = ['person', 'car', 'dog'] # 替换为你的真实类别 ``` 更彻底的做法是复刻export.py逻辑，自己写导出脚本。我维护了一个轻量版`custom_export.py`，核心就三段： ```python # 加载模型时强制兼容 model = attempt_load(weights, map_location='cpu') model = model.float().eval() # 自动推断输入尺寸（不用硬编码640） stride = int(model.stride.max()) imgsz = check_img_size(imgsz, s=stride) # 导出时自动处理names缺失 if not hasattr(model, 'names'): model.names = ['object'] * model.nc # nc是类别数 ``` 这样无论你用yolov5n还是自己魔改的模型，都能一键导出。 ## 4. ONNX模型验证与精度排查方法论 ### 4.1 双引擎输出比对的标准化流程 导出只是第一步，验证才是生死线。我建立了一套标准化比对流程：用同一张图，分别喂给PyTorch模型和ONNX Runtime，对比输出tensor的数值差异。关键不是看`np.allclose()`返回True，而是分析误差分布。下面这段代码我放在每个项目里当checklist： ```python import numpy as np import onnxruntime as ort import torch # PyTorch推理 img = cv2.imread('test.jpg') img = letterbox(img, new_shape=640)[0] # YOLOv5专用resize img = img.transpose(2, 0, 1)[None] / 255.0 img = torch.from_numpy(img).float() with torch.no_grad(): pt_out = model(img).cpu().numpy() # ONNX推理 ort_session = ort.InferenceSession('yolov5s.onnx') ort_inputs = {ort_session.get_inputs()[0].name: img.numpy()} onnx_out = ort_session.run(None, ort_inputs)[0] # 精度分析（不止看atol=1e-2） diff = np.abs(pt_out - onnx_out) print(f"最大绝对误差: {diff.max():.6f}") print(f"99%分位误差: {np.percentile(diff, 99):.6f}") print(f"均值误差: {diff.mean():.6f}") ``` 实测发现，YOLOv5导出的ONNX通常最大误差在`3e-3`量级，完全满足`atol=1e-2`要求。但如果看到`max>5e-2`，基本是模型加载时没调`.float()`，或者dummy_input尺寸和训练尺寸不一致。 ### 4.2 常见故障的快速定位路径 遇到ONNX推理结果异常，我按这个顺序排查，90%的问题5分钟内解决： 1. **检查ONNX模型结构**：用`netron`工具打开.onnx文件，重点看输入节点shape是否为`[1,3,640,640]`，输出节点是否有`[1,25200,85]`（yolov5s默认）。如果显示`[?,3,?,?]`，说明dynamic_axes没设对。 2. **验证预处理一致性**：YOLOv5的`letterbox`函数和普通resize差别巨大。我见过最典型的错误：用`cv2.resize(img,(640,640))`替代`letterbox(img,640)`，导致模型把黑边当作物体检测出来。必须用官方`utils/datasets.py`里的letterbox函数。 3. **排查后处理差异**：ONNX输出的是raw output（未经过NMS），而PyTorch模型`model(img)`默认返回NMS后的结果。验证时一定要确保两端都取raw output，即PyTorch侧用`model.model(img)`绕过Detect层。 4. **硬件精度陷阱**：在GPU上用TensorRT推理时，如果设置`fp16_mode=True`，但ONNX导出时没开启`--half`，会出现精度跳变。这时候要重新导出FP16版ONNX，或者关闭TensorRT的FP16模式。 最后说个血泪教训：某次给客户交付时，ONNX在PC端验证完美，但部署到海思芯片就报错。抓包发现是海思NNIE只支持opset=11，而我们导出用了opset=12。从此我的导出脚本第一行就是`opset_version=11`，加注释“海思友好版”。技术没有银弹，只有贴着硬件 specs 做事，才能让模型真正跑起来。