简介：面向目标检测模型轻量化与知识蒸馏研究需求，这份YOLOv8知识蒸馏源码整合了在线蒸馏、logit蒸馏、mimic特征蒸馏、cwd与mgd等多种主流蒸馏方案。代码结构清晰、注释细致，适合希望在不大幅增加推理成本的前提下提升轻量模型精度的开发者参考，也便于初学者按注释逐步理解蒸馏实现原理。包内共1088个文件，压缩包约294.63MB，以Python源码、Markdown说明文档、yaml配置、训练日志、图表等为主，并包含少量预训练权重与TensorBoard事件文件，方便对照运行记录分析训练趋势。目前已有2940人学习下载。相比只提供单一蒸馏分支的仓库，该项目将多种机制统一到易读框架中，并配有过程解读。读者可对比logit与特征蒸馏的差异，直接复用cwd、mgd模块完成自定义实验，也可借助文档快速定位关键代码，适合作为算法研究与工程落地的参考工具。 做目标检测的同学应该都有过这种体会：模型训练完，mAP挺好看，一提到部署就头疼。尤其当你手头只有一块GTX 1660Ti，或者项目交付目标是RK3588、Orin Nano这类边缘设备时，yolov8m甚至yolov8l跑起来那个帧率，真能让人怀疑人生。换小模型吧，精度又肉眼可见地掉。我前阵子接手的一个项目就是这么个局面，最后是靠着给yolov8做知识蒸馏才把这事圆过去的。这篇文章就把我折腾yolov8知识蒸馏源码的完整过程、踩过的坑、调参心得一次性说清楚，给正在被模型压缩折磨的朋友一条能直接走的路。
1. 先说清楚：你的项目到底需不需要蒸馏
很多人一听“知识蒸馏”能涨点，就兴冲冲去跑源码，结果折腾一星期，精度没变化，反而怪蒸馏没用。其实蒸馏这件事，得先看你处在哪个阶段。
1.1 什么时候该上蒸馏，什么时候别折腾
我个人的判断标准很简单。如果模型还没有在目标数据集上过拟合，或者你的yolov8s本身就欠拟合、训练loss还没降下去，那蒸馏对你没有意义。蒸馏的本质是让student模型去模仿teacher模型的“软目标”，如果student连硬标签都还没学好，它根本没有能力去理解teacher输出的那些概率分布里的细微差异。
反过来，如果你的student模型单独训练已经能到一个不错的基线，但距离业务要求的精度还差一口气，或者你想把yolov8m的知识迁移到yolov8n上节省推理时间，那蒸馏就是性价比最高的方案。另一个典型场景是，数据集很小、标注质量一般，teacher模型见过足够的多样本，能提供比人工标注更平滑的监督信号——这时候蒸馏等于给student请了个“见过世面的私教”。
1.2 蒸馏前先做的两个验证
正式动源码之前，我建议你先花半天时间做两件事。
第一，把teacher模型（比如yolov8l）和student模型（比如yolov8s）在同一个验证集上的表现拉一个表格出来，确认teacher的mAP明显高于student。如果teacher和student精度本来就差不多，强行蒸馏只是自欺欺人。第二，跑通一次student的标准训练流程，把基线记录下来。没有基线，后面蒸馏是涨是跌你根本无法判断，全靠感觉调参等于盲人摸象。
2. 选对蒸馏形式和开源方案，比写代码重要
搞清楚了该不该用蒸馏，接下来才是技术选型。yolov8的知识蒸馏源码网上不少，但大多数方案质量参差不齐，用错了反而起副作用。
2.1 logit蒸馏、feature蒸馏、注意力蒸馏怎么选
当前对yolov8做蒸馏，主流有三条技术路线，我分别说下适用场景。
第一条是logit蒸馏，也就是Hinton那套经典方案，让student的输出概率分布去逼近teacher的输出概率分布，核心是用带温度T的softmax把分布“软化”。这套方案实现最简单，对检测头输出直接算KL散度就行，但它有个明显的局限——yolov8的输出不是单一的分类logits，而是多个尺度、每个尺度又带边框回归分支的解耦头，简单套一条蒸馏loss，信息传递效率不高。
第二条是feature蒸馏，让student的中间特征图去匹配teacher的中间特征图，这是目前yolov8蒸馏的主流做法。因为特征图里包含的空间信息、语义层次比最后那层logits丰富得多。常见实现有mimic、MGD（Masked Generative Distillation）、CWD（Channel-wise Distillation）等，其中CWD按通道做分布匹配，对检测任务效果比较稳，我后面会细说。
第三条是attention蒸馏，利用attention map作为蒸馏媒介，让student关注teacher关注的区域。这类方案可视化效果漂亮，但实际涨点往往不如feature蒸馏稳定，我建议你把注意力蒸馏当作辅助手段，而不是主方案。
2.2 自己改Ultralytics框架还是用现成蒸馏库
这里我必须强调一个判断：yolov8知识蒸馏源码，不建议直接去GitHub上拉一个看起来star很多的蒸馏项目就跑。因为Ultralytics的版本更新很快，v8.0到v8.2的代码结构变动不小，很多蒸馏项目还停留在老版本，拉下来很可能因为API变化直接报错。
我最终的做法，是在Ultralytics官方源码的基础上自己动手改，只改两个文件：一个是训练器trainer，负责加载teacher模型和并轨计算；另一个是损失函数loss，负责增加蒸馏loss的计算项。这样不管以后官方更新到哪个版本，只要核心改动逻辑清楚，手搓也能跟上。如果你实在不想自己改，可以看看MMDetection系里的蒸馏插件，但那边配置体系又是另一套，学习成本同样不低。
3. 环境搭建和Teacher模型准备：容易被忽视的细节
蒸馏的代码改动本身不大，环境却有不少坑，我在这上面浪费了两天时间，给你们提前排掉。
3.1 训练环境和蒸馏环境的配平
首先，teacher模型的推理不需要梯度，所以要挂torch.no_grad()，这在显存上能省出一大块。但很多蒸馏源码忘了做这件事，导致显存直接翻倍，1660Ti这种显卡一上来就OOM。这也是为什么网上有人抱怨蒸馏显存占用夸张——多半是没冻结teacher的梯度。
其次，teacher和student的预处理必须严格一致。yolov8的数据增强有三套逻辑：训练时的Mosaic、CopyPaste、随机仿射等，以及推理时的letterbox缩放。如果你在teacher前向时用了和student不一样的输入尺寸，或者teacher分支忘了做归一化，蒸馏loss直接失真。最稳妥的做法是：teacher和student共用同一个数据加载器、共用同一个预处理pipeline，只在forward的时候分叉。
3.2 Teacher权重的选择：不是越大越好
很多人一上来就选yolov8x做teacher，觉得越大知识越丰富。但teacher和student之间的能力差距如果过大，teacher输出的软标签分布过于尖锐，student根本学不动；而如果teacher训练不充分，它本身输出质量就很差，还会污染student的梯度。
我的经验是，当student是yolov8n/s的时候，选择yolov8m或yolov8l做teacher就够了，不需要上x。另外，选teacher权重时，一定要挑在验证集上表现最好的那个checkpoint，而不是最后一个epoch的权重。实践中最后几十个epoch经常会有波动，直接拿last.pt做teacher，蒸馏出来的student精度会打折扣。
4. yolov8蒸馏源码的核心逻辑拆解
下面进入正题。我基于Ultralytics的detect训练流程，把蒸馏的核心改动拆成三块：teacher推理的接入、蒸馏loss的计算、训练流程的控制。
4.1 Teacher前向与Student前向的并轨设计
熟悉yolov8源码的话，应该知道训练入口在train.py的trainer.py里，核心是_do_train方法。每一轮迭代，原本只跑一个student模型的前向。改蒸馏，最干净的做法是在BaseTrainer里挂一个teacher_model属性，然后在DetectTrainer的_do_train里先跑teacher的forward。
以我对yolov8模型的实践，核心代码示意如下：
# 在trainer的__init__里加载teacher if self.args.distill: self.teacher_model = YOLO(self.args.teacher_weights).model self.teacher_model.eval() # 冻结teacher，关闭梯度，显存友好 for p in self.teacher_model.parameters(): p.requires_grad = False # 在_do_train的batch循环里，student forward之后 with torch.no_grad(): teacher_preds = self.teacher_model(batch_img, augment=False)这里有个关键点：Ultralytics的模型forward会返回一个loss元组（如果你传了gt_labels），所以我建议你调用teacher时只传图像不传标签，拿到原始预测输出preds即可。还要注意，teacher和student的输入batch_img千万不要在同一个变量上去做两次不同的transform，必须保证进入两个网络的图像张量完全一致。
4.2 Loss计算：蒸馏项和原损失怎么融合
yolov8的损失分为box_loss、cls_loss和dfl_loss三部分，在蒸馏时，主流做法是保留原有的三个损失，另外接一个蒸馏损失项，用权重系数平衡。我最终采用的方案是：
# distill loss 计算 def distillation_loss(student_preds, teacher_preds, temperature=4.0, alpha=0.3): # 以sigmoid分布做KL散度，等价于logit蒸馏 loss_kd = 0.0 for s_feat, t_feat in zip(student_preds, teacher_preds): s_logits = s_feat / temperature t_logits = t_feat / temperature # 这里省略了对齐shape的reshape操作 loss_kd += F.kl_div( F.log_softmax(s_logits, dim=1), F.softmax(t_logits, dim=1), reduction='batchmean' ) * (temperature ** 2) return loss_kd但在实际项目中，我发现对yolov8的decoupled head，光做logit蒸馏，student学到的主要是分类头的“软化分布”，对回归头的帮助很有限。所以我在第二阶段加了一个基于CWD的feature对齐损失，从backbone的某一层（通常是第4、6、8层）取特征图做通道维度的softmax，再做KL散度。这里有一个血泪教训：teacher和student的通道数通常不一样，直接用原特征图做loss会shape mismatch，必须先用一个1x1卷积或线性投影把student的通道数对齐到teacher，这个align模块本身可以跟着训练一起学，不用单独预训练。
4.3 Trainer里最容易被忽略的EMA和BatchNorm
yolov8框架默认使用EMA（指数移动平均）来平滑模型权重。蒸馏场景下，teacher本身是M个连续epoch的软集成，如果再叠加student自己的EMA，收敛会更稳，但你必须在每个epoch结束后把teacher也做一次ema更新，或者干脆固定teacher不动。我的经验是：offline蒸馏（即teacher完全冻结）是最省事也最稳的，不需要管teacher的BN统计量更新问题。
还有BatchNorm，这个更坑。yolov8默认的BN在训练时是计算batch内统计量的，但如果teacher被设置为eval模式，它内部BN会切换到running_mean/running_var。这本来没问题，问题在于：很多人加载teacher权重后，忘记调用model.eval()，导致teacher的BN仍然用batch统计量，而teacher输出又是在torch.no_grad()下计算的——training模式下的BN更新跑到一半又被冻住，统计量错乱，蒸馏出来的soft label质量极其不稳定。所以我建议你写一行断言：assert not self.teacher_model.training，从机制上堵死这个坑。
5. 训练节奏与超参调节：把T和alpha调对，效果立竿见影
蒸馏的超参数比模型结构更影响最终精度。我调试过程中把温度T和蒸馏权重alpha从默认值换到最优组合之后，mAP上升了一个多点。
5.1 温度T的物理含义和设定经验
温度T控制softmax分布的平滑程度，T越大，teacher给出的标签越“软”，student能学到的类间相似关系越多，但信息也越模糊；T太小则退化成one-hot，和直接用真实标签区别不大。对yolov8的检测头来说，分类分支的logits数值通常在几个到十几个的量级，我实测T=4到T=6之间比较稳，低于2基本没效果，高于10容易把背景类和小目标的信号稀释掉。
5.2 蒸馏权重alpha和损失项的增长策略
很多蒸馏源码上来就用一个固定的alpha乘以loss_kd，跟原始损失相加。但检测任务的原始loss本身就包含box和dfl的回归项，如果alpha设得太大，student会过分关注模仿teacher的输出分布，忽略对真实框的回归。我的做法是采用推土机式增长：
# warmup 5个epoch，alpha从0线性涨到0.5 if epoch < warmup_epochs: alpha = 0.5 * (epoch / warmup_epochs) else: alpha = 0.5为什么要这样？因为前几个epoch里student的检测头输出还是乱的，让它去匹配teacher的分布，等于一个刚学走路的孩子去模仿百米运动员的动作，反而把基础步伐带偏。等到student对目标位置有了基本感知，再逐步提高模仿力度，它才有能力吸收teacher特征里的优越信息。
5.3 一份可以抄作业的训练配置
我最终跑通的一套配置是这样的：
- Teacher：yolov8l，输入分辨率640，mAP约59.2
- Student：yolov8s，输入分辨率640，单独训练mAP约53.4
- 蒸馏方式：logit蒸馏 + 在backbone第6层加CWD特征蒸馏
- 温度T：4.0
- 蒸馏权重alpha：0.5（5个epoch线性warmup到0.5）
- 优化器：SGD，momentum 0.937，weight_decay 0.0005
- 学习率：初始0.01，采用cosine退火，batch_size=16
- 训练总epoch：80，前10个epoch只用原始损失，防止扰动
这套配置跑完，student的mAP涨到55.8，相比单独训练的53.4涨了2.4个点，已经接进yolov8m的水平，但推理速度还是yolov8s的速度。另外我还对比过直接拿yolov8l的权重做微调（fine-tune）代替蒸馏，发现两者的差异在于：微调后的student在原始数据集上精度更高，但在一个我临时测的新场景下，蒸馏模型泛化明显更好，这应该是soft label保留了类间相似关系带来的好处。
6. 实测定点：GTX 1660Ti和边缘设备上的显存与部署体会
蒸馏毕竟是要多跑一个teacher前向的，硬件资源是个绕不开的现实问题，我这部分给大家交个底。
6.1 显存占用实测与batch_size取舍
我手上正好有一块GTX 1660Ti，6GB显存。单独训练yolov8s时，batch_size=16勉强够用，开了蒸馏加teacher（yolov8l，冻结梯度）之后，显存占用直接往5.5GB走。如果你还想开Mosaic增强，那就得降batch_size。
实测下来一个可参考的组合是：yolov8s student + yolov8l teacher，batch_size=8，梯度累积4步，显存占用稳定在4.3GB左右。这里有个细节，梯度累积虽然等效增大了batch，但对BN统计量无效，因为BN是逐batch算的。所以如果业务数据场景比较多样，我宁可把输入分辨率降到512来保batch_size，也不要开梯度累积硬扛——BN统计量会变差，蒸馏出来的模型精度也会波动。
6.2 蒸馏完部署到RK3588/Orin Nano的两个注意点
蒸馏的最终目的，大多数时候就是上边缘设备。我在RK3588上部署蒸馏后模型时发现，蒸馏对INT8量化的友好度比单独训练的模型好很多。这很好理解：蒸馏让student的输出分布更平滑，权重分布也更集中，量化时的信息损失更小。所以在RK3588上我用INT8量化后，mAP只掉了1.1个点，而单独训练模型直接掉2.8个点，这个差距在边缘设备上是质变的。
还有一个点是，蒸馏后的模型在导出ONNX时，不要导出训练时额外加的align层或feature蒸馏分支。我建议你对student单独做一次权重提取，只保留backbone和head，再用Ultralytics的export脚本导出。不然ONNX模型里会残留一个无用的输入输出节点，轻则增加转换报错风险，重则拖慢推理速度。
7. 踩坑记录：蒸馏效果反而变差的四类原因
这部分是全文最值钱的地方。我在调yolov8蒸馏源码的过程中，遇到过蒸馏后精度还不如不蒸馏的情况，排查下来基本就是下面四个原因。
第一个坑是teacher和student的数据增强不一致。我前面提过，两者必须共用同一个pipeline，但有些改法是在forward里单独对图像做缩放，导致teacher和student看到的图片几何内容不同，蒸馏loss学到的全是噪声。
第二个坑是标签分配器打架。yolov6和v8的anchor-free分支里，teacher和student各自有匹配逻辑。student在训练初期匹配到的正样本和teacher倾向的样本不完全一致。如果你直接把teacher的输出作为student的回归目标，student会一直左右摇摆。我的对策是蒸馏早期在前向计算student自己的loss时，仍然使用student自己匹配出来的正样本，只在蒸馏loss里对全特征图计算分布匹配，而不是硬套teacher的匹配结果。
第三个坑是同步BatchNorm引起的隐藏依赖。很多人在trainer里只把teacher冻结了，却没有把teacher的BN层也冻结，结果teacher在eval模式下反复被forward，BN的running_statistics被污染。我在3.1节提过这个坑，这里再强调一遍，这可能是你蒸馏莫名变差的头号元凶。
第四个坑是用了过高的学习率去微调student。蒸馏任务中student的梯度方向是原始损失和蒸馏损失的加权组合，如果你还用单独训练时的初始学习率0.01，很容易在前几个epoch就把特征空间冲乱。我换成0.005之后，loss曲线就明显稳定了。
8. 如果你用的是yolov8-seg或yolov8-pose，蒸馏还要多改两处
最后再提一个很多人没注意到的点。热词里有人搜“运动的物体经过摄像头只识别一次yolov8 seg”，说明现在不少项目是yolov8分割或姿态任务。这类任务的蒸馏，除了检测头之外，还要在mask分支或keypoint分支额外加对齐loss。
我做过一次yolov8n-seg追赶yolov8m-seg的蒸馏，核心是在分割分支上加了pixel-wise的KL散度，但尺度问题很头大——mask feature的空间尺寸在不同层不一样，必须显式地对齐到同一分辨率。我的做法是取teacher的mask分支倒数第二层的特征图，和student对应层做多尺度平均池化对齐，然后计算逐像素的L2 loss。对于pose任务，我对heatmap的蒸馏方式和CWD类似，但要注意每个关键点的heatmap尺度差异非常大，建议按通道分别做softmax再算KL，别把所有通道拉通算。
这套思路跑下来，yolov8n-seg的mAP从43.6涨到46.1，关键点任务PCK涨了2个百分点，效果还是很理想的。所以如果你做的不是纯检测，而是seg或pose，只要掌握了上面这些核心逻辑，往自己的分支上加loss并不难。
从我个人的实操经验来说，yolov8知识蒸馏源码的真正难点不在“加一个loss”，而在于搞清楚teacher在什么时候输出什么、student在什么时候该学什么、硬件资源在哪个尺度上能承受什么。把这三个问题想清楚，剩下的就是对代码的机械修改和耐心调参了。
本文还有配套的精品资源，点击获取
