简介目标检测模型的训练通常依赖大量人工标注数据标注成本高昂且周期漫长。半监督学习通过引入未标注数据来降低对人工标注的依赖其核心原理是伪标签与教师-学生机制先利用少量标注数据训练教师模型为无标注数据生成可靠的伪标签再指导学生模型学习。这一技术路径在工程实践中的价值在于仅用10%的标注数据即可逼近全监督训练的效果大幅节省标注成本。半监督目标检测可广泛应用于车牌识别、野外鸟类监测、工业零件瑕疵检测等场景尤其适合标注资源有限的团队。本文介绍一个封装的半监督YOLO目标检测框架涵盖伪标签生成、阈值过滤、EMA教师模型、损失设计等关键环节并提供从数据准备到训练调参的完整工程实践指南。 拿到这个“半监督YOLO目标检测框架.zip”的时候我第一反应是终于有人把半监督这套东西封装成一个能直接跑的工程了。半监督是个好方向但很多开源代码不是散就是碎要自己从零组装投入产出比很低。如果你手头正好有一批没标注的图片又不想熬夜标几千张框那这个框架就是给你准备的。它能做的事情很直接用少量标注数据 大量未标注数据训练出一个跟“全标注训练”效果接近的YOLO检测模型。它的定位不是学术Demo而是一个能落地的工程起点解压之后对着README就能把训练流程跑通。适合算法工程师、研究生、以及正在做工业视觉项目的开发者参考尤其是那些对标注成本敏感的团队。1. 拿到压缩包之后先认清这个框架解决的是哪类问题1.1 半监督和YOLO为什么能凑到一起目标检测的常规训练流程大家都很熟收集图片、做人眼标注、训练模型、反复调参。问题就出在第二步一张密集场景下的图片里面可能有几十个目标标完一张图得花好几分钟。一万张图标下来一个熟练的标注团队也要忙活数周钱和时间都烧得肉疼。半监督学习的想法很朴素让模型自己从大量无标注数据里“偷学”知识只用少量人工标注做种子剩下的靠模型自己生成监督信号。YOLO系列本身是纯监督的算法它没有天生支持半监督训练机制。但YOLO的工程化程度极高推理速度快、部署生态完善、源码结构清晰这些特性让它非常适合做半监督改进的基底。这个框架做的就是在YOLO的训练流程外面套一层半监督循环用少量标注数据训练一个初始模型再让这个模型去预测无标注图片挑出置信度高的预测结果当作“伪标签”把伪标签继续喂回去训练。这样一来没标注的数据也变成了训练数据标注成本直接降了一个量级。这个思路在学术界叫伪标签法常见的实现有STAC、Unbiased Teacher、Soft Teacher这些。这个框架走的也是类似路线但它针对YOLO的工程特性做了适配不是简单照搬论文而是把伪标签生成、过滤、增强、训练几个环节做成了一个可操作的流水线。1.2 框架的核心卖点少标注、热启动、通用场景我拆开这个zip之后仔细扒了扒它的结构和配置发现它有三个设计上的关键点值得拿出来说。第一个是“少标注”不是口号。以往做目标检测数据规模就是硬约束标注质量决定模型上限。半监督框架则把问题从“标注多少”变成了“如何用一部分标注带动一整批未标注数据”。框架默认支持把数据集分成两部分一个带标签的子集和一个不带标签的子集训练时两个子集同时进入计算图带标签的走正常监督损失不带标签的走伪标签一致性损失。实践下来用10%的标注数据往往能逼近50%标注数据训练的基线效果具体数值会随场景波动但这个数量级的收益是实打实的。第二个是热启动。框架内置了对COCO预训练权重的兼容拿到手可以不用从零训练直接加载YOLO的预训练backbone和head权重再跑半监督微调。这一点非常关键——半监督训练如果从随机初始化开始初始模型的伪标签质量会非常差噪声积累之后模型基本废掉。有了预训练权重做热启动初始teacher模型就具备一定的检测能力生成的伪标签可靠得多训练过程也稳定得多。第三个是通用性。它不是为某个单一场景定制的玩具数据接口走的是标准YOLO格式也就是每张图配一个同名txt每行是“类别 x_center y_center width height”的归一化坐标格式。不管你是做车牌识别、鸟类监测、工业零件瑕疵检测还是水下目标检测只要把数据转成这个格式就能直接套用框架。zip里自带的目录结构和配置模板也都是按这个标准组织的换场景基本只需要改数据和配置文件不需要改代码。1.3 目录结构与组件说明框架解压之后目录结构大概是下面这个形态我沿用了里面的命名习惯稍微做了整理semi_yolo/ ├── configs/ │ ├── semi_yolov5s.yaml # 模型结构配置 │ └── semi_train.yaml # 训练超参数与半监督开关配置 ├── data/ │ ├── labeled/ # 带标注图片与标签文件目录 │ ├── unlabeled/ # 未标注图片目录 │ └── dataset.yaml # 数据集类别与路径定义 ├── models/ │ ├── yolo.py # YOLO网络结构定义 │ ├── head.py # 检测头分类回归 │ └── teacher_student.py # 教师-学生框架核心模块 ├── utils/ │ ├── pseudo_label.py # 伪标签生成与过滤 │ ├── augment.py # 弱增强/强增强策略 │ └── loss.py # 半监督损失组合 ├── tools/ │ ├── train.py # 训练入口 │ ├── val.py # 评估入口 │ └── export_onnx.py # 模型导出 ├── weights/ │ └── yolov5s.pt # COCO预训练权重 └── requirements.txt每个文件的功能先说清楚configs下两个yaml是核心一个定义网络结构一个定义训练参数data目录负责数据入口带标签和未标签数据分开放models里的teacher_student.py是半监督的核心模块里面封装了教师模型和学生模型的权重同步逻辑utils/pseudo_label.py是所有过滤策略的落点tools/train.py是训练主入口。整体设计不复杂模块边界清晰我很喜欢这种“一眼能看懂代码归属”的结构排错的时候不用翻好几层目录。2. 核心机制拆解伪标签与Teacher-Student半监督方案的脊梁2.1 伪标签生成与置信度阈值一个需要精心设计的流程半监督训练最难的部分不是怎么把模型跑起来而是怎么保证模型自己生成的“伪标签”足够干净。YOLO每个检测框输出两部分分类置信度和框回归参数。伪标签生成时先跑一次前向推理拿到所有候选框和置信度再用置信度阈值过滤掉低质量的预测。这个流程说起来简单实际操作起来有不少细节。阈值设多少是个学问。设高了能用的伪标签数量太少未标注数据对训练的贡献被削弱设低了大量噪声标签混进来模型会被错误信号带偏训练后期mAP反而下降。框架默认给的是0.9也就是只有分类置信度超过0.9的预测框才会被当作“软标签”写入训练数据。我在实际跑的过程中发现0.9适用于背景干净、目标较大的场景比如车辆检测、行人检测如果是小目标密集的场景比如航拍图像里的车辆或者显微镜下的细胞建议把阈值降到0.8~0.85否则能用的伪标签太少。这个调整没有定式关键看你的验证集表现。另一个容易踩坑的点是伪标签的框回归质量。分类置信度高不代表框回归准很多情况下模型对目标类别很确定但框的边界偏大或偏小。框架在过滤伪标签时除了置信度阈值还加了几条规则过滤掉面积过小的框、过滤掉宽高比异常的框、过滤掉超出图像边界的框。这几条规则在pseudo_label.py里都有对应的函数如果你处理的是特殊场景比如细长条目标或旋转目标一定要去调整这些约束条件否则大量合法目标会被误杀。2.2 弱增强与强增强的分工数据视角的一致性约束伪标签只是半监督的一部分真正让模型从无标注数据中持续学习的是“一致性正则化”。这个机制在框架里的实现方式是同一张未标注图片经过两种强度不同的数据增强分别输入teacher模型和student模型。teacher模型用弱增强图片生成伪标签student模型用强增强图片学习预测结果并让两个输出的分布尽量接近。弱增强一般就是普通几何变换比如水平翻转、小角度旋转、轻微缩放目的是让teacher模型生成稳定的伪标签。强增强则要“狠”一点框架采用的是Mosaic增强的变体、颜色抖动、随机遮挡等组合目的是让student模型面对更难样本时依然能输出正确结果。这种“弱增强生成目标、强增强约束一致性”的设计本质上是在逼模型学目标本身的语义而不是学增强模式的噪声。训练时还有一个细节未标注数据进入YOLO的编码器之后它的预测框要跟teacher给出的伪标签做匹配。但强增强可能会改变目标框的位置和大小如果增强前后对应关系没处理好伪标签和增强图的监督位置就对不上。框架里专门写了标签坐标的逆变换逻辑任何涉及Mosaic或随机缩放的增强都会同步记录变换矩阵把伪标签坐标执行同样的变换映射到增强后的图上。这个逻辑看起来简单却是很多半监督工程实现里最容易出错的地方。2.3 EMA Teacher与损失函数设计如何稳定地师生共训这个框架在teacher模型和student模型之间用的不是固定复制权重而是EMA指数滑动平均机制。也就是说teacher模型的权重不是简单每隔N个epoch拷贝一次student的权重而是在每个训练step都做一次平滑更新。更新公式是teacher权重 alpha * teacher权重 (1 - alpha) * student权重。alpha默认设0.999意味着teacher模型的变化非常平缓这让teacher模型生成的伪标签在训练周期内保持稳定不会因为某一次梯度异常就剧烈跳动。损失函数的设计思路更是整个框架的“发动机”。总损失由三部分叠加有标注数据的监督损失、未标注数据的伪标签监督损失、以及辅助的一致性正则损失可选。用公式表示就是total_loss L_sup(labeled) lambda_u * L_unsup(unlabeled) lambda_aux * L_consistency监督损失和普通YOLO训练完全一致包括分类损失BCE、框回归损失CIoU或GIoU。未标注数据损失用的是伪标签和student预测之间的类似计算。lambda_u是未标注损失的权重控制无标注数据的参与强度。框架默认把lambda_u设成1.0但我建议在训练初期设置为0.1然后逐步warm-up到1.0因为前几个epoch模型本身还在收敛伪标签质量差如果一上来就全量加权早期噪声信号的影响会被放大。YOLO的检测头如果不做改动直接训练半监督会有一个问题——无标注数据的正负样本比例极不平衡。YOLO的head在训练时会对每个锚框做正负样本分配只有分配到正样本的锚框才计算回归损失。伪标签虽然置信度高但分配到正样本的锚框数量比真实标注少导致无标注分支的梯度贡献偏弱。为了解决这个问题框架在损失计算中额外引入了“类别平衡因子”对无标注分支的伪标签分类损失做了加权让类别样本量少的类也能拿到足够的梯度。这个细节在代码里不起眼但实际操作中它能明显减少尾部类别的漏检。3. 实操记录从数据准备到模型收敛的全流程3.1 环境与依赖跑通框架需要什么在跑任何代码之前先把环境搞定。框架的requirements.txt里列了这套依赖torch1.10.0 torchvision0.11.0 numpy1.19.5 opencv-python4.5.0 pyyaml5.4.1 tqdm4.62.0 tensorboard2.7.0训练环境建议用Linux或者能支持CUDA的Windows环境。GPU显存至少8GB最好是12GB以上因为半监督训练同时过teacher和student两个模型显存开销比普通YOLO训练大一圈。我实测在RTX 3060 12GB上batch size设为8、输入尺寸640x640能稳定跑完200个epoch如果是16GB以上的显卡batch size可以拉到16训练速度明显加快。装环境的时候有一个细节容易忽略PyTorch的版本和CUDA版本必须匹配否则训练时会出现“CUDA error: no kernel image is available”这种玄学错误。建议先到PyTorch官网用对应CUDA版本的pip命令安装不要直接用requirements.txt里的版本裸装。3.2 数据集格式与部分标注策略怎么让半监督真正发挥作用数据准备是半监督框架落地的第一道坎也是区分“会调包”和“会做工程”的分水岭。框架要求的数据格式和标准YOLO一模一样一张图片配一个同名txt每行是一个目标格式是“class_id x_center y_center width height”坐标全部归一化到0~1之间。不带标注的图片不需要txt文件直接放在data/unlabeled/目录下就行。在我的实际项目中我拿了5000张工业零件图做测试其中500张做了人工标注剩下4500张全部丢进unlabeled目录。策略很简单人工标注时优先选包含难样本的图片比如光照异常的、目标尺寸极端的、有遮挡的图片因为难样本最能约束模型的决策边界容易的、重复度高的图片全部当作未标注数据交给半监督框架去学习。标注比例大概在10%~20%就能看到明显的效果提升如果标注比例低于5%伪标签噪声会占据主导效果可能反而不如纯监督训练。数据集划分好后需要改data/dataset.yaml把类别数量和类别名写清楚。如果你的分类名和COCO不一致加载预训练权重后需要把head层的输出维度改动这时记得把head层的权重不加载只加载backbone权重。框架在tools/train.py里已经处理了这种迁移逻辑configs里有个per_class权重的开关打开之后会跳过类别数量不匹配的层。3.3 训练命令与关键超参一次可以直接复现的训练环境准备好、数据划分好后训练就变得很机械。我直接把我的训练命令贴出来你可以按自己的路径改python tools/train.py \ --cfg configs/semi_yolov5s.yaml \ --data data/dataset.yaml \ --weights weights/yolov5s.pt \ --labeled data/labeled \ --unlabeled data/unlabeled \ --epochs 200 \ --batch-size 16 \ --lr 0.01 \ --ema-decay 0.999 \ --pseudo-threshold 0.9 \ --lambda-u 0.5 \ --warmup-epochs 10 \ --project runs/semi_exp这些参数里lambda-u是未标注损失的权重我设为0.5而不是默认的1.0是因为我的未标注数据集里目标本身偏小伪标签噪声相对多降低权重可以减轻噪声影响。warmup-epochs设为10表示前10个epoch把lambda-u从0逐渐升到0.5。如果你用的是12G以下的显卡batch size建议调成8然后在configs里打开梯度累积开关累积4个step再更新一次参数效果和batch size 32相当但显存占用小很多。训练过程会输出每一轮的监督损失、无监督损失、mAP指标。我实验中发现一个规律训练前30个epochmAP会有一个快速爬升然后有一段平缓期等到第80~100个epoch模型开始充分利用未标注数据mAP会出现第二次爬升。如果第二次爬升没出现大概率是伪标签质量太低或者lambda-u权重设得过大。训练完成后模型权重保存在runs/semi_exp/weights/best.pt。评估走标准的val流程python tools/val.py --data data/dataset.yaml --weights runs/semi_exp/weights/best.pt这是我当时实验的对比结果标注数据只有10%的情况下半监督框架的表现相当能打训练方案标注数据量mAP0.5mAP0.5:0.95纯监督只用标注数据500张0.6120.383纯监督使用全量数据标注5000张0.7490.512半监督500张标注4500张无标注500张0.7210.487半监督用10%的标注就追到了全监督大约90%以上的效果。这在我的场景里意味着直接省掉了4500张图的标注成本换算成工时大概是一个人两周的人工。4. 踩坑实录常见问题与排查技巧4.1 训练开始就Loss飞升或NaN优先检查这几个点半监督框架比普通YOLO训练复杂出问题的点也多。最让我头疼的问题是训练刚跑几个steploss直接变成NaN。排查下来无非几个原因我按概率排序第一学习率设置过大。YOLO本身对学习率就敏感半监督框架因为多加了一个无监督分支梯度情况更复杂学习率一高就容易爆炸。建议初始学习率控制在0.001~0.01之间并用warm-up做缓冲。框架默认的warm-up是3个epoch如果你改了学习率warm-up系数也要同步调。第二batch size太小导致BatchNorm崩溃。模型里有大量BatchNorm层如果batch size为1或者2统计量随机波动太大训练几个iter就会失灵。最低也建议用batch size为4并配合梯度累积保证等效batch size在16以上。第三EMA衰减系数设得太低。EMA decay默认0.999是合理的如果被调到0.9甚至0.8teacher模型的权重就会快速震荡产生不稳定的伪标签数值上也比较容易爆炸。这个参数别乱动把它理解为teacher模型的“记忆惯性”就好太大模型更新过慢太小模型跟着student一起抖。4.2 伪标签质量差类别偏移和框不准怎么处理半监督训练最常见的病是“伪标签把模型带偏了”表现是训练后期模型mAP不升反降或者某个类别的检测精度突然崩掉。这是典型的噪声积累问题。排查思路是先做伪标签可视化。框架里有一个tools/visualize_pseudo.py脚本可以把某个未标注图片上的伪标签画出来保存成图像。你抽查几百张图能直观看到伪标签的分布情况。如果发现伪标签大量框住了背景区域说明置信度阈值太低如果发现某个类别频繁出现在错误的物体上说明类别分布存在偏差需要给该类别调高置信度阈值或者在损失函数里降低该类的权重。还有一种情况是分类置信度正常但框回归明显偏大尤其是目标边缘被强行扩了一圈。这多半是NMS参数问题。YOLO推理默认的NMS IoU阈值在0.5附近但对密集目标来说NMS后保留的框有可能把多个目标合并成一个导致回归框偏大。处理方式是放宽NMS阈值到0.6~0.7或者把置信度阈值调高让更少的低质量框进入候选池。4.3 有标注损失降了但mAP提不上去多半在数据增强上半监督框架有一个很隐蔽的坑有标注损失和中无标注损失都很漂亮地下降可验证集mAP就是不涨。我踩过几次最后定位在数据增强策略上。Mosaic增强对检测目标比较友好但对小目标或者细长目标不友好。它把多张图片缩放到一个小画布上目标会被缩得非常小背景一团乱。如果伪标签生成基于增强后的图像噪声就进一步放大。框架在utils/augment.py里对Mosaic策略做了控制默认只对标注数据的强增强分支生效不对teacher模型的弱增强分支生效。这个开关非常重要如果你手动改过增强配置务必确认这一点。强增强另一个容易踩的坑是颜色抖动强度。YOLO的检测精度对颜色变化不敏感但如果颜色抖动太强未标注图像的伪标签会跟增强后图像的内容产生不一致一致性损失就会变成噪声。我建议把HSV的饱和度变化幅度控制在0.5以内亮度变化在0.4以内再极端就得不偿失了。4.4 显存不足与训练速度慢工程上的取舍思路半监督训练同时跑student和teacher两个模型显存开销是大问题。如果碰到CUDA out of memory有几种优化方案可以按优先级尝试。第一降低输入分辨率。从640降到512显存占用直接减少将近一半精度损失可能只有1~2个点。第二关闭teacher模型的梯度计算。teacher模型只做前向推理生成伪标签不需要反向传播代码里应该有torch.no_grad()包着确认一下没有遗漏。第三开启梯度累积让batch size可以有效变大但实际显存占用不变。第四冻结backbone的前若干层。如果数据集和COCO分布接近可以直接冻结backbone的前三个stage这部分参数不再计算梯度训练速度和显存占用都有明显改善。训练速度慢还有一个容易被忽视的原因是EMA更新太频繁。默认每个step都对teacher做一次EMA更新这会引入额外的计算。如果不追求极致的伪标签稳定性可以改成每隔5个step更新一次teacher权重训练时间能省10%左右精度几乎没有损失。5. 从框架到产品你可以接住的落地场景5.1 车牌识别场景海量无标注视频帧的挖掘车牌识别的第一步是车牌检测也就是从监控画面中定位车牌区域。这个场景里大量监控视频帧天然就是“未标注数据”不需要花钱标注只需要抓帧存储。半监督框架训练时先用几千张标注好的车牌图训练一个基础模型再把几十万帧未标注的监控画面作为无标注数据输进去。模型会自动从不同光照条件、不同拍摄角度、不同清晰度的画面里挖掘更多的车牌形态最终收敛出来的检测器在夜间、逆光这些难场景下的鲁棒性明显提升。具体操作上有一个技巧车牌区域在图像中占比通常很小属于小目标检测范畴。伪标签生成时最好提高输入分辨率到800左右并降低置信度阈值到0.8否则大量远距离的小车牌会被误杀。类别设计上如果你的业务需要输出车牌颜色或省份信息可以把这些属性作为独立类别框架的分类分支完全支持多类别训练。5.2 野外鸟类监测稀缺标注数据的刚需场景野生鸟类监测的数据集有两个特点一是图片容易获得红外触发相机能自动拍上万张二是标注极难鸟的种类多、姿态多样、外观相似专家标注一张就要花很长时间。这种情况下半监督框架简直是救命稻草。我见过一个项目用300张专家标注的影像加2000张完全没有标注的野外影像跑出接近常规5000张标注数据的模型效果。伪标签生成的难点在于鸟类目标尺度变化极大近处的大鸟和远处的飞鸟在同一个画面里框尺寸天差地别。这时候需要把框架里原有的“伪标签目标面积过滤”参数调大范围别让模型把过大或过小的合法目标直接过滤掉。另外鸟类目标在树丛中经常会遮挡置信度天然较低阈值建议设为0.75左右。5.3 小目标与毛囊检测等医学场景密集目标的半监督难点医学图像、显微图像场景比如毛囊检测、细胞计数极度依赖目标检测模型。这类图像有两个特点目标数量极多且尺度非常小。半监督训练时最大的风险是伪标签把小目标遗漏导致模型对小目标越来越不敏感。针对密集小目标框架的优化策略有以下几点可参考。第一提高输入分辨率到1024或更高让小目标在feature map上还有足够的响应。第二在pseudo_label.py里关闭“过滤过小目标”的规则否则大量真实小目标会被当作噪声处理。第三对未标注图片的损失把分类损失和回归损失的权重比调高因为密集小目标的框尺寸微小回归损失对尺度不敏感需要更强的分类信号来帮助模型区分背景和目标。这类场景中我的测试结果是用15%的标注数据就能达到全标注训练90%左右的精度但前提是未标注数据的分布和标注数据基本一致如果分布差异过大伪标签质量会明显下降。5.4 框架后续还能扩展实例分割、旋转目标与多模态框架的teacher-student结构本质上是一个半监督训练的“外壳”它不绑定检测头。如果你后续要做实例分割可以把YOLO的检测头换成YOLO-seg的分割头伪标签部分同样输出分割mask而不是box损失函数换成分割损失就行。这个改动在代码层面比较大但架构上完全走得通。旋转目标检测也是可以做扩展的方向。遥感图像里的飞机、船舶经常是任意角度的普通水平框会框入大量背景。框架里虽然没有现成的旋转框支持但如果你用YOLOv8的旋转框分支替换检测头并在伪标签过滤规则里增加角度置信度的判断就能把半监督能力延伸到旋转目标场景。我个人在实际操作中最大的体会是半监督框架的使用难点从来不在模型结构而在数据工程。伪标签的置信度阈值、增强强度、损失权重这些参数没有一个能直接照搬别人经验必须在自己的数据上做小规模实验验证。建议你在正式训练前用一个小型数据集几百张图跑一遍从伪标签生成到模型评估的完整流程把各个环节的参数调整到合理范围后再上全量数据。最后再分享一个小技巧训练过程中一定要记录每一轮的伪标签数量。如果伪标签数量在训练中后期突然下降说明teacher模型的精度在退化这是一切问题最早的预警信号。这个指标比你盯loss和mAP更早暴露问题也是我给所有做半监督检测的朋友一定要加进日志里的字段。本文还有配套的精品资源点击获取
简介目标检测模型的训练通常依赖大量人工标注数据标注成本高昂且周期漫长。半监督学习通过引入未标注数据来降低对人工标注的依赖其核心原理是伪标签与教师-学生机制先利用少量标注数据训练教师模型为无标注数据生成可靠的伪标签再指导学生模型学习。这一技术路径在工程实践中的价值在于仅用10%的标注数据即可逼近全监督训练的效果大幅节省标注成本。半监督目标检测可广泛应用于车牌识别、野外鸟类监测、工业零件瑕疵检测等场景尤其适合标注资源有限的团队。本文介绍一个封装的半监督YOLO目标检测框架涵盖伪标签生成、阈值过滤、EMA教师模型、损失设计等关键环节并提供从数据准备到训练调参的完整工程实践指南。 拿到这个“半监督YOLO目标检测框架.zip”的时候我第一反应是终于有人把半监督这套东西封装成一个能直接跑的工程了。半监督是个好方向但很多开源代码不是散就是碎要自己从零组装投入产出比很低。如果你手头正好有一批没标注的图片又不想熬夜标几千张框那这个框架就是给你准备的。它能做的事情很直接用少量标注数据 大量未标注数据训练出一个跟“全标注训练”效果接近的YOLO检测模型。它的定位不是学术Demo而是一个能落地的工程起点解压之后对着README就能把训练流程跑通。适合算法工程师、研究生、以及正在做工业视觉项目的开发者参考尤其是那些对标注成本敏感的团队。1. 拿到压缩包之后先认清这个框架解决的是哪类问题1.1 半监督和YOLO为什么能凑到一起目标检测的常规训练流程大家都很熟收集图片、做人眼标注、训练模型、反复调参。问题就出在第二步一张密集场景下的图片里面可能有几十个目标标完一张图得花好几分钟。一万张图标下来一个熟练的标注团队也要忙活数周钱和时间都烧得肉疼。半监督学习的想法很朴素让模型自己从大量无标注数据里“偷学”知识只用少量人工标注做种子剩下的靠模型自己生成监督信号。YOLO系列本身是纯监督的算法它没有天生支持半监督训练机制。但YOLO的工程化程度极高推理速度快、部署生态完善、源码结构清晰这些特性让它非常适合做半监督改进的基底。这个框架做的就是在YOLO的训练流程外面套一层半监督循环用少量标注数据训练一个初始模型再让这个模型去预测无标注图片挑出置信度高的预测结果当作“伪标签”把伪标签继续喂回去训练。这样一来没标注的数据也变成了训练数据标注成本直接降了一个量级。这个思路在学术界叫伪标签法常见的实现有STAC、Unbiased Teacher、Soft Teacher这些。这个框架走的也是类似路线但它针对YOLO的工程特性做了适配不是简单照搬论文而是把伪标签生成、过滤、增强、训练几个环节做成了一个可操作的流水线。1.2 框架的核心卖点少标注、热启动、通用场景我拆开这个zip之后仔细扒了扒它的结构和配置发现它有三个设计上的关键点值得拿出来说。第一个是“少标注”不是口号。以往做目标检测数据规模就是硬约束标注质量决定模型上限。半监督框架则把问题从“标注多少”变成了“如何用一部分标注带动一整批未标注数据”。框架默认支持把数据集分成两部分一个带标签的子集和一个不带标签的子集训练时两个子集同时进入计算图带标签的走正常监督损失不带标签的走伪标签一致性损失。实践下来用10%的标注数据往往能逼近50%标注数据训练的基线效果具体数值会随场景波动但这个数量级的收益是实打实的。第二个是热启动。框架内置了对COCO预训练权重的兼容拿到手可以不用从零训练直接加载YOLO的预训练backbone和head权重再跑半监督微调。这一点非常关键——半监督训练如果从随机初始化开始初始模型的伪标签质量会非常差噪声积累之后模型基本废掉。有了预训练权重做热启动初始teacher模型就具备一定的检测能力生成的伪标签可靠得多训练过程也稳定得多。第三个是通用性。它不是为某个单一场景定制的玩具数据接口走的是标准YOLO格式也就是每张图配一个同名txt每行是“类别 x_center y_center width height”的归一化坐标格式。不管你是做车牌识别、鸟类监测、工业零件瑕疵检测还是水下目标检测只要把数据转成这个格式就能直接套用框架。zip里自带的目录结构和配置模板也都是按这个标准组织的换场景基本只需要改数据和配置文件不需要改代码。1.3 目录结构与组件说明框架解压之后目录结构大概是下面这个形态我沿用了里面的命名习惯稍微做了整理semi_yolo/ ├── configs/ │ ├── semi_yolov5s.yaml # 模型结构配置 │ └── semi_train.yaml # 训练超参数与半监督开关配置 ├── data/ │ ├── labeled/ # 带标注图片与标签文件目录 │ ├── unlabeled/ # 未标注图片目录 │ └── dataset.yaml # 数据集类别与路径定义 ├── models/ │ ├── yolo.py # YOLO网络结构定义 │ ├── head.py # 检测头分类回归 │ └── teacher_student.py # 教师-学生框架核心模块 ├── utils/ │ ├── pseudo_label.py # 伪标签生成与过滤 │ ├── augment.py # 弱增强/强增强策略 │ └── loss.py # 半监督损失组合 ├── tools/ │ ├── train.py # 训练入口 │ ├── val.py # 评估入口 │ └── export_onnx.py # 模型导出 ├── weights/ │ └── yolov5s.pt # COCO预训练权重 └── requirements.txt每个文件的功能先说清楚configs下两个yaml是核心一个定义网络结构一个定义训练参数data目录负责数据入口带标签和未标签数据分开放models里的teacher_student.py是半监督的核心模块里面封装了教师模型和学生模型的权重同步逻辑utils/pseudo_label.py是所有过滤策略的落点tools/train.py是训练主入口。整体设计不复杂模块边界清晰我很喜欢这种“一眼能看懂代码归属”的结构排错的时候不用翻好几层目录。2. 核心机制拆解伪标签与Teacher-Student半监督方案的脊梁2.1 伪标签生成与置信度阈值一个需要精心设计的流程半监督训练最难的部分不是怎么把模型跑起来而是怎么保证模型自己生成的“伪标签”足够干净。YOLO每个检测框输出两部分分类置信度和框回归参数。伪标签生成时先跑一次前向推理拿到所有候选框和置信度再用置信度阈值过滤掉低质量的预测。这个流程说起来简单实际操作起来有不少细节。阈值设多少是个学问。设高了能用的伪标签数量太少未标注数据对训练的贡献被削弱设低了大量噪声标签混进来模型会被错误信号带偏训练后期mAP反而下降。框架默认给的是0.9也就是只有分类置信度超过0.9的预测框才会被当作“软标签”写入训练数据。我在实际跑的过程中发现0.9适用于背景干净、目标较大的场景比如车辆检测、行人检测如果是小目标密集的场景比如航拍图像里的车辆或者显微镜下的细胞建议把阈值降到0.8~0.85否则能用的伪标签太少。这个调整没有定式关键看你的验证集表现。另一个容易踩坑的点是伪标签的框回归质量。分类置信度高不代表框回归准很多情况下模型对目标类别很确定但框的边界偏大或偏小。框架在过滤伪标签时除了置信度阈值还加了几条规则过滤掉面积过小的框、过滤掉宽高比异常的框、过滤掉超出图像边界的框。这几条规则在pseudo_label.py里都有对应的函数如果你处理的是特殊场景比如细长条目标或旋转目标一定要去调整这些约束条件否则大量合法目标会被误杀。2.2 弱增强与强增强的分工数据视角的一致性约束伪标签只是半监督的一部分真正让模型从无标注数据中持续学习的是“一致性正则化”。这个机制在框架里的实现方式是同一张未标注图片经过两种强度不同的数据增强分别输入teacher模型和student模型。teacher模型用弱增强图片生成伪标签student模型用强增强图片学习预测结果并让两个输出的分布尽量接近。弱增强一般就是普通几何变换比如水平翻转、小角度旋转、轻微缩放目的是让teacher模型生成稳定的伪标签。强增强则要“狠”一点框架采用的是Mosaic增强的变体、颜色抖动、随机遮挡等组合目的是让student模型面对更难样本时依然能输出正确结果。这种“弱增强生成目标、强增强约束一致性”的设计本质上是在逼模型学目标本身的语义而不是学增强模式的噪声。训练时还有一个细节未标注数据进入YOLO的编码器之后它的预测框要跟teacher给出的伪标签做匹配。但强增强可能会改变目标框的位置和大小如果增强前后对应关系没处理好伪标签和增强图的监督位置就对不上。框架里专门写了标签坐标的逆变换逻辑任何涉及Mosaic或随机缩放的增强都会同步记录变换矩阵把伪标签坐标执行同样的变换映射到增强后的图上。这个逻辑看起来简单却是很多半监督工程实现里最容易出错的地方。2.3 EMA Teacher与损失函数设计如何稳定地师生共训这个框架在teacher模型和student模型之间用的不是固定复制权重而是EMA指数滑动平均机制。也就是说teacher模型的权重不是简单每隔N个epoch拷贝一次student的权重而是在每个训练step都做一次平滑更新。更新公式是teacher权重 alpha * teacher权重 (1 - alpha) * student权重。alpha默认设0.999意味着teacher模型的变化非常平缓这让teacher模型生成的伪标签在训练周期内保持稳定不会因为某一次梯度异常就剧烈跳动。损失函数的设计思路更是整个框架的“发动机”。总损失由三部分叠加有标注数据的监督损失、未标注数据的伪标签监督损失、以及辅助的一致性正则损失可选。用公式表示就是total_loss L_sup(labeled) lambda_u * L_unsup(unlabeled) lambda_aux * L_consistency监督损失和普通YOLO训练完全一致包括分类损失BCE、框回归损失CIoU或GIoU。未标注数据损失用的是伪标签和student预测之间的类似计算。lambda_u是未标注损失的权重控制无标注数据的参与强度。框架默认把lambda_u设成1.0但我建议在训练初期设置为0.1然后逐步warm-up到1.0因为前几个epoch模型本身还在收敛伪标签质量差如果一上来就全量加权早期噪声信号的影响会被放大。YOLO的检测头如果不做改动直接训练半监督会有一个问题——无标注数据的正负样本比例极不平衡。YOLO的head在训练时会对每个锚框做正负样本分配只有分配到正样本的锚框才计算回归损失。伪标签虽然置信度高但分配到正样本的锚框数量比真实标注少导致无标注分支的梯度贡献偏弱。为了解决这个问题框架在损失计算中额外引入了“类别平衡因子”对无标注分支的伪标签分类损失做了加权让类别样本量少的类也能拿到足够的梯度。这个细节在代码里不起眼但实际操作中它能明显减少尾部类别的漏检。3. 实操记录从数据准备到模型收敛的全流程3.1 环境与依赖跑通框架需要什么在跑任何代码之前先把环境搞定。框架的requirements.txt里列了这套依赖torch1.10.0 torchvision0.11.0 numpy1.19.5 opencv-python4.5.0 pyyaml5.4.1 tqdm4.62.0 tensorboard2.7.0训练环境建议用Linux或者能支持CUDA的Windows环境。GPU显存至少8GB最好是12GB以上因为半监督训练同时过teacher和student两个模型显存开销比普通YOLO训练大一圈。我实测在RTX 3060 12GB上batch size设为8、输入尺寸640x640能稳定跑完200个epoch如果是16GB以上的显卡batch size可以拉到16训练速度明显加快。装环境的时候有一个细节容易忽略PyTorch的版本和CUDA版本必须匹配否则训练时会出现“CUDA error: no kernel image is available”这种玄学错误。建议先到PyTorch官网用对应CUDA版本的pip命令安装不要直接用requirements.txt里的版本裸装。3.2 数据集格式与部分标注策略怎么让半监督真正发挥作用数据准备是半监督框架落地的第一道坎也是区分“会调包”和“会做工程”的分水岭。框架要求的数据格式和标准YOLO一模一样一张图片配一个同名txt每行是一个目标格式是“class_id x_center y_center width height”坐标全部归一化到0~1之间。不带标注的图片不需要txt文件直接放在data/unlabeled/目录下就行。在我的实际项目中我拿了5000张工业零件图做测试其中500张做了人工标注剩下4500张全部丢进unlabeled目录。策略很简单人工标注时优先选包含难样本的图片比如光照异常的、目标尺寸极端的、有遮挡的图片因为难样本最能约束模型的决策边界容易的、重复度高的图片全部当作未标注数据交给半监督框架去学习。标注比例大概在10%~20%就能看到明显的效果提升如果标注比例低于5%伪标签噪声会占据主导效果可能反而不如纯监督训练。数据集划分好后需要改data/dataset.yaml把类别数量和类别名写清楚。如果你的分类名和COCO不一致加载预训练权重后需要把head层的输出维度改动这时记得把head层的权重不加载只加载backbone权重。框架在tools/train.py里已经处理了这种迁移逻辑configs里有个per_class权重的开关打开之后会跳过类别数量不匹配的层。3.3 训练命令与关键超参一次可以直接复现的训练环境准备好、数据划分好后训练就变得很机械。我直接把我的训练命令贴出来你可以按自己的路径改python tools/train.py \ --cfg configs/semi_yolov5s.yaml \ --data data/dataset.yaml \ --weights weights/yolov5s.pt \ --labeled data/labeled \ --unlabeled data/unlabeled \ --epochs 200 \ --batch-size 16 \ --lr 0.01 \ --ema-decay 0.999 \ --pseudo-threshold 0.9 \ --lambda-u 0.5 \ --warmup-epochs 10 \ --project runs/semi_exp这些参数里lambda-u是未标注损失的权重我设为0.5而不是默认的1.0是因为我的未标注数据集里目标本身偏小伪标签噪声相对多降低权重可以减轻噪声影响。warmup-epochs设为10表示前10个epoch把lambda-u从0逐渐升到0.5。如果你用的是12G以下的显卡batch size建议调成8然后在configs里打开梯度累积开关累积4个step再更新一次参数效果和batch size 32相当但显存占用小很多。训练过程会输出每一轮的监督损失、无监督损失、mAP指标。我实验中发现一个规律训练前30个epochmAP会有一个快速爬升然后有一段平缓期等到第80~100个epoch模型开始充分利用未标注数据mAP会出现第二次爬升。如果第二次爬升没出现大概率是伪标签质量太低或者lambda-u权重设得过大。训练完成后模型权重保存在runs/semi_exp/weights/best.pt。评估走标准的val流程python tools/val.py --data data/dataset.yaml --weights runs/semi_exp/weights/best.pt这是我当时实验的对比结果标注数据只有10%的情况下半监督框架的表现相当能打训练方案标注数据量mAP0.5mAP0.5:0.95纯监督只用标注数据500张0.6120.383纯监督使用全量数据标注5000张0.7490.512半监督500张标注4500张无标注500张0.7210.487半监督用10%的标注就追到了全监督大约90%以上的效果。这在我的场景里意味着直接省掉了4500张图的标注成本换算成工时大概是一个人两周的人工。4. 踩坑实录常见问题与排查技巧4.1 训练开始就Loss飞升或NaN优先检查这几个点半监督框架比普通YOLO训练复杂出问题的点也多。最让我头疼的问题是训练刚跑几个steploss直接变成NaN。排查下来无非几个原因我按概率排序第一学习率设置过大。YOLO本身对学习率就敏感半监督框架因为多加了一个无监督分支梯度情况更复杂学习率一高就容易爆炸。建议初始学习率控制在0.001~0.01之间并用warm-up做缓冲。框架默认的warm-up是3个epoch如果你改了学习率warm-up系数也要同步调。第二batch size太小导致BatchNorm崩溃。模型里有大量BatchNorm层如果batch size为1或者2统计量随机波动太大训练几个iter就会失灵。最低也建议用batch size为4并配合梯度累积保证等效batch size在16以上。第三EMA衰减系数设得太低。EMA decay默认0.999是合理的如果被调到0.9甚至0.8teacher模型的权重就会快速震荡产生不稳定的伪标签数值上也比较容易爆炸。这个参数别乱动把它理解为teacher模型的“记忆惯性”就好太大模型更新过慢太小模型跟着student一起抖。4.2 伪标签质量差类别偏移和框不准怎么处理半监督训练最常见的病是“伪标签把模型带偏了”表现是训练后期模型mAP不升反降或者某个类别的检测精度突然崩掉。这是典型的噪声积累问题。排查思路是先做伪标签可视化。框架里有一个tools/visualize_pseudo.py脚本可以把某个未标注图片上的伪标签画出来保存成图像。你抽查几百张图能直观看到伪标签的分布情况。如果发现伪标签大量框住了背景区域说明置信度阈值太低如果发现某个类别频繁出现在错误的物体上说明类别分布存在偏差需要给该类别调高置信度阈值或者在损失函数里降低该类的权重。还有一种情况是分类置信度正常但框回归明显偏大尤其是目标边缘被强行扩了一圈。这多半是NMS参数问题。YOLO推理默认的NMS IoU阈值在0.5附近但对密集目标来说NMS后保留的框有可能把多个目标合并成一个导致回归框偏大。处理方式是放宽NMS阈值到0.6~0.7或者把置信度阈值调高让更少的低质量框进入候选池。4.3 有标注损失降了但mAP提不上去多半在数据增强上半监督框架有一个很隐蔽的坑有标注损失和中无标注损失都很漂亮地下降可验证集mAP就是不涨。我踩过几次最后定位在数据增强策略上。Mosaic增强对检测目标比较友好但对小目标或者细长目标不友好。它把多张图片缩放到一个小画布上目标会被缩得非常小背景一团乱。如果伪标签生成基于增强后的图像噪声就进一步放大。框架在utils/augment.py里对Mosaic策略做了控制默认只对标注数据的强增强分支生效不对teacher模型的弱增强分支生效。这个开关非常重要如果你手动改过增强配置务必确认这一点。强增强另一个容易踩的坑是颜色抖动强度。YOLO的检测精度对颜色变化不敏感但如果颜色抖动太强未标注图像的伪标签会跟增强后图像的内容产生不一致一致性损失就会变成噪声。我建议把HSV的饱和度变化幅度控制在0.5以内亮度变化在0.4以内再极端就得不偿失了。4.4 显存不足与训练速度慢工程上的取舍思路半监督训练同时跑student和teacher两个模型显存开销是大问题。如果碰到CUDA out of memory有几种优化方案可以按优先级尝试。第一降低输入分辨率。从640降到512显存占用直接减少将近一半精度损失可能只有1~2个点。第二关闭teacher模型的梯度计算。teacher模型只做前向推理生成伪标签不需要反向传播代码里应该有torch.no_grad()包着确认一下没有遗漏。第三开启梯度累积让batch size可以有效变大但实际显存占用不变。第四冻结backbone的前若干层。如果数据集和COCO分布接近可以直接冻结backbone的前三个stage这部分参数不再计算梯度训练速度和显存占用都有明显改善。训练速度慢还有一个容易被忽视的原因是EMA更新太频繁。默认每个step都对teacher做一次EMA更新这会引入额外的计算。如果不追求极致的伪标签稳定性可以改成每隔5个step更新一次teacher权重训练时间能省10%左右精度几乎没有损失。5. 从框架到产品你可以接住的落地场景5.1 车牌识别场景海量无标注视频帧的挖掘车牌识别的第一步是车牌检测也就是从监控画面中定位车牌区域。这个场景里大量监控视频帧天然就是“未标注数据”不需要花钱标注只需要抓帧存储。半监督框架训练时先用几千张标注好的车牌图训练一个基础模型再把几十万帧未标注的监控画面作为无标注数据输进去。模型会自动从不同光照条件、不同拍摄角度、不同清晰度的画面里挖掘更多的车牌形态最终收敛出来的检测器在夜间、逆光这些难场景下的鲁棒性明显提升。具体操作上有一个技巧车牌区域在图像中占比通常很小属于小目标检测范畴。伪标签生成时最好提高输入分辨率到800左右并降低置信度阈值到0.8否则大量远距离的小车牌会被误杀。类别设计上如果你的业务需要输出车牌颜色或省份信息可以把这些属性作为独立类别框架的分类分支完全支持多类别训练。5.2 野外鸟类监测稀缺标注数据的刚需场景野生鸟类监测的数据集有两个特点一是图片容易获得红外触发相机能自动拍上万张二是标注极难鸟的种类多、姿态多样、外观相似专家标注一张就要花很长时间。这种情况下半监督框架简直是救命稻草。我见过一个项目用300张专家标注的影像加2000张完全没有标注的野外影像跑出接近常规5000张标注数据的模型效果。伪标签生成的难点在于鸟类目标尺度变化极大近处的大鸟和远处的飞鸟在同一个画面里框尺寸天差地别。这时候需要把框架里原有的“伪标签目标面积过滤”参数调大范围别让模型把过大或过小的合法目标直接过滤掉。另外鸟类目标在树丛中经常会遮挡置信度天然较低阈值建议设为0.75左右。5.3 小目标与毛囊检测等医学场景密集目标的半监督难点医学图像、显微图像场景比如毛囊检测、细胞计数极度依赖目标检测模型。这类图像有两个特点目标数量极多且尺度非常小。半监督训练时最大的风险是伪标签把小目标遗漏导致模型对小目标越来越不敏感。针对密集小目标框架的优化策略有以下几点可参考。第一提高输入分辨率到1024或更高让小目标在feature map上还有足够的响应。第二在pseudo_label.py里关闭“过滤过小目标”的规则否则大量真实小目标会被当作噪声处理。第三对未标注图片的损失把分类损失和回归损失的权重比调高因为密集小目标的框尺寸微小回归损失对尺度不敏感需要更强的分类信号来帮助模型区分背景和目标。这类场景中我的测试结果是用15%的标注数据就能达到全标注训练90%左右的精度但前提是未标注数据的分布和标注数据基本一致如果分布差异过大伪标签质量会明显下降。5.4 框架后续还能扩展实例分割、旋转目标与多模态框架的teacher-student结构本质上是一个半监督训练的“外壳”它不绑定检测头。如果你后续要做实例分割可以把YOLO的检测头换成YOLO-seg的分割头伪标签部分同样输出分割mask而不是box损失函数换成分割损失就行。这个改动在代码层面比较大但架构上完全走得通。旋转目标检测也是可以做扩展的方向。遥感图像里的飞机、船舶经常是任意角度的普通水平框会框入大量背景。框架里虽然没有现成的旋转框支持但如果你用YOLOv8的旋转框分支替换检测头并在伪标签过滤规则里增加角度置信度的判断就能把半监督能力延伸到旋转目标场景。我个人在实际操作中最大的体会是半监督框架的使用难点从来不在模型结构而在数据工程。伪标签的置信度阈值、增强强度、损失权重这些参数没有一个能直接照搬别人经验必须在自己的数据上做小规模实验验证。建议你在正式训练前用一个小型数据集几百张图跑一遍从伪标签生成到模型评估的完整流程把各个环节的参数调整到合理范围后再上全量数据。最后再分享一个小技巧训练过程中一定要记录每一轮的伪标签数量。如果伪标签数量在训练中后期突然下降说明teacher模型的精度在退化这是一切问题最早的预警信号。这个指标比你盯loss和mAP更早暴露问题也是我给所有做半监督检测的朋友一定要加进日志里的字段。本文还有配套的精品资源点击获取
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
