YOLOv8课堂行为检测实战：从数据标注检查到训练避坑指南

简介这份课堂行为检测数据集面向计算机视觉与教育信息化方向的学习者聚焦真实课堂与教室场景提供“回答问题”“板书”等4类行为的目标检测标注可直接用于YOLO系列模型的训练与评估数据已完成训练集、验证集划分并配套py脚本可快速可视化标注。压缩包共2000个文件其中1999个txt为YOLO格式标签、1个py为可视化脚本整体787.64MB约11,800张图像的目标框信息按场景前缀命名组织便于筛选和增量训练。目前已有75人浏览学习对入门目标检测或开展课堂行为分析实验的读者而言这套数据既能用作迁移学习底料也能配合作者主页的YOLOv5改进实战拓展模型结构减少从零标注的时间成本。1. 真实课堂行为检测数据集为什么你的模型在教室里总是“装死”问题出在数据上去年带一个本科实训团队做课堂行为检测预研他们直接拿 COCO 预训练权重去跑教室监控视频在会议室样张上框得很稳一进教室就翻车后排学生目标小到只有几个像素举手、玩手机、伏案睡觉这些关键行为漏检率极高。后来换了一套真实课堂、教室行为检测图像目标检测数据图片和 YOLO 标注格式的标签加一起约 11,800 张模型结构完全没动mAP 直接涨了接近一倍。这种数据解决的是行业里最烧时间的环节——标注教室场景目标密集、遮挡严重、俯拍视角下长宽比和普通行人数据集完全不同手工标注一张图往往要十几分钟11800 张图的量足够让一个小组磨一个月。这篇文章适合正在做课堂行为分析、教育 AI、校园安防相关工程的工程师和研究生我会按自己拿到这种数据包后的完整处理顺序来讲检查标签、接入 YOLOv8 训练、排坑、调增强和部署链路。2. 先讲清楚 YOLO 标注格式拿到约 11,800 张图片后第一件事不是训练而是检查标签很多同学拿到数据集就把 images 和 labels 丢给 yolo 训练听起来是一键操作实际上翻车点全在标签上。YOLO 标注格式和 VOC 的 XML、COCO 的 JSON 都不一样每张图片对应一个同名 txt 文件每行一个目标五个数字分别是类别 id、归一化中心点 x、中心点 y、目标宽度 w、目标高度 h。归一化的意思是这些坐标全部除以了图片宽高取值范围在 0 到 1 之间。正因为做了归一化训练时把输入分辨率从 640 改成 1280边框的相对位置不会变这也是 YOLO 格式能跨分辨率训练的根本原因。2.1 目录结构与 classes.txt先确认有没有这个文件拿到已标注数据集第一步不是写 train 脚本而是先看目录结构。一个规范的 YOLO 数据集通常长这样classroom_det/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── classes.txtimages 和 labels 两边的 train、val 子目录名必须完全一致否则 ultralytics 按图片路径去找同名标签时会直接报错。更关键的是 classes.txt它定义了每个类别 id 对应的行为名称。这个文件顺序一旦错模型会把“举手”学到“玩手机”上。先检查文件数量和类别数find labels/train -name *.txt | wc -l cat classes.txt | nl第一行数量应该和 images/train 里的图片数一致第二行输出是一个编号列表例如0 sitting 1 standing 2 hand_up 3 sleeping 4 phone如果类别数比网络输出层还多后面 training 时会出现维度不匹配这类问题在数据接入阶段解决最省事。数量检查之外还要看有没有空标签文件。教室场景里大量纯背景远景图有些标注工具会自动生成空 txt不报错但文件大小是 0 字节。import os empty_count 0 label_dir labels/train for f in os.listdir(label_dir): label_path os.path.join(label_dir, f) if os.path.isfile(label_path) and os.path.getsize(label_path) 0: empty_count 1 print(fempty label count: {empty_count})空标签文件不建议直接删。如果源图确实是纯背景留着它能让模型学会把这种画面判断成“背景无目标”而不是把讲台、课桌、投影仪误检成行为目标。只有当某张图有明确行为目标但 txt 为空时才需要怀疑文件名匹配出了问题。2.2 用 Python 把标签画回原图5 分钟看出漏标和错标数据格式对了还不够真正判断这批真实课堂数据能不能用的是把标签画回图像之后看效果。把 YOLO txt 里的归一化坐标转换成像素坐标并画框直接用 OpenCVimport cv2 def draw_yolo_boxes(image_path: str, label_path: str, class_names: list): img cv2.imread(image_path) h, w img.shape[:2] with open(label_path, r, encodingutf-8) as f: lines f.readlines() for line in lines: parts line.strip().split() if len(parts) ! 5: continue cls_id int(parts[0]) cx, cy, bw, bh map(float, parts[1:]) x1 int((cx - bw / 2) * w) y1 int((cy - bh / 2) * h) x2 int((cx bw / 2) * w) y2 int((cy bh / 2) * h) cv2.rectangle(img, (x1, y1), (x2, y2), (0, 200, 0), 1) cv2.putText(img, class_names[cls_id], (x1, y1 - 4), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 200, 0), 1) return img class_names [sitting, standing, hand_up, sleeping, phone] for i in range(10): img draw_yolo_boxes(fimages/train/sample_{i:04d}.jpg, flabels/train/sample_{i:04d}.txt, class_names) cv2.imwrite(fdebug/check_{i:04d}.jpg, img)这段代码有两个重点第一标签坐标一定是用原始图片宽高归一化的有的数据包会先把原图压缩过再标注训练时读进来是未压缩图所有框整体偏移可视化后一眼就能看出来第二框要和人体行为部位贴合如果“举手”的框只罩住半条手臂而没包含头部说明标注标准不统一后续 NMS 清洗可以缓解但不如重新标注规范。我在真实教室里见过最常见的问题是重复框同一个学生被两三个框覆盖密集课桌之间特别普遍这属于标注标准不一致需要在训练前决定保留哪一种。2.3 统计类别与边框大小分布把“小目标漏检”提前暴露出来可视化抽查挑不出来的是整体数据分布问题。教室行为检测最容易出现一种类别占 80%、其他类别合计只有 20% 的情况比如“坐姿”几乎每张图都有“玩手机”可能只有几百个标签。这种不平衡会让模型把低频行为学成背景。用 collections 统计一下类别数量from collections import Counter import glob counter Counter() for label_file in glob.glob(labels/train/*.txt): with open(label_file) as f: for line in f: cls_id line.strip().split()[0] counter[cls_id] 1 print(counter)数值出来后对占比低于 5% 的类别后面要做复制粘贴类增强或在 loss 上做类别加权。另外还要统计边框面积分布教室后排的“手机”和“表情”目标往往只有几十个像素如果整份数据里小目标占比过低模型会偏向学大目标特征。area_bins [0, 32, 96, 100000] counts {i: 0 for i in range(len(area_bins) - 1)} for label_file in glob.glob(labels/train/*.txt): with open(label_file) as f: for line in f: parts line.strip().split() if len(parts) ! 5: continue w float(parts[3]) * 1280 h float(parts[4]) * 720 area w * h for i in range(len(area_bins) - 1): if area_bins[i] area area_bins[i 1]: counts[i] 1 break print(counts)这里把归一化宽高乘上常见输入分辨率粗略估算目标面积。如果小于 32 像素的边框占比不到 10%后续训练就必须加大 imgsz或者用 Mosaic 增强把小目标相对尺寸撑大。检查完这几项才建议进入下一步训练否则后面所有调参都是在给数据问题擦屁股。3. 用 YOLOv8 训练课堂行为数据集data.yaml、超参数与损失函数监控数据检查通过后进入训练阶段。现在做目标检测很少自己写网络结构YOLOv8 是社区里最稳的选择安装、训练、部署链路都成熟。对约 11,800 张图的规模YOLOv8n 或 YOLOv8s 的参数量完全够用。训练真实课堂数据时影响最终指标的关键往往不是换更大主干而是 data.yaml 路径、输入分辨率和损失函数反馈这三件事。3.1 环境和最小项目文件别在 Anaconda 上浪费半天先建一个干净环境用 conda 是常见姿势mkdir classroom_det cd classroom_det conda create -n classroom python3.10 -y conda activate classroom然后安装 ultralytics它会自动带上匹配的 PyTorchpip install ultralytics验证安装yolo predict modelyolov8n.pt sourcebus.jpg需要提醒的是机器上如果装过旧版 PyTorch最好在这步重装因为 Torch 和 CUDA 不匹配时训练会卡在数据加载阶段表现为 GPU 利用率很低但 CPU 一直满载。如果有 NVIDIA 显卡显存至少 4GB没有独立显卡用 CPU 跑 11800 张图会很慢建议先抽 500 张测试数据跑通流程再全量训练。3.2 data.yaml 里最容易错的路径写法把数据集路径和类别名统一写到一个 data.yaml 文件里path: /home/user/classroom_det train: images/train val: images/val names: 0: sitting 1: standing 2: hand_up 3: sleeping 4: phone最容易错的是 path 字段很多人在 train 和 val 两行直接写绝对路径换台机器就报 Fatal error。正确写法是 path 指向数据集根目录train 和 val 使用相对于 path 的相对路径。yaml 文件本身放哪无所谓因为路径基准是 path 字段不是 yaml 所在目录。还有一个坑names 的顺序必须和 classes.txt 一致否则边框坐标没变但语义标签全错。如果数据包只给了全部图片没有划分 train 和 val可以用一段小脚本按 8:2 随机划分import os, random, shutil random.seed(42) all_imgs os.listdir(images) random.shuffle(all_imgs) split_idx int(len(all_imgs) * 0.8) for i, img in enumerate(all_imgs): sub train if i split_idx else val shutil.move(fimages/{img}, fimages/{sub}/{img}) label_name os.path.splitext(img)[0] .txt shutil.move(flabels/{label_name}, flabels/{sub}/{label_name})注意类别是课堂行为时视频帧之间高度相关随机切分容易让同一段视频的连续帧同时出现在 train 和 val 里指标虚高。规范做法是按摄像头视角或按时间片段切分实在不行再随机切分。3.3 训练命令img、batch、epochs 之间的取舍目录和 yaml 都正常后启动 YOLOv8 训练yolo detect train modelyolov8n.pt dataclassroom_det.yaml \ imgsz768 batch16 epochs80 device0 projectruns nameclassroom_v1model 选择 YOLOv8n、YOLOv8s 或 YOLOv8m。课堂数据集目标小且密集常用 YOLOv8n 换取推理速度项目要求精度优先换成 YOLOv8s 受显存和帧率限制也算合理。imgsz 默认是 640但真实课堂原始视频多数是 1080p 或更高分辨率压到 640 时后排学生的小尺寸目标直接消失。显存足够时我一般用 768 或 896。YOLO 标签是归一化坐标改 imgsz 不需要重新计算标签只需改命令里的数字。batch 最好是先用 16 试显存没爆就往上加ultralytics 也支持 batchauto 自动检测。课堂上目标密集batch 太小会让 BN 层统计不稳定但显存不足时 8 也能跑。epochs 不用一上来就 300。11800 张图规模80 轮已经能看到趋势。观察 best.pt 出现在哪一轮模型在验证集上连续 20 轮 mAP 不上升就提前停省 GPU 时间。3.4 训练日志里看 loss 和 mAP判断数据集质量训练时终端输出几个关键指标box_loss、cls_loss、dfl_loss分别代表边框回归损失、分类损失和分布焦点损失。课堂场景下小目标多如果 model 输出日志里 box_loss 在高位震荡多半是大量小目标的边框没有被拟合住。cls_loss 和 dfl_loss 都在降而 box_loss 不动优先怀疑标签对齐问题。正常训练曲线是 train 和 val 的 loss 同步稳定下降mAP50 初期快速上升后平缓mAP50-95 比 mAP50 低很多是正常现象。如果 val loss 在第 20 轮开始上升而 train loss 继续降说明过拟合应该增加数据增强或减少 epochs。训练结束后权重文件在runs/detect/classroom_v1/weights/best.pt和last.pt后续验证和部署都用 best.pt。中途断掉想接着跑不用从零开始yolo detect train resume modelruns/detect/classroom_v1/weights/last.pt训练输出目录里还会生成 results.png里面画了每一轮的 loss 和 mAP 曲线这比在终端看数字直观得多。第一次跑不理想时先看这个图再决定是加数据还是调增强。4. 课堂行为检测数据集避坑指南五个反复踩中的训练事故数据集看起来正常、训练也能跑不代表不会翻车。下面五个问题我在真实课堂行为检测数据上反复遇到过每一条都是现象、原因、解决。4.1 现象train 和 val 指标都很高但现场视频里漏检模型在测试集上 mAP 挺好看放到教室摄像头实时视频里后排学生全部漏框只有画面中央的学生能检测到。原因往往是训练图像和现场视频的采集视角不一致数据集里大多是平视或教师视角现场摄像头装在黑板正上方俯拍人体目标的宽高比和三观完全变了。另一个原因是 imgsz 设太低训练时把图压到 640小目标被压没模型学不到后排特征。解决训练时直接把 imgsz 提到 896并从现场视频里抽 200~500 帧加入训练集如果换了摄像头位置最好重新标注一部分现场帧不要只依赖原有数据。4.2 现象loss 稳定下降mAP 一直贴着 0.01训练日志里 box_loss、cls_loss 都在降但每轮验证 mAP50 始终是 0.01 或 0。最典型的标签文件没有归一化写的是像素坐标的 x、y、w、h数值达到几千映射到归一化区间后边框中心全跑到图像外模型自然学不到东西。解决重新检查标签样例确认五个数字都在 0~1 之间如果混入未归一化数据写脚本把 x1、y1、x2、y2 转成 cx、cy、w、h 再除以图像宽高。另一个常见原因是类别 id 从 1 开始而不是从 0 开始导致所有类别偏一位分类 loss 无法收敛。4.3 现象标签文件为空模型对部分图像没有预测训练时某几个 batch 的 loss 突然跳高推理时同机位的某些画面完全没有输出。原因是空标签文件多模型把这些图像当成了纯背景负样本但实际画面上有学生和后摄像头。解决对空标签文件做二次确认不要用程序自动删除先人工看一眼对应图片。确定属于漏标需要补标确实是纯背景也建议保留并单独放一个 no_object 目录在 data.yaml 里不加入任何标注让模型学到“这种教室空镜是背景”。4.4 现象训练集里有 10 个类别网络输出只有 5 个有人拿到数据包后手动改 names发现类别 id 到 9 但 data.yaml 只写了 5 个名字。训练时不报错因为 ultralytics 会按 data.yaml 的类别长度动态调整输出层但标签里类别 id 大于 4 的那些样本会被忽略模型只学了 5 类剩下类别全是背景。解决拿到数据后先执行cat classes.txt | wc -l确认类别总数和 data.yaml 一致如果 classes.txt 里有多余类别而你只想训练其中 5 个必须用脚本把标签中多余的类别过滤掉不能直接在 yaml 里删名字。4.5 现象数据集中含重复图像测试集被“偷看”val 指标高得离谱但新测试场景效果差google 后发现 train 和 val 里有大量相似帧这是因为数据采集来自连续视频帧随机 8:2 切分时同一场景的相邻帧同时进了训练集和验证集。解决按视频片段分组切分同一个视频的帧只能进 train 或只能在 val统计相邻帧相似度用去重工具把重复帧踢掉。如果已经训练完回看训练输出里的 val 图像预测结果一眼能看出预测框和标注框几乎完全重合就是数据泄露。5. 数据增强与置信度门限让手机、表情和小目标在课堂场景不翻车课堂行为检测的“难”主要体现在小目标和类别不平衡上。手机、表情、后排举手都是小目标sitting 这类高频类别又占了大半标签。解决思路不是一开始就换大模型而是先做离线增强补齐少数类别再在训练阶段用 Mosaic 和 MixUp 把小目标上下文丰富起来最后在推理时调置信度门限三件事做完指标提升比换 YOLOv8m 明显。5.1 离线增强用 Albumentations 补足数量少的课堂行为类别对“phone”“hand_up”这些低频类别我会复制一批样本做离线增强让模型能见到的次数多一点。Albumentations 是常用的增强库它直接支持 YOLO 的归一化 bbox 格式import albumentations as A import cv2 aug A.Compose([ A.HorizontalFlip(p0.5), A.RandomBrightnessContrast(brightness_limit0.3, contrast_limit0.3, p0.5), A.RandomGamma(p0.3), ], bbox_paramsA.BboxParams(formatyolo, min_visibility0.3, label_fields[class_labels]))使用时对少数类别的图片做循环每张增强出的图片要同时保存原图和同名 txtfor img_path in minority_images: image cv2.imread(img_path) label_path img_path.replace(images, labels)[:-4] .txt with open(label_path) as f: lines [x.strip().split() for x in f] bboxes [[float(v) for v in line[1:]] for line in lines] class_labels [int(line[0]) for line in lines] for idx in range(5): out aug(imageimage, bboxesbboxes, class_labelsclass_labels) # 保存 out[image], out[bboxes], 对应类别到增强集box_loss 与增强时框坐标的转换无关但 min_visibility 参数要留意它表示增强后如果框小于可见面积的 30% 就丢掉避免翻转后边框被裁得只剩一条边。离线增强不要对全部类别做只复制低频类别否则数据集又会陷入重复样本过拟合。5.2 训练阶段的 Mosaic 与 MixUp 参数小目标类别的调试经验离线增强解决数量问题训练阶段的 Mosaic 和 MixUp 解决上下文问题。Mosaic 会把四张图拼成一张小目标经过缩放后相对尺寸变大模型更容易学到手机和表情MixUp 则把两张图按比例叠加课堂场景下目标密集MixUp 太高类别重叠严重反而让分类模糊。我的常用做法是 Mosaic1.0、MixUp0.2copy_paste 对课堂这种目标重叠较多的场景可以开大一点yolo detect train modelyolov8n.pt dataclassroom_det.yaml \ imgsz768 epochs100 mosaic1.0 mixup0.2 copy_paste0.1如果训练时发现 val loss 不平滑、周期性跳高先把 mixup 降回 0。mosaic 导致每轮看到的数据完全不同loss 天然会比关闭 mosaic 时波动大这是正常现象不用因为一个 epoch 的尖峰就停训练。这个参数组合下模型对后排小目标的 recall 通常会有明显上升。5.3 推理时调置信度门限和 NMS比改模型更快见效模型训练完部署时很多人直接拿默认 conf0.25、iou0.45 去跑视频发现误检一堆。真实课堂场景下遮住的“低头”目标置信度普遍在 0.2~0.3 波动而空桌椅可能被误判成“坐姿”且置信度高达 0.5。这时套用默认门限就是灾难。先跑一批测试帧看预测框的置信度分布再定门限from ultralytics import YOLO model YOLO(runs/detect/classroom_v1/weights/best.pt) results model.predict(test_frame.jpg, conf0.3, iou0.4, imgsz768, device0)conf 表示置信度门限低于这个分数的预测框直接丢弃iou 是 NMS 时的重叠阈值教室密集场景下同类目标高度重叠iou 设到 0.4 会保留更多重叠框设成默认的 0.45 则可能把两个相邻学生合并成一个框。小目标漏检多conf 就降误检多conf 就升。我用一手在 100 张测试图上用 conf0.2、0.25、0.3、0.35 四个档位各跑一次找到漏检和误检的平衡点如果某类行为始终置信度很低回到数据增强环节专门补这一类的样本而不是继续调整模型的 NMS 阈值。6. 把检测结果变成课堂行为统计从视频帧到每节课的行为曲线模型部署到教室后最终交付的往往不是一些画着框的视频而是“这节课学生举手几次、睡觉占比多少”的行为统计。这里有个具体技巧不要把视频每一帧都当成独立样本来计算比例这会让统计结果剧烈抖动先按时间窗口聚合再生成课堂行为曲线。单张图片的统计很简单直接用模型预测结果的 cls 做直方图from collections import Counter from ultralytics import YOLO model YOLO(runs/detect/classroom_v1/weights/best.pt) results model.predict(frame_0400.jpg, conf0.3, iou0.4) cls_list results[0].boxes.cls.tolist() counter Counter(int(c) for c in cls_list) print(counter)对视频做统计时我一般按 30 秒或 1 分钟为窗口统计窗口内每帧的各类别检测次数再除以窗口内总帧数得到“该时间段举手行为密度”。这类数据交付给教务人员可读性更强也方便做成课堂行为曲线。把结果写成 CSVimport csv with open(behavior_stats.csv, w, newline) as f: writer csv.writer(f) writer.writerow([timestamp, sitting, standing, hand_up, sleeping, phone]) for timestamp, counter in window_stats.items(): writer.writerow([timestamp, counter.get(0, 0), counter.get(1, 0), counter.get(2, 0), counter.get(3, 0), counter.get(4, 0)])这个脚本看起来简单但不要直接在热插拔摄像头视频上跑每帧预测一次的推理时间如果超过视频帧间隔行为占比会偏向同目标反复检测数值没有参考意义。我会先把视频抽帧到 5 FPS 再做统计节省时间和显存而且行为变化在秒级粒度下完全够用。这里有一个印象很深的教训第一版课堂行为报告我直接用逐帧计数取平均输出曲线全是毛刺教务那边根本没法看。后来改成按 30 秒窗口聚合、取窗口内类别众数才真正能落地。建议你从拿到数据的第一天起就把数据划分、标签检查、增强参数、统计窗口这些习惯写进代码里不要等到项目交付前再临时补。希望帮到你。本文还有配套的精品资源点击获取