不少做计算机视觉项目的朋友在 YOLO26 训练完、跑通验证集之后都会问同一个问题接下来呢我最近刚好带了一个 YOLO26 人员入侵检测项目训练部分做得很顺真正卡住大家的反而是最后一步——模型导出。很多人以为导出就是把.pt后缀换成.onnx或者.engine复制到部署机上就能用但实际操作里涉及环境匹配、算子兼容、输出结构调整、NMS 后处理对齐等问题每一个都能让人卡上一整天。这篇文章我会围绕“YOLO26 模型导出”这件事从部署场景、格式选型、环境准备到检测/姿态/分割/深度等不同任务变体的导出差异再到常见报错排障完整走一遍。适合三类人看一是做计算机视觉大作业、还没搞清楚训练产物和部署产物区别的学生二是需要把 YOLO26 人员入侵检测或姿态模型推到边缘盒子、服务端 GPU 上的工程开发者三是在做 YOLO26 改进结构、改完网络以后想把新模块成功导出验证的实验党。无论你是哪一类这篇文章都会尽量用能直接抄作业的方式把“为什么这么导”讲清楚。1. 为什么“模型导出”是 YOLO26 项目里绕不开的一步1.1 训练完的 .pt 文件离真正“能用”还有多远我这里说的 .pt 是训练结束时保存的权重文件通常命名为best.pt或last.pt。很多第一次做 YOLO26 项目的同学会把.pt直接当成部署文件发给后端同事结果后端要么装不上 PyTorch要么推理速度慢得离谱要么发现模型结构里还有优化器状态、EMA 权重等一堆和推理无关的变量。YOLO26 的.pt本质是 PyTorch 序列化文件里面存的是训练状态的快照。哪怕你训练结束后没有保留优化器默认保存逻辑也可能包含模型结构、类别名、训练超参数、EMA 状态、anchor 信息等。直接用 PyTorch 加载.pt做推理当然可以但这要求部署环境与训练环境高度一致Python 版本、PyTorch 版本、本地代码库结构、自定义模块定义一个不对就报错。而且 PyTorch 原生推理在 GPU 上一般没有把卷积和 BatchNorm 融合、没有做层间算子合并、没有针对目标硬件生成 kernel所以速度和资源占用都很难满足工业级需求。模型导出做的事本质上是一次“推理图裁剪与迁移”。它在导出过程中会把训练用的 loss 分支去掉把需要在前处理里完成的归一化尽量提前固化把检测头最终的解码逻辑按目标格式展开再通过目标运行时生成独立于原始训练代码的推理文件。换句话说导出不是改了文件后缀而是把 YOLO26 从一个“依赖 PyTorch 训练生态的训练器”变成一个“只需要推理运行时就能跑的部署模型”。对比项训练权重 .pt导出后 .onnx / .engine是否包含优化器/EMA可能包含不包含是否依赖原始训练代码是模块定义必须完全一致否独立推理图算子是否做过融合一般不优化ONNX 可简化TensorRT/OpenVINO 会做图优化是否包含后处理靠 SDK 动态完成可裸输出也可按配置内嵌典型推理速度慢快尤其 GPU 上提升明显1.2 YOLO26 结构图与导出前必须理解的网络输出在导出一个模型之前我建议大家先看一眼 YOLO26 结构图不是让你去背诵每个模块而是要搞清楚三点主干网络有哪些输出 stride、检测头有哪几个分支、最终输出的 shape 怎么排。YOLO26 作为 YOLO 系列较新的迭代结构上保留了多尺度特征金字塔思想通常有 3 个不同 stride 的输出层。导出的 ONNX 模型输出可能有 1 个或者 3 个张量取决于你怎么配导出参数。传统模式下检测头的输出会拼接成一个大的预测张量所有 anchor 点都铺开。如果只看官方结构图会觉得网络很复杂但导出时真正起作用的是最后那个 head。你只要知道“这个张量里每一行代表什么、一共有多少个候选框、坐标和类别是怎么摆放的”部署时的解码就成功了一半。很多人在导出后拿 Python 的 ONNX 可视化工具一打开发现里面的节点和 YOLO26 结构图对不上立刻慌了。其实这非常正常因为 PyTorch 在导出到 ONNX 时会把一些复合操作拆成基础算子比如把 GroupNorm 拆成多个小算子把所有卷积展开成 ConvAdd/Bias 的组合。结构图是给人看的逻辑结构ONNX 是给机器执行的算子图两者本来就不需要一一对应。我见过有人在导出后花费大量时间试图让 ONNX 图和论文结构图一模一样这基本是徒劳。真正应该做的是验证输入输出数据流是否一致而不是追求图层长得像。1.3 不同部署场景对“导出格式”的隐性要求YOLO26 模型导出成什么格式不由个人喜好决定而是由部署硬件和业务场景决定。比如同样是做人员入侵检测服务端如果是一台 NVIDIA GPU 机器用 TensorRT 的 engine 文件通常能拿到最大吞吐如果客户现场只有 Intel CPU没有独立显卡那么 OpenVINO 会明显快于原生 ONNX如果模型要跑在手机 App 里则可能需要 CoreML 或 TFLite如果跑在国产 NPU 盒子上往往还要把 ONNX 进一步交给厂商提供的工具链做转换。所以我在实际项目里第一步永远是问客户你的程序最终跑在什么硬件上用什么语言调用是否允许安装 Python 环境。这三个问题决定了我到底导出到哪一层。YOLO26 官方仓库的 export 接口支持很多格式但并不是每种格式都适合你的场景。比如 ONNX Runtime 可以跑大多数平台但它只是一个通用推理引擎并没有针对具体 GPU 做 kernel 级调优TensorRT 在 NVIDIA 硬件上非常快但也因此绑定了显卡型号和驱动版本。拿着一张 RTX 3090 上导出的.engine文件跑到 RTX 3050 上通常会报错必须重新导出。这一点很多人第一次接触时都会踩坑后面我会专门讲。2. 导出前的环境和参数准备2.1 环境依赖先别急着敲 export 命令很多导出报错并不是模型本身的问题而是环境不一致导致的。YOLO26 项目在导出前最好先检查几项依赖。Python 环境方面建议 Python 3.8 到 3.11 之间。我见过有人在 Python 3.12 上装 PyTorch 和 ONNX 时碰到的兼容性问题特别多单纯为了跑导出没必要给自己增加难度。PyTorch 的版本不要追求太新除非你有特殊需求否则使用项目 requirements 里锁定的版本最稳。CUDA 版本要和 PyTorch 以及 TensorRT 匹配这里说的不是系统里nvidia-smi显示的驱动版本而是 PyTorch 编译时对应的 CUDA runtime 版本。很多人看nvidia-smi显示 CUDA 12.4 就以为 PyTorch 也应该装 cu124实际上只要驱动够新PyTorch 用 cu118 或 cu121 都能跑关键看 cuDNN 和 TensorRT 之间的兼容矩阵。如果在本地复现 YOLO26 源码建议用虚拟环境不要图省事直接装在系统 Python 里。我常用的命令是python -m venv yolo26_env source yolo26_env/bin/activate pip install -r requirements.txt如果只需要导出而不需要从头训练也可以只装必要依赖。别一下子把 requirements 里所有包都装齐很多训练相关库如 WB、clearml 对导出毫无用处反而会在导入模型时因为网络问题触发不必要的初始化。我习惯导出一个模型只依赖 torch、onnx、onnxruntime、opencv-python、pyyaml 这几个核心包遇到特定格式再补装 tensorrt、openvino 等。2.2 导出接口的核心参数逐个拆解YOLO26 的导出通常调用模型的 export 方法最简单的方式是这样from ultralytics import YOLO model YOLO(yolo26n.pt) model.export(formatonnx, imgsz640, halfFalse, opset13, simplifyTrue)每个参数都有它自己的坑。format不用说决定输出文件后缀常见的是onnx、engine、openvino、coreml、tflite等。imgsz决定导出模型的输入尺寸它影响的不止是输入张量的宽高还影响最终候选框数量和精度表现。如果你训练时用的是 640x640导出时最好也用 640如果训练时用了多尺度导出时可以固定到一个部署需要的尺寸比如 1280但前提是模型在验证集上对高分辨率输入确实有收益。half表示是否导出 FP16 精度。对 ONNX 格式来说halfTrue会生成半精度权重体积缩小一半但在 CPU 上不一定有速度收益在 GPU 上则通常明显对 TensorRT 来说FP16 几乎是必开项否则性能优势体现不出来。opset是 ONNX 的算子集版本数值越新支持的算子越多但太新的 opset 可能让老设备上的推理引擎不支持。一般选 13 或 14 比较保险老项目里也有人用 11 或 12主要看目标推理引擎的支持范围。simplifyTrue是很多人容易忽略的好参数。它会调用 onnx-simplifier 对导出的模型进行冗余节点消除、常量折叠、算子融合等优化。原来 PyTorch 导出时可能残留的很多无用节点比如形状计算的辅助节点会在 simplify 后被清理。文件变小推理变快兼容性也更好。代价是 simplify 偶尔会把某些图结构改到和某些自定义算子冲突所以如果简化后模型推理结果不对可以关闭 simplify 重新导出对照。2.3 导出前先确认三类信息任务类型、类别数、anchor 配置YOLO26 的导出不是简单的“塞一个 pt 进去”你最好在脑海里有几个明确信息。第一任务类型。YOLO26 的检测模型、姿态模型、分割模型、目标检测加旋转框模型甚至深度估计模型导出的关键结构完全不同。检测模型输出的是框坐标和类别概率姿态模型在检测输出后面还要追加每个关键点的坐标和可见度分割模型会额外输出 mask 原型和掩码系数旋转框模型会多一个角度参数。这些任务差异决定了你在部署端看到的输出张量结构。第二类别数。如果你训练的是自己的数据集类别数不是默认的 80那么导出的输出通道也要随之变化。典型情况下假设类别数为 nc每个候选框的输出通道就是 4 nc。如果是姿态模型每个关键点输出 3 个值x、y、可见度假设关键点数为 k那么通道数就是 4 nc 3*k。这个规律在你手写 C 解码的时候特别有用。第三anchor 相关配置。YOLO26 沿用 anchor-free 还是 anchor-based不同变体不一样。但导出到 ONNX 时通常都会把 anchor 信息以某种方式固化到图里。如果你在导出后试图用动态 anchor 或自定义 anchor 做后处理需要先确认导出文件里是否包含这些信息。一般建议直接信任导出 SDK 的处理方式尽量不要在部署端额外修改 anchor。3. 实操从 .pt 到 ONNX、TensorRT、OpenVINO 的完整流程3.1 检测模型导出 ONNX 的现场记录我以一个自己训练过的 YOLO26 人员入侵检测模型为例。训练产物是best.pt类别只有 person 一个类别因为业务只需识别是否有人闯入区域。导出命令from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) onnx_path model.export( formatonnx, imgsz640, halfFalse, opset13, simplifyTrue, dynamicFalse, ) print(onnx_path)这里我没有开halfTrue因为客户机器上既有 CPU 又有 GPUONNX 模型需要在两种环境下都能稳定跑。FP16 ONNX 在很多 CPU 推理引擎上不受支持或者会退化成低精度计算反而可能掉点。dynamicFalse表示输入 shape 固定为 1x3x640x640。固定输入的最大好处是后处理代码可以写死很多 TensorRT 优化也能在静态 shape 下做得更好。代价是不能随意改 batch 和输入分辨率。如果业务里有比较大的检测视频想一次批量处理多帧可以开dynamicTrue但后续代码复杂度会明显上升。导出完成后我一般会立即检查产物大小和结构。.onnx文件如果只有几兆那可能是导出出了问题YOLO26 的 ONNX 导出来通常会有几十兆到上百兆具体看模型尺寸是 n/s/m/l/x 哪个档位。检查 ONNX 文件的合法性可以用这段代码import onnx model_onnx onnx.load(best.onnx) onnx.checker.check_model(model_onnx) print(onnx.helper.printable_graph(model_onnx.graph)[:3000])合法之后不代表能直接跑出正确结果最好马上用 onnxruntime 做一次推理对比。我建议准备一张训练集之外的图片分别用.pt模型和.onnx模型预测对比检测框结果。由于精度损失可能很小你不必要求坐标完全一致但关键目标必须都能检出框位置不能有系统性偏移。3.2 ONNX 模型推理验证时的输出张量排布很多人导出 ONNX 之后不会看输出结构直接用 Python 代码把输出拿来凑 NMS结果怎么调都不对。我在这里说一个非常容易被忽视的细节YOLO26 导出的 ONNX 输出 shape 常见有两种排布一种是[1, 4nc, 8400]一种是[1, 8400, 4nc]。如果你的模型配置、opset 或者导出工具版本不同排布就可能不一样。假设类型数为 1输入是 640总的候选框数量是 8400。如果输出是[1, 5, 8400]那么第 0 维固定为 batch第 1 维是每个候选框的属性通道第 2 维是候选框索引如果输出是[1, 8400, 5]那就是候选框维度在前。别看这只是转置的区别在部署代码里一个维度写错轻则所有框的坐标读到类别概率上重则直接内存越界崩溃。我的建议是用 onnxruntime 推理后立刻查一下输出的具体 shapeimport onnxruntime as ort import numpy as np sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) inputs sess.get_inputs() outputs sess.get_outputs() for inp in inputs: print(input:, inp.name, inp.shape, inp.type) for out in outputs: print(output:, out.name, out.shape, out.type) input_name inputs[0].name dummy np.random.randn(1, 3, 640, 640).astype(np.float32) result sess.run(None, {input_name: dummy}) print(result shape:, result[0].shape)看到真实输出 shape 之后再去写后处理就基本不会跑偏了。3.3 从 ONNX 生成 TensorRT engine 以及 workspace 参数YOLO26 在 NVIDIA GPU 上部署时TensorRT engine 通常是最终选择。如果环境已经安装了 TensorRT并且 YOLO26 的导出接口能识别到可以直接一步到位model.export(formatengine, imgsz640, halfTrue, workspace4, device0)workspace4表示允许 TensorRT 构建引擎时最多使用 4GB 显存作为临时工作空间。这个值不要设太小否则会自动降低优化力度也不要设太大否则在大显存机器上构建的引擎到小显存机器上可能无法加载或运行。我的经验是单卡 8GB 显存设 4 到 6单卡 24GB 显存设 8 到 12 就足够了。如果直接通过 SDK 导出失败或者你想更精确控制转换参数可以用 TensorRT 自带的trtexec命令行工具trtexec \ --onnxbest.onnx \ --saveEnginebest_fp16.engine \ --fp16 \ --minShapesimages:1x3x640x640 \ --optShapesimages:8x3x640x640 \ --maxShapesimages:16x3x640x640这个命令的好处是你能明确看到每个阶段的耗时、显存占用、算子使用情况。--fp16开启半精度通常能让推理速度提升一倍以上。如果模型里有某些算子对 FP16 不敏感可能会导致精度下降这时需要通过层级别精度控制去排除特定层比较复杂一般网络在 FP16 下都能稳住。3.4 OpenVINO 导出CPU 部署的实用选择如果客户现场是 Intel CPU 且没有独显我会直接把模型导出为 OpenVINO 格式。YOLO26 导出 OpenVINO 同样很简单model.export(formatopenvino, imgsz640, halfTrue)生成结果通常是一个文件夹里面包含.xml和.bin文件。.xml是模型结构描述.bin是权重数据。OpenVINO 推理可以用它的 Python API也可以用 C API。在我实际测试中同一个 YOLO26 ONNX 模型在 Intel CPU 上用 OpenVINO 比用 onnxruntime CPU 快很多尤其当 batch size 为 1 时优势更明显。有一点要注意OpenVINO 版本更新比较快升级后旧模型可能因为算子映射变化而需要重新导出。最好在项目文档里记录 YOLO26 代码库版本、OpenVINO 版本、导出命令方便后续重新生成。4. 不同任务变体的导出差异详解4.1 YOLO26 检测模型最标准但别忽略类别筛选检测模型是最常见的导出任务。很多人说检测模型导出简单其实只是表面简单。如果你的业务只需要“人”这一类比如人员入侵检测强烈建议训练时就做成单类别模型而不是导出模型后做类别筛选。单类别模型在导出后输出张量从[1, 84, 8400]变成[1, 5, 8400]后面的 NMS 计算量会明显降低部署时也不需要为人的类别单独写过滤逻辑。另外检测模型导出后的 NMS 一定要自己实现或者调用推理框架里的高效插件。onnxruntime 本身没有内置通用 NMS而 TensorRT 的 NMS 插件有版本兼容限制。很多 YOLO26 新手以为导出 ONNX 后模型会自己把框滤掉其实并没有。导出的 ONNX 往往只输出原始预测结果也就是几百上千个候选框你需要用置信度阈值过滤掉大部分框再用 NMS 去掉重叠框。如果哪次部署时发现检测框一团重叠大概率不是模型问题而是根本没有做 NMS。4.2 YOLO26 姿态模型的版本选择和输出通道规律姿态模型是很多项目里容易混用的点。YOLO26 姿态模型里有 n/s/m/l/x 等多个尺度的权重不同尺度的关键点数量可以一样但准确度和推理速度差别很大。选择哪个版本要看业务对关键点精度的要求和硬件预算。比如做人员入侵检测带姿态辅助判断摔倒时通常不需要特别高的关键点精度用 n 或 s 档就够如果是做康复动作评估、体育姿态分析则需要 m 或 l 档。在导出姿态模型时我会先确认关键点数量。YOLO26 的人体姿态模型通常输出 17 个关键点每个关键点包含 x、y、可见度三个值。如果你只训练了自己的三点姿态或二十一点姿态那么导出的输出通道会随之变化。姿态模型的输出张量通常会包含检测框信息、类别概率以及关键点信息。我自己实现 C 解码时会按这个规律读取先取前 4 个值作为框坐标第 5 个为类别置信度后面每 3 个值为一个关键点的 x、y、可见度。如果你发现坐标点读了但错位严重多半是忘记在关键点表达前插入 x/y/vis 的排布。YOLO26 姿态模型的导出尺寸也不能盲目照搬检测模型的 640。人体关节点是尺度敏感任务当图像中人体较小时640 的输入很难保证关键点定位精度。经验做法是导出成 960 或 1280看验证集指标和推理速度的平衡。不要忽视这种方式对显存的占用输入分辨率从 640 提高到 1280特征图计算量是成好几倍增长的。4.3 分割模型与 OBB 旋转框导出的特殊之处分割模型和普通检测模型的导出差别比较大。YOLO26 分割模型除了输出检测框和类别外还包含 mask 原型和 mask 系数。在 ONNX 导出后你往往会看到两个输出一个是候选框层面的输出另一个是 mask 原型输出。只有把 mask 原型和 mask 系数做矩阵乘再经过上采样和阈值化才能得到真正的像素级 mask。很多人在部署端以为自己拿到一个类似语义分割的输出结果直接 reshape 成原图大小去看当然什么也看不见。OBB 旋转框模型则在常规检测输出上多了一个角度值。如果你的现场应用需要检测倾斜的物体比如船舶、飞机、仓库货品旋转框模型很重要。导出的关键是把角度值的表示方式确定清楚是弧度还是角度范围是多少。很多后处理库对角度定义不一致导致框看起来完全正确但旋转方向反了。导出后务必用一张带旋转目标的图像做可视化验证。4.4 YOLO26 depth 模型导出时容易混淆的问题在 YOLO26 各类热词里“depth”经常被提及。如果你用的是深度估计分支或相关任务导出时要注意它和检测任务的本质差异深度模型输出的不是框而是一个密集的深度图或者点云输出 shape 通常是[1, 1, H, W]这种格式也可能输出多个尺度的深度图。深度图对应的数值范围取决于训练时的标注方式可能是相对深度也可能是绝对距离导出后如果直接把它当灰度图显示完全看不出效果不代表模型坏了而是需要做归一化或者反变换。深度模型和检测模型如果放在同一个 YOLO26 工程里导出前要确认你加载的权重是否带着正确的任务头。我见过有人为了在检测任务里辅助判断距离把 YOLO26 depth 版本和检测版本训练到一起最后导出时因为只导出了其中一个头导致另一个任务完全没有输出。这种多任务导出的问题最好在模型定义阶段就规划好把需要部署的分支都显式保留。4.5 人员入侵检测场景里的“模型瘦身”经验人员入侵检测在真实业务里有个特点大部分画面没有人员出现但依然要持续拉流推理。这时候模型导出阶段的静态尺寸选择就很重要。如果现场摄像头有固定的 ROI 区域可以在前处理里直接裁剪出 ROI然后以较小的输入尺寸导出模型比如将 1920x1080 的画面裁剪为 800x450 再 resize 到 320x320 输入模型。这里不是简单地把输入尺寸调小而是在准备数据时配合 ROI 和缩放策略。我的做法是先用一个较大的 ONNX 模型做离线验证确认 ROI 区域在 resize 后依然能检出目标再固定尺寸导出给现场。同时人员入侵检测对误报率非常敏感。如果你在部署后发现模型经常把远处的人影或动物检测成人建议检查置信度阈值和 NMS 阈值而不是重新训练。YOLO26 模型在导出时并不强制固定阈值阈值通常在你的调用代码里设置。我在很多项目里将置信度阈值设为 0.45NMS 阈值设为 0.5然后在现场根据误报情况调整。5. 导出结果的验证、性能基准与交付注意事项5.1 对比 .pt 与导出模型的结果一致性模型导出后必须做一致性验证否则等于黑盒交付。最简单的方案是准备 100 到 200 张覆盖不同场景的测试图分别用原始.pt模型和导出模型推理统计检测框的类别、数量、坐标差异。如果导出前用了dynamicFalse那么.pt模型在验证时也需要把输入 resize 到对应尺寸否则两者看到的图像分辨率不同结果自然有差异。对比时允许有一定浮点误差一般 FP32 导出的坐标误差在 1e-3 量级以内FP16 导出可能到 1e-1 量级但框位置不应该有大偏移。如果你发现导出模型的检测框整体偏移了一两个像素多半是图片预处理差异如果偏移了几十像素那基本是输出解析代码问题。5.2 用导出后的模型在部署端做端到端性能测试导出成功后不能只看模型文件是否生成要在目标硬件上做端到端测试。我最常做的是三件事单张图片耗时测试、视频流平均帧率测试、长时间稳定性测试。单张图片耗时测试可以用 onnxruntime 或 TensorRT 的 Python API测 100 次取平均。注意第一次推理通常会触发显存分配和 kernel 编译要预留预热时间。视频流平均帧率则要把解码耗时、预处理耗时、模型推理耗时、后处理耗时都算进去。很多同学拿着模型推理 5ms 就以为能跑到 200 帧却把图像缩放和 NMS 的时间算了之后发现只有 40 帧。长时间稳定性测试尤其重要TensorRT engine 连续跑几小时后有时候会遇到显存泄漏或温度降频导致的性能波动这在项目交付前必须发现。5.3 把导出产物和配套代码一起交付在实际项目交付中我从来不会只给一个.onnx或.engine文件。我会同时给一份简短的 README里面写清楚训练时用的输入尺寸、归一化方式、图片通道顺序 BGR 还是 RGB、输出张量 shape、后处理伪代码和实测性能数据。很多人觉得这些信息很基础但客户换一个后端工程师接手时这些就是救命文档。特别要提的是颜色通道顺序。YOLO26 训练时通常使用 OpenCV 读取图片也就是 BGR 顺序。但一些部署框架默认读取图像是 RGB比如部分 Python 图像库或移动端 SDK。如果导出的 ONNX 模型是按 BGR 训练的而部署端送入了 RGB 数据模型的检测效果会明显变差而且不是那种完全检测不到而是置信度普遍下降。这个问题的隐蔽性在于你不容易想到是通道顺序问题。所以我会在 README 里用加粗字体写清楚部署端输入图片必须与训练前处理保持一致默认按 BGR 顺序输入。5.4 模型更新后重新导出的注意事项如果你的 YOLO26 项目隔了一段时间又重新训练导出了新版本模型千万不要直接覆盖旧模型文件而不做回归测试。我在一次项目里因为只替换了模型权重没有重新生成对应的 TensorRT engine结果在旧 engine 上加载新权重时报了结构不匹配的错误排查了很久才发现是构建缓存的问题。YOLO26 的导出过程会在目录里生成一些缓存文件比如构建 TensorRT engine 时的.cache如果新旧模型结构不一致缓存会导致加载异常。安全做法是每次重新导出到独立目录并在标签里加上时间戳例如best_20250115.engine避免新旧文件混淆。6. 导出过程常见报错与排查速查6.1 报错信息和我的排查思路很多人遇到模型导出报错就慌了其实报错并不可怕关键是看它发生在哪个阶段。导出过程可以分为三个阶段PyTorch 模型加载与解析、转为 ONNX 图、目标格式转换。不同阶段的报错对应不同解决方案。在 PyTorch 模型加载阶段最常见的报错是提示找不到自定义模块或 key 不匹配。这种问题多半因为你换了 YOLO26 代码版本训练时用的模块类名和加载时的类名不一致。解决办法是检查权重文件中的模型结构 key 是否和当前代码一致尤其是model.yaml配置里的模块组合不能随意修改。如果你做过 YOLO26 改进比如换了一个轻量化注意力模块那么训练、导出、部署最好全程使用同一分支代码不要中途升级代码库。在 ONNX 图转换阶段报错如果有“Unsupported operator”这样的关键词说明 PyTorch 模型里有某些算子没有被 ONNX exporter 识别。遇到这种情况先锁定是哪一层产生的问题通常建议用torch.onnx.export的verboseTrue打印导出细节或者在模型代码里临时把可疑模块替换为等价基础算子。千万不要硬要求 ONNX 支持所有算子很多自定义模块本身就不适合直接导出。在目标格式转换阶段比如从 ONNX 转 TensorRT 时报精度不支持、维度不支持一般需要回到 ONNX 图层面修改输入输出的动态维度范围或者排查模型中是否用了 TensorRT 不友好的算子比如某些动态 resize、动态循环。这个阶段最花时间但也最能体现经验积累。6.2 导出常见问题速查表现象可能原因处理办法导出报错缺少自定义模块代码库版本不一致用训练时同一份代码重新加载ONNX 导出成功但结果全为 0前处理通道顺序、归一化不一致检查输入是否使用 BGR 和相同的除以 255TensorRT 引擎构建时显存不足workspace 配置过大调低 workspace或减小 batch size导出模型体积比预期小很多satisfy 清理了太多节点或输出裁剪错误检查输出节点关闭 simplify 对比输入尺寸不匹配导出和推理时 imgsz 不一致统一为训练时的输入尺寸检测框位置偏移明显候选框排布读错或 NMS 缺失查看输出 shape确认是否需要转置和实现 NMSFP16 导出后置信度显著下降FP16 精度敏感层较多改用 FP32 或对特定层禁用 FP16同一份 engine 换显卡后报错TensorRT engine 与显卡绑定在目标显卡上重新生成 engine导出后自定义 attention 模块无法运行目标后端不支持某些动态算子改用固定 shape 或替换为等效结构6.3 导出时间太长和内存占满的处理YOLO26 在导出到 TensorRT 时如果模型较大且没有合理设置 workspace可能会出现构建几十秒甚至几分钟没有动静的情况。这不是死机而是在做算子选择和 kernel autotuning。如果构建时间太长可以尝试用trtexec的--verbose参数观察进度确认是卡在某个具体层还是整体优化较慢。对于特别大的模型比如 YOLO26x 配合 1280 输入导出时的显存峰值可能很高。如果你只有一块 8GB 显存建议导出时加devicecpu或者采用分块优化方式。YOLO26 的 export 接口允许在 CPU 上导出模型虽然慢一点但能避免显存不足的报错。ONNX 转 TensorRT 也可以将构建过程放到内存较大的无 GPU 机器上TensorRT 支持在没有目标 GPU 的情况下构建 engine但需要注意某些硬件相关优化会失效最好还是在目标硬件上构建。6.4 部署端拿到模型后“正常但不对”的排查顺序这里总结一套我的排查顺序。如果部署端能跑通但结果不对先别怀疑模型文件按顺序做四件事。第一打印输入张量确认图片尺寸、通道顺序、归一化后的数值范围是否符合预期。只要输入不对后面全错。第二打印模型输出的 shape 和典型值确认输出维度和脚本解析方式匹配。第三单步检查从原始输出到最终框的转换逻辑尤其是框坐标是在原图尺度还是模型输入尺度。第四和.pt模型对同一张图的输出做数值比较定位差异出现在前处理、模型计算还是后处理阶段。7. 我用 YOLO26 做完整个导出链路后的几点体会做模型导出这件事心态上要放平。它不像模型训练那么有成就感也没有那么多论文可读但它是把算法变成产品的最后一道工序。我在帮别人验收 YOLO26 项目时经常看到训练指标很不错一到导出阶段就卡壳原因大多不是技术难度而是太想当然。很多人训练完拿.pt文件直接部署觉得模型能出结果就行结果没考虑到 PyTorch 推理速度太慢、部署环境无法安装训练框架、输出后处理缺了 NMS 等问题。如果一开始就把“最终要导出成什么格式”融入训练前的方案设计里很多弯路都能提前避开。我还想强调一点导出模型不能只看一张测试图没问题就结束。我在实际项目里吃过亏模型在白天场景下导出后表现完美但晚上因为画面整体变暗、通道统计分布偏移检测效果大幅下降。这个问题不是模型导出本身造成的但它提醒我做导出验证时要覆盖实际业务的各种光线、角度、目标大小情况。把测试集准备得越接近真实场景导出交付后的稳定性就越高。最后分享一个小经验在 YOLO26 项目开始训练之前先花十分钟用一个没训练好的权重跑一遍完整导出流程。这个做法能提前暴露代码库、PyTorch 版本、ONNX opset、目标硬件工具链之间可能存在的兼容性问题。如果真的想在计算机视觉这条路上走得更远建议把模型导出当成一个正式工程环节来对待而不是训练结束后的附带动作。它能让你更清楚模型内部发生了什么、部署端需要什么这份理解在后续做 YOLO26 改进或结构设计时也一定会帮到你。 
长河君 · 2026/9/4 3:24:39 · 阅读 1.2k YOLO26模型导出全攻略：从ONNX到TensorRT的部署实践
不少做计算机视觉项目的朋友在 YOLO26 训练完、跑通验证集之后都会问同一个问题接下来呢我最近刚好带了一个 YOLO26 人员入侵检测项目训练部分做得很顺真正卡住大家的反而是最后一步——模型导出。很多人以为导出就是把.pt后缀换成.onnx或者.engine复制到部署机上就能用但实际操作里涉及环境匹配、算子兼容、输出结构调整、NMS 后处理对齐等问题每一个都能让人卡上一整天。这篇文章我会围绕“YOLO26 模型导出”这件事从部署场景、格式选型、环境准备到检测/姿态/分割/深度等不同任务变体的导出差异再到常见报错排障完整走一遍。适合三类人看一是做计算机视觉大作业、还没搞清楚训练产物和部署产物区别的学生二是需要把 YOLO26 人员入侵检测或姿态模型推到边缘盒子、服务端 GPU 上的工程开发者三是在做 YOLO26 改进结构、改完网络以后想把新模块成功导出验证的实验党。无论你是哪一类这篇文章都会尽量用能直接抄作业的方式把“为什么这么导”讲清楚。1. 为什么“模型导出”是 YOLO26 项目里绕不开的一步1.1 训练完的 .pt 文件离真正“能用”还有多远我这里说的 .pt 是训练结束时保存的权重文件通常命名为best.pt或last.pt。很多第一次做 YOLO26 项目的同学会把.pt直接当成部署文件发给后端同事结果后端要么装不上 PyTorch要么推理速度慢得离谱要么发现模型结构里还有优化器状态、EMA 权重等一堆和推理无关的变量。YOLO26 的.pt本质是 PyTorch 序列化文件里面存的是训练状态的快照。哪怕你训练结束后没有保留优化器默认保存逻辑也可能包含模型结构、类别名、训练超参数、EMA 状态、anchor 信息等。直接用 PyTorch 加载.pt做推理当然可以但这要求部署环境与训练环境高度一致Python 版本、PyTorch 版本、本地代码库结构、自定义模块定义一个不对就报错。而且 PyTorch 原生推理在 GPU 上一般没有把卷积和 BatchNorm 融合、没有做层间算子合并、没有针对目标硬件生成 kernel所以速度和资源占用都很难满足工业级需求。模型导出做的事本质上是一次“推理图裁剪与迁移”。它在导出过程中会把训练用的 loss 分支去掉把需要在前处理里完成的归一化尽量提前固化把检测头最终的解码逻辑按目标格式展开再通过目标运行时生成独立于原始训练代码的推理文件。换句话说导出不是改了文件后缀而是把 YOLO26 从一个“依赖 PyTorch 训练生态的训练器”变成一个“只需要推理运行时就能跑的部署模型”。对比项训练权重 .pt导出后 .onnx / .engine是否包含优化器/EMA可能包含不包含是否依赖原始训练代码是模块定义必须完全一致否独立推理图算子是否做过融合一般不优化ONNX 可简化TensorRT/OpenVINO 会做图优化是否包含后处理靠 SDK 动态完成可裸输出也可按配置内嵌典型推理速度慢快尤其 GPU 上提升明显1.2 YOLO26 结构图与导出前必须理解的网络输出在导出一个模型之前我建议大家先看一眼 YOLO26 结构图不是让你去背诵每个模块而是要搞清楚三点主干网络有哪些输出 stride、检测头有哪几个分支、最终输出的 shape 怎么排。YOLO26 作为 YOLO 系列较新的迭代结构上保留了多尺度特征金字塔思想通常有 3 个不同 stride 的输出层。导出的 ONNX 模型输出可能有 1 个或者 3 个张量取决于你怎么配导出参数。传统模式下检测头的输出会拼接成一个大的预测张量所有 anchor 点都铺开。如果只看官方结构图会觉得网络很复杂但导出时真正起作用的是最后那个 head。你只要知道“这个张量里每一行代表什么、一共有多少个候选框、坐标和类别是怎么摆放的”部署时的解码就成功了一半。很多人在导出后拿 Python 的 ONNX 可视化工具一打开发现里面的节点和 YOLO26 结构图对不上立刻慌了。其实这非常正常因为 PyTorch 在导出到 ONNX 时会把一些复合操作拆成基础算子比如把 GroupNorm 拆成多个小算子把所有卷积展开成 ConvAdd/Bias 的组合。结构图是给人看的逻辑结构ONNX 是给机器执行的算子图两者本来就不需要一一对应。我见过有人在导出后花费大量时间试图让 ONNX 图和论文结构图一模一样这基本是徒劳。真正应该做的是验证输入输出数据流是否一致而不是追求图层长得像。1.3 不同部署场景对“导出格式”的隐性要求YOLO26 模型导出成什么格式不由个人喜好决定而是由部署硬件和业务场景决定。比如同样是做人员入侵检测服务端如果是一台 NVIDIA GPU 机器用 TensorRT 的 engine 文件通常能拿到最大吞吐如果客户现场只有 Intel CPU没有独立显卡那么 OpenVINO 会明显快于原生 ONNX如果模型要跑在手机 App 里则可能需要 CoreML 或 TFLite如果跑在国产 NPU 盒子上往往还要把 ONNX 进一步交给厂商提供的工具链做转换。所以我在实际项目里第一步永远是问客户你的程序最终跑在什么硬件上用什么语言调用是否允许安装 Python 环境。这三个问题决定了我到底导出到哪一层。YOLO26 官方仓库的 export 接口支持很多格式但并不是每种格式都适合你的场景。比如 ONNX Runtime 可以跑大多数平台但它只是一个通用推理引擎并没有针对具体 GPU 做 kernel 级调优TensorRT 在 NVIDIA 硬件上非常快但也因此绑定了显卡型号和驱动版本。拿着一张 RTX 3090 上导出的.engine文件跑到 RTX 3050 上通常会报错必须重新导出。这一点很多人第一次接触时都会踩坑后面我会专门讲。2. 导出前的环境和参数准备2.1 环境依赖先别急着敲 export 命令很多导出报错并不是模型本身的问题而是环境不一致导致的。YOLO26 项目在导出前最好先检查几项依赖。Python 环境方面建议 Python 3.8 到 3.11 之间。我见过有人在 Python 3.12 上装 PyTorch 和 ONNX 时碰到的兼容性问题特别多单纯为了跑导出没必要给自己增加难度。PyTorch 的版本不要追求太新除非你有特殊需求否则使用项目 requirements 里锁定的版本最稳。CUDA 版本要和 PyTorch 以及 TensorRT 匹配这里说的不是系统里nvidia-smi显示的驱动版本而是 PyTorch 编译时对应的 CUDA runtime 版本。很多人看nvidia-smi显示 CUDA 12.4 就以为 PyTorch 也应该装 cu124实际上只要驱动够新PyTorch 用 cu118 或 cu121 都能跑关键看 cuDNN 和 TensorRT 之间的兼容矩阵。如果在本地复现 YOLO26 源码建议用虚拟环境不要图省事直接装在系统 Python 里。我常用的命令是python -m venv yolo26_env source yolo26_env/bin/activate pip install -r requirements.txt如果只需要导出而不需要从头训练也可以只装必要依赖。别一下子把 requirements 里所有包都装齐很多训练相关库如 WB、clearml 对导出毫无用处反而会在导入模型时因为网络问题触发不必要的初始化。我习惯导出一个模型只依赖 torch、onnx、onnxruntime、opencv-python、pyyaml 这几个核心包遇到特定格式再补装 tensorrt、openvino 等。2.2 导出接口的核心参数逐个拆解YOLO26 的导出通常调用模型的 export 方法最简单的方式是这样from ultralytics import YOLO model YOLO(yolo26n.pt) model.export(formatonnx, imgsz640, halfFalse, opset13, simplifyTrue)每个参数都有它自己的坑。format不用说决定输出文件后缀常见的是onnx、engine、openvino、coreml、tflite等。imgsz决定导出模型的输入尺寸它影响的不止是输入张量的宽高还影响最终候选框数量和精度表现。如果你训练时用的是 640x640导出时最好也用 640如果训练时用了多尺度导出时可以固定到一个部署需要的尺寸比如 1280但前提是模型在验证集上对高分辨率输入确实有收益。half表示是否导出 FP16 精度。对 ONNX 格式来说halfTrue会生成半精度权重体积缩小一半但在 CPU 上不一定有速度收益在 GPU 上则通常明显对 TensorRT 来说FP16 几乎是必开项否则性能优势体现不出来。opset是 ONNX 的算子集版本数值越新支持的算子越多但太新的 opset 可能让老设备上的推理引擎不支持。一般选 13 或 14 比较保险老项目里也有人用 11 或 12主要看目标推理引擎的支持范围。simplifyTrue是很多人容易忽略的好参数。它会调用 onnx-simplifier 对导出的模型进行冗余节点消除、常量折叠、算子融合等优化。原来 PyTorch 导出时可能残留的很多无用节点比如形状计算的辅助节点会在 simplify 后被清理。文件变小推理变快兼容性也更好。代价是 simplify 偶尔会把某些图结构改到和某些自定义算子冲突所以如果简化后模型推理结果不对可以关闭 simplify 重新导出对照。2.3 导出前先确认三类信息任务类型、类别数、anchor 配置YOLO26 的导出不是简单的“塞一个 pt 进去”你最好在脑海里有几个明确信息。第一任务类型。YOLO26 的检测模型、姿态模型、分割模型、目标检测加旋转框模型甚至深度估计模型导出的关键结构完全不同。检测模型输出的是框坐标和类别概率姿态模型在检测输出后面还要追加每个关键点的坐标和可见度分割模型会额外输出 mask 原型和掩码系数旋转框模型会多一个角度参数。这些任务差异决定了你在部署端看到的输出张量结构。第二类别数。如果你训练的是自己的数据集类别数不是默认的 80那么导出的输出通道也要随之变化。典型情况下假设类别数为 nc每个候选框的输出通道就是 4 nc。如果是姿态模型每个关键点输出 3 个值x、y、可见度假设关键点数为 k那么通道数就是 4 nc 3*k。这个规律在你手写 C 解码的时候特别有用。第三anchor 相关配置。YOLO26 沿用 anchor-free 还是 anchor-based不同变体不一样。但导出到 ONNX 时通常都会把 anchor 信息以某种方式固化到图里。如果你在导出后试图用动态 anchor 或自定义 anchor 做后处理需要先确认导出文件里是否包含这些信息。一般建议直接信任导出 SDK 的处理方式尽量不要在部署端额外修改 anchor。3. 实操从 .pt 到 ONNX、TensorRT、OpenVINO 的完整流程3.1 检测模型导出 ONNX 的现场记录我以一个自己训练过的 YOLO26 人员入侵检测模型为例。训练产物是best.pt类别只有 person 一个类别因为业务只需识别是否有人闯入区域。导出命令from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) onnx_path model.export( formatonnx, imgsz640, halfFalse, opset13, simplifyTrue, dynamicFalse, ) print(onnx_path)这里我没有开halfTrue因为客户机器上既有 CPU 又有 GPUONNX 模型需要在两种环境下都能稳定跑。FP16 ONNX 在很多 CPU 推理引擎上不受支持或者会退化成低精度计算反而可能掉点。dynamicFalse表示输入 shape 固定为 1x3x640x640。固定输入的最大好处是后处理代码可以写死很多 TensorRT 优化也能在静态 shape 下做得更好。代价是不能随意改 batch 和输入分辨率。如果业务里有比较大的检测视频想一次批量处理多帧可以开dynamicTrue但后续代码复杂度会明显上升。导出完成后我一般会立即检查产物大小和结构。.onnx文件如果只有几兆那可能是导出出了问题YOLO26 的 ONNX 导出来通常会有几十兆到上百兆具体看模型尺寸是 n/s/m/l/x 哪个档位。检查 ONNX 文件的合法性可以用这段代码import onnx model_onnx onnx.load(best.onnx) onnx.checker.check_model(model_onnx) print(onnx.helper.printable_graph(model_onnx.graph)[:3000])合法之后不代表能直接跑出正确结果最好马上用 onnxruntime 做一次推理对比。我建议准备一张训练集之外的图片分别用.pt模型和.onnx模型预测对比检测框结果。由于精度损失可能很小你不必要求坐标完全一致但关键目标必须都能检出框位置不能有系统性偏移。3.2 ONNX 模型推理验证时的输出张量排布很多人导出 ONNX 之后不会看输出结构直接用 Python 代码把输出拿来凑 NMS结果怎么调都不对。我在这里说一个非常容易被忽视的细节YOLO26 导出的 ONNX 输出 shape 常见有两种排布一种是[1, 4nc, 8400]一种是[1, 8400, 4nc]。如果你的模型配置、opset 或者导出工具版本不同排布就可能不一样。假设类型数为 1输入是 640总的候选框数量是 8400。如果输出是[1, 5, 8400]那么第 0 维固定为 batch第 1 维是每个候选框的属性通道第 2 维是候选框索引如果输出是[1, 8400, 5]那就是候选框维度在前。别看这只是转置的区别在部署代码里一个维度写错轻则所有框的坐标读到类别概率上重则直接内存越界崩溃。我的建议是用 onnxruntime 推理后立刻查一下输出的具体 shapeimport onnxruntime as ort import numpy as np sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) inputs sess.get_inputs() outputs sess.get_outputs() for inp in inputs: print(input:, inp.name, inp.shape, inp.type) for out in outputs: print(output:, out.name, out.shape, out.type) input_name inputs[0].name dummy np.random.randn(1, 3, 640, 640).astype(np.float32) result sess.run(None, {input_name: dummy}) print(result shape:, result[0].shape)看到真实输出 shape 之后再去写后处理就基本不会跑偏了。3.3 从 ONNX 生成 TensorRT engine 以及 workspace 参数YOLO26 在 NVIDIA GPU 上部署时TensorRT engine 通常是最终选择。如果环境已经安装了 TensorRT并且 YOLO26 的导出接口能识别到可以直接一步到位model.export(formatengine, imgsz640, halfTrue, workspace4, device0)workspace4表示允许 TensorRT 构建引擎时最多使用 4GB 显存作为临时工作空间。这个值不要设太小否则会自动降低优化力度也不要设太大否则在大显存机器上构建的引擎到小显存机器上可能无法加载或运行。我的经验是单卡 8GB 显存设 4 到 6单卡 24GB 显存设 8 到 12 就足够了。如果直接通过 SDK 导出失败或者你想更精确控制转换参数可以用 TensorRT 自带的trtexec命令行工具trtexec \ --onnxbest.onnx \ --saveEnginebest_fp16.engine \ --fp16 \ --minShapesimages:1x3x640x640 \ --optShapesimages:8x3x640x640 \ --maxShapesimages:16x3x640x640这个命令的好处是你能明确看到每个阶段的耗时、显存占用、算子使用情况。--fp16开启半精度通常能让推理速度提升一倍以上。如果模型里有某些算子对 FP16 不敏感可能会导致精度下降这时需要通过层级别精度控制去排除特定层比较复杂一般网络在 FP16 下都能稳住。3.4 OpenVINO 导出CPU 部署的实用选择如果客户现场是 Intel CPU 且没有独显我会直接把模型导出为 OpenVINO 格式。YOLO26 导出 OpenVINO 同样很简单model.export(formatopenvino, imgsz640, halfTrue)生成结果通常是一个文件夹里面包含.xml和.bin文件。.xml是模型结构描述.bin是权重数据。OpenVINO 推理可以用它的 Python API也可以用 C API。在我实际测试中同一个 YOLO26 ONNX 模型在 Intel CPU 上用 OpenVINO 比用 onnxruntime CPU 快很多尤其当 batch size 为 1 时优势更明显。有一点要注意OpenVINO 版本更新比较快升级后旧模型可能因为算子映射变化而需要重新导出。最好在项目文档里记录 YOLO26 代码库版本、OpenVINO 版本、导出命令方便后续重新生成。4. 不同任务变体的导出差异详解4.1 YOLO26 检测模型最标准但别忽略类别筛选检测模型是最常见的导出任务。很多人说检测模型导出简单其实只是表面简单。如果你的业务只需要“人”这一类比如人员入侵检测强烈建议训练时就做成单类别模型而不是导出模型后做类别筛选。单类别模型在导出后输出张量从[1, 84, 8400]变成[1, 5, 8400]后面的 NMS 计算量会明显降低部署时也不需要为人的类别单独写过滤逻辑。另外检测模型导出后的 NMS 一定要自己实现或者调用推理框架里的高效插件。onnxruntime 本身没有内置通用 NMS而 TensorRT 的 NMS 插件有版本兼容限制。很多 YOLO26 新手以为导出 ONNX 后模型会自己把框滤掉其实并没有。导出的 ONNX 往往只输出原始预测结果也就是几百上千个候选框你需要用置信度阈值过滤掉大部分框再用 NMS 去掉重叠框。如果哪次部署时发现检测框一团重叠大概率不是模型问题而是根本没有做 NMS。4.2 YOLO26 姿态模型的版本选择和输出通道规律姿态模型是很多项目里容易混用的点。YOLO26 姿态模型里有 n/s/m/l/x 等多个尺度的权重不同尺度的关键点数量可以一样但准确度和推理速度差别很大。选择哪个版本要看业务对关键点精度的要求和硬件预算。比如做人员入侵检测带姿态辅助判断摔倒时通常不需要特别高的关键点精度用 n 或 s 档就够如果是做康复动作评估、体育姿态分析则需要 m 或 l 档。在导出姿态模型时我会先确认关键点数量。YOLO26 的人体姿态模型通常输出 17 个关键点每个关键点包含 x、y、可见度三个值。如果你只训练了自己的三点姿态或二十一点姿态那么导出的输出通道会随之变化。姿态模型的输出张量通常会包含检测框信息、类别概率以及关键点信息。我自己实现 C 解码时会按这个规律读取先取前 4 个值作为框坐标第 5 个为类别置信度后面每 3 个值为一个关键点的 x、y、可见度。如果你发现坐标点读了但错位严重多半是忘记在关键点表达前插入 x/y/vis 的排布。YOLO26 姿态模型的导出尺寸也不能盲目照搬检测模型的 640。人体关节点是尺度敏感任务当图像中人体较小时640 的输入很难保证关键点定位精度。经验做法是导出成 960 或 1280看验证集指标和推理速度的平衡。不要忽视这种方式对显存的占用输入分辨率从 640 提高到 1280特征图计算量是成好几倍增长的。4.3 分割模型与 OBB 旋转框导出的特殊之处分割模型和普通检测模型的导出差别比较大。YOLO26 分割模型除了输出检测框和类别外还包含 mask 原型和 mask 系数。在 ONNX 导出后你往往会看到两个输出一个是候选框层面的输出另一个是 mask 原型输出。只有把 mask 原型和 mask 系数做矩阵乘再经过上采样和阈值化才能得到真正的像素级 mask。很多人在部署端以为自己拿到一个类似语义分割的输出结果直接 reshape 成原图大小去看当然什么也看不见。OBB 旋转框模型则在常规检测输出上多了一个角度值。如果你的现场应用需要检测倾斜的物体比如船舶、飞机、仓库货品旋转框模型很重要。导出的关键是把角度值的表示方式确定清楚是弧度还是角度范围是多少。很多后处理库对角度定义不一致导致框看起来完全正确但旋转方向反了。导出后务必用一张带旋转目标的图像做可视化验证。4.4 YOLO26 depth 模型导出时容易混淆的问题在 YOLO26 各类热词里“depth”经常被提及。如果你用的是深度估计分支或相关任务导出时要注意它和检测任务的本质差异深度模型输出的不是框而是一个密集的深度图或者点云输出 shape 通常是[1, 1, H, W]这种格式也可能输出多个尺度的深度图。深度图对应的数值范围取决于训练时的标注方式可能是相对深度也可能是绝对距离导出后如果直接把它当灰度图显示完全看不出效果不代表模型坏了而是需要做归一化或者反变换。深度模型和检测模型如果放在同一个 YOLO26 工程里导出前要确认你加载的权重是否带着正确的任务头。我见过有人为了在检测任务里辅助判断距离把 YOLO26 depth 版本和检测版本训练到一起最后导出时因为只导出了其中一个头导致另一个任务完全没有输出。这种多任务导出的问题最好在模型定义阶段就规划好把需要部署的分支都显式保留。4.5 人员入侵检测场景里的“模型瘦身”经验人员入侵检测在真实业务里有个特点大部分画面没有人员出现但依然要持续拉流推理。这时候模型导出阶段的静态尺寸选择就很重要。如果现场摄像头有固定的 ROI 区域可以在前处理里直接裁剪出 ROI然后以较小的输入尺寸导出模型比如将 1920x1080 的画面裁剪为 800x450 再 resize 到 320x320 输入模型。这里不是简单地把输入尺寸调小而是在准备数据时配合 ROI 和缩放策略。我的做法是先用一个较大的 ONNX 模型做离线验证确认 ROI 区域在 resize 后依然能检出目标再固定尺寸导出给现场。同时人员入侵检测对误报率非常敏感。如果你在部署后发现模型经常把远处的人影或动物检测成人建议检查置信度阈值和 NMS 阈值而不是重新训练。YOLO26 模型在导出时并不强制固定阈值阈值通常在你的调用代码里设置。我在很多项目里将置信度阈值设为 0.45NMS 阈值设为 0.5然后在现场根据误报情况调整。5. 导出结果的验证、性能基准与交付注意事项5.1 对比 .pt 与导出模型的结果一致性模型导出后必须做一致性验证否则等于黑盒交付。最简单的方案是准备 100 到 200 张覆盖不同场景的测试图分别用原始.pt模型和导出模型推理统计检测框的类别、数量、坐标差异。如果导出前用了dynamicFalse那么.pt模型在验证时也需要把输入 resize 到对应尺寸否则两者看到的图像分辨率不同结果自然有差异。对比时允许有一定浮点误差一般 FP32 导出的坐标误差在 1e-3 量级以内FP16 导出可能到 1e-1 量级但框位置不应该有大偏移。如果你发现导出模型的检测框整体偏移了一两个像素多半是图片预处理差异如果偏移了几十像素那基本是输出解析代码问题。5.2 用导出后的模型在部署端做端到端性能测试导出成功后不能只看模型文件是否生成要在目标硬件上做端到端测试。我最常做的是三件事单张图片耗时测试、视频流平均帧率测试、长时间稳定性测试。单张图片耗时测试可以用 onnxruntime 或 TensorRT 的 Python API测 100 次取平均。注意第一次推理通常会触发显存分配和 kernel 编译要预留预热时间。视频流平均帧率则要把解码耗时、预处理耗时、模型推理耗时、后处理耗时都算进去。很多同学拿着模型推理 5ms 就以为能跑到 200 帧却把图像缩放和 NMS 的时间算了之后发现只有 40 帧。长时间稳定性测试尤其重要TensorRT engine 连续跑几小时后有时候会遇到显存泄漏或温度降频导致的性能波动这在项目交付前必须发现。5.3 把导出产物和配套代码一起交付在实际项目交付中我从来不会只给一个.onnx或.engine文件。我会同时给一份简短的 README里面写清楚训练时用的输入尺寸、归一化方式、图片通道顺序 BGR 还是 RGB、输出张量 shape、后处理伪代码和实测性能数据。很多人觉得这些信息很基础但客户换一个后端工程师接手时这些就是救命文档。特别要提的是颜色通道顺序。YOLO26 训练时通常使用 OpenCV 读取图片也就是 BGR 顺序。但一些部署框架默认读取图像是 RGB比如部分 Python 图像库或移动端 SDK。如果导出的 ONNX 模型是按 BGR 训练的而部署端送入了 RGB 数据模型的检测效果会明显变差而且不是那种完全检测不到而是置信度普遍下降。这个问题的隐蔽性在于你不容易想到是通道顺序问题。所以我会在 README 里用加粗字体写清楚部署端输入图片必须与训练前处理保持一致默认按 BGR 顺序输入。5.4 模型更新后重新导出的注意事项如果你的 YOLO26 项目隔了一段时间又重新训练导出了新版本模型千万不要直接覆盖旧模型文件而不做回归测试。我在一次项目里因为只替换了模型权重没有重新生成对应的 TensorRT engine结果在旧 engine 上加载新权重时报了结构不匹配的错误排查了很久才发现是构建缓存的问题。YOLO26 的导出过程会在目录里生成一些缓存文件比如构建 TensorRT engine 时的.cache如果新旧模型结构不一致缓存会导致加载异常。安全做法是每次重新导出到独立目录并在标签里加上时间戳例如best_20250115.engine避免新旧文件混淆。6. 导出过程常见报错与排查速查6.1 报错信息和我的排查思路很多人遇到模型导出报错就慌了其实报错并不可怕关键是看它发生在哪个阶段。导出过程可以分为三个阶段PyTorch 模型加载与解析、转为 ONNX 图、目标格式转换。不同阶段的报错对应不同解决方案。在 PyTorch 模型加载阶段最常见的报错是提示找不到自定义模块或 key 不匹配。这种问题多半因为你换了 YOLO26 代码版本训练时用的模块类名和加载时的类名不一致。解决办法是检查权重文件中的模型结构 key 是否和当前代码一致尤其是model.yaml配置里的模块组合不能随意修改。如果你做过 YOLO26 改进比如换了一个轻量化注意力模块那么训练、导出、部署最好全程使用同一分支代码不要中途升级代码库。在 ONNX 图转换阶段报错如果有“Unsupported operator”这样的关键词说明 PyTorch 模型里有某些算子没有被 ONNX exporter 识别。遇到这种情况先锁定是哪一层产生的问题通常建议用torch.onnx.export的verboseTrue打印导出细节或者在模型代码里临时把可疑模块替换为等价基础算子。千万不要硬要求 ONNX 支持所有算子很多自定义模块本身就不适合直接导出。在目标格式转换阶段比如从 ONNX 转 TensorRT 时报精度不支持、维度不支持一般需要回到 ONNX 图层面修改输入输出的动态维度范围或者排查模型中是否用了 TensorRT 不友好的算子比如某些动态 resize、动态循环。这个阶段最花时间但也最能体现经验积累。6.2 导出常见问题速查表现象可能原因处理办法导出报错缺少自定义模块代码库版本不一致用训练时同一份代码重新加载ONNX 导出成功但结果全为 0前处理通道顺序、归一化不一致检查输入是否使用 BGR 和相同的除以 255TensorRT 引擎构建时显存不足workspace 配置过大调低 workspace或减小 batch size导出模型体积比预期小很多satisfy 清理了太多节点或输出裁剪错误检查输出节点关闭 simplify 对比输入尺寸不匹配导出和推理时 imgsz 不一致统一为训练时的输入尺寸检测框位置偏移明显候选框排布读错或 NMS 缺失查看输出 shape确认是否需要转置和实现 NMSFP16 导出后置信度显著下降FP16 精度敏感层较多改用 FP32 或对特定层禁用 FP16同一份 engine 换显卡后报错TensorRT engine 与显卡绑定在目标显卡上重新生成 engine导出后自定义 attention 模块无法运行目标后端不支持某些动态算子改用固定 shape 或替换为等效结构6.3 导出时间太长和内存占满的处理YOLO26 在导出到 TensorRT 时如果模型较大且没有合理设置 workspace可能会出现构建几十秒甚至几分钟没有动静的情况。这不是死机而是在做算子选择和 kernel autotuning。如果构建时间太长可以尝试用trtexec的--verbose参数观察进度确认是卡在某个具体层还是整体优化较慢。对于特别大的模型比如 YOLO26x 配合 1280 输入导出时的显存峰值可能很高。如果你只有一块 8GB 显存建议导出时加devicecpu或者采用分块优化方式。YOLO26 的 export 接口允许在 CPU 上导出模型虽然慢一点但能避免显存不足的报错。ONNX 转 TensorRT 也可以将构建过程放到内存较大的无 GPU 机器上TensorRT 支持在没有目标 GPU 的情况下构建 engine但需要注意某些硬件相关优化会失效最好还是在目标硬件上构建。6.4 部署端拿到模型后“正常但不对”的排查顺序这里总结一套我的排查顺序。如果部署端能跑通但结果不对先别怀疑模型文件按顺序做四件事。第一打印输入张量确认图片尺寸、通道顺序、归一化后的数值范围是否符合预期。只要输入不对后面全错。第二打印模型输出的 shape 和典型值确认输出维度和脚本解析方式匹配。第三单步检查从原始输出到最终框的转换逻辑尤其是框坐标是在原图尺度还是模型输入尺度。第四和.pt模型对同一张图的输出做数值比较定位差异出现在前处理、模型计算还是后处理阶段。7. 我用 YOLO26 做完整个导出链路后的几点体会做模型导出这件事心态上要放平。它不像模型训练那么有成就感也没有那么多论文可读但它是把算法变成产品的最后一道工序。我在帮别人验收 YOLO26 项目时经常看到训练指标很不错一到导出阶段就卡壳原因大多不是技术难度而是太想当然。很多人训练完拿.pt文件直接部署觉得模型能出结果就行结果没考虑到 PyTorch 推理速度太慢、部署环境无法安装训练框架、输出后处理缺了 NMS 等问题。如果一开始就把“最终要导出成什么格式”融入训练前的方案设计里很多弯路都能提前避开。我还想强调一点导出模型不能只看一张测试图没问题就结束。我在实际项目里吃过亏模型在白天场景下导出后表现完美但晚上因为画面整体变暗、通道统计分布偏移检测效果大幅下降。这个问题不是模型导出本身造成的但它提醒我做导出验证时要覆盖实际业务的各种光线、角度、目标大小情况。把测试集准备得越接近真实场景导出交付后的稳定性就越高。最后分享一个小经验在 YOLO26 项目开始训练之前先花十分钟用一个没训练好的权重跑一遍完整导出流程。这个做法能提前暴露代码库、PyTorch 版本、ONNX opset、目标硬件工具链之间可能存在的兼容性问题。如果真的想在计算机视觉这条路上走得更远建议把模型导出当成一个正式工程环节来对待而不是训练结束后的附带动作。它能让你更清楚模型内部发生了什么、部署端需要什么这份理解在后续做 YOLO26 改进或结构设计时也一定会帮到你。