简介面向智慧校园场景的YOLOv5教室行为检测系统代码包主要服务教育信息化开发者、AI初学者及教学管理人员可解决课堂中人数统计、学生行为检测与老师行为检测等多维管理需求。包体非常轻量共5个文件以HTML、JavaScript前端文件为主配合TODO.md、.inscode及.gitignore其中HTML/JS构成可视化入口TODO.md记录待办与扩展方向.gitignore便于工程化同步整个zip压缩包仅12KB适合快速拉取预览。目前已有40人浏览学习。描述中覆盖了从数据预处理、模型训练到推理部署、可视化交互的完整模块划分并提及学生端坐、举手提问、低头书写及教师板书、巡视等课堂行为识别维度虽然受限于包体规模并非完整训练工程但保留了清晰的目录结构与后续优化线索适合需要快速了解YOLOv5课堂行为检测方案、搭建演示原型或做二次开发的读者。1. 教室行为检测为什么比通用目标检测更“吃代码”这套 YOLOv5 代码包要怎么拆通用目标检测在公开数据集上跑出再漂亮的精度搬到教室监控画面里往往直接翻车学生目标小、互相遮挡、动作相似同一个权重在别的场景好用的进教室就频繁漏检和误报。教室行为检测系统这份代码包本质上不是“YOLOv5 换了个名字”而是把数据标注规则、训练参数、推理平滑策略都围绕教室座椅场景重新调了一遍的源码工程。它解决的问题是学生睡觉、玩手机、举手、站立、读写等行为的自动检测与汇总适合正在开发校园行为管理软件的人适合给安防集成商做现场验证的工程师也适合想拿真实工程结构做课设修改的新手。它比普通目标检测示例多出来的部分正是最需要在本地复刻的工程边界。2. 代码包结构和数据准备把下载的源码包改造成能直接训练的工程2.1 先看目录边界数据区高频改算法区只读解压代码包后我一般留 10 分钟做目录巡查这个时间在后续排错中会被十倍省回来。教室行为检测工程延续了 YOLOv5 系列的布局但增加了一些自定义目录典型的文件树长这样classroom-detect/ ├── data/ │ ├── classroom.yaml │ └── images/ # 按 train/val 划分的原始图片 ├── labels/ # 与 images 同名的 YOLO 格式标签 ├── models/ │ ├── yolov5s.yaml │ └── yolov5m.yaml ├── utils/ ├── runs/ # 训练输出、best.pt、测试结果 ├── train.py ├── detect.py ├── export.py └── requirements.txtdata/classroom.yaml 是训练入口必须读的核心文件类别名、类别数量、训练集路径都写在这里。labels 目录则是逐张图片对应的标注文件每个 .txt 里每一行代表一个目标框格式是class_id cx cy w h。models 目录我建议只读除非你要自己加注意力模块否则行为检测这种任务不需要动网络结构先把损失函数、I/O、NMS 这几个参数吃透更重要。utils 里是锚点计算、数据增强、损失计算等底层逻辑我的习惯是只读不写避免后续拉新数据时静默改坏行为。真正需要高频修改的是 data、labels 和 runs。data 决定模型学什么labels 决定学得准不准runs 是实验结果删掉旧的 runs 再做对比实验视角会更清楚。很多人拿到代码包直接把整包丢进去跑遇到问题也不知道是代码问题、数据问题还是参数问题就是没做第一步的目录边界划分。2.2 最小数据集合images、labels 与 classroom.yaml 的三者对应YOLO 格式有一个容易翻车的地方训练时给的路径是 images 目录但代码会自动去同级的 labels 目录找同名标签。如果标注文件被放在 images 里面训练日志会提示找不到标签然后悄悄跳过大量图片。我见过有一个小组 5000 张验证图实际参与评估的只有 300 张原因就是 labels 目录和 images 目录的对应写错了。正确结构应该是dataset/ ├── images/ │ ├── train/ │ │ └── 0001.jpg │ └── val/ │ └── 0001.jpg └── labels/ ├── train/ │ └── 0001.txt └── val/ └── 0001.txtclassroom.yaml 里的路径写成相对根目录的方式兼容性最好# classroom.yaml path: ../dataset train: images/train val: images/val nc: 6 names: [sleeping, phone, hand_raising, standing, reading, writing]names 的顺序非常关键。如果标注工具导出的 classes.txt 顺序和这里不一致模型会把“玩手机”识别成“睡觉”。我一般会先看标注工具导出顺序再照抄到 yaml 里绝不凭感觉排。nc 必须和 names 长度一致否则训练脚本会在 shape 检查环节直接报错。标签文件里每一行的归一化坐标也值得检查。比如某一行是2 0.45 0.35 0.12 0.18表示类别 2hand_raising中心点在图像宽高 45% 和 35% 的位置框宽高分别占图像宽高的 12% 和 18%。训练前应该写一个极小的扫描脚本把坐标小于 0 或大于 1 的标签列出来。这类脏数据会造成空标注框Loss 变成 NaN模型直接学崩。2.3 环境安装先锁定 PyTorch 与 CUDA再做 30 秒冒烟测试代码包里的 requirements.txt 通常会固定 torch、torchvision、opencv-python 等版本。不要直接无脑pip install -r requirements.txt因为本机 CUDA 版本不匹配时安装过程看起来正常但训练时模型会退回 CPU 模式速度慢到你怀疑代码包有问题。我先用这条命令确认本机状态python -c import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))如果 cuda.is_available 是 False就去装匹配本机 CUDA 的 PyTorch 版本再回来看 requirements。安装完成后用代码包自带的一张测试图跑一次最简推理这个动作我称为冒烟测试python detect.py --weights yolov5s.pt --source data/images/smoke.jpg --conf 0.25冒烟测试通过说明源码包、依赖、权重文件三条链路是通的。之后训练出问题就不会再花一整晚去查环境问题。这一步成本只有一分钟但能把环境问题从模型问题里分离出来排错快很多。2.4 数据划分脚本随机种子定死验证集分布训练和验证的划分如果每次随机种子不同你看到的 mAP 会忽高忽低很难判断模型改得好不好。我在接入行为检测代码包时会把数据划分脚本固定下来并把划分结果落盘import random from pathlib import Path random.seed(2025) image_root Path(raw_images) train_out Path(dataset/images/train) val_out Path(dataset/images/val) images list(image_root.glob(*.jpg)) random.shuffle(images) val_count int(len(images) * 0.2) for img in images: label image_root / (img.stem .txt) if img in images[:val_count]: dest_img val_out / img.name dest_lbl Path(dataset/labels/val) / label.name else: dest_img train_out / img.name dest_lbl Path(dataset/labels/train) / label.name dest_img.parent.mkdir(parentsTrue, exist_okTrue) dest_lbl.parent.mkdir(parentsTrue, exist_okTrue) img.rename(dest_img) label.rename(dest_lbl)这里的 20% 是行为检测场景里比较稳的比例。教室行为类别分布差异大如果验证集只有几十张很可能一个睡觉样本都没有验证分数完全失真。运行完要检查 images 和 labels 的文件数是否一致这一步我会做成一个简单的 pytest 入口每次数据更新都跑一遍。还有一件容易被忽略的事分类别统计一下验证集里的目标数量尽量保证每个类别在 train 和 val 里都有出现避免“训练时见过手机、验证时一张手机都没有”这种假 mAP。2.5 标签清洗过滤空标签、重复标注和损坏图片标注数据并非越多越好。行为检测这类任务标注员会因为“睡觉”和“趴桌”分不清产生大量边界模糊框。我的经验是模型第一版跑出来的错误很大比例可以从标签里找到根源。空标签文件会让模型隐式学出一种背景分支数量多了之后误检率明显上升。重复标注则会造成同一个目标有两个重叠框训练时计算 loss 会来回拉扯。损坏 JPEG 会在 mosaic 增强时读入半个文件导致这一轮训练 Loss 骤降或直接中断。我常用的清洗脚本如下from PIL import Image from pathlib import Path for img_path in Path(dataset/images).rglob(*.jpg): try: Image.open(img_path).load() except Exception: print(损坏图片:, img_path) img_path.unlink()这份清洗动作在训练前执行一次之后每次扩展数据集时再执行一次能明显减少“训练到第三天突然 OOM”的玄学问题。数据准备做到这个程度再去开训练命令后面调参时的心智负担会小很多。3. 训练参数设置预训练模型、输入尺寸与增强策略的调优方向3.1 预训练模型怎么选COCO 权重迁移到教室行为的边界行为检测代码包默认给出 YOLOv5s 和 YOLOv5m 两个尺寸。我的建议是从 s 起步因为教室行为标注工程通常只有几万张图属于中小规模数据量s 模型在显存占用和实时推理上的压力最小。等你把类别数、输入尺寸、置信度阈值这些变量都理清楚再切到 m 去刷精度才是合理的路线。不要跳过预训练权重。COCO 预训练权重前几层已经学到颜色、边缘、纹理等底层特征后层则学到了通用形状结构这些能力可以迁移到“睡觉”“举手”这类行为因为行为识别的外观特征依然来自人、手机、书本这些物理目标。真正需要重新学的是最后分类器层的类别分布所以在训练日志里看到Transferred 346/365 layers属于正常提示那几十层没有迁移的正好是分类和回归头由随机初始化重新训练。如果在本地小数据集上从 0 开始训练收敛会慢很多而且容易陷在局部最优。我试过按社区里瞎传的“从随机权重练起防过拟合”做法结果 mAP 卡在 0.3 上不去后来换回预训练权重同样参数直接到 0.7。行为检测在这个问题上没有例外回头路可走。3.2 训练命令与核心参数从 batch 到 mosaic 的取舍YOLOv5 的训练入口是 train.py我用得最多的一条命令长这样python train.py \ --data classroom.yaml \ --weights yolov5s.pt \ --img 640 \ --batch 16 \ --epochs 80 \ --device 0 \ --multi-scale \ --mosaic 1.0--img 640 表示训练时把输入图缩放到 640×640。更高的 1280 对检测小目标有好处但显存占用和训练时间会非线性上升。教室监控画面中如果摄像头覆盖的是半个教室学生头部大约 40×60 像素640 就能用如果覆盖一整间大教室学生头部只有 20 像素我会先用 768 做一轮对比再决定是否上 960。--batch 16 在 8GB 显存上比较安全显存不够就先降到 8同时加 --accumulate 来模拟大 batch。--mosaic 1.0 表示每张训练图由四张图拼接这个增强在密集目标场景帮助明显但它也会短暂打乱 loss 曲线让 loss 出现周期抖动这是正常现象。看曲线时不要被单次尖峰吓到。还应该用 --cache 参数把训练图缓存进内存如果服务器内存够 32GB 的话。教室图像集模型加载速度会快一大截训练时不会因为频繁读磁盘把 GPU 利用率拉低。若内存不足且有机械硬盘拖后腿训练等待时间会非常感人。3.3 训练验证mAP、PR 曲线和 loss 曲线怎么配合看训练停止时不要只盯着 best.pt 的 mAP。mAP 是一个汇总值两个模型可能 mAP 一样但实际行为检测表现完全不同。我会同时看三个东西loss 曲线的 trendval 正常 rebalancing分类别 PR 曲线。如果 mAP0.5 高但 mAP0.5:0.95 很低说明模型检测到的框定位精度差。行为检测场景里监考人员更关心“有没有这个人站起来”而不是框精确到什么程度所以 mAP0.5 的重要性高于 COCO 风格的长程均值。用自带的 val.py 或代码包里的验证脚本可以输出每个类别的 AP 值。我把这个表当作“行为检测体检报告”。比如 sleeping 的 AP 远低于 phone那问题大概率在标签数量或标签一致性而不是模型。此时增加训练轮数是没有意义的应该回去补数据。训练产生的 runs/train/exp 目录下会有 results.csv把它按列画线观察 val loss 在 epoch 60 之后是否还稳定下降。如果 val loss 开始回升而训练 loss 还在降那就是过拟合应该提前停掉而不是继续等到 80 epoch。我用 early stopping 的逻辑只在 val loss 连续 10 个 epoch 没有改善时切到 last.pt 之前保存的快照。3.4 超参数文件不动的代码包也能调行为分类YOLOv5 默认的 hyp 文件是针对 COCO 调的换到教室行为这个小数据场景有两处我经常改。第一处是 weight_decay默认值约 0.0005数据量不足 5000 张时这个值偏大模型权重被压制小目标框不稳定。第二处是 cls_pw睡觉样本可能只有手机样本的三分之一需要适当提高分类损失权重。我把修改放到一个独立的 hyp 文件不改代码包源码# hyp.classroom.yaml lr0: 0.01 lrf: 0.01 momentum: 0.85 weight_decay: 0.00025 warmup_epochs: 3 cls_pw: 1.2然后在训练命令后追加--hyp hyp.classroom.yaml。这样代码包保持原样对比实验时只要切换不同的 hyp 文件就可以清楚隔离变量。momentum 从 0.937 降到 0.85 会让训练更稳但收敛稍慢配合 warmup_epochs 3 比较合适。在实际部署中我一般只动 weight_decay 和 cls_pw其他维持源码默认减少变量干扰。4. 推理验证与工程化部署从单张图片到视频流的检测链路4.1 detect.py 快速验证置信度阈值与 IoU 阈值的组合判断训练完成后先用代码包里的 detect.py 跑一遍测试目录不要急着上视频流。单张测试才能看清模型到底学到了什么视频流里的动态干扰容易让人误判。常用命令如下python detect.py \ --weights runs/train/exp/best.pt \ --source test_images/ \ --conf 0.25 \ --iou 0.45 \ --save-txt \ --save-conf--conf 0.25 表示置信度超过 25% 才输出。教室多目标场景我习惯先用 0.25再降到 0.2 对比是否漏检增加。--iou 0.45 是 NMS 的 IoU 阈值数值越低抑制越狠。学生坐得很密时相邻两个目标高度重叠0.45 很容易把后排的人吞掉这时可以调到 0.5 或 0.55 再观察。输出结果里同时保存的labels/和 图片画框图和真实标注做叠加对比。如果大量把“站立”错检成“睡觉”大概率是标注边界问题或视角问题而不是继续训练能解决的。单帧验证通过后才进入部署环节。4.2 导出 ONNXCPU 服务器与老旧推理机的现实选择很多教室监控的现场机房没有独立显卡只有 CPU 服务器。PyTorch 直接在 CPU 上推理速度会让人崩溃。一般做法是把 best.pt 导出成 ONNX再交给 OpenCV DNN 或 ONNX Runtime 推理python export.py --weights runs/train/exp/best.pt --include onnx --opset 12 --simplify导出时有一个我踩过多次的坑训练时用了 --multi-scale模型没有固定输入尺寸导出 ONNX 时会取一个批量维度但后续部署代码如果用了不同的 imgsz前处理会 resize 到不一致的尺寸导致输出坐标错乱。我通常导出时就固定--img 640部署端也跟随 640统一预处理的填充方式。ONNX 模型冷暖不均时教室窗户外阳光导致局部过曝OpenCV 推理的预处理要按训练时的 normalize 参数来。很多同学直接把像素值除以 255 就开始推理忘记了原代码在训练时用的标准化手段结果是 mAP 很高现场完全不可用。我把blobFromImage(frame, 1/255.0, (640, 640), swapRBTrue)这一步当成固定模板每次导出和部署都核对一遍。4.3 视频流接入抽帧、断线重连和结果回传教室行为检测业务上更多是接多路 RTSP 视频流对推理程序的稳定性要求比单张高得多。我常用的最小推理结构是import cv2 cap cv2.VideoCapture(rtsp://your-camera-stream) model cv2.dnn.readNetFromONNX(best.onnx) frame_count 0 lost_count 0 while True: ok, frame cap.read() if not ok: lost_count 1 if lost_count 10: cap.release() cap cv2.VideoCapture(rtsp://your-camera-stream) lost_count 0 continue lost_count 0 frame_count 1 if frame_count % 5 ! 0: continue blob cv2.dnn.blobFromImage(frame, 1/255.0, (640, 640), swapRBTrue) model.setInput(blob) detections model.forward() # 后续把 detections 映射回原图坐标存入行为事件这个脚本关键是抽帧而非逐帧分析。25 帧/秒的视频降到 5 帧/秒CPU 占用能降一半以上而行为识别这种相对慢速的动作不会漏掉。参数 frame_count 的 5 是“抽帧间隔”如果你接的是 15 帧摄像头可以改成 3保证每秒处理 5 帧左右。lost_count 是断线重连计数RTSP 流长时间运行后会偶发断开没有重连逻辑的进程会一直退出或卡死。结果回传部分我会把检测到的行为类别、置信度、目标中心坐标、时间戳拼成一行 JSON写进本地队列再异步上报。不要直接在全局 executive 循环里访问数据库或写日志文件避免推理阻塞导致画面丢帧。教室行为检测系统的工程价值很大程度体现在这里。4.4 坐标映射模型输出坐标到原画面的正确换算ONNX 输出是归一化坐标部署时要把它们换算到原视频画面的像素坐标系。常见错误是将归一化坐标直接乘上原图宽高而忘了预处理时的 letterbox padding。YOLOv5 的前处理通常会把原图缩放到 640×640同时留下灰边推理坐标是相对于加边之后画面的。因此要保存 pad 和 scale 信息def post_process(boxes, scale, pad): x_center, y_center, w, h boxes[:, 0], boxes[:, 1], boxes[:, 2], boxes[:, 3] x1 (x_center - w / 2 - pad[0]) / scale y1 (y_center - h / 2 - pad[1]) / scale x2 (x_center w / 2 - pad[0]) / scale y2 (y_center h / 2 - pad[1]) / scale return np.stack([x1, y1, x2, y2], axis-1)scale 是原图到 640 的缩放比例pad 是被填充的灰边宽度。这里只要写错一个画框位置就会整体偏移。教室的课桌区域对框定位非常敏感框偏移半个身位就会导致行为归因到隔壁学生身上因此这个函数务必单独做单元测试。5. 避坑指南教室行为检测训练部署的五个真实翻车点5.1 现象训练 mAP 很高现场检测率却惨不忍睹有一次我把行为检测模型训练到 mAP0.5 接近 0.9以为可以直接部署到教学楼结果现场画面里三分之一的学生都没被识别出来。原因分析到最后是训练集图片全部来自一个年级同一间教室座位排列、颜色、摄像头视角高度相似模型把这间教室的“环境细节”当成关键特征。解决方法是把不同教室、不同摄像头高度的录像混合进训练集并且验证集按教室来源分组抽样。在那之后我强制要求至少包含三个不同物理环境的图片再开始训练。数据来源的多样性比多调 0.01 学习率重要得多。5.2 现象睡觉行为被大量识别成趴桌或低头现象就是模型把闭眼睡觉的学生框成 normal 或者 writing。原因在于“睡觉”和“趴桌”在视觉上没有清晰边界尤其是侧面视角头部低垂和看书姿态几乎一样。解决方法是重新定类别标注规范睡觉必须包含闭眼或头部低于桌沿且持续时间长两个条件趴桌单帧如果无法判断就归到不感兴趣的背景类避免模型学到一个混淆分类。同时清洗已经标好的边界样本把明显贴边的标签全部重标。行为检测的标注规范如果没有人盯模型再训练也救不回来。5.3 现象手机目标太小置信度一直很低小目标问题在教室里非常突出。一支手机在整教室画面里可能只有 12×30 像素模型在小特征图上几乎无法分辨。原因不只是 imgsz 低而是训练集中手机目标的正样本数量远少于其他类别。解决办法有三步先提高 imgsz 到 768 做一个对比再把手机特写片段单独抽帧并入训练集提升小目标比例最后适当调高 hyp 里 cls_pw让损失函数更关注少数类别。我还发现用小目标切片抽帧训练时不要只截手机局部还要保留周围十几像素背景否则推理时模型的上下文信息不够误报反而增加。5.4 现象GPU 显存充足但训练中途报 CUDA out of memory这个现象很迷惑单张卡 24GB看起来没吃满却中途 OOM。原因通常是 mosaic 增强把四张大图同时加载到显存计算再加上自动锚点计算阶段的临时 buffer峰值占用远超平均值。解决方法是先降低 batch 一半确认训练能过第一个 epoch再逐步加 batch 并配合--accumulate。如果降到 batch 4 仍然 OOM就要检查代码包所在磁盘是不是满了因为 YOLOv5 会把缓存图片写到临时目录磁盘满了也会表现为显存异常。另外损坏图片在 mosaic 阶段读取时会额外申请临时内存这也是隐藏的显存杀手。5.5 现象导出 ONNX 后行为类别全部错乱部署端加载 ONNX 模型后检测框数量正常但类别名对不上比如一直输出睡觉而原模型训练时明明是手机。原因大多出在导出前的 names 顺序不一致。训练时 yaml 里 names 顺序已经固定但 export 后如果部署代码从另一个coco.names或旧版classes.txt读取类别就会发生错位。解决办法是在导出脚本和部署端同时固定从一个 yaml 读取 names禁止手工复制列表。另一个原因是导出时模型权重路径写错加载了上次实验的旧权重。我在部署目录里会专门建立一个deploy_config.yaml把权重路径、names 顺序、imgsz、conf 阈值全部放一起每次发布前用 sha256 校验 best.pt 和 ONNX 是否对应从根上杜绝类别错乱和版本串台。6. 进阶技巧把单帧检测升级成行为时序判罚一个滑动窗口方案单帧检测只能告诉你“这一刻有个人低头”但业务方想知道的是“这个学生是不是已经睡了超过两分钟”。如果每一帧低头都上报系统会被噪声淹没。教室行为检测系统的价值恰好体现在如何把单帧结果稳定成行为事件。我在推理脚本里维护一个滑动窗口缓存每个类别对应一个固定长度的 deque每处理一帧就更新一次窗口内比例超过阈值才触发行为判定from collections import deque window_size 15 # 保持与抽帧间隔联动5帧/秒下等于3秒 threshold 0.7 # 窗口内出现比例阈值 behavior_state {cls_id: deque(maxlenwindow_size) for cls_id in range(6)} def judge_behavior(cls_results): for cls_id in range(6): behavior_state[cls_id].append(1 if cls_results.get(cls_id) else 0) active {} for cls_id, queue in behavior_state.items(): if len(queue) window_size: continue ratio sum(queue) / window_size active[cls_id] ratio threshold return active这段逻辑看起来简单真正部署后会发现它抑制抖动的效果非常明显。我用 15 帧窗口、0.7 阈值把“睡觉误报”从每节课二十多次降到三次以内。参数 window_size 和 threshold 必须和抽帧间隔联动上面代码里假设 5 帧/秒15 帧约等于 3 秒如果你改成每秒处理 2 帧窗口至少要 40 才够覆盖 20 秒的持续行为。阈值 0.7 的意思是一秒内大约 7 帧里有 5 帧被检测成睡觉才算事件成立这个比例可以根据现场误报情况上下浮动。这个升级方案并不增加训练成本只改部署端但在交付验收时给用户的感受是完全不同的单帧系统像演示 Demo滑动窗口系统才像行为管理软件。后来我每次接入新的教室数据都会强制走一遍“单帧置信度过滤 → 滑动窗口时序判定 → 业务上报”的三层链路把窗口长度、抽帧间隔、上报接口三处参数确认时间戳一致再也不会出现现场屏幕上一个人同时“既睡觉又举手”的尴尬。掉过一次这种坑之后就长了记性希望帮到你。本文还有配套的精品资源点击获取
简介面向智慧校园场景的YOLOv5教室行为检测系统代码包主要服务教育信息化开发者、AI初学者及教学管理人员可解决课堂中人数统计、学生行为检测与老师行为检测等多维管理需求。包体非常轻量共5个文件以HTML、JavaScript前端文件为主配合TODO.md、.inscode及.gitignore其中HTML/JS构成可视化入口TODO.md记录待办与扩展方向.gitignore便于工程化同步整个zip压缩包仅12KB适合快速拉取预览。目前已有40人浏览学习。描述中覆盖了从数据预处理、模型训练到推理部署、可视化交互的完整模块划分并提及学生端坐、举手提问、低头书写及教师板书、巡视等课堂行为识别维度虽然受限于包体规模并非完整训练工程但保留了清晰的目录结构与后续优化线索适合需要快速了解YOLOv5课堂行为检测方案、搭建演示原型或做二次开发的读者。1. 教室行为检测为什么比通用目标检测更“吃代码”这套 YOLOv5 代码包要怎么拆通用目标检测在公开数据集上跑出再漂亮的精度搬到教室监控画面里往往直接翻车学生目标小、互相遮挡、动作相似同一个权重在别的场景好用的进教室就频繁漏检和误报。教室行为检测系统这份代码包本质上不是“YOLOv5 换了个名字”而是把数据标注规则、训练参数、推理平滑策略都围绕教室座椅场景重新调了一遍的源码工程。它解决的问题是学生睡觉、玩手机、举手、站立、读写等行为的自动检测与汇总适合正在开发校园行为管理软件的人适合给安防集成商做现场验证的工程师也适合想拿真实工程结构做课设修改的新手。它比普通目标检测示例多出来的部分正是最需要在本地复刻的工程边界。2. 代码包结构和数据准备把下载的源码包改造成能直接训练的工程2.1 先看目录边界数据区高频改算法区只读解压代码包后我一般留 10 分钟做目录巡查这个时间在后续排错中会被十倍省回来。教室行为检测工程延续了 YOLOv5 系列的布局但增加了一些自定义目录典型的文件树长这样classroom-detect/ ├── data/ │ ├── classroom.yaml │ └── images/ # 按 train/val 划分的原始图片 ├── labels/ # 与 images 同名的 YOLO 格式标签 ├── models/ │ ├── yolov5s.yaml │ └── yolov5m.yaml ├── utils/ ├── runs/ # 训练输出、best.pt、测试结果 ├── train.py ├── detect.py ├── export.py └── requirements.txtdata/classroom.yaml 是训练入口必须读的核心文件类别名、类别数量、训练集路径都写在这里。labels 目录则是逐张图片对应的标注文件每个 .txt 里每一行代表一个目标框格式是class_id cx cy w h。models 目录我建议只读除非你要自己加注意力模块否则行为检测这种任务不需要动网络结构先把损失函数、I/O、NMS 这几个参数吃透更重要。utils 里是锚点计算、数据增强、损失计算等底层逻辑我的习惯是只读不写避免后续拉新数据时静默改坏行为。真正需要高频修改的是 data、labels 和 runs。data 决定模型学什么labels 决定学得准不准runs 是实验结果删掉旧的 runs 再做对比实验视角会更清楚。很多人拿到代码包直接把整包丢进去跑遇到问题也不知道是代码问题、数据问题还是参数问题就是没做第一步的目录边界划分。2.2 最小数据集合images、labels 与 classroom.yaml 的三者对应YOLO 格式有一个容易翻车的地方训练时给的路径是 images 目录但代码会自动去同级的 labels 目录找同名标签。如果标注文件被放在 images 里面训练日志会提示找不到标签然后悄悄跳过大量图片。我见过有一个小组 5000 张验证图实际参与评估的只有 300 张原因就是 labels 目录和 images 目录的对应写错了。正确结构应该是dataset/ ├── images/ │ ├── train/ │ │ └── 0001.jpg │ └── val/ │ └── 0001.jpg └── labels/ ├── train/ │ └── 0001.txt └── val/ └── 0001.txtclassroom.yaml 里的路径写成相对根目录的方式兼容性最好# classroom.yaml path: ../dataset train: images/train val: images/val nc: 6 names: [sleeping, phone, hand_raising, standing, reading, writing]names 的顺序非常关键。如果标注工具导出的 classes.txt 顺序和这里不一致模型会把“玩手机”识别成“睡觉”。我一般会先看标注工具导出顺序再照抄到 yaml 里绝不凭感觉排。nc 必须和 names 长度一致否则训练脚本会在 shape 检查环节直接报错。标签文件里每一行的归一化坐标也值得检查。比如某一行是2 0.45 0.35 0.12 0.18表示类别 2hand_raising中心点在图像宽高 45% 和 35% 的位置框宽高分别占图像宽高的 12% 和 18%。训练前应该写一个极小的扫描脚本把坐标小于 0 或大于 1 的标签列出来。这类脏数据会造成空标注框Loss 变成 NaN模型直接学崩。2.3 环境安装先锁定 PyTorch 与 CUDA再做 30 秒冒烟测试代码包里的 requirements.txt 通常会固定 torch、torchvision、opencv-python 等版本。不要直接无脑pip install -r requirements.txt因为本机 CUDA 版本不匹配时安装过程看起来正常但训练时模型会退回 CPU 模式速度慢到你怀疑代码包有问题。我先用这条命令确认本机状态python -c import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))如果 cuda.is_available 是 False就去装匹配本机 CUDA 的 PyTorch 版本再回来看 requirements。安装完成后用代码包自带的一张测试图跑一次最简推理这个动作我称为冒烟测试python detect.py --weights yolov5s.pt --source data/images/smoke.jpg --conf 0.25冒烟测试通过说明源码包、依赖、权重文件三条链路是通的。之后训练出问题就不会再花一整晚去查环境问题。这一步成本只有一分钟但能把环境问题从模型问题里分离出来排错快很多。2.4 数据划分脚本随机种子定死验证集分布训练和验证的划分如果每次随机种子不同你看到的 mAP 会忽高忽低很难判断模型改得好不好。我在接入行为检测代码包时会把数据划分脚本固定下来并把划分结果落盘import random from pathlib import Path random.seed(2025) image_root Path(raw_images) train_out Path(dataset/images/train) val_out Path(dataset/images/val) images list(image_root.glob(*.jpg)) random.shuffle(images) val_count int(len(images) * 0.2) for img in images: label image_root / (img.stem .txt) if img in images[:val_count]: dest_img val_out / img.name dest_lbl Path(dataset/labels/val) / label.name else: dest_img train_out / img.name dest_lbl Path(dataset/labels/train) / label.name dest_img.parent.mkdir(parentsTrue, exist_okTrue) dest_lbl.parent.mkdir(parentsTrue, exist_okTrue) img.rename(dest_img) label.rename(dest_lbl)这里的 20% 是行为检测场景里比较稳的比例。教室行为类别分布差异大如果验证集只有几十张很可能一个睡觉样本都没有验证分数完全失真。运行完要检查 images 和 labels 的文件数是否一致这一步我会做成一个简单的 pytest 入口每次数据更新都跑一遍。还有一件容易被忽略的事分类别统计一下验证集里的目标数量尽量保证每个类别在 train 和 val 里都有出现避免“训练时见过手机、验证时一张手机都没有”这种假 mAP。2.5 标签清洗过滤空标签、重复标注和损坏图片标注数据并非越多越好。行为检测这类任务标注员会因为“睡觉”和“趴桌”分不清产生大量边界模糊框。我的经验是模型第一版跑出来的错误很大比例可以从标签里找到根源。空标签文件会让模型隐式学出一种背景分支数量多了之后误检率明显上升。重复标注则会造成同一个目标有两个重叠框训练时计算 loss 会来回拉扯。损坏 JPEG 会在 mosaic 增强时读入半个文件导致这一轮训练 Loss 骤降或直接中断。我常用的清洗脚本如下from PIL import Image from pathlib import Path for img_path in Path(dataset/images).rglob(*.jpg): try: Image.open(img_path).load() except Exception: print(损坏图片:, img_path) img_path.unlink()这份清洗动作在训练前执行一次之后每次扩展数据集时再执行一次能明显减少“训练到第三天突然 OOM”的玄学问题。数据准备做到这个程度再去开训练命令后面调参时的心智负担会小很多。3. 训练参数设置预训练模型、输入尺寸与增强策略的调优方向3.1 预训练模型怎么选COCO 权重迁移到教室行为的边界行为检测代码包默认给出 YOLOv5s 和 YOLOv5m 两个尺寸。我的建议是从 s 起步因为教室行为标注工程通常只有几万张图属于中小规模数据量s 模型在显存占用和实时推理上的压力最小。等你把类别数、输入尺寸、置信度阈值这些变量都理清楚再切到 m 去刷精度才是合理的路线。不要跳过预训练权重。COCO 预训练权重前几层已经学到颜色、边缘、纹理等底层特征后层则学到了通用形状结构这些能力可以迁移到“睡觉”“举手”这类行为因为行为识别的外观特征依然来自人、手机、书本这些物理目标。真正需要重新学的是最后分类器层的类别分布所以在训练日志里看到Transferred 346/365 layers属于正常提示那几十层没有迁移的正好是分类和回归头由随机初始化重新训练。如果在本地小数据集上从 0 开始训练收敛会慢很多而且容易陷在局部最优。我试过按社区里瞎传的“从随机权重练起防过拟合”做法结果 mAP 卡在 0.3 上不去后来换回预训练权重同样参数直接到 0.7。行为检测在这个问题上没有例外回头路可走。3.2 训练命令与核心参数从 batch 到 mosaic 的取舍YOLOv5 的训练入口是 train.py我用得最多的一条命令长这样python train.py \ --data classroom.yaml \ --weights yolov5s.pt \ --img 640 \ --batch 16 \ --epochs 80 \ --device 0 \ --multi-scale \ --mosaic 1.0--img 640 表示训练时把输入图缩放到 640×640。更高的 1280 对检测小目标有好处但显存占用和训练时间会非线性上升。教室监控画面中如果摄像头覆盖的是半个教室学生头部大约 40×60 像素640 就能用如果覆盖一整间大教室学生头部只有 20 像素我会先用 768 做一轮对比再决定是否上 960。--batch 16 在 8GB 显存上比较安全显存不够就先降到 8同时加 --accumulate 来模拟大 batch。--mosaic 1.0 表示每张训练图由四张图拼接这个增强在密集目标场景帮助明显但它也会短暂打乱 loss 曲线让 loss 出现周期抖动这是正常现象。看曲线时不要被单次尖峰吓到。还应该用 --cache 参数把训练图缓存进内存如果服务器内存够 32GB 的话。教室图像集模型加载速度会快一大截训练时不会因为频繁读磁盘把 GPU 利用率拉低。若内存不足且有机械硬盘拖后腿训练等待时间会非常感人。3.3 训练验证mAP、PR 曲线和 loss 曲线怎么配合看训练停止时不要只盯着 best.pt 的 mAP。mAP 是一个汇总值两个模型可能 mAP 一样但实际行为检测表现完全不同。我会同时看三个东西loss 曲线的 trendval 正常 rebalancing分类别 PR 曲线。如果 mAP0.5 高但 mAP0.5:0.95 很低说明模型检测到的框定位精度差。行为检测场景里监考人员更关心“有没有这个人站起来”而不是框精确到什么程度所以 mAP0.5 的重要性高于 COCO 风格的长程均值。用自带的 val.py 或代码包里的验证脚本可以输出每个类别的 AP 值。我把这个表当作“行为检测体检报告”。比如 sleeping 的 AP 远低于 phone那问题大概率在标签数量或标签一致性而不是模型。此时增加训练轮数是没有意义的应该回去补数据。训练产生的 runs/train/exp 目录下会有 results.csv把它按列画线观察 val loss 在 epoch 60 之后是否还稳定下降。如果 val loss 开始回升而训练 loss 还在降那就是过拟合应该提前停掉而不是继续等到 80 epoch。我用 early stopping 的逻辑只在 val loss 连续 10 个 epoch 没有改善时切到 last.pt 之前保存的快照。3.4 超参数文件不动的代码包也能调行为分类YOLOv5 默认的 hyp 文件是针对 COCO 调的换到教室行为这个小数据场景有两处我经常改。第一处是 weight_decay默认值约 0.0005数据量不足 5000 张时这个值偏大模型权重被压制小目标框不稳定。第二处是 cls_pw睡觉样本可能只有手机样本的三分之一需要适当提高分类损失权重。我把修改放到一个独立的 hyp 文件不改代码包源码# hyp.classroom.yaml lr0: 0.01 lrf: 0.01 momentum: 0.85 weight_decay: 0.00025 warmup_epochs: 3 cls_pw: 1.2然后在训练命令后追加--hyp hyp.classroom.yaml。这样代码包保持原样对比实验时只要切换不同的 hyp 文件就可以清楚隔离变量。momentum 从 0.937 降到 0.85 会让训练更稳但收敛稍慢配合 warmup_epochs 3 比较合适。在实际部署中我一般只动 weight_decay 和 cls_pw其他维持源码默认减少变量干扰。4. 推理验证与工程化部署从单张图片到视频流的检测链路4.1 detect.py 快速验证置信度阈值与 IoU 阈值的组合判断训练完成后先用代码包里的 detect.py 跑一遍测试目录不要急着上视频流。单张测试才能看清模型到底学到了什么视频流里的动态干扰容易让人误判。常用命令如下python detect.py \ --weights runs/train/exp/best.pt \ --source test_images/ \ --conf 0.25 \ --iou 0.45 \ --save-txt \ --save-conf--conf 0.25 表示置信度超过 25% 才输出。教室多目标场景我习惯先用 0.25再降到 0.2 对比是否漏检增加。--iou 0.45 是 NMS 的 IoU 阈值数值越低抑制越狠。学生坐得很密时相邻两个目标高度重叠0.45 很容易把后排的人吞掉这时可以调到 0.5 或 0.55 再观察。输出结果里同时保存的labels/和 图片画框图和真实标注做叠加对比。如果大量把“站立”错检成“睡觉”大概率是标注边界问题或视角问题而不是继续训练能解决的。单帧验证通过后才进入部署环节。4.2 导出 ONNXCPU 服务器与老旧推理机的现实选择很多教室监控的现场机房没有独立显卡只有 CPU 服务器。PyTorch 直接在 CPU 上推理速度会让人崩溃。一般做法是把 best.pt 导出成 ONNX再交给 OpenCV DNN 或 ONNX Runtime 推理python export.py --weights runs/train/exp/best.pt --include onnx --opset 12 --simplify导出时有一个我踩过多次的坑训练时用了 --multi-scale模型没有固定输入尺寸导出 ONNX 时会取一个批量维度但后续部署代码如果用了不同的 imgsz前处理会 resize 到不一致的尺寸导致输出坐标错乱。我通常导出时就固定--img 640部署端也跟随 640统一预处理的填充方式。ONNX 模型冷暖不均时教室窗户外阳光导致局部过曝OpenCV 推理的预处理要按训练时的 normalize 参数来。很多同学直接把像素值除以 255 就开始推理忘记了原代码在训练时用的标准化手段结果是 mAP 很高现场完全不可用。我把blobFromImage(frame, 1/255.0, (640, 640), swapRBTrue)这一步当成固定模板每次导出和部署都核对一遍。4.3 视频流接入抽帧、断线重连和结果回传教室行为检测业务上更多是接多路 RTSP 视频流对推理程序的稳定性要求比单张高得多。我常用的最小推理结构是import cv2 cap cv2.VideoCapture(rtsp://your-camera-stream) model cv2.dnn.readNetFromONNX(best.onnx) frame_count 0 lost_count 0 while True: ok, frame cap.read() if not ok: lost_count 1 if lost_count 10: cap.release() cap cv2.VideoCapture(rtsp://your-camera-stream) lost_count 0 continue lost_count 0 frame_count 1 if frame_count % 5 ! 0: continue blob cv2.dnn.blobFromImage(frame, 1/255.0, (640, 640), swapRBTrue) model.setInput(blob) detections model.forward() # 后续把 detections 映射回原图坐标存入行为事件这个脚本关键是抽帧而非逐帧分析。25 帧/秒的视频降到 5 帧/秒CPU 占用能降一半以上而行为识别这种相对慢速的动作不会漏掉。参数 frame_count 的 5 是“抽帧间隔”如果你接的是 15 帧摄像头可以改成 3保证每秒处理 5 帧左右。lost_count 是断线重连计数RTSP 流长时间运行后会偶发断开没有重连逻辑的进程会一直退出或卡死。结果回传部分我会把检测到的行为类别、置信度、目标中心坐标、时间戳拼成一行 JSON写进本地队列再异步上报。不要直接在全局 executive 循环里访问数据库或写日志文件避免推理阻塞导致画面丢帧。教室行为检测系统的工程价值很大程度体现在这里。4.4 坐标映射模型输出坐标到原画面的正确换算ONNX 输出是归一化坐标部署时要把它们换算到原视频画面的像素坐标系。常见错误是将归一化坐标直接乘上原图宽高而忘了预处理时的 letterbox padding。YOLOv5 的前处理通常会把原图缩放到 640×640同时留下灰边推理坐标是相对于加边之后画面的。因此要保存 pad 和 scale 信息def post_process(boxes, scale, pad): x_center, y_center, w, h boxes[:, 0], boxes[:, 1], boxes[:, 2], boxes[:, 3] x1 (x_center - w / 2 - pad[0]) / scale y1 (y_center - h / 2 - pad[1]) / scale x2 (x_center w / 2 - pad[0]) / scale y2 (y_center h / 2 - pad[1]) / scale return np.stack([x1, y1, x2, y2], axis-1)scale 是原图到 640 的缩放比例pad 是被填充的灰边宽度。这里只要写错一个画框位置就会整体偏移。教室的课桌区域对框定位非常敏感框偏移半个身位就会导致行为归因到隔壁学生身上因此这个函数务必单独做单元测试。5. 避坑指南教室行为检测训练部署的五个真实翻车点5.1 现象训练 mAP 很高现场检测率却惨不忍睹有一次我把行为检测模型训练到 mAP0.5 接近 0.9以为可以直接部署到教学楼结果现场画面里三分之一的学生都没被识别出来。原因分析到最后是训练集图片全部来自一个年级同一间教室座位排列、颜色、摄像头视角高度相似模型把这间教室的“环境细节”当成关键特征。解决方法是把不同教室、不同摄像头高度的录像混合进训练集并且验证集按教室来源分组抽样。在那之后我强制要求至少包含三个不同物理环境的图片再开始训练。数据来源的多样性比多调 0.01 学习率重要得多。5.2 现象睡觉行为被大量识别成趴桌或低头现象就是模型把闭眼睡觉的学生框成 normal 或者 writing。原因在于“睡觉”和“趴桌”在视觉上没有清晰边界尤其是侧面视角头部低垂和看书姿态几乎一样。解决方法是重新定类别标注规范睡觉必须包含闭眼或头部低于桌沿且持续时间长两个条件趴桌单帧如果无法判断就归到不感兴趣的背景类避免模型学到一个混淆分类。同时清洗已经标好的边界样本把明显贴边的标签全部重标。行为检测的标注规范如果没有人盯模型再训练也救不回来。5.3 现象手机目标太小置信度一直很低小目标问题在教室里非常突出。一支手机在整教室画面里可能只有 12×30 像素模型在小特征图上几乎无法分辨。原因不只是 imgsz 低而是训练集中手机目标的正样本数量远少于其他类别。解决办法有三步先提高 imgsz 到 768 做一个对比再把手机特写片段单独抽帧并入训练集提升小目标比例最后适当调高 hyp 里 cls_pw让损失函数更关注少数类别。我还发现用小目标切片抽帧训练时不要只截手机局部还要保留周围十几像素背景否则推理时模型的上下文信息不够误报反而增加。5.4 现象GPU 显存充足但训练中途报 CUDA out of memory这个现象很迷惑单张卡 24GB看起来没吃满却中途 OOM。原因通常是 mosaic 增强把四张大图同时加载到显存计算再加上自动锚点计算阶段的临时 buffer峰值占用远超平均值。解决方法是先降低 batch 一半确认训练能过第一个 epoch再逐步加 batch 并配合--accumulate。如果降到 batch 4 仍然 OOM就要检查代码包所在磁盘是不是满了因为 YOLOv5 会把缓存图片写到临时目录磁盘满了也会表现为显存异常。另外损坏图片在 mosaic 阶段读取时会额外申请临时内存这也是隐藏的显存杀手。5.5 现象导出 ONNX 后行为类别全部错乱部署端加载 ONNX 模型后检测框数量正常但类别名对不上比如一直输出睡觉而原模型训练时明明是手机。原因大多出在导出前的 names 顺序不一致。训练时 yaml 里 names 顺序已经固定但 export 后如果部署代码从另一个coco.names或旧版classes.txt读取类别就会发生错位。解决办法是在导出脚本和部署端同时固定从一个 yaml 读取 names禁止手工复制列表。另一个原因是导出时模型权重路径写错加载了上次实验的旧权重。我在部署目录里会专门建立一个deploy_config.yaml把权重路径、names 顺序、imgsz、conf 阈值全部放一起每次发布前用 sha256 校验 best.pt 和 ONNX 是否对应从根上杜绝类别错乱和版本串台。6. 进阶技巧把单帧检测升级成行为时序判罚一个滑动窗口方案单帧检测只能告诉你“这一刻有个人低头”但业务方想知道的是“这个学生是不是已经睡了超过两分钟”。如果每一帧低头都上报系统会被噪声淹没。教室行为检测系统的价值恰好体现在如何把单帧结果稳定成行为事件。我在推理脚本里维护一个滑动窗口缓存每个类别对应一个固定长度的 deque每处理一帧就更新一次窗口内比例超过阈值才触发行为判定from collections import deque window_size 15 # 保持与抽帧间隔联动5帧/秒下等于3秒 threshold 0.7 # 窗口内出现比例阈值 behavior_state {cls_id: deque(maxlenwindow_size) for cls_id in range(6)} def judge_behavior(cls_results): for cls_id in range(6): behavior_state[cls_id].append(1 if cls_results.get(cls_id) else 0) active {} for cls_id, queue in behavior_state.items(): if len(queue) window_size: continue ratio sum(queue) / window_size active[cls_id] ratio threshold return active这段逻辑看起来简单真正部署后会发现它抑制抖动的效果非常明显。我用 15 帧窗口、0.7 阈值把“睡觉误报”从每节课二十多次降到三次以内。参数 window_size 和 threshold 必须和抽帧间隔联动上面代码里假设 5 帧/秒15 帧约等于 3 秒如果你改成每秒处理 2 帧窗口至少要 40 才够覆盖 20 秒的持续行为。阈值 0.7 的意思是一秒内大约 7 帧里有 5 帧被检测成睡觉才算事件成立这个比例可以根据现场误报情况上下浮动。这个升级方案并不增加训练成本只改部署端但在交付验收时给用户的感受是完全不同的单帧系统像演示 Demo滑动窗口系统才像行为管理软件。后来我每次接入新的教室数据都会强制走一遍“单帧置信度过滤 → 滑动窗口时序判定 → 业务上报”的三层链路把窗口长度、抽帧间隔、上报接口三处参数确认时间戳一致再也不会出现现场屏幕上一个人同时“既睡觉又举手”的尴尬。掉过一次这种坑之后就长了记性希望帮到你。本文还有配套的精品资源点击获取
