简介基于YOLOv5的教室行为检测系统代码包面向智慧校园建设覆盖人数统计、学生行为分析举手、书写、使用电子设备等与教师授课行为识别。系统整合数据预处理、模型训练、推理部署与可视化交互四大模块能接入图片、视频及RTSP网络流适合教育信息化开发者、算法落地工程师及计算机视觉学习者快速建立课堂智能管理原型。资源包为zip格式共5个文件约12KB包含HTML可视化页面、JavaScript逻辑脚本、Markdown说明文档以及Git忽略规则和平台配置结构简洁便于快速阅读与上手。已有40人学习浏览。读者可由此查看前端交互设计、业务调用流程与工程组织方式并借助说明文档明确后续接入YOLOv5权重、优化模型参数和扩展实时检测能力的路径适合作为课设、毕设或轻量级演示项目的基础骨架。1. YOLOv5教室行为检测系统一套能少踩一半冤枉路的可复用实战方案教室行为检测这几年需求量极大高校巡课、培训机构课堂质量评估、线上网课考勤都在做但真正能直接跑到显存里的开源方案却很少。YOLOv5教室行为检测系统正是把这个需求打包成一套可跑可训的完整代码从数据标注、模型训练到行为判定都有现成落点。它解决的痛点是普通目标检测模型进教室几乎必翻车固定视角、密集课桌、小目标、遮挡加逆光这四座大山让通用权重根本顶不住。如果你正打算给某高校或某机构做课堂考勤、抬头率统计、睡觉举手识别或者只是想把YOLO系列接到教育场景里这套思路值得你投入时间复现一遍。2. 为什么教室行为检测还在用YOLOv5选型对比与最小复现路径2.1 YOLOv5在教室场景的不可替代性内存、时延与生态先说结论如果让我选择做一个教室行为检测项目首选仍然是YOLOv5而不是YOLOv8或RT-DETR。原因不是YOLOv5精度更高而是教室场景对极限算力和最新结构并不敏感但对内存占用、推理时延、边缘部署兼容性极其敏感。YOLOv5的Anchor-Based检测头对密集排列的课桌小目标非常友好尤其是教室后排的起立和趴桌动作Anchor-based的先验框在小目标召回率上比Anchor-Free的YOLOv8在同等尺寸输入下更稳。另一个现实因素是YOLOv5的工程化生态成熟度TensorRT导出、OpenVINO转换、Jetson部署踩坑案例随手能搜到换成YOLOv8遇到问题只能自己啃文档。内存占用上YOLOv5s在640×640输入下权重只有14MB左右FP16推理时显存占用不到1.5GB这意味着教室场景常见的部署硬件——某国产边缘盒子或Jetson Nano级别的设备——都能跑得动。而YOLOv8同等精度档位权重略大最关键的是v8的C2f结构在部分老设备上的加速库支持不完整比如某些RK3588平台的NPU工具链至今只对v5的模型结构做了充分优化。做教室行为检测这种预算受限的项目选v5不是技术落后是务实选择。对比维度YOLOv5sYOLOv8s权重体积约14MB约21MB640输入显存占用约1.5GB约2.1GB小目标召回率密集场景更好相当但需调锚框RK3588/Jetson生态成熟部分平台支持不全2.2 本地跑通官方检测的最小命令环境、权重与源码我从来不建议一上来就改网络结构先把官方推理跑通确认环境没问题再谈定制。这是所有教室行为检测项目的第一步也是我自己每次接手新机器时的固定动作。# 1. 拉取官方源码并创建虚拟环境 git clone https://github.com/ultralytics/yolov5.git cd yolov5 python -m venv venv source venv/bin/activate # 2. 安装依赖 pip install -r requirements.txt # 3. 下载预训练权重 wget https://github.com/ultralytics/yolov5/releases/download/v6.1/yolov5s.pt # 4. 跑通推理 python detect.py --weights yolov5s.pt --source data/images/bus.jpg --conf 0.5这段流程的核心逻辑是先用官方图片验证整条链路。注意几个关键参数--conf 0.5是置信度阈值教室场景后面建议调到0.3左右因为小目标置信度天然偏低0.5会滤掉太多候选框--source可以是图片、视频文件或实时摄像头地址部署阶段改成rtsp://流地址就行。如果你的机器是Apple Silicon芯片pip install之后还需要额外装ultralytics依赖的MPS支持版本否则detect.py会报MPS不可用。跑通后你会看到runs/detect/exp/目录下生成标注好类别的输出图这说明环境OK可以进入下一步了。2.3 源码目录结构说明训练、推理、配置各自在哪很多新手拿到这套代码后第一反应是找不到改哪里。我按重要程度梳理一份文件清单你只需要关注这几个其他暂时不用管文件路径作用何时需要改detect.py推理入口部署阶段做后处理逻辑时train.py训练入口自定义数据集训练时models/yolov5s.yaml网络结构定义需要调整检测层或注意力时data/coco128.yaml数据集配置模板换成自己的dataset.yaml时utils/loss.py损失函数类别不均衡严重时runs/训练和推理输出目录无需手动创建这里有个容易忽略的细节models/yolov5s.yaml中的nc参数是类别数改成你的行为类别数之前如果直接加载yolov5s.pt预训练权重会报维度不匹配错误。常见做法是在train.py里指定--weights yolov5s.pt框架检测到nc不匹配时自动裁剪最后的检测头只保留前面特征提取层的预训练参数这个特性在v6.0之后已经内置了。3. 教室行为数据集构建策略、标注规范与格式转换3.1 行为类别怎么定以可落地的粒度划分教室行为教室行为检测最容易犯的错是把类别定得过于细碎比如把「抬头」「低头看黑板」「低头看书」「侧头聊天」都分成独立类别。我接过一个模拟项目X的需求甲方一开始提了12个行为类别结果标注到手软模型也学出一堆混淆。我的建议是面向「巡课考勤和教学质量评估」的真实诉求收敛到6个核心类别person正常听讲坐姿、hand_up举手、sleep趴桌或闭眼、play_phone玩手机、stand起立、leave离开座位。这6类比12类好标注、好训练、好解释而且能覆盖教室行为分析90%以上的有效信息。这里有一个关键认知不要试图用目标检测去做「交头接耳」这种需要多人交互关系的行为判断。YOLO系模型是单帧实例检测器它不理解「两个人之间的距离变化」和「头部朝向」这类语义。正确做法是把交头接耳交给后一层的规则引擎处理——检测出两个人的person框距离小于某个阈值且持续超过5秒才判定为交头接耳。这一点想通了你的数据标注压力能减小一半。3.2 自采数据与公开数据集的融合比例数据配比经验教室场景对训练数据的要求非常聚焦视角固定基本都是教室后方或侧上方、光照变化大晴天拉窗帘、阴天开灯、目标尺寸分布极端前排大后排小。我的做法是自采数据占70%公开数据集占30%。公开数据集比如COCO里的人物类别只用来做预训练阶段的领域粗对齐让模型先学会「什么是人的基本形态」真正决定教室场景精度的还是自采数据。自采数据要覆盖三个维度的变化时间段维度上午、下午、晚自习各采集不低于2000帧教室布局维度阶梯教室、普通方桌教室、实验室圆桌教室行为动作维度每个类别不少于800个实例hand_up和stand这种动作帧建议每个机位采集500帧以上视频再抽帧约每类1000~1500个实例6个类别总计8000个实例左右训练出的权重已经能稳定达到mAP0.5 85%以上的水平。少于这个数量后排小目标检不出来就是你标注量不够不是模型问题。3.3 转成YOLO格式的转换脚本与四个边界坑教室行为数据集的标注我基本都用LabelImg或XAnyLabeling输出的是VOC格式的XML文件。但YOLOv5训练需要的是txt格式的归一化坐标所以必须写转换脚本。下面这个脚本是我常用的可靠版本import os import xml.etree.ElementTree as ET import random # 类别映射表按你的需求调整顺序顺序就是ID CLASS_MAP {person: 0, hand_up: 1, sleep: 2, play_phone: 3, stand: 4, leave: 5} def convert_xml_to_yolo(xml_path, out_dir): tree ET.parse(xml_path) root tree.getroot() img_w int(root.find(size/width).text) img_h int(root.find(size/height).text) out_lines [] for obj in root.iter(object): name obj.find(name).text if name not in CLASS_MAP: continue # 跳过不在类别表里的标注 cls_id CLASS_MAP[name] box obj.find(bndbox) x1 float(box.find(xmin).text) y1 float(box.find(ymin).text) x2 float(box.find(xmax).text) y2 float(box.find(ymax).text) # 归一化并裁到[0,1]区间 x_center min(max((x1 x2) / 2 / img_w, 0.0), 1.0) y_center min(max((y1 y2) / 2 / img_h, 0.0), 1.0) box_w min(max((x2 - x1) / img_w, 0.0), 1.0) box_h min(max((y2 - y1) / img_h, 0.0), 1.0) out_lines.append(f{cls_id} {x_center:.6f} {y_center:.6f} {box_w:.6f} {box_h:.6f}) if out_lines: txt_name os.path.splitext(os.path.basename(xml_path))[0] .txt with open(os.path.join(out_dir, txt_name), w) as f: f.write(\n.join(out_lines)) # 没有合法标注的xml不会生成txt文件训练时yolo会跳过 # 转换全部xml xml_dir annotations/ out_dir labels/ os.makedirs(out_dir, exist_okTrue) for xml_file in os.listdir(xml_dir): if xml_file.endswith(.xml): convert_xml_to_yolo(os.path.join(xml_dir, xml_file), out_dir)逻辑说明脚本首先读取XML里的图片尺寸作为归一化分母遍历每个object标签取出类别名和边界框坐标换算成YOLO需要的中心点坐标加宽高格式。换算是YOLO训练最关键的预处理步骤任何一步出问题都表现为训练时正样本数量为0。转换过程中有四个高频坑都是我在教室项目里真实踩过的第一个坑是边界值越界。有时候标注框刚好贴在图片边缘x2或y2等于图片宽高导致计算出的框坐标恰好等于1.0YOLOv5内部的坐标解析在边界情况下偶尔会产生空框。解决方式就是脚本里写的那行min(max(...))把坐标强制裁进[0,1]区间。第二个坑是类别ID错位。如果LabelImg里勾选的类别名和CLASS_MAP键值对不上比如写成了sleeping而不是sleep脚本会静默跳过该对象最后训练出来某类永远没有正样本。排查方法是转换完成后统计一下每类txt文件里出现的类别ID个数和标注数量对齐。第三个坑是空txt文件。一张图上如果有标注但全部是difficult1或被过滤脚本会生成空文件或者不生成文件。YOLOv5训练时会警告No labels found但不报错这个警告很容易被忽略。我的习惯是每次转换后跑一下下面的校验命令find labels -name *.txt -size 0 -print | head第四个坑是图片和标注文件名不一致。LabelImg保存的XML文件名和图片文件名不同比如手动改过名YOLO训练时会匹配不到label。所以我在标注前就统一用frame_000001.jpg这种格式命名图片XML文件名保持一致杜绝这个问题。4. 训练与调参教室场景的模型配置、损失观察与收敛判断4.1 YOLOv5训练命令与关键参数imgsz、batch、epochs怎么设准备训练前先写数据集配置文件classroom.yaml这是训练的基础。我的配置通常长这样# classroom.yaml path: ./datasets/classroom # 数据集根目录 train: images/train val: images/val nc: 6 names: [person, hand_up, sleep, play_phone, stand, leave]这里path是相对或绝对路径train和val是图片目录注意YOLOv5会自动在同级目录下找labels文件夹目录结构是datasets/classroom/images/train/xxx.jpg配datasets/classroom/labels/train/xxx.txt。配好之后启动训练的核心命令python train.py \ --data classroom.yaml \ --weights yolov5s.pt \ --img 640 \ --batch 16 \ --epochs 200 \ --cache \ --workers 8 \ --project classroom_runs \ --name exp_baseline关键参数的选择逻辑--img 640是训练输入尺寸教室场景我建议至少用640。如果后排小目标检测压力大可以升到960但显存占用会涨到原来的2.25倍16GB以下显存配batch 16会OOM需要降到batch 8。教室场景我一般先用640跑通确认整体流程后再试更高分辨率。--batch 16是显存决定的每张卡的显存除以单张图片训练时占用约1.5GB就是能设的max值。这个参数直接影响批次归一化稳定性batch太小小于8会导致收敛慢且震荡。--epochs 200是给足训练量。教室数据集几千张的量级200个epoch足够收敛且能明显看到过拟合拐点。--cache是显存加速参数它把图片直接加载进RAM或显存省去每轮IO时间。训练过程中最需要关注的输出是终端里的box_loss、obj_loss、cls_loss三个指标以及每个epoch结束后的mAP0.5。正常情况是前50个epoch三个loss快速下降之后缓慢趋平mAP稳步爬升。如果你的loss在150个epoch还在抖动那基本是学习率没有配合好YOLOv5默认的cosine调度在长训练时通常没问题但如果前50个epoch就出现loss反弹说明lr0初始值默认0.01偏大我一般会降到0.005。4.2 训练过程看什么loss曲线、P/R曲线与混淆矩阵的判读训练结束后的runs/classroom_runs/exp_baseline/目录里results.png是第一个要看的文件。这张图包含了所有训练曲线的汇总我通常按优先级看四个子图第一是train/box_loss和train/obj_loss曲线。如果这两个值最终收敛到0.03~0.06区间具体数值随数据集变化说明边界框回归和置信度预测正常。如果你的obj_loss在50个epoch后仍然高于0.08大概率是正负样本严重失衡教室场景里背景占比极高课桌、黑板、墙面置信度头学不出「什么是前景」——这时要用后面的类别权重策略缓解。第二是Precision和Recall曲线。教学楼场景里你要看的核心指标是Recall宁可误报多一点也不能漏掉后排的玩手机。经验值是Recall达到85%以上、Precision在80%左右时整体可用性良好。第三是混淆矩阵confusion_matrix.png它直接揭示类别混淆问题。教室场景最常见的混淆对是person和stand起立状态下人体框被检测成person而不是stand。这类混淆靠调参数解决不了你只能回去补stand的样本或者把两个类别合并成一个语义——「坐姿vs站立」交给后续行为规则判这反而更稳。第四是labels.png里的目标尺度分布图。如果绝大多数目标框面积在图片总面积的5%以下说明这是典型的小目标场景除了提高输入分辨率你也该认真考虑第4.3节说的锚框调整方案。4.3 小目标与密集遮挡场景的改进注意力模块与锚框调整教室场景有它的独有痛点前排学生起立时后排学生会被大面积遮挡且由于教室纵深大后排人体高度经常只有50像素左右。针对这两个问题有两个相对便宜且稳定的改进方向。第一个方向是注意力模块。我推荐在YOLOv5的C3模块之后接入坐标注意力模块Coordinate Attention它能同时感知空间位置和通道关系对密集遮挡场景的增益明显。实现方式是修改models/yolov5s.yaml里的backbone层结构在倒数第二层C3后插入CoordAtt模块。注意这个改动会增加约1.2MB的权重体积和约10%的推理耗时对于边缘设备上做实时检测要评估你的帧率余量。第二个方向是锚框调整。YOLOv5默认的锚框是从COCO数据集聚类得到的COCO里的大目标居多直接用在教室场景会出问题。教室行为检测的锚框应该更扁更小——因为坐姿状态下人体框的高宽比通常大于1.5而趴桌状态的框接近正方形。我用下面的脚本重新聚类得到适配教室数据的锚框import numpy as np from tqdm import tqdm # 读取所有txt标注收集所有框的宽高 boxes [] for label_file in tqdm(label_files): with open(label_file) as f: for line in f.readlines(): _, x, y, w, h line.strip().split() boxes.append([float(w), float(h)]) boxes np.array(boxes) # 用k-means聚类出9个锚框3个尺度各3个 from sklearn.cluster import KMeans kmeans KMeans(n_clusters9, random_state0).fit(boxes) anchors kmeans.cluster_centers_ # 按面积排序后写入yaml anchors sorted(anchors, keylambda x: x[0]*x[1]) print(anchors.tolist())这个脚本的本质是用k-means在归一化坐标空间里对你的标注框做聚类聚类中心就是最匹配你数据的先验框。把得到的9组值填进yolov5s.yaml的anchors字段然后删除之前的训练缓存再加--weights重新训练。我做过一个对比实验只在锚框上做了调整没有改任何网络结构mAP0.5就从81%涨到84%。这不是玄学是教室数据集的目标尺度分布确实和COCO差异过大锚框是物美价廉的改进杠杆。5. 教室行为检测避坑指南5个真实翻车点与排查链路5.1 白天误报拉窗帘行为数据增强把光照做过头了现象模型在晴天下午的教室里大量误报把逆光状态下抬头看黑板的学生框成sleep尤其靠窗座位严重。原因训练时YOLOv5默认数据增强里的HSV扰动对色相和饱和度的调整幅度较大会让模型对暗部区域失去区分能力。而真实教室场景中靠窗座位逆光时人脸区域对比度极低sleep类别低头或闭眼在特征上跟逆光下的正常坐姿高度相似模型学到的是「暗部低头姿态≈sleep」的错误关联。解决训练配置里关掉过度的颜色扰动。在data/hyps/hyp.scratch-low.yaml中把hsv_h、hsv_s、hsv_v三个参数各下调一半比如hsv_v: 0.2调到0.1。同时按第3.2节的策略补采1000帧以上逆光时段的训练图。这一步能直接降掉70%的晴天误报。5.2 后排学生反复漏检分辨率不足导致小目标丢失现象训练时mAP看起来正常但一到实际巡检视频里后排学生特别是坐着趴桌的检测框断断续续。同一个学生一会检测到一会消失。原因640×640输入经过5次下采样后特征图尺寸只有20×20。后排学生头部在画面里可能只有15×15像素映射到特征图上不足一个格子目标特征完全消失。解决优先方案是把推理输入的--img从640提高到960或1280。显存不够时用切图推理。我一般用SAHI库把大图切成带重叠的若干小图分别推理再合并结果教室1080P画面切成2×2的4块重叠比例设为0.2后排目标召回率能提升10个点以上。这个方法不必重训模型部署阶段临时加个切片步骤就行。5.3 训练loss正常但全部漏检类别权重失衡的隐性陷阱现象cls_loss降得很低但某个冷门类别比如leave离开座位在验证集上的mAP是0训练过程看不出任何异常。原因教室数据集里person的数量可能是leave数量的50倍以上模型把所有样本都学成高频类就能拿到很低的loss。这是标准的类别不均衡问题而且YOLOv5默认的BCE损失函数没有内置类别权重。解决两个层面同时处理。数据层面把leave和play_phone这类低频样本复制扩充到每类800框以上训练层面在utils/loss.py里对cls_loss按类别频率倒数的平方根加权权重公式是w_i (1 / freq_i) ** 0.5。我在一次真实调优中靠这个权重调整把hand_up的召回率从55%拉到82%比改模型结构有效得多。5.4 推理速度达标但视频画面卡顿解码瓶颈与帧率策略问题现象用detect.py跑单帧视频文件时模型推理FPS显示30但实际视频输出肉眼看着像PPT一样一顿一顿的。原因模型的推理耗时只是整条链的一部分。OpenCV默认用CPU软解码1080P H.264视频软解码可能占掉两个核心如果同时在跑推理线程帧率计算被解码阻塞。这是典型的工程陷阱——模型优化到位了但数据管线和解码没有跟上。解决用多线程解耦解码和推理解码线程只负责把帧塞进队列推理线程从队列取帧处理。如果用的是本地视频文件还可以试试把视频先转成原始帧序列再逐帧推理绕开解码瓶颈。如果接的是IP摄像头RTSP流优先开启硬件解码英伟达平台用cv2.cudacodec瑞芯微平台用mpp硬解效果立竿见影。5.5 模型在另一间教室失效场地泛化与背景过拟合现象训练用的教室测试mAP正常部署到另一个装修风格完全不同的教室漏检率暴增尤其stand和person的区分几乎失效。原因这是两个问题叠加。第一训练集只在一间教室采集模型把特定背景墙色、课桌颜色、窗户位置当成了判别特征第二stand类别的训练样本里有相当部分学生站在特定位置比如讲台旁模型学到的是「那个位置的人stand」而不是「站立姿态stand」。解决数据层面要主动做场地多样性采样至少要覆盖两到三间朝向、背景色、课桌布局不同的教室。代码层面可以做Exchange-Net数据增强用随机生成的背景替换训练图里的环境部分强迫模型只关注前景人体。这两个措施二选一我优先建议前者多采集一个教室的半小时视频效果胜过任何高级增强算法。6. 从检测框到行为判定规则引擎、跨帧跟踪与硬件落点6.1 检测与行为判定之间的关键一步跨帧ID跟踪目标检测是逐帧进行的单帧结果没有任何时间连续性。这就导致一个尴尬现象学生只是正常低头捡笔sleep框闪现一帧然后消失有人一直在举手hand_up框时有时无。解决这个问题需要在检测之上加一个简单跟踪器我常用的是ByteTrack而不是DeepSORT后者依赖ReID特征提取在低分辨率小目标上ReID质量很差反而不如ByteTrack这种纯运动关联的跟踪器稳定。ByteTrack的核心是给每个人体框分配稳定的ID之后行为判定就不再依赖单帧结果而是依赖ID维度的行为序列。from boxmot import BYTETracker tracker BYTETracker() frame_id 0 for frame in video_frames: results model(frame) # YOLOv5推理 boxes results.xyxy[0].cpu().numpy()[:, :5] # x1,y1,x2,y2,conf tracks tracker.update(boxes, frame_id) for t in tracks: track_id, x1, y1, x2, y2 t[:5] cls_id int(t[5]) # 类别ID persist_dict[track_id].append((frame_id, cls_id, x1, y1, x2, y2)) frame_id 1逻辑说明代码里tracker.update输入的是检测框数组和帧号输出的是带稳定ID的跟踪结果。persist_dict按ID记录每个学生的时序轨迹它是后续所有行为判定的数据源。参数上需要注意的是track_thresh检测框置信度阈值教室场景建议设为0.3低于默认的0.5这样能让低置信度的后排小目标也参与跟踪匹配减少ID跳变。6.2 行为判定规则持续时长、空间关系与置信度阈值有了稳定的ID轨迹判定行为就转换成两个问题这个动作持续了多久这个动作和其他空间对象有什么关系。我习惯按这四条规则来定第一是sleep和play_phone判定走持续时长方。单帧检测到sleep还不可信连续20帧按20FPS推理算即持续1秒都检测到才判定为真睡眠。这个时长阈值可以根据你的巡检需求调整巡检严格就调成10帧宽松就调成30帧。第二是stand走框形态变化检测。起立的本质是人体框高宽比变化如果某ID的人体框高度h在10帧内从坐姿的100像素涨到160像素以上且置信度超过0.35就判定为起立。这比单帧检测stand类别更可靠因为起立过程的中间帧经常被模型分类成person。第三是hand_up走后处理验证。YOLOv5直接检测手部小目标很容易漏我的经验是检测器输出hand_up框时再用一个几何约束复核手部框的底部必须高于该ID对应person框的顶部说明手确实举过了肩膀高度否则丢弃这个框。这个规则能滤掉大量误报。第四是leave走区域判定。教室场景里固定一个讲台区域或门口区域如果person框的中心点落入该区域且持续消失超过50帧判定为离开座位。这个逻辑完全绕开了检测器对leave类别的识别压力反而更准确。6.3 部署端选型与性能验收技巧教室行为检测的部署端我一般按两个方向选型。预算充足且要做多路教室并发直接用某英伟达边缘盒子TensorRT FP16量化后YOLOv5s推理单路1080P视频能做到25~30FPS这也是为何前面章节反复强调别乱改模型结构结构一改TensorRT的算子支持就要重新评估。预算受限的教室单路部署用某国产平台的NPU或CPU方案YOLOv5s在CPU上的推理速度大概8~12FPS用第6.1节的抽帧策略每3帧检测1帧中间帧用跟踪做平滑也能交付出可用体验。最后的性能验收我习惯录一段真实教室的10分钟视频覆盖上午逆光、下午顺光、课间活动三个时段统计三个核心指标各类别召回率、ID切换次数切换越少说明跟踪越稳、从视频输入到行为结果输出的端到端延迟。验收时有一个容易被忽略的习惯把置信度阈值和持续帧数这两个参数同时做一个小的网格搜索你会发现教室里真正可靠的是一组参数组合而不是单独调某个值。这套项目我做下来最大的感悟是教室行为检测的难点从来不在YOLOv5本身而在数据粒度、时序规则和场景泛化这三个检测器之外的地方。把模型看作眼而不是大脑行为判定逻辑才是大脑。先跑通最小闭环再逐步加强规则和数据这种做法比一开始就追求高精度模型结构稳妥得多。希望这些经验能帮到你少走我当年绕过的弯路。本文还有配套的精品资源点击获取