1. 项目背景与整体设计思路

1.1 这个阶段到底在做什么

Phase A · Step 2 这个名字听起来很工程化，但说白了就一件事：在正式跑训练之前，把预训练权重准备好，把整条 Pipeline 从头到尾验证一遍，确保数据能进、模型能出、中间不掉链子。很多人一上来就急着调参、改结构、跑训练，结果跑到一半发现权重加载失败、ONNX 导出报错、推理结果对不上，回头排查的成本远高于提前花半天做验证。

我自己的习惯是，任何一次新的训练任务，不管是用 YOLO26 还是其他检测框架，都先把“权重—数据—导出—推理”这条链路走通一遍，用极小的数据量跑一个 epoch，确认没有低级错误，再上全量数据。这个阶段的核心目标有三个：第一，确认预训练权重能正确加载，类别数和结构匹配；第二，确认数据 Pipeline 从读取、增强到 batch 组装没有问题；第三，确认模型能正常导出为 ONNX，并且导出后的推理结果和 PyTorch 原生推理一致。

1.2 为什么权重和 Pipeline 验证要放在训练之前

这里面的逻辑其实很朴素。预训练权重决定了你模型的起点，如果权重加载时 key 对不上、层名错位、类别头维度不匹配，训练照样能跑，但 loss 会异常高，收敛极慢，你以为是学习率问题，实际上是权重根本没加载进去。Pipeline 验证则是保证数据流的正确性，包括图像解码、letterbox 填充、归一化、标签对齐这些环节，任何一个环节出问题，模型看到的都是“错的数据”，训练再久也是白费。

从工程角度看，把验证前置还有一个好处：它把问题隔离在最小范围内。训练阶段出问题，可能的原因有几十个；但验证阶段出问题，原因通常就那么几个，排查起来快得多。我踩过最典型的一个坑是，数据增强里的 mosaic 在某个版本下标签坐标没有同步更新，训练时 loss 一直震荡，查了两天才发现是增强逻辑的问题。如果当时先做 Pipeline 验证，用可视化把增强后的图和框画出来看一眼，十分钟就能定位。

1.3 整体流程拆解

整个 Step 2 我一般拆成四块来做，顺序上可以并行，但逻辑上是递进的：

• 权重准备：下载或转换预训练权重，检查结构匹配，确认加载无警告。
• 数据 Pipeline 验证：小批量数据过一遍，可视化检查增强结果和标签对齐。
• 前向推理验证：用 PyTorch 原生跑一次推理，确认输出维度、数值范围正常。
• 导出链路验证：导出 ONNX，用 onnxruntime 跑一次，对比数值一致性。

这四块做完，基本可以确认整条链路是通的，后面训练和部署才有意义。下面我逐个展开讲，把每一步的操作细节、参数选择和踩坑经验都写清楚。

2. 预训练权重准备与加载验证

2.1 权重来源与格式选择

预训练权重的来源主要有几种：官方发布的 checkpoint、社区转换的权重、以及从其他格式反推回来的权重。YOLO 系列常见的权重格式包括.pt（PyTorch）、.onnx、以及一些部署框架专用的格式。做训练时，我们需要的通常是.pt格式，因为要在此基础上继续训练。

选择权重时要注意几个关键点。第一是类别数，COCO 预训练是 80 类，如果你自己的数据集是 10 类，加载时类别头维度不匹配，需要做裁剪或重新初始化。第二是输入分辨率，预训练权重通常是在 640x640 上训练的，如果你要用 1280 的输入，权重本身可以加载，但特征分布会有偏移，建议先在小分辨率上微调。第三是模型规模，n/s/m/l/x 不同规模的权重不能混用，层数和通道数都不一样。

提示：下载权重后先校验文件完整性，MD5 或 SHA256 对一下，避免下载中断导致权重损坏，加载时报奇怪的错。

2.2 权重加载的代码实现与常见报错

加载权重的核心代码其实很简单，但细节很多。以 PyTorch 为例，基本流程是：构建模型结构，读取 checkpoint，过滤不匹配的 key，加载 state_dict。

import torch from models.yolo import Model # 构建模型结构 cfg = "configs/yolo26.yaml" model = Model(cfg, ch=3, nc=10) # nc 为自定义类别数 # 读取预训练权重 ckpt = torch.load("weights/yolo26_pretrained.pt", map_location="cpu") state_dict = ckpt["model"].state_dict() if "model" in ckpt else ckpt # 过滤不匹配的 key model_dict = model.state_dict() filtered = {k: v for k, v in state_dict.items() if k in model_dict and v.shape == model_dict[k].shape} # 加载并打印未匹配项 missing, unexpected = model.load_state_dict(filtered, strict=False) print("Missing keys:", missing) print("Unexpected keys:", unexpected)

这段代码里，strict=False是关键，它允许部分加载。但要注意，missing和unexpected必须人工检查。如果 missing 里包含大量 backbone 的层，说明权重根本没加载进去；如果 unexpected 里全是类别头相关的 key，那是正常的，因为类别数变了。

常见的报错有这么几类：size mismatch for ...通常是类别头或某个层的维度对不上；unexpected key(s) in state_dict是权重里有模型没有的层；Missing key(s)反过来。我一般会把 missing 和 unexpected 打印出来，逐条看，确认哪些是预期内的，哪些是异常。

2.3 权重加载后的快速自检

加载完权重，不要急着训练，先做几个自检。第一，用一张真实图片跑一次前向，看输出 shape 是否是[1, num_anchors, 5+nc]这种预期格式。第二，看输出的置信度分布，如果全是 0 或者全是极大值，说明权重可能没加载对。第三，对比加载权重前后同一张图的输出，如果完全一样，说明权重没生效。

我自己的习惯是写一个小脚本，把这几项检查自动化，每次换权重都跑一遍。这个脚本不超过 50 行，但能省下大量排查时间。

model.eval() with torch.no_grad(): dummy = torch.randn(1, 3, 640, 640) out = model(dummy) print("Output shape:", out[0].shape if isinstance(out, (list, tuple)) else out.shape) print("Output range:", out[0].min().item(), out[0].max().item())

输出 shape 和数值范围正常，基本可以确认权重加载没问题。

3. 数据 Pipeline 验证实操

3.1 Pipeline 的组成与验证目标

数据 Pipeline 一般包含这几个环节：数据读取（图像+标签）、预处理（resize、letterbox、归一化）、数据增强（mosaic、mixup、HSV 调整、翻转等）、batch 组装（collate）。验证的目标是确认每个环节的输出都符合预期，尤其是标签坐标在增强后是否和图像对齐。

这一步最容易被忽视，因为 Pipeline 通常封装得很好，调用起来就一行DataLoader。但封装越好，出问题时越难查。我的做法是把 Pipeline 拆开，逐环节可视化，用 matplotlib 把增强后的图和框画出来，肉眼确认。

3.2 小批量数据过 Pipeline 的实操

先准备一个极小的数据集，比如 20 张图，确保能快速迭代。然后构建 Dataset 和 DataLoader，取一个 batch 出来检查。

from dataset import YOLODataset from torch.utils.data import DataLoader dataset = YOLODataset("data/mini/images", "data/mini/labels", img_size=640) loader = DataLoader(dataset, batch_size=4, shuffle=False, collate_fn=dataset.collate_fn) imgs, targets = next(iter(loader)) print("Image batch shape:", imgs.shape) # [4, 3, 640, 640] print("Targets shape:", targets.shape) # [N, 6] -> [img_idx, cls, x, y, w, h] print("Targets sample:", targets[:5])

检查要点：图像 batch 的 shape 是否正确，数值范围是否在 0-1 之间（归一化后）；targets 的坐标是否在 0-1 之间（归一化后），类别索引是否在有效范围内。如果 targets 里有负数或大于 1 的值，说明坐标转换有问题。

3.3 增强结果可视化与标签对齐检查

这一步是重点。把增强后的图像和框画出来，肉眼确认框是否贴合目标。我一般会画 8-16 张，覆盖不同的增强组合。

import matplotlib.pyplot as plt import matplotlib.patches as patches def visualize(imgs, targets, idx=0): img = imgs[idx].permute(1, 2, 0).numpy() fig, ax = plt.subplots(1, figsize=(8, 8)) ax.imshow(img) h, w = img.shape[:2] for t in targets[targets[:, 0] == idx]: _, cls, x, y, bw, bh = t.tolist() rect = patches.Rectangle( ((x - bw/2) * w, (y - bh/2) * h), bw * w, bh * h, linewidth=2, edgecolor="r", facecolor="none") ax.add_patch(rect) plt.show()

画出来之后重点看几件事：框是否和目标对齐，有没有框跑到图像外面，有没有目标没有框，有没有框重叠错位。mosaic 增强特别容易出问题，因为它是四张图拼接，标签坐标要经过平移和缩放，任何一步算错都会导致框错位。

注意：mosaic 增强在训练后期通常会关闭（close_mosaic 参数），验证时也要确认这个开关是否按预期生效。

3.4 数据 Pipeline 的常见坑

我整理了几个高频问题。第一，letterbox 填充后的坐标还原，如果推理时忘了把坐标映射回原图，框的位置会整体偏移。第二，归一化方式不一致，训练用 0-1 归一化，推理用 0-255，结果会差很多。第三，标签格式混淆，xywh 和 xyxy 混用，或者归一化和绝对坐标混用，这是最常见的错误来源。第四，多进程 DataLoader 的随机种子，如果每个 worker 的种子没设好，增强结果可能不可复现。

4. 前向推理与 ONNX 导出验证

4.1 PyTorch 原生推理验证

在导出之前，先用 PyTorch 原生跑一次推理，把结果作为基准。这一步的目的是拿到一组“标准答案”，后面导出 ONNX 后对比数值一致性。

model.eval() with torch.no_grad(): img = torch.randn(1, 3, 640, 640) torch_out = model(img) if isinstance(torch_out, (list, tuple)): torch_out = torch_out[0] print("Torch output shape:", torch_out.shape) print("Torch output sum:", torch_out.sum().item())

记录下输出的 shape 和数值统计量（sum、mean、max），后面 ONNX 推理要和这些值对比。如果差异在 1e-4 以内，基本可以认为是一致的。

4.2 ONNX 导出的关键参数

导出 ONNX 时，有几个参数直接影响后续部署的难易程度。opset_version建议用 11 或 12，兼容性好；dynamic_axes如果要做动态 batch 或动态输入尺寸，必须设置；simplify可以简化计算图，减少冗余节点。

torch.onnx.export( model, dummy_input, "yolo26.onnx", opset_version=12, input_names=["images"], output_names=["output"], dynamic_axes={ "images": {0: "batch", 2: "height", 3: "width"}, "output": {0: "batch"} }, do_constant_folding=True )

导出后，用 onnxruntime 跑一次，对比数值。

import onnxruntime as ort import numpy as np sess = ort.InferenceSession("yolo26.onnx") onnx_out = sess.run(None, {"images": dummy_input.numpy()})[0] print("ONNX output shape:", onnx_out.shape) print("Max diff:", np.abs(onnx_out - torch_out.numpy()).max())

如果 max diff 在 1e-4 以内，说明导出没问题。如果差异很大，通常是某些算子导出不正确，或者动态轴设置有问题。

4.3 ONNX 量化与部署格式转换

如果目标是端侧部署，ONNX 之后通常还要做量化或转成其他格式。INT8 量化能显著减小模型体积、提升推理速度，但会带来精度损失。量化的关键是校准数据集的选择，要用有代表性的真实数据，不能随便拿几张图凑数。

from onnxruntime.quantization import quantize_dynamic, QuantType quantize_dynamic( "yolo26.onnx", "yolo26_int8.onnx", weight_type=QuantType.QInt8 )

量化后一定要重新跑一遍精度对比，确认 mAP 下降在可接受范围内。我遇到过量化后小目标检测明显变差的情况，后来发现是校准集里小目标样本太少，补充之后就好了。

如果部署目标是特定硬件，可能还需要转成专用格式。转换时要注意算子支持情况，有些自定义算子在某些框架里不支持，需要替换或重写。转换后同样要做数值对比和精度验证，不能想当然认为转换是无损的。

5. 常见问题与排查技巧实录

5.1 权重加载类问题速查

权重相关的问题占了验证阶段问题的一半以上。我整理了一个速查表，遇到问题先对号入座。

排查时我一般会先把 state_dict 的 key 打印出来，和模型的 key 对比，看差异在哪。很多时候问题就是命名前缀不一样，比如权重里是module.开头，模型里没有，加个前缀处理就行。

5.2 Pipeline 与导出类问题排查

Pipeline 的问题往往表现为训练 loss 异常，但根因在数据。我的排查顺序是：先可视化增强结果，确认数据没问题；再检查 loss 计算，确认标签格式对；最后才怀疑模型和超参。导出类问题则集中在算子兼容性和数值精度上，ONNX 导出失败通常是某个算子不支持，可以尝试换 opset 版本或替换算子实现。

提示：导出 ONNX 时如果报Unsupported operator，先用torch.onnx.export的 verbose 模式看是哪个节点，再针对性处理。

5.3 我踩过的几个典型坑

第一个坑是权重加载了但没生效。当时用strict=False加载，missing 和 unexpected 都没仔细看，训练了几个 epoch 发现 loss 和从头训练差不多，回头一查发现 backbone 的 key 全在 missing 里，等于只加载了类别头。从那以后我养成了打印并逐条检查 missing/unexpected 的习惯。

第二个坑是ONNX 动态轴设置错误。设置了动态 batch 但没设置动态高宽，结果换了个输入尺寸推理就报错。动态轴要根据实际部署需求设置，不能盲目全开，全开有时会拖慢推理。

第三个坑是量化校准集不具代表性。用了几十张背景图做校准，量化后模型对目标的响应明显变弱。后来换成覆盖各类目标的校准集，精度就回来了。校准集的选择比量化算法本身更重要，这一点很多教程不会强调。

第四个坑是Pipeline 验证时用了训练集之外的预处理。验证脚本里自己写了一套 resize 逻辑，和训练时的 letterbox 不一致，导致验证结果和训练对不上。后来统一用同一个预处理函数，问题消失。这个教训是：预处理逻辑一定要复用，不要重复实现。

6. 验证通过后的下一步衔接

6.1 从验证到正式训练的过渡

验证通过后，正式训练前还有几件事要做。第一，把验证用的小数据集换成全量数据，确认数据加载速度能跟上训练需求，避免 GPU 等数据。第二，把 batch size 和学习率按全量数据规模重新调整，小批量验证时的超参不能直接套用。第三，开启训练日志和 checkpoint 保存，确保训练过程可追溯。

我一般会先跑一个 epoch 的短训练，确认 loss 正常下降、验证指标有响应，再启动完整训练。这个短训练相当于最后一次冒烟测试，成本很低但能避免大事故。

6.2 部署链路的提前规划

如果项目最终要部署，验证阶段就应该把部署链路考虑进来。比如目标硬件支持哪些算子、推理框架对输入输出的要求、量化精度要求等。这些问题在训练后再处理，往往要回头改模型结构，成本很高。提前规划的话，可以在训练时就避开不支持的算子，或者预留量化友好的结构。

6.3 我个人在验证阶段的一点体会

做了这么多项目，我越来越觉得验证阶段的价值被低估了。大家总想快点看到训练结果，但真正省时间的恰恰是前期这些看起来“没产出”的验证工作。我现在会把 Step 2 当成一个独立的交付物来做，权重、Pipeline、导出三条线各自有检查清单，全部打勾才进入训练。这个习惯让我少熬了很多夜，也少了很多“训练到一半发现根本问题”的崩溃时刻。

最后分享一个小技巧：把验证脚本固化下来，做成可复用的模块，每次新项目直接调用，只改配置不改逻辑。这样既保证了验证的完整性，又不用每次重新写一遍。验证脚本本身也是文档，新人接手时看一眼脚本就知道整条链路是怎么走的。