简介这份PDF面向零基础想系统掌握YOLOv11目标检测的开发者与学习者围绕从PyTorch训练到ONNX跨平台部署的完整链路展开帮助解决环境配置、数据准备、模型训练、格式转换与多平台落地中的常见问题。资源包仅含1个PDF文件大小约2.29MB共45页支持目录跳转、阅读器左侧大纲显示与章节快速定位。内容先讲目标检测与YOLO发展、YOLOv11核心架构中的骨干网络、颈部网络与检测头以及相较前代的精度、速度、泛化和可扩展性改进随后覆盖环境搭建、数据收集标注与划分、PyTorch训练参数配置、损失监控和TensorBoard可视化并展开精确率、召回率、F1、mAP等评估指标与过拟合欠拟合处理。后半部分详细说明PyTorch转ONNX、ONNX Runtime验证、Netron可视化、算子不支持与形状不一致排错以及服务器、嵌入式、移动端部署、模型量化、并行计算和常见错误调试。已有77人学习下载适合按章节查阅、跟练与查漏补缺。1. 从一次部署翻车说起为什么要把 PyTorch 模型转成 ONNX去年帮一个做产线质检的朋友收拾过一个烂摊子模型在训练机上 mAP 跑到 0.89指标漂亮得能直接写进验收报告结果一上产线的工控机就卡在 12 FPS产线节拍要求 30 FPS整整差了一倍多。问题不在模型本身而在他们把训练环境那一整套 PyTorch CUDA 运行时原封不动搬到了没有独显的工控机上推理路径从 GPU 掉到 CPU还顺带背了一堆用不上的依赖。这类问题的解法通常是拆开两件事训练归训练部署归部署。训练阶段用 PyTorch 把 YOLOv11 调好导出成 ONNX 这个中间表示再由 ONNX Runtime 在目标硬件上跑推理。ONNX 的价值在于它把模型的计算图用一套与框架无关的算子描述固定下来同一份 .onnx 文件服务器上走 CUDA EP工控机上走 CPU EP边缘盒子上换成别的执行提供者不用重训也不用重写模型代码。这篇围绕 YOLOv11 的完整链路展开环境怎么配不踩坑、数据怎么组织、训练参数怎么设、评估指标怎么读、导出 ONNX 时哪些算子会炸、ONNX Runtime 推理的后处理怎么写、INT8 量化到底能省多少。适合刚接触目标检测的开发者也适合已经会训模型但卡在部署这一环的工程师。2. 训练前的环境、数据与依赖版本对齐2.1 PyTorch 环境搭建CUDA 版本先定再选轮子环境这一步翻车率极高根源基本都是一个先装 PyTorch 再去看显卡驱动顺序反了。正确顺序是先确认驱动支持的最高 CUDA 版本再挑对应的 PyTorch 轮子。# 1. 查驱动与它支持的 CUDA 上限 nvidia-smi # 2. 建独立环境避免污染系统 Python conda create -n yolo11 python3.10 -y conda activate yolo11 # 3. 按 nvidia-smi 右上角显示的 CUDA 版本选轮子以 CUDA 12.1 为例 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 # 4. 验证 python -c import torch; print(torch.__version__, torch.cuda.is_available())nvidia-smi右上角的 CUDA Version 是驱动能兼容的上限不是必须装这个版本装低一档的轮子兼容性更好。第 3 步的--index-url必须写默认 PyPI 源给的是 CPU 版这也是「明明有显卡却是 CPU 推理」的最常见原因。第 4 步必须输出 True如果输出 False先别往下走回去查驱动和轮子版本是否匹配。没有独显的机器就省掉 index-url直接pip install torch torchvision。用 conda 装的同学注意conda 渠道的 PyTorch 更新通常比 pip 慢半拍新卡建议直接走 pip。其余依赖pip install ultralytics opencv-python numpy onnx onnxruntime matplotlib tqdm依赖作用版本敏感点torch / torchvision训练与导出与 CUDA 驱动强绑定ultralyticsYOLOv11 训练/导出封装版本决定 API 命名onnx导出时构图需与 opset 匹配onnxruntimeCPU/GPU 推理与量化方式绑定opencv-python图像读写与后处理影响 resize 行为2.2 数据集组织YOLO 格式的目录与 YAML 写法YOLOv11 用的是 YOLO 系的标注格式每张图配一个同名 .txt每行类别 中心x 中心y 宽 高后四个值都是相对图像尺寸归一化到 0~1 的小数。dataset/ ├── images/ │ ├── train/ *.jpg │ └── val/ *.jpg ├── labels/ │ ├── train/ *.txt │ └── val/ *.txt └── data.yaml# data.yaml path: /home/user/dataset train: images/train val: images/val nc: 3 names: [scratch, dent, stain]path是数据集根目录train和val写相对路径即可程序会拼到 path 后面。nc与names长度必须一致不一致训练会直接报索引越界。图片和标签文件名必须严格对应除扩展名少一个标签文件这一张图就会被跳过且不会有明显警告这一点在排查「训练集数量对不上」时要记得查。划分比例上小数据集常见做法是按 8:1:1 分 train/val/test如果样本本来就少几百张量级建议只留 train/val用交叉验证替代独立测试集。提示标注完先跑一遍校验脚本检查有没有坐标越界1 或 0、有没有类别号大于 nc-1这两类错误在训练中往往表现为 loss 突然飙高而不是直接报错。2.3 训练参数学习率、批大小与轮数的配合关系from ultralytics import YOLO model YOLO(yolo11n.pt) # 从预训练权重起步 model.train( datadata.yaml, epochs150, imgsz640, batch16, lr00.01, # 初始学习率 lrf0.01, # 最终学习率 lr0 * lrf warmup_epochs3, # 前 3 轮线性预热 weight_decay0.0005, mosaic1.0, # 马赛克增强概率 close_mosaic15, # 最后 15 轮关闭稳定收敛 cacheTrue, device0, )lr0是最关键的一个数。从预训练权重微调时0.01 通常偏大更容易出现前几轮 loss 震荡可以降到 0.001~0.005 试。lrf控制学习率衰减的终点配合余弦退火策略训练后期学习率会逐渐逼近lr0*lrf让模型落到更平的极小值。warmup_epochs存在的意义是前期权重更新幅度大不加预热容易把预训练学到的特征直接冲垮。batch受显存限制显存不够时先降 batch 再考虑降 imgsz因为降分辨率会直接影响小目标的可检测性。close_mosaic是个容易被忽略但很有用的参数马赛克增强把四张图拼一起对小目标有利但拼出来的目标边界被裁切训练末期关掉能让模型在真实分布上收得更稳。cacheTrue把解码后的图像缓存在内存里数据集不大时几千张以内能明显减少每个 epoch 的 IO 等待。3. 训练过程监控与评估指标怎么读3.1 损失曲线与 TensorBoard 监控训练启动后会自动在runs/detect/train/下写结果results.csv是逐轮的指标记录weights/里放best.pt和last.pt。可视化直接用 TensorBoardtensorboard --logdir runs/detect/train --port 6006看三组曲线box_loss定位损失、cls_loss分类损失、dfl_loss分布焦点损失。健康形态是三条线同步下降然后趋于平缓。如果cls_loss降而box_loss不降通常是标注框质量差或锚框尺度与目标不匹配如果验证集 loss 在某个 epoch 后开始回升而训练 loss 继续降那就是过拟合。3.2 mAP、Precision、Recall 的取舍评估指标里最容易被误读的是 mAP。它是各类别 AP 的平均AP 又是 Precision-Recall 曲线下的面积所以 mAP 高不代表每个类都好。必看的是各类的 P/R 分布metrics model.val(datadata.yaml, splitval) print(metrics.box.map) # mAP0.5:0.95 print(metrics.box.map50) # mAP0.5 per_class metrics.box.ap_class_index # 每个类别的 AP指标含义低值时的排查方向Precision检出的框里正确的比例误检多检查负样本与背景Recall真实目标里被检出的比例漏检多检查标注覆盖与小目标mAP0.5IoU0.5 时的均值整体定位能力mAP0.5:0.95多 IoU 阈值平均对框的紧致度更敏感实际业务里 P 和 R 的取舍取决于代价。安防场景漏检代价高宁可有误报置信度阈值就调低质检场景误报会中断产线阈值调高牺牲一点 Recall 换 Precision。这个阈值是推理期的参数不用重训就能调但要在 mAP 表现好的模型上调才有意义。3.3 过拟合与欠拟合的判别和处理欠拟合的信号是训练集上指标本身就低通常意味着模型容量不足或训练轮数不够可以换更大规模的模型档位n→s→m或加轮数。过拟合的信号是训练集指标远高于验证集处理手段按性价比排序先加数据增强mosaic、mixup、随机缩放再考虑加 weight_decay最后才是减模型容量。注意小数据集上直接用 YOLOv11l/x 这类大模型几乎必然过拟合而且显存吃紧导致 batch 很小BN 统计不稳定反而不如中等档位稳。4. 导出 ONNX动态轴、opset 与验证4.1 导出参数怎么定from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) model.export( formatonnx, imgsz640, opset12, # 兼容性优先选 11/12 simplifyTrue, # 合并冗余算子 dynamicTrue, # 动态 batch 与尺寸 halfFalse, # 导出阶段不宜直接半精度 )opset决定算子的版本集合数值越高支持的算子越多但推理端的兼容性越差。很多嵌入式推理框架对 opset 17 以上支持不完整工程上常见的做法是锁在 11 或 12先保证能跑起来。dynamicTrue会把 batch 维和 H/W 维标成动态服务端需要变长输入时打开但某些推理后端对动态维优化较差固定尺寸的吞吐会更高按实际需求取舍。导出后先做一次形状检查import onnx m onnx.load(best.onnx) onnx.checker.check_model(m) # 结构合法性 print(m.graph.input[0]) # 输入名与形状 print([o.name for o in m.graph.output])onnx.checker.check_model通过只说明图结构合法不代表推理端能跑。更实用的是拿 Netron 打开看一眼输入输出张量的维度描述以及有没有异常的中间节点。4.2 导出后的数值一致性验证这一步很多人跳过结果部署后发现框全部偏移。做法是用同一张图分别跑原模型和 ONNX比较输出差异import numpy as np, onnxruntime as ort, torch from ultralytics import YOLO img cv2.imread(test.jpg) x torch.from_numpy(img).permute(2,0,1).float().unsqueeze(0) / 255.0 pt_out YOLO(best.pt).model(x)[0].detach().numpy() sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) onnx_out sess.run(None, {sess.get_inputs()[0].name: x.numpy()})[0] print(np.abs(pt_out - onnx_out).max()) # 一般应在 1e-3 ~ 1e-2 量级差异在 1e-2 以内通常可接受超过 1e-1 就要查是不是预处理不一致归一化系数、通道顺序、letterbox 的填充值、是不是导出时动态轴导致某些 reshape 行为变了。letterbox 的填充值不一致是很隐蔽的一类问题原模型和推理脚本对同一张图做了不同的 padding输出框坐标就会系统性地偏。4.3 常见导出报错及处理最典型的是算子不支持报错信息里会指出某个算子名。处理思路是回到导出参数降 opset 或开启 simplify如果是自定义算子需要提供自定义符号函数。第二类是输入输出形状不一致多半源于 dynamic 轴设置与实际推理输入不匹配。第三类是导出的模型体积异常大通常是 simplify 没生效或权重没被正确 constant folding可以对比导出前后节点数确认。提示导出前把模型设为 eval 模式否则 BN 和 Dropout 层会保留训练行为导出的图在推理时结果会漂。Ultralytics 的 export 内部已经处理了但自己写导出脚本时容易漏。5. ONNX Runtime 推理与 INT8 量化落地5.1 完整推理脚本预处理、会话、后处理import cv2, numpy as np, onnxruntime as ort sess ort.InferenceSession( best.onnx, providers[CPUExecutionProvider], # 有 GPU 换 CUDAExecutionProvider ) iname sess.get_inputs()[0].name def letterbox(img, size640): h, w img.shape[:2] r min(size / h, size / w) nh, nw int(round(h * r)), int(round(w * r)) resized cv2.resize(img, (nw, nh)) canvas np.full((size, size, 3), 114, dtypenp.uint8) # 填充值需与训练一致 canvas[:nh, :nw] resized return canvas, r img cv2.imread(test.jpg) canvas, r letterbox(img) x canvas[:, :, ::-1].transpose(2, 0, 1)[None].astype(np.float32) / 255.0 preds sess.run(None, {iname: x})[0] # shape: (1, 4nc, 8400) # 后处理置信度过滤 NMS scores preds[0, 4:, :].max(axis0) keep scores 0.25 boxes, cls preds[0, :4, keep], preds[0, 4:, keep].argmax(axis0)预处理里有三个必须与训练对齐的点通道顺序cv2 读进来是 BGR模型要 RGB、归一化系数除以 255、letterbox 填充值YOLO 系默认 114。任何一处不一致都会让精度掉得莫名其妙。输出张量的布局是(1, 4nc, 8400)8400 是三个尺度特征图的锚点数之和4nc前四位是中心点和宽高。这里的坐标还是相对 640 输入框的归一化值映射回原图时要先减掉 padding 偏移再除以缩放系数r。5.2 INT8 量化收益、代价与操作步骤INT8 量化的目的很直接把权重从 FP32 压到 8 位模型体积降到约四分之一CPU 上推理速度通常提升 1.5~3 倍。代价是精度损失对小目标尤其明显因为激活值的动态范围在小目标区域变化剧烈量化误差更容易放大。from onnxruntime.quantization import quantize_dynamic, QuantType quantize_dynamic( model_inputbest.onnx, model_outputbest_int8.onnx, weight_typeQuantType.QInt8, )这是动态量化只量化权重激活值在运行时量化不需要校准数据集操作最简单。如果精度掉得不能接受就得改用静态量化quantize_static需要准备一批代表性的校准图片让量化器统计激活值的分布来确定缩放因子。量化方式是否需要校准集体积速度精度损失FP32 原模型否1x基准无动态 INT8否约 0.25x中小到中静态 INT8是约 0.25x高可控判断量化是否可用还是要回到 5.1 里那套数值比对跑同一批图比较 FP32 和 INT8 输出的框数量、类别和 IoU。经验上 mAP 掉 1~2 个点属于常见范围掉超过 5 个点说明校准集代表性不够或者模型里对量化敏感的算子太多可以尝试对特定层做混合精度把最后几层检测头保留为 FP32。5.3 执行提供者的选择与一个调优技巧providers列表的顺序就是优先级ONNX Runtime 会依次尝试。服务端有 N 卡用CUDAExecutionProvider纯 CPU 用CPUExecutionProvider。CPU 场景下有两个参数值得调opts ort.SessionOptions() opts.intra_op_num_threads 4 # 算子内并行线程数 opts.graph_optimization_level ort.GraphOptimizationLevel.ORT_ENABLE_ALL sess ort.InferenceSession(best_int8.onnx, opts, providers[CPUExecutionProvider])intra_op_num_threads设成物理核心数而不是逻辑核心数超线程在这种计算密集场景里往往帮倒忙。另外如果是服务化部署并且输入尺寸固定把导出时的dynamic关掉让推理引擎能在构图阶段做更彻底的内存复用和算子融合吞吐通常比开启动态维高出一截。第一次推理会包含构图和内存分配的开销做性能测试时记得先跑几十次预热再统计。本文还有配套的精品资源点击获取 
长河君 · 2026/9/17 16:02:03 · 阅读 1.2k YOLOv11 部署链路：PyTorch 转 ONNX 与 INT8 量化
简介这份PDF面向零基础想系统掌握YOLOv11目标检测的开发者与学习者围绕从PyTorch训练到ONNX跨平台部署的完整链路展开帮助解决环境配置、数据准备、模型训练、格式转换与多平台落地中的常见问题。资源包仅含1个PDF文件大小约2.29MB共45页支持目录跳转、阅读器左侧大纲显示与章节快速定位。内容先讲目标检测与YOLO发展、YOLOv11核心架构中的骨干网络、颈部网络与检测头以及相较前代的精度、速度、泛化和可扩展性改进随后覆盖环境搭建、数据收集标注与划分、PyTorch训练参数配置、损失监控和TensorBoard可视化并展开精确率、召回率、F1、mAP等评估指标与过拟合欠拟合处理。后半部分详细说明PyTorch转ONNX、ONNX Runtime验证、Netron可视化、算子不支持与形状不一致排错以及服务器、嵌入式、移动端部署、模型量化、并行计算和常见错误调试。已有77人学习下载适合按章节查阅、跟练与查漏补缺。1. 从一次部署翻车说起为什么要把 PyTorch 模型转成 ONNX去年帮一个做产线质检的朋友收拾过一个烂摊子模型在训练机上 mAP 跑到 0.89指标漂亮得能直接写进验收报告结果一上产线的工控机就卡在 12 FPS产线节拍要求 30 FPS整整差了一倍多。问题不在模型本身而在他们把训练环境那一整套 PyTorch CUDA 运行时原封不动搬到了没有独显的工控机上推理路径从 GPU 掉到 CPU还顺带背了一堆用不上的依赖。这类问题的解法通常是拆开两件事训练归训练部署归部署。训练阶段用 PyTorch 把 YOLOv11 调好导出成 ONNX 这个中间表示再由 ONNX Runtime 在目标硬件上跑推理。ONNX 的价值在于它把模型的计算图用一套与框架无关的算子描述固定下来同一份 .onnx 文件服务器上走 CUDA EP工控机上走 CPU EP边缘盒子上换成别的执行提供者不用重训也不用重写模型代码。这篇围绕 YOLOv11 的完整链路展开环境怎么配不踩坑、数据怎么组织、训练参数怎么设、评估指标怎么读、导出 ONNX 时哪些算子会炸、ONNX Runtime 推理的后处理怎么写、INT8 量化到底能省多少。适合刚接触目标检测的开发者也适合已经会训模型但卡在部署这一环的工程师。2. 训练前的环境、数据与依赖版本对齐2.1 PyTorch 环境搭建CUDA 版本先定再选轮子环境这一步翻车率极高根源基本都是一个先装 PyTorch 再去看显卡驱动顺序反了。正确顺序是先确认驱动支持的最高 CUDA 版本再挑对应的 PyTorch 轮子。# 1. 查驱动与它支持的 CUDA 上限 nvidia-smi # 2. 建独立环境避免污染系统 Python conda create -n yolo11 python3.10 -y conda activate yolo11 # 3. 按 nvidia-smi 右上角显示的 CUDA 版本选轮子以 CUDA 12.1 为例 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 # 4. 验证 python -c import torch; print(torch.__version__, torch.cuda.is_available())nvidia-smi右上角的 CUDA Version 是驱动能兼容的上限不是必须装这个版本装低一档的轮子兼容性更好。第 3 步的--index-url必须写默认 PyPI 源给的是 CPU 版这也是「明明有显卡却是 CPU 推理」的最常见原因。第 4 步必须输出 True如果输出 False先别往下走回去查驱动和轮子版本是否匹配。没有独显的机器就省掉 index-url直接pip install torch torchvision。用 conda 装的同学注意conda 渠道的 PyTorch 更新通常比 pip 慢半拍新卡建议直接走 pip。其余依赖pip install ultralytics opencv-python numpy onnx onnxruntime matplotlib tqdm依赖作用版本敏感点torch / torchvision训练与导出与 CUDA 驱动强绑定ultralyticsYOLOv11 训练/导出封装版本决定 API 命名onnx导出时构图需与 opset 匹配onnxruntimeCPU/GPU 推理与量化方式绑定opencv-python图像读写与后处理影响 resize 行为2.2 数据集组织YOLO 格式的目录与 YAML 写法YOLOv11 用的是 YOLO 系的标注格式每张图配一个同名 .txt每行类别 中心x 中心y 宽 高后四个值都是相对图像尺寸归一化到 0~1 的小数。dataset/ ├── images/ │ ├── train/ *.jpg │ └── val/ *.jpg ├── labels/ │ ├── train/ *.txt │ └── val/ *.txt └── data.yaml# data.yaml path: /home/user/dataset train: images/train val: images/val nc: 3 names: [scratch, dent, stain]path是数据集根目录train和val写相对路径即可程序会拼到 path 后面。nc与names长度必须一致不一致训练会直接报索引越界。图片和标签文件名必须严格对应除扩展名少一个标签文件这一张图就会被跳过且不会有明显警告这一点在排查「训练集数量对不上」时要记得查。划分比例上小数据集常见做法是按 8:1:1 分 train/val/test如果样本本来就少几百张量级建议只留 train/val用交叉验证替代独立测试集。提示标注完先跑一遍校验脚本检查有没有坐标越界1 或 0、有没有类别号大于 nc-1这两类错误在训练中往往表现为 loss 突然飙高而不是直接报错。2.3 训练参数学习率、批大小与轮数的配合关系from ultralytics import YOLO model YOLO(yolo11n.pt) # 从预训练权重起步 model.train( datadata.yaml, epochs150, imgsz640, batch16, lr00.01, # 初始学习率 lrf0.01, # 最终学习率 lr0 * lrf warmup_epochs3, # 前 3 轮线性预热 weight_decay0.0005, mosaic1.0, # 马赛克增强概率 close_mosaic15, # 最后 15 轮关闭稳定收敛 cacheTrue, device0, )lr0是最关键的一个数。从预训练权重微调时0.01 通常偏大更容易出现前几轮 loss 震荡可以降到 0.001~0.005 试。lrf控制学习率衰减的终点配合余弦退火策略训练后期学习率会逐渐逼近lr0*lrf让模型落到更平的极小值。warmup_epochs存在的意义是前期权重更新幅度大不加预热容易把预训练学到的特征直接冲垮。batch受显存限制显存不够时先降 batch 再考虑降 imgsz因为降分辨率会直接影响小目标的可检测性。close_mosaic是个容易被忽略但很有用的参数马赛克增强把四张图拼一起对小目标有利但拼出来的目标边界被裁切训练末期关掉能让模型在真实分布上收得更稳。cacheTrue把解码后的图像缓存在内存里数据集不大时几千张以内能明显减少每个 epoch 的 IO 等待。3. 训练过程监控与评估指标怎么读3.1 损失曲线与 TensorBoard 监控训练启动后会自动在runs/detect/train/下写结果results.csv是逐轮的指标记录weights/里放best.pt和last.pt。可视化直接用 TensorBoardtensorboard --logdir runs/detect/train --port 6006看三组曲线box_loss定位损失、cls_loss分类损失、dfl_loss分布焦点损失。健康形态是三条线同步下降然后趋于平缓。如果cls_loss降而box_loss不降通常是标注框质量差或锚框尺度与目标不匹配如果验证集 loss 在某个 epoch 后开始回升而训练 loss 继续降那就是过拟合。3.2 mAP、Precision、Recall 的取舍评估指标里最容易被误读的是 mAP。它是各类别 AP 的平均AP 又是 Precision-Recall 曲线下的面积所以 mAP 高不代表每个类都好。必看的是各类的 P/R 分布metrics model.val(datadata.yaml, splitval) print(metrics.box.map) # mAP0.5:0.95 print(metrics.box.map50) # mAP0.5 per_class metrics.box.ap_class_index # 每个类别的 AP指标含义低值时的排查方向Precision检出的框里正确的比例误检多检查负样本与背景Recall真实目标里被检出的比例漏检多检查标注覆盖与小目标mAP0.5IoU0.5 时的均值整体定位能力mAP0.5:0.95多 IoU 阈值平均对框的紧致度更敏感实际业务里 P 和 R 的取舍取决于代价。安防场景漏检代价高宁可有误报置信度阈值就调低质检场景误报会中断产线阈值调高牺牲一点 Recall 换 Precision。这个阈值是推理期的参数不用重训就能调但要在 mAP 表现好的模型上调才有意义。3.3 过拟合与欠拟合的判别和处理欠拟合的信号是训练集上指标本身就低通常意味着模型容量不足或训练轮数不够可以换更大规模的模型档位n→s→m或加轮数。过拟合的信号是训练集指标远高于验证集处理手段按性价比排序先加数据增强mosaic、mixup、随机缩放再考虑加 weight_decay最后才是减模型容量。注意小数据集上直接用 YOLOv11l/x 这类大模型几乎必然过拟合而且显存吃紧导致 batch 很小BN 统计不稳定反而不如中等档位稳。4. 导出 ONNX动态轴、opset 与验证4.1 导出参数怎么定from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) model.export( formatonnx, imgsz640, opset12, # 兼容性优先选 11/12 simplifyTrue, # 合并冗余算子 dynamicTrue, # 动态 batch 与尺寸 halfFalse, # 导出阶段不宜直接半精度 )opset决定算子的版本集合数值越高支持的算子越多但推理端的兼容性越差。很多嵌入式推理框架对 opset 17 以上支持不完整工程上常见的做法是锁在 11 或 12先保证能跑起来。dynamicTrue会把 batch 维和 H/W 维标成动态服务端需要变长输入时打开但某些推理后端对动态维优化较差固定尺寸的吞吐会更高按实际需求取舍。导出后先做一次形状检查import onnx m onnx.load(best.onnx) onnx.checker.check_model(m) # 结构合法性 print(m.graph.input[0]) # 输入名与形状 print([o.name for o in m.graph.output])onnx.checker.check_model通过只说明图结构合法不代表推理端能跑。更实用的是拿 Netron 打开看一眼输入输出张量的维度描述以及有没有异常的中间节点。4.2 导出后的数值一致性验证这一步很多人跳过结果部署后发现框全部偏移。做法是用同一张图分别跑原模型和 ONNX比较输出差异import numpy as np, onnxruntime as ort, torch from ultralytics import YOLO img cv2.imread(test.jpg) x torch.from_numpy(img).permute(2,0,1).float().unsqueeze(0) / 255.0 pt_out YOLO(best.pt).model(x)[0].detach().numpy() sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) onnx_out sess.run(None, {sess.get_inputs()[0].name: x.numpy()})[0] print(np.abs(pt_out - onnx_out).max()) # 一般应在 1e-3 ~ 1e-2 量级差异在 1e-2 以内通常可接受超过 1e-1 就要查是不是预处理不一致归一化系数、通道顺序、letterbox 的填充值、是不是导出时动态轴导致某些 reshape 行为变了。letterbox 的填充值不一致是很隐蔽的一类问题原模型和推理脚本对同一张图做了不同的 padding输出框坐标就会系统性地偏。4.3 常见导出报错及处理最典型的是算子不支持报错信息里会指出某个算子名。处理思路是回到导出参数降 opset 或开启 simplify如果是自定义算子需要提供自定义符号函数。第二类是输入输出形状不一致多半源于 dynamic 轴设置与实际推理输入不匹配。第三类是导出的模型体积异常大通常是 simplify 没生效或权重没被正确 constant folding可以对比导出前后节点数确认。提示导出前把模型设为 eval 模式否则 BN 和 Dropout 层会保留训练行为导出的图在推理时结果会漂。Ultralytics 的 export 内部已经处理了但自己写导出脚本时容易漏。5. ONNX Runtime 推理与 INT8 量化落地5.1 完整推理脚本预处理、会话、后处理import cv2, numpy as np, onnxruntime as ort sess ort.InferenceSession( best.onnx, providers[CPUExecutionProvider], # 有 GPU 换 CUDAExecutionProvider ) iname sess.get_inputs()[0].name def letterbox(img, size640): h, w img.shape[:2] r min(size / h, size / w) nh, nw int(round(h * r)), int(round(w * r)) resized cv2.resize(img, (nw, nh)) canvas np.full((size, size, 3), 114, dtypenp.uint8) # 填充值需与训练一致 canvas[:nh, :nw] resized return canvas, r img cv2.imread(test.jpg) canvas, r letterbox(img) x canvas[:, :, ::-1].transpose(2, 0, 1)[None].astype(np.float32) / 255.0 preds sess.run(None, {iname: x})[0] # shape: (1, 4nc, 8400) # 后处理置信度过滤 NMS scores preds[0, 4:, :].max(axis0) keep scores 0.25 boxes, cls preds[0, :4, keep], preds[0, 4:, keep].argmax(axis0)预处理里有三个必须与训练对齐的点通道顺序cv2 读进来是 BGR模型要 RGB、归一化系数除以 255、letterbox 填充值YOLO 系默认 114。任何一处不一致都会让精度掉得莫名其妙。输出张量的布局是(1, 4nc, 8400)8400 是三个尺度特征图的锚点数之和4nc前四位是中心点和宽高。这里的坐标还是相对 640 输入框的归一化值映射回原图时要先减掉 padding 偏移再除以缩放系数r。5.2 INT8 量化收益、代价与操作步骤INT8 量化的目的很直接把权重从 FP32 压到 8 位模型体积降到约四分之一CPU 上推理速度通常提升 1.5~3 倍。代价是精度损失对小目标尤其明显因为激活值的动态范围在小目标区域变化剧烈量化误差更容易放大。from onnxruntime.quantization import quantize_dynamic, QuantType quantize_dynamic( model_inputbest.onnx, model_outputbest_int8.onnx, weight_typeQuantType.QInt8, )这是动态量化只量化权重激活值在运行时量化不需要校准数据集操作最简单。如果精度掉得不能接受就得改用静态量化quantize_static需要准备一批代表性的校准图片让量化器统计激活值的分布来确定缩放因子。量化方式是否需要校准集体积速度精度损失FP32 原模型否1x基准无动态 INT8否约 0.25x中小到中静态 INT8是约 0.25x高可控判断量化是否可用还是要回到 5.1 里那套数值比对跑同一批图比较 FP32 和 INT8 输出的框数量、类别和 IoU。经验上 mAP 掉 1~2 个点属于常见范围掉超过 5 个点说明校准集代表性不够或者模型里对量化敏感的算子太多可以尝试对特定层做混合精度把最后几层检测头保留为 FP32。5.3 执行提供者的选择与一个调优技巧providers列表的顺序就是优先级ONNX Runtime 会依次尝试。服务端有 N 卡用CUDAExecutionProvider纯 CPU 用CPUExecutionProvider。CPU 场景下有两个参数值得调opts ort.SessionOptions() opts.intra_op_num_threads 4 # 算子内并行线程数 opts.graph_optimization_level ort.GraphOptimizationLevel.ORT_ENABLE_ALL sess ort.InferenceSession(best_int8.onnx, opts, providers[CPUExecutionProvider])intra_op_num_threads设成物理核心数而不是逻辑核心数超线程在这种计算密集场景里往往帮倒忙。另外如果是服务化部署并且输入尺寸固定把导出时的dynamic关掉让推理引擎能在构图阶段做更彻底的内存复用和算子融合吞吐通常比开启动态维高出一截。第一次推理会包含构图和内存分配的开销做性能测试时记得先跑几十次预热再统计。本文还有配套的精品资源点击获取