简介面向目标检测模型轻量化场景的 YOLOv5 知识蒸馏实战资源结合教师网络-学生网络迁移范式帮助有一定 YOLO 基础的学习者掌握蒸馏原理、环境配置与完整训练流程。压缩包共 8 个文件约 593MB包含 4 个 zip 资料包、3 个 pt 权重文件与 1 个 Python 处理脚本zip 内为代码、数据集及说明文档pt 可用于对比蒸馏前后模型效果py 用于数据预处理整体按教程逐步操作即可复现实验。已有 2022 人学习下载。亮点在于不仅提供可直接运行的 YOLOv5 蒸馏源码还配套 VOC 格式数据、整理好的说明文档与权重文件读者可对照教师网络与学生网络的训练差异理解蒸馏 loss 设计与模型轻量化调优思路并基于现有数据快速迁移到自己的检测任务。1. 为什么 YOLOv5 要做知识蒸馏轻量模型不是练不大是没找对老师做目标检测落地的工程师几乎都撞过同一堵墙模型在服务器上跑得挺好一换到边缘设备就卡成 PPT。YOLOv5s 在 Jetson Nano 上勉强能跑实时精度却比 YOLOv5x 掉了一截换成 YOLOv5n 倒是快了小目标直接漏成筛子。知识蒸馏Knowledge Distillation解决的就是这个矛盾——用一个笨重但精准的教师模型把一个轻量学生模型教到尽可能接近教师的精度而不是让学生从头自己悟。基于 YOLOv5 的知识蒸馏实战源码本质上就是把这套教师-学生训练框架写进 YOLOv5 原本的训练流程里让蒸馏不是论文里的概念而是你能跑起来、能调参、能评估收益的工程代码。本文适合两类人一类是手里有边缘部署需求、想压缩模型但不想牺牲太多精度的算法工程师另一类是把 YOLOv5 当入门框架、想搞懂蒸馏到底怎么改训练逻辑的学生。2. 知识蒸馏在 YOLOv5 里的落地形态从教师选择到损失函数设计2.1 教师模型选型不是越大越好是越像越好先解决一个最容易被带偏的问题教师模型是不是直接选 YOLOv5x 就完事我在项目里试过用 YOLOv5x 蒸馏 YOLOv5s效果有提升但提升幅度天花板很明显。原因在于蒸馏的有效性取决于教师和学生之间能力差与结构差的平衡。结构差太大学生的特征表达空间根本装不下教师的信息学到的只是一堆无法消化的高维噪声。我一般这样选型教师选比学生大一到两个量级的同族模型。学生是 YOLOv5s教师选 YOLOv5l 或 YOLOv5x 都行学生是 YOLOv5n教师选 YOLOv5s 或 YOLOv5m 就够了。关键指标不是参数量差距而是教师自身在验证集上的 mAP 要明显高于学生直接训练的 mAP差值最好在 5 个点以上。如果教师只比学生高两三个点蒸馏收益会很小不如直接调学生的超参数。另一个容易被忽略的点是输入分辨率。YOLOv5 训练时默认 imgsz640但如果你的教师模型是用 1280 分辨率训出来的蒸馏时教师和学生必须用同一个输入尺寸。否则教师输出的 feature map 尺寸和学生完全对不上蒸馏 loss 都没法算。2.2 学生模型的三个改造点预测头、neck、backbone拿到 YOLOv5 源码后蒸馏改造不是从零写训练脚本而是基于原有的train.py做增量修改。需要动三个位置。第一是 backbone 的输出。YOLOv5 的 backbone 在三个尺度上输出特征分别是下采样 8 倍、16 倍、32 倍的位置。蒸馏时我们要在这些位置分别取教师的 feature map 和学生的 feature map 算 distance loss。你可以在models/yolo.py的Detect层前面把 backbone 和 neck 的输出引出来或者在forward函数里加一个返回中间特征的开关。第二是 neck 部分。YOLOv5 的 PANet 结构会把高层语义信息往下融合蒸馏时如果只对齐 backbone 特征而忽略 neck学生的浅层特征可能学到位了但融合后的信息仍然是乱的。我在实际项目里发现neck 输出的三个特征图做蒸馏对齐收益比 backbone 蒸馏更明显因为检测头的定位和分类直接消费的是 neck 的输出。第三是预测头。YOLOv5 的检测头输出是(batch, 3*(5num_classes), grid_h, grid_w)的格式蒸馏时需要把教师和学生的输出 reshape 成(batch, 3, grid_h, grid_w, 5num_classes)然后分别取 objectness、box、class logits 来算 loss。这里有一个坑教师和学生的 grid 尺寸必须一致如果教师用了更大的输入grid 尺寸会不同蒸馏 loss 压根算不了。2.3 损失函数怎么拼Logits 蒸馏与 Feature 蒸馏的主次关系知识蒸馏的损失函数有两类主流做法YOLOv5 的检测场景下我建议两个都上但主次要分清。第一类是 logits 蒸馏对应分类分支。YOLOv5 的分类头输出的是每个 anchor 在每个类别上的 logits蒸馏时用 KL Divergence 让学生 logits 逼近教师 logits。温度 T 是这里的核心参数T 越大softmax 后的分布越平滑学生能学到类别之间的相似关系。检测任务里我一般把 T 设在 3 到 7 之间太低学不到暗知识太高会把背景类的噪声也放大。第二类是 feature 蒸馏对应的是 backbone 和 neck 的中间特征。常用的做法是计算教师和学生 feature map 之间的 L2 loss 或者 L1 loss。但这里有个玄学问题直接对齐绝对数值会让学生模型训练不稳定因为教师特征的数值范围和学生完全不一样。业界更稳的做法是先用 attention map 或者归一化把特征变换到同一量纲再算距离。我在实战里用的是 channel-wise 归一化后再算 MSE效果比直接算稳得多。整体 loss 的拼法是# 蒸馏总loss YOLOv5原始loss 蒸馏loss loss loss_box loss_obj loss_cls lambda_distill * loss_distilllambda_distill 的取值我在 0.1 到 1.0 之间都试过最终稳定在 0.5 左右。蒸馏 loss 权重太大学生会过度拟合教师的预测反而丢失自己从 ground truth 学到的信息太小则基本没效果。这个参数值得花时间细调它比学习率对最终精度的影响更直接。检测头的 box 回归部分不参与蒸馏因为 box 坐标是连续值回归问题教师给的信息优势不大直接让学生学 ground truth 更干净。3. 把 YOLOv5 改造成支持蒸馏的训练框架环境准备与代码结构3.1 环境与依赖conda 创建环境避免污染现有项目YOLOv5 的依赖相对固定但蒸馏会引入额外的张量操作建议单独用 conda 建一个环境避免跟其他项目打架。我用的组合是 Python 3.9 PyTorch 1.13 CUDA 11.7这个组合在 YOLOv5 官方仓库的 requirements 里能直接对齐。如果你用的是更新的 PyTorch 2.xYOLOv5 也能跑但某些算子行为可能有细微差异蒸馏训练时显存占用会更高。# 创建独立环境并激活 conda create -n yolo_kd python3.9 -y conda activate yolo_kd # 安装 PyTorch 全家桶 pip install torch1.13.1cu117 torchvision0.14.1cu117 --extra-index-url https://download.pytorch.org/whl/cu117 # 安装 YOLOv5 的官方依赖 pip install -r requirements.txt这里要特别说一下requirements.txt里的版本问题。YOLOv5 官方仓库会定期更新依赖如果你克隆的是最新版里面的opencv-python和numpy版本可能和 PyTorch 1.13 有冲突。我踩过一次 numpy 2.0 和 PyTorch 1.13 的兼容性坑训练到一半直接报_ARRAY_API not found。解决办法是把 numpy 降到 1.24 以下再装其他依赖。3.2 目录结构把蒸馏代码放在哪里拿到 YOLOv5 源码包之后默认目录结构是models/、utils/、data/、train.py、detect.py这些。我不建议把蒸馏逻辑全部塞进train.py那样文件会膨胀到没法维护。常见做法是新增一个kd/目录放三个模块distill_loss.py、teacher_model.py、distill_utils.py。yolov5/ ├── kd/ │ ├── __init__.py │ ├── distill_loss.py # 蒸馏loss计算 │ ├── teacher_model.py # 教师模型加载与冻结 │ └── distill_utils.py # 特征对齐、温度控制等工具函数 ├── models/ │ ├── yolo.py # 原模型定义需微调 │ └── ... ├── train.py # 原训练入口需微调 └── ...这个结构的好处是隔离清晰train.py只负责调用蒸馏模块具体的 loss 计算和特征对齐逻辑都封装在kd/下。如果要换蒸馏策略比如从 logits 蒸馏换成 relation distillation只需要改distill_loss.py不需要动训练入口。3.3 教师模型加载与冻结推理模式教师模型加载是蒸馏框架里最容易出问题的一环。很多人直接torch.load教师权重就丢进训练循环结果发现显存爆了——原因是教师模型也在反向传播它的梯度也要保留。教师模型在整个训练过程中是只读的必须冻结它的全部参数并且在 forward 之外包torch.no_grad()。def load_teacher_model(weights_path, device, halfTrue): # 加载教师模型只推理不求梯度 teacher torch.load(weights_path, map_locationdevice) teacher teacher[model].float() teacher.eval() # 冻结所有参数不参与梯度计算 for param in teacher.parameters(): param.requires_grad False # 半精度推理节省显存 if half: teacher teacher.half() return teacher逻辑说明torch.load返回的 checkpoint 是个字典YOLOv5 的权重文件里model字段存放的是 nn.Module 实例。.eval()必须调用否则模型里的 BatchNorm 层还在用训练模式running mean 会继续更新教师输出的特征分布就不稳定了。half()可以在显存吃紧时把教师模型切成半精度但要注意蒸馏 loss 计算时要把教师输出转回 float32否则数值精度不够会导致梯度波动。教师模型放在哪个设备上也有讲究如果你的显存是 24GB学生和教师放同一张卡没问题如果只有 12GB建议把教师放 CPU 上跑推理虽然慢一点但能省下 GPU 显存给学生模型做更大 batch。4. 基于 YOLOv5 的知识蒸馏实战源码核心训练主循环改写4.1 KD Loss 的计算从 teacher 输出到学生梯度训练主循环的改写是整套源码的核心。原始 YOLOv5 的train.py里每个 batch 的流程是前向学生模型、算 loss、反向传播、更新参数。蒸馏模式下流程变成前向教师模型冻结、前向学生模型、分别算原始 loss 和蒸馏 loss、合并反向传播。for batch_idx, (imgs, targets, paths, _) in enumerate(dataloader): imgs imgs.to(device).float() / 255.0 targets targets.to(device) # 教师模型前向不计算梯度 with torch.no_grad(): teacher_outputs teacher_model(imgs) # 学生模型前向 student_outputs, student_feats student_model(imgs) # 原始YOLOv5 lossbox obj cls loss_box, loss_obj, loss_cls compute_yolo_loss(student_outputs, targets) # 蒸馏loss基于教师和学生的输出 loss_distill distill_loss( teacher_outputsteacher_outputs, # 教师logits和特征 student_outputsstudent_outputs, # 学生logits和特征 temperature3.0, lambda_feat0.5 ) # 合并loss loss loss_box loss_obj loss_cls 0.5 * loss_distill # 反向传播 loss.backward() optimizer.step() optimizer.zero_grad()这段代码是训练主循环的最小骨架。compute_yolo_loss是 YOLOv5 原始代码里的ComputeLoss类我直接引用了没有改动。distill_loss是核心函数负责把教师的输出和学生的输出对应起来算 KL 散度和特征距离。参数说明temperature3.0在分类数较少的数据集上偏保守如果检测类别超过 20 个可以尝试把温度调到 5.0让类别分布更平滑lambda_feat0.5控制特征蒸馏在总蒸馏 loss 里的占比如果训练早期 loss 波动太大可以先把 lambda_feat 降到 0.2 看看稳定性。student_model(imgs)返回了两个值这个需要你在models/yolo.py的 forward 里改造。原始 YOLOv5 的 forward 只返回检测输出拿到后面做 NMS 用。蒸馏训练需要额外的中间特征我在 forward 里加了一个return_feats的开关默认是False训练时置为True就能拿到 backbone 和 neck 的多层特征。4.2 Feature 蒸馏用 attention map 对齐特征分布仅仅对 logits 做 KL 散度学生学到的是结果而非过程。YOLOv5 的检测能力高度依赖多尺度特征融合所以特征层面的蒸馏不能省。我实现了一个 channel-wise attention 对齐的方案比直接算 MSE 更稳。def distill_feature_loss(teacher_feats, student_feats, device): teacher_feats和student_feats都是列表包含三个尺度的特征图 每个特征图形状: (batch, channels, grid_h, grid_w) total_loss 0.0 for t_feat, s_feat in zip(teacher_feats, student_feats): # Channel-wise 归一化消除量纲差异 t_norm F.normalize(t_feat, p2, dim1) s_norm F.normalize(s_feat, p2, dim1) # 计算通道注意力权重 t_attn torch.mean(torch.abs(t_feat), dim(2, 3), keepdimTrue) s_attn torch.mean(torch.abs(s_feat), dim(2, 3), keepdimTrue) # 加权后的L2距离 t_weighted t_norm * t_attn s_weighted s_norm * s_attn # 逐像素计算MSE loss F.mse_loss(s_weighted, t_weighted) total_loss loss return total_loss / len(teacher_feats)逻辑说明这里做了两步关键处理。第一步是F.normalize把特征图沿 channel 方向归一化消除教师和学生特征数值范围不一致的问题。如果不做这一步教师特征中某些通道的值是学生的 10 倍MSE loss 会被这些通道主导学生模型只会疯狂拟合大数值通道其他通道学不到东西。第二步是通道注意力加权这个 trick 来自实验经验——特征图中响应值大的通道也就是模型更关注的语义信息应该在蒸馏里占更高权重用torch.mean(torch.abs())算出一个通道级别的标量乘到归一化后的特征上。实践效果是加入 attention 加权后蒸馏收敛速度明显加快早期 loss 震荡也减轻了。尺度对齐是另一个必须有前瞻性的点。YOLOv5 的 neck 输出三个尺度如果教师和学生输入尺寸不一样grid 大小就对不上。我处理的方法是强制蒸馏时教师和学生使用相同输入尺寸且不启用 mosaic 增强的随机缩放部分。mosaic 会随机改变图像的拼接比例导致 label 和特征的对应关系在不同 batch 之间漂移蒸馏 loss 会被这种漂移干扰。我一般在蒸馏训练阶段把mosaic概率从默认的 1.0 降到 0.5保证特征对齐的稳定性。4.3 训练参数温度、权重系数、学习率怎么调蒸馏训练的参数设定和普通训练有明显差别。下面是我在多个数据集上调过之后认为比较稳的默认起点适用于 COCO 类别的检测任务。参数建议值说明温度 T3~7T 越大类别分布越平滑暗知识越充分但 T 过大会放大背景噪声蒸馏权重 λ0.5超过 1.0 学生会过度拟合教师低于 0.1 基本无效果特征蒸馏权重 λ_feat0.2~0.5先小后大前期 focus 在 logits 蒸馏学习率 lr0.001比原始训练略低蒸馏本身能加速收敛优化器SGDAdam 在蒸馏场景下容易丢失精度Batch size尽量大蒸馏对 batch 的稳定性更敏感建议 32训练轮数原始训练的 60%~80%蒸馏加速收敛不需要训满 300 epoch学习率是这里最反直觉的一个参数。我一开始按原始训练的习惯用 0.01结果训练 loss 震荡得非常厉害——因为 KL 散度对 logits 的尺度变化很敏感学习率太大导致学生的 logits 跳动幅度大蒸馏这部分 loss 根本稳定不下来。降到 0.001 之后整个训练就顺了。这里给一个调参思路如果你观察到训练早期蒸馏 loss 在下降但原始 yolo loss 在上升说明学习率太高学生模型被蒸馏 loss带偏了需要降 lr 或者降 λ。SGD 和 Adam 的选择也是实践里踩出来的。Adam 在普通 YOLOv5 训练上表现一般但蒸溜场景下问题更严重——它对 logits 的梯度响应不均衡容易让学生模型在蒸馏收敛后又跑偏。SGD momentum 0.937 是 YOLOv5 官方默认组合在蒸馏模式下表现更稳定。5. 避坑指南基于 YOLOv5 的知识蒸馏常见的 5 个翻车现场5.1 教师模型没冻结显存直接爆掉现象训练刚开始GPU 显存占用飙到接近满格但不报错只是训到第 10 个 batch 左右 OOM进程被杀。原因教师模型的参数没有冻结反向传播时系统要保存教师模型的所有激活值显存占用比学生模型还高。解决在加载教师模型后显式遍历所有参数把requires_grad都置为False同时在每个 batch 前向时用torch.no_grad()包住教师推理。做了这两步之后显存占用基本和学生单独训练差不多只多了教师 forward 的临时缓存。提示检查冻结是否生效的一个小技巧是打印教师模型参数梯度的总数如果torch.nn.utils.parameters_to_vector(teacher.parameters()).grad不为 None说明还有参数没冻结。5.2 温度设太高学生学到了背景噪声现象训练 loss 降得很好但验证集 mAP 不升反降而且降的主要是 recall。原因温度 T 设到了 10 以上softmax 输出被拉得太平教师对背景类通常是 80 个类别里的第 0 类给出的微小 logits 也被放大成了有效信号学生疯狂拟合这些噪声反而忽略了真实目标类别之间的区分。解决把 T 拉回 3 到 5 的范围同时调整蒸馏 loss 只对前景类别的 logits 计算 KL 散度背景类的 logits 直接 mask 掉。我在代码里加了一个foreground_mask参数根据 ground truth 的 label 把背景位置过滤掉再算蒸馏 loss效果非常明显。5.3 小目标不蒸馏特征对齐后小目标检测反而变差现象蒸馏后整体 mAP 涨了但小目标面积小于 32x32 像素的 AP 掉了 2 个点以上。原因YOLOv5 的三个预测尺度对应下采样 8 倍、16 倍、32 倍的特征图小目标主要由下采样 8 倍的大特征图负责。但大特征图包含大量背景纹理信息蒸馏时教师和学生在这些位置的特征差异大loss 权重大模型为了拟合教师特征把更多容量花在了背景纹理上反而挤占了对小目标的学习。解决在特征蒸馏时对不同尺度的特征图设置不同的权重下采样 8 倍的特征权重降低到 0.3下采样 32 倍的高层语义特征权重提到 0.7。这样学生模型不会把注意力全放在低层纹理上小目标精度能保住。5.4 评测指标没对齐mAP 涨了但 PR 曲线崩了现象mAP 从 0.72 涨到 0.76很兴奋但换了测试集之后精度暴跌泛化变差了。原因蒸馏让学生的输出分布向教师靠拢而教师的预测置信度普遍偏高学生学到的不仅是怎么检测还有多自信。如果只对比 mAP 一个指标看到的是整体提升但 PR 曲线其实变得陡峭了——高置信度区域的 precision 上去了低置信度区域的 recall 掉了。解决评测时一定要同时看 mAP0.5 和 mAP0.5:0.95 两组指标这两者的差值如果超过 8 个点说明模型过拟合了教师的置信度分布。我还会额外跑一次 TTATest Time Augmentation做对照蒸馏后的模型 TTA 提升幅度应该和原始模型差不多如果提升异常大说明模型本身的判别力不足只是学到了教师的自信感。5.5 多卡训练的同步问题DDP 下蒸馏 loss 不一致现象使用torch.distributed跑多卡训练每张卡的 loss 都不一样而且差异不是随机噪声是肉眼可见的系统性偏差。原因DDP 模式下每张卡独立前向教师模型但 BatchNorm 的 running mean 是在每张卡上独立更新的如果不做同步教师模型在每张卡上的特征分布会逐渐偏离。带 BatchNorm 的 YOLOv5 教师模型在没有同步 BN 的情况下不同卡输出的 teacher logits 都不一样。解决在 DDP 初始化里加上sync_bnTrue把教师的 BatchNorm 层同步。但要注意YOLOv5 的模型结构里有些 BN 层的 num_features 比较大同步 BN 会额外增加通信开销训练速度会降 5% 左右这是值得付的代价。6. 蒸馏效果验证与进阶玩法怎么确认这套源码真的有用6.1 蒸馏前后的同权重评测脚本排除变量干扰很多人在蒸馏之后直接用 YOLOv5 官方的val.py跑一遍 mAP 就下结论说涨了多少这个流程有漏洞。因为你可能改了训练超参数、数据增强、训练轮数甚至换了优化器mAP 的提升可能来自这些改动而不全是蒸馏的功劳。我一般用一个独立的评测脚本把教师、学生、蒸馏后学生三个模型放在同一个评测配置下跑一模一样的验证集然后打印对比表。# 教师模型基准 python val.py --data coco.yaml --weights teacher.pt --img 640 --task val # 学生模型直接训练的基准 python val.py --data coco.yaml --weights student_baseline.pt --img 640 --task val # 学生模型蒸馏后的结果 python val.py --data coco.yaml --weights student_distilled.pt --img 640 --task val评测结果记录三个数mAP0.5、mAP0.5:0.95、推理耗时。推理耗时要在同一个设备上测最好固定 batch size前 50 次 warmup 之后取平均。这个对比表能回答三个问题蒸馏到底涨了多少、涨的点值不值得付训练时间成本、学生蒸馏后和教师的差距还有多大。6.2 把蒸馏和剪枝、量化串起来蒸馏是前端不是终点知识蒸馏不是说做完就完了它最大的价值是给后续的模型压缩铺路。我常用的链路是蒸馏 → 剪枝 → 量化。蒸馏先把学生模型的精度拉上去相当于给模型挖了一层额外储备然后做结构剪枝把一些响应值低的通道剪掉精度会掉但蒸馏带来的储备正好弥补这部分的损失最后做 INT8 量化精度还会再掉一点蒸馏储备还能再兜一程。这条链路里蒸馏的位置特别讲究它必须放在剪枝之前不能放在剪枝之后。因为剪枝后的模型结构已经不完整了再去对齐教师的特征图会出现结构不匹配的问题。我做过一次顺序颠倒的试验先剪枝再蒸馏效果很差——剪枝后的通道数和教师对不上只能做 logits 蒸馏特征蒸馏完全没法用最后精度比先蒸馏再剪枝低了 3 个点。6.3 训练日志的可视化蒸馏 loss 应该在哪个范围判断蒸馏是否正常不能只看 loss 曲线形态还要看具体数值范围。我总结了一个经验蒸馏 loss 占总 loss 的比例如果在 10% 到 30% 之间说明蒸馏的作用是辅助修正而不是主导训练这是健康的状态。如果蒸馏 loss 占比超过 50%学生模型基本是被教师摁着学它会丧失从 ground truth 学习新信息的能力。# 在训练循环里记录蒸馏loss占比 distill_ratio loss_distill.item() / loss.item() if batch_idx % 10 0: logger.info(fDistill ratio: {distill_ratio:.3f}, total loss: {loss.item():.3f})如果发现 distill_ratio 持续高于 0.5就把 λ_distill 往下调或者提高 batch size 让原始 loss 更稳定。如果 distill_ratio 低于 0.05说明蒸馏已经不起作用了可以停掉蒸馏直接用学生模型 finetune 到最后。用 tensorboard 记录 loss 曲线时记得同时记录 distill_ratio 这个标量它比单独的 loss 曲线更能反映蒸馏的训练状态。最后说一个习惯我跑蒸馏项目至今最有效的经验不是调参技巧而是养成每改一个变量只动一个变量的强迫症心态。蒸馏涉及教师模型、温度、多个权重系数、学习率、数据增强任何两个变量同时变动结果出了问题你都分不清是谁导致的。有一次我把温度从 3 调到 5 的同时改小了 λ_feat结果 mAP 掉了 2 个点排查了半天才定位到是 λ_feat 改动的影响温度根本没造成问题。从那以后我每次只改一个参数跑完一组对比再动下一个。这套基于 YOLOv5 的知识蒸馏实战源码本身不复杂复杂的是你对待实验变量的态度希望帮到你。本文还有配套的精品资源点击获取