简介面向智慧校园场景的YOLOv5教室行为检测系统代码包整合人数统计、学生行为识别与教师行为分析能力适合算法开发者、教育信息化工程师用于课堂视觉分析或二次开发。压缩包体积仅12KB共5个文件包含HTML展示页面、JavaScript交互脚本、Markdown说明文档、gitignore及inscode项目配置文件可快速搭建演示界面并理解工程目录结构。系统采用PyTorch与YOLOv5s轻量骨干网络描述中涵盖数据增强、超参数配置、推理部署与可视化交互等模块并预留RESTful API便于与教务平台集成代码包虽未携带训练权重但模块化分层设计清晰可辅助学习工程落地流程。目前已有35人学习适合具备深度学习基础、希望参考检测系统前后端实现或扩展行为识别功能的研发人员。1. 项目概述当YOLOv5走进教室行为检测到底在检测什么先明确一个概念教室行为检测并不是什么黑科技监控本质上它就是目标检测模型在特定场景下的垂直应用。把摄像头画面送进YOLOv5模型输出每个学生的位置框和对应的行为类别——举手、趴桌、站立、玩手机、睡觉、阅读、写字、交头接耳等等。做这个系统的人多半是高校实验室、毕设团队或者想给传统课堂加一点智能化手段的开发者。这个项目最核心的问题有三个环境怎么搭、数据怎么标、模型怎么练。看起来是老生常谈但实际动手时会发现光是PyTorch和CUDA版本匹配就能卡住一大半新手。我写这篇文章的目的就是把我自己从零跑通YOLOv5教室行为检测的全过程复盘一遍包括踩过的坑、试过的参数、改过的代码尽量把每一步的关键决策讲明白。适合正在做相关毕设、课程项目或者想入门目标检测实战的读者。顺便说一句YOLOv5官方仓库虽然是老版本了但它的生态成熟度、资料丰富程度、部署方案多样性至今仍然是工程落地时最稳的选择之一。你不会踩到什么断更没人管的坑因为社区里已经有人把你能想到的报错全部踩过一遍了。2. 整体设计思路拆解为什么是YOLOv5行为检测系统的架构怎么搭2.1 模型选型的底层逻辑每次有人问我行为检测用什么模型我的第一反应永远是反问你的硬件是什么如果是英伟达显卡YOLOv5s或者YOLOv5m完全够用训练快、部署简单、资料多。如果是树莓派、IMX8MP这类边缘设备那就得走YOLOv5s的轻量化路线甚至要转成NCNN或者ONNX Runtime再量化一下。选YOLOv5而不是YOLOv8或者RT-DETR核心原因有三个。第一YOLOv5的代码风格非常工程向detect.py、train.py、val.py拆得清清楚楚改起来不费劲。第二官方仓库自带丰富的预训练权重COCO预训练模型微调到教室场景收敛速度远快于从零训练。第三部署生态成熟——导出ONNX、OpenVINO、TensorRT网上教程一条龙几乎不会卡壳。但这里必须说清楚教室行为检测不等于动作识别。YOLOv5本质是目标检测器它识别的是某个框里有什么物体/姿态而不是这个学生正在做什么连续动作。比如举手和放下手YOLOv5只能检测到举起手的那一帧连续动作需要靠时序模型如LSTM、SlowFast或者简单的帧差法逻辑去判断。很多新手在这里会混淆导致项目做到一半发现效果不理想。2.2 系统整体架构和模块划分一个完整的教室行为检测系统通常由四个模块组成数据采集模块教室监控视频、公开数据集如COCO中的person类、自己拍摄的课堂画面。这里有个小技巧可以直接用现成的课堂视频按帧截取图片作为训练素材远比一张张拍照高效。数据标注模块用LabelImg或labelme对图片中的学生进行框选并打上行为标签。模型训练模块基于YOLOv5官方仓库修改数据配置、调整超参数训练自己的检测器。推理部署模块加载训练好的权重对实时视频流或单张图片进行推理输出带有行为类别标签的检测结果。打通这四块之后你手上的YOLOv5才算真正变成了一个教室行为检测系统而不是一个跑通的demo。下面我把每一个模块的实操细节和关键决策展开讲。3. 环境搭建与核心代码讲解YOLOv5模型训练环境搭建全流程3.1 版本选型和安装步骤YOLOv5对不同PyTorch版本、Python版本的兼容性其实相当宽松但为了少踩坑我推荐一套经过验证的组合Python 3.8/3.9 PyTorch 1.12/2.0 CUDA 11.6/11.8。如果你用的是新一点的显卡比如RTX 30/40系CUDA 11.8是稳妥的选择。安装步骤拆开来就三步创建虚拟环境建议用conda隔离性好删了重来不心疼conda create -n yolov5 python3.9 conda activate yolov5安装PyTorch。这里注意不要直接pip install torch要用官方源匹配CUDA版本pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118克隆YOLOv5仓库并安装依赖git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txt装完依赖后强烈建议先跑一次官方推理测试环境有没有问题python detect.py --weights yolov5s.pt --source data/images/bus.jpg如果能在runs/detect/下看到标注好的输出图恭喜你环境已经通了。这一步能帮你把环境问题和模型问题彻底隔离后面训练出错了不用怀疑是CUDA没配好。3.2 环境配置的几个隐性坑关于环境大多数报错都集中在显卡驱动和PyTorch版本不对应上。你可以先用nvidia-smi查看驱动支持的CUDA版本上限再决定安装哪个CUDA版本的PyTorch。比如驱动显示CUDA Version 12.2那安装cu118或者cu121都行。另一个容易忽略的是OpenCV版本冲突。YOLOv5的requirements里锁定了opencv-python版本范围如果你之前装过新版OpenCV可能出现cv2.error: Unknown C error之类的诡异问题。处理方式很粗暴但有效按requirements里锁定的版本重装一次。我自己的习惯是在环境装好之后立刻做一次快照导出方便以后复现pip freeze requirements_lock.txt这个文件留着换机器或者帮同学配置的时候直接pip install -r requirements_lock.txt省去大量排查时间。4. 训练自己的数据集从标注到出模型的一步步实录4.1 数据采集与标注比想象中更费时间的环节教室行为检测的数据集最理想的情况是目标场景的实拍画面——你要检测的就是你教室的视角、光线、座位排列那用同样的场景数据训练效果当然最好。采集方法很简单用教室监控视频按每秒抽1~2帧截取一个45分钟的课堂大概能抽出两三千张图足够起步了。如果条件有限也可以用公开数据集兜底。这里推荐两个方向一是COCO数据集里的person类做预训练底座二是直接挂载公开的人类行为检测数据集比如PASCAL VOC中的人相关类别。但注意公开数据集的课堂场景多样性通常不足后期还是需要自己补采。标注工具我用的是LabelImg操作逻辑就是画框选标签。对于教室场景建议标签类别控制在6到10个以内多了模型学不过来少了业务上又不够用。我自己的标签方案供参考类别ID标签名称说明0raise_hand举手1writing写字2reading阅读3looking_at_phone看手机4sleeping趴桌睡觉5standing站立6talking交头接耳每个类别至少准备300到500个标注实例总体图片数在1500到3000张之间否则模型很容易过拟合或漏检。标注时有一个细节遮挡严重的、太小的目标可以适当放弃它们带来的噪声远大于信息量。4.2 数据集格式转换与目录组织LabelImg默认输出的是Pascal VOC格式的XML文件但YOLOv5需要的是YOLO格式的txt标注文件每个标注行为class_id x_center y_center width height其中坐标值是相对于图片宽高的归一化比例取值0到1之间。转换脚本网上很多但我建议自己写一次顺便理解坐标换算的逻辑import xml.etree.ElementTree as ET import os def convert_voc_to_yolo(xml_file, class_names, output_dir): tree ET.parse(xml_file) root tree.getroot() img_w int(root.find(size/width).text) img_h int(root.find(size/height).text) lines [] for obj in root.iter(object): class_name obj.find(name).text if class_name not in class_names: continue class_id class_names.index(class_name) bbox obj.find(bndbox) xmin int(bbox.find(xmin).text) ymin int(bbox.find(ymin).text) xmax int(bbox.find(xmax).text) ymax int(bbox.find(ymax).text) x_center (xmin xmax) / 2 / img_w y_center (ymin ymax) / 2 / img_h width (xmax - xmin) / img_w height (ymax - ymin) / img_h lines.append(f{class_id} {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}) txt_path os.path.join(output_dir, os.path.basename(xml_file).replace(.xml, .txt)) with open(txt_path, w) as f: f.write(\n.join(lines)) class_names [raise_hand, writing, reading, looking_at_phone, sleeping, standing, talking]目录结构按YOLOv5官方要求组织datasets/ ├── classroom/ │ ├── images/ │ │ ├── train/ # 训练集图片 │ │ └── val/ # 验证集图片 │ └── labels/ │ ├── train/ # 训练集标注txt │ └── val/ # 验证集标注txt划分比例我用的是8:2训练集和验证集。还有一个关键划分的时候要按整个视频的时间段切分不要随机打乱。否则同一个学生的连续帧会同时出现在训练集和验证集里导致验证集准确率虚高实际部署效果打折扣。4.3 修改配置文件与启动训练YOLOv5训练需要两个配置文件一个是数据集配置文件描述数据路径和类别一个是模型配置文件定义网络结构。数据集配置文件classroom.yamltrain: datasets/classroom/images/train val: datasets/classroom/images/val nc: 7 names: [raise_hand, writing, reading, looking_at_phone, sleeping, standing, talking]模型配置文件直接用官方自带的yolov5s.yaml把nc改成7就行不需要动网络结构。至于用什么规模的模型我给个建议GPU显存8G以下YOLOv5s训练快部署容易精度尚可GPU显存16G左右YOLOv5m精度明显提升训练时间适中显卡很好且追求极致精度YOLOv5l但训练时间和显存开销大教室场景一般用不上启动训练的命令如下python train.py --data classroom.yaml --weights yolov5s.pt --epochs 100 --batch-size 16 --img 640 --device 0训练结束后权重保存在runs/train/exp/weights/下best.pt是验证集上效果最好的权重last.pt是最后一步的权重。推理时优先用best.pt。5. 推理部署与代码修改让模型在真实场景中跑起来5.1 用detect.py对图片和视频进行推理训练完成后立刻做一次推理测试确认模型在从未见过的教室画面上有可用的表现python detect.py --weights runs/train/exp/weights/best.pt --source test_images/ --conf-thres 0.5--source可以指向图片文件夹、单张图片、视频文件甚至摄像头ID比如0表示笔记本自带摄像头。--conf-thres是置信度阈值默认0.25教室场景建议调到0.4到0.5之间。因为教室目标很密集低阈值会造成大量误检框重叠高阈值可以过滤掉那些看着像但不自信的预测。如果想处理视频流或者实时摄像头可以加--save-txt把每帧的检测结果保存成txt方便后续做行为统计分析。这里有个小坑直接跑视频推理时如果视频分辨率很高帧率会明显下降。可以加--imgsz 640降采样到640分辨率速度和精度能达到一个较好的平衡。5.2 行为检测的后处理逻辑和模块扩展YOLOv5输出的是逐帧的检测结果每个框的坐标、类别、置信度。但行为检测如果只是输出这一帧里有人举手可用性其实不高。真正落地的系统需要做一层后处理——把单帧结果聚合成片段级的行为事件。我自己的实现思路是用队列做滑窗统计每隔几帧输出一次结果把最近3秒钟的检测结果放在一个时间窗口里统计每个学生用检测框的中心坐标作为ID最频繁出现的行为类别作为这一窗口的行为判断。伪代码如下from collections import deque # 用一个字典维护每个目标的历史行为队列 history {} def analyze_behavior(detections, current_time, window_seconds3): results {} for det in detections: obj_id det[id] # 实际项目中可以用跟踪算法生成稳定ID behavior det[class_name] if obj_id not in history: history[obj_id] deque(maxlen30) history[obj_id].append((current_time, behavior)) # 过滤掉超出时间窗口的历史数据 while history[obj_id] and current_time - history[obj_id][0][0] window_seconds: history[obj_id].popleft() # 统计窗口内最频繁的行为 counter Counter([h[1] for h in history[obj_id]]) results[obj_id] counter.most_common(1)[0][0] return results注意这里有个前置条件你需要一个稳定的目标跟踪ID。最简单的做法是直接用YOLOv5的检测框中心点做最近邻匹配但拥挤教室场景下容易串号。进阶做法是接入ByteTrack或DeepSORT跟踪器。我在项目中试过ByteTrack在密集场景下ID切换率明显降低代码量也只是在yolov5的检测结果基础上加一个tack的封装性价比很高。5.3 边缘设备部署树莓派5和NXPi.MX8MP的优化思路很多读者会在树莓派5上部署YOLOv5模型。树莓派5的CPU性能比前代强不少但直接用PyTorch推理速度依旧不理想我实测YOLOv5s在树莓派5上跑640分辨率大概只有2到3 FPS。要让实际可用至少要做到两步优化第一步导出ONNX再转NCNN格式用NCNN的C接口推理。转换命令python export.py --weights best.pt --include onnx # 然后用NCNN工具转换为ncnn.param和ncnn.bin第二步使用--img 416甚至--img 320来推理。教室场景下学生目标相对较大降分辨率对精度影响在可接受范围内但速度能提升三四倍。对于NXPi.MX8MP这类带NPU的边缘平台处理方式和树莓派类似关键是模型转换。IMX8MP的NPU支持量化后的TFLite或者ONNX模型导出后需要用NXP的eIQ Toolkit做量化校准。这里提醒一句量化会掉点尤其对看手机这类小目标掉点可能比较明显。建议在量化之后跑一轮验证集对比mAP变化如果掉点超过3个百分点考虑用YOLOv5s原始精度部署或者换更强的模型。6. 常见问题与排查技巧实录6.1 训练时的经典报错和排查逻辑我在训练YOLOv5的过程中遇到了不少问题挑几个最典型的列出来报错/问题实测原因解决方案CUDA out of memorybatch_size过大或图片分辨率过高调小--batch-size或加--cache换显存为内存AssertionError: train: No labels in ...标注txt缺失或路径指向错误检查images和labels目录是否一一对应文件名是否完全一致mAP0.5一直很低低于0.3标签类别名和yaml对不上或者标注框本身不准检查class_names顺序是否和yaml中一致抽样检查标注框是否贴合目标训练几轮loss变成NaN学习率过高或数据集中有异常标注调低--lr0比如从0.01降到0.001检查是否有宽度或高度为0的标注框每当训练出现诡异问题时我习惯先检查数据再检查参数最后才怀疑代码。大多数情况下问题出在数据集上文件没配对、类别对不上、标注坐标越界等。YOLOv5的train.py启动时会打印标注数量和类别分布花几秒钟看一下就能发现很多隐患。6.2 推理时检测效果不佳的几个优化方向训练完模型在真实教室画面上一测常见的问题是漏检多、误检多、小目标检测不到。针对这些情况我的排查顺序如下漏检多先看置信度阈值是否过高适当降低--conf-thres如果还是漏说明训练样本中该类别的样本量不足回去补标注做数据增强尤其是亮度、色度和翻转增强。误检多优先提高置信度阈值如果高阈值下还是误检大概率是背景太复杂需要采集更多含背景的负样本不包含目标的图片加入训练集。小目标如远处的学生看手机检测不到训练时把--img从640提高到960甚至1280模型能更好识别小目标。代价是训练速度和显存开销会上升。这里有一个我踩过多次的经验值教室行为检测的mAP0.5到0.7之间算合格0.8以上算优秀。不要盲目追求在验证集上刷到0.9以上大概率是数据划分出了问题——训练和验证存在同源重复而不是模型真的那么强。6.3 几个能显著提升体验的实操技巧预处理加速批量推理视频时先把视频抽帧用多线程并发推理再按帧序号重组视频速度比直接推视频流快很多。类别不平衡处理教室场景里写字通常占绝大多数站立和看手机可能很少。训练时可以在--hyp超参数文件里调大稀有类别的loss权重或者用--class-balance开启自动类别平衡。利用早停策略YOLOv5自带--patience参数默认100个epoch不提升就早停。我的习惯是配合--save-period 10每10个epoch存一次权重万一中间过拟合了也能回退。推理结果可视化除了画框还可以在框上标注置信度、在画面左上角叠加各类别人数统计这样演示的时候直观得多。代码里只需要读detect.py生成的txt或直接改plot_one_box函数追加信息。6.4 最后分享一个小技巧如果你手头有91网站代码里提到的各类开源前端资源其实可以顺手把教室行为检测做成一个实时统计看板后端用FastAPI把YOLOv5推理封装成Web接口前端用现成的图表框架展示每个行为类别的实时人数占比。这个方向很适合做成毕业设计展示或者给学院做一个智慧课堂的demo。技术栈上没有新难点就是把已经训练好的模型用WebSocket推流到浏览器再加上一个柱状图而已。我自己实际跑下来的体会是YOLOv5的生态成熟度确实让这个项目变得有手就行但真正拉开差距的从来不是训练命令本身而是你对数据质量的把控和后处理设计的理解。把这两块做扎实了哪怕模型还是YOLOv5s最终效果也能让人眼前一亮。本文还有配套的精品资源点击获取 YOLOv5教室行为检测实战：从环境搭建到模型训练部署全流程
简介面向智慧校园场景的YOLOv5教室行为检测系统代码包整合人数统计、学生行为识别与教师行为分析能力适合算法开发者、教育信息化工程师用于课堂视觉分析或二次开发。压缩包体积仅12KB共5个文件包含HTML展示页面、JavaScript交互脚本、Markdown说明文档、gitignore及inscode项目配置文件可快速搭建演示界面并理解工程目录结构。系统采用PyTorch与YOLOv5s轻量骨干网络描述中涵盖数据增强、超参数配置、推理部署与可视化交互等模块并预留RESTful API便于与教务平台集成代码包虽未携带训练权重但模块化分层设计清晰可辅助学习工程落地流程。目前已有35人学习适合具备深度学习基础、希望参考检测系统前后端实现或扩展行为识别功能的研发人员。1. 项目概述当YOLOv5走进教室行为检测到底在检测什么先明确一个概念教室行为检测并不是什么黑科技监控本质上它就是目标检测模型在特定场景下的垂直应用。把摄像头画面送进YOLOv5模型输出每个学生的位置框和对应的行为类别——举手、趴桌、站立、玩手机、睡觉、阅读、写字、交头接耳等等。做这个系统的人多半是高校实验室、毕设团队或者想给传统课堂加一点智能化手段的开发者。这个项目最核心的问题有三个环境怎么搭、数据怎么标、模型怎么练。看起来是老生常谈但实际动手时会发现光是PyTorch和CUDA版本匹配就能卡住一大半新手。我写这篇文章的目的就是把我自己从零跑通YOLOv5教室行为检测的全过程复盘一遍包括踩过的坑、试过的参数、改过的代码尽量把每一步的关键决策讲明白。适合正在做相关毕设、课程项目或者想入门目标检测实战的读者。顺便说一句YOLOv5官方仓库虽然是老版本了但它的生态成熟度、资料丰富程度、部署方案多样性至今仍然是工程落地时最稳的选择之一。你不会踩到什么断更没人管的坑因为社区里已经有人把你能想到的报错全部踩过一遍了。2. 整体设计思路拆解为什么是YOLOv5行为检测系统的架构怎么搭2.1 模型选型的底层逻辑每次有人问我行为检测用什么模型我的第一反应永远是反问你的硬件是什么如果是英伟达显卡YOLOv5s或者YOLOv5m完全够用训练快、部署简单、资料多。如果是树莓派、IMX8MP这类边缘设备那就得走YOLOv5s的轻量化路线甚至要转成NCNN或者ONNX Runtime再量化一下。选YOLOv5而不是YOLOv8或者RT-DETR核心原因有三个。第一YOLOv5的代码风格非常工程向detect.py、train.py、val.py拆得清清楚楚改起来不费劲。第二官方仓库自带丰富的预训练权重COCO预训练模型微调到教室场景收敛速度远快于从零训练。第三部署生态成熟——导出ONNX、OpenVINO、TensorRT网上教程一条龙几乎不会卡壳。但这里必须说清楚教室行为检测不等于动作识别。YOLOv5本质是目标检测器它识别的是某个框里有什么物体/姿态而不是这个学生正在做什么连续动作。比如举手和放下手YOLOv5只能检测到举起手的那一帧连续动作需要靠时序模型如LSTM、SlowFast或者简单的帧差法逻辑去判断。很多新手在这里会混淆导致项目做到一半发现效果不理想。2.2 系统整体架构和模块划分一个完整的教室行为检测系统通常由四个模块组成数据采集模块教室监控视频、公开数据集如COCO中的person类、自己拍摄的课堂画面。这里有个小技巧可以直接用现成的课堂视频按帧截取图片作为训练素材远比一张张拍照高效。数据标注模块用LabelImg或labelme对图片中的学生进行框选并打上行为标签。模型训练模块基于YOLOv5官方仓库修改数据配置、调整超参数训练自己的检测器。推理部署模块加载训练好的权重对实时视频流或单张图片进行推理输出带有行为类别标签的检测结果。打通这四块之后你手上的YOLOv5才算真正变成了一个教室行为检测系统而不是一个跑通的demo。下面我把每一个模块的实操细节和关键决策展开讲。3. 环境搭建与核心代码讲解YOLOv5模型训练环境搭建全流程3.1 版本选型和安装步骤YOLOv5对不同PyTorch版本、Python版本的兼容性其实相当宽松但为了少踩坑我推荐一套经过验证的组合Python 3.8/3.9 PyTorch 1.12/2.0 CUDA 11.6/11.8。如果你用的是新一点的显卡比如RTX 30/40系CUDA 11.8是稳妥的选择。安装步骤拆开来就三步创建虚拟环境建议用conda隔离性好删了重来不心疼conda create -n yolov5 python3.9 conda activate yolov5安装PyTorch。这里注意不要直接pip install torch要用官方源匹配CUDA版本pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118克隆YOLOv5仓库并安装依赖git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txt装完依赖后强烈建议先跑一次官方推理测试环境有没有问题python detect.py --weights yolov5s.pt --source data/images/bus.jpg如果能在runs/detect/下看到标注好的输出图恭喜你环境已经通了。这一步能帮你把环境问题和模型问题彻底隔离后面训练出错了不用怀疑是CUDA没配好。3.2 环境配置的几个隐性坑关于环境大多数报错都集中在显卡驱动和PyTorch版本不对应上。你可以先用nvidia-smi查看驱动支持的CUDA版本上限再决定安装哪个CUDA版本的PyTorch。比如驱动显示CUDA Version 12.2那安装cu118或者cu121都行。另一个容易忽略的是OpenCV版本冲突。YOLOv5的requirements里锁定了opencv-python版本范围如果你之前装过新版OpenCV可能出现cv2.error: Unknown C error之类的诡异问题。处理方式很粗暴但有效按requirements里锁定的版本重装一次。我自己的习惯是在环境装好之后立刻做一次快照导出方便以后复现pip freeze requirements_lock.txt这个文件留着换机器或者帮同学配置的时候直接pip install -r requirements_lock.txt省去大量排查时间。4. 训练自己的数据集从标注到出模型的一步步实录4.1 数据采集与标注比想象中更费时间的环节教室行为检测的数据集最理想的情况是目标场景的实拍画面——你要检测的就是你教室的视角、光线、座位排列那用同样的场景数据训练效果当然最好。采集方法很简单用教室监控视频按每秒抽1~2帧截取一个45分钟的课堂大概能抽出两三千张图足够起步了。如果条件有限也可以用公开数据集兜底。这里推荐两个方向一是COCO数据集里的person类做预训练底座二是直接挂载公开的人类行为检测数据集比如PASCAL VOC中的人相关类别。但注意公开数据集的课堂场景多样性通常不足后期还是需要自己补采。标注工具我用的是LabelImg操作逻辑就是画框选标签。对于教室场景建议标签类别控制在6到10个以内多了模型学不过来少了业务上又不够用。我自己的标签方案供参考类别ID标签名称说明0raise_hand举手1writing写字2reading阅读3looking_at_phone看手机4sleeping趴桌睡觉5standing站立6talking交头接耳每个类别至少准备300到500个标注实例总体图片数在1500到3000张之间否则模型很容易过拟合或漏检。标注时有一个细节遮挡严重的、太小的目标可以适当放弃它们带来的噪声远大于信息量。4.2 数据集格式转换与目录组织LabelImg默认输出的是Pascal VOC格式的XML文件但YOLOv5需要的是YOLO格式的txt标注文件每个标注行为class_id x_center y_center width height其中坐标值是相对于图片宽高的归一化比例取值0到1之间。转换脚本网上很多但我建议自己写一次顺便理解坐标换算的逻辑import xml.etree.ElementTree as ET import os def convert_voc_to_yolo(xml_file, class_names, output_dir): tree ET.parse(xml_file) root tree.getroot() img_w int(root.find(size/width).text) img_h int(root.find(size/height).text) lines [] for obj in root.iter(object): class_name obj.find(name).text if class_name not in class_names: continue class_id class_names.index(class_name) bbox obj.find(bndbox) xmin int(bbox.find(xmin).text) ymin int(bbox.find(ymin).text) xmax int(bbox.find(xmax).text) ymax int(bbox.find(ymax).text) x_center (xmin xmax) / 2 / img_w y_center (ymin ymax) / 2 / img_h width (xmax - xmin) / img_w height (ymax - ymin) / img_h lines.append(f{class_id} {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}) txt_path os.path.join(output_dir, os.path.basename(xml_file).replace(.xml, .txt)) with open(txt_path, w) as f: f.write(\n.join(lines)) class_names [raise_hand, writing, reading, looking_at_phone, sleeping, standing, talking]目录结构按YOLOv5官方要求组织datasets/ ├── classroom/ │ ├── images/ │ │ ├── train/ # 训练集图片 │ │ └── val/ # 验证集图片 │ └── labels/ │ ├── train/ # 训练集标注txt │ └── val/ # 验证集标注txt划分比例我用的是8:2训练集和验证集。还有一个关键划分的时候要按整个视频的时间段切分不要随机打乱。否则同一个学生的连续帧会同时出现在训练集和验证集里导致验证集准确率虚高实际部署效果打折扣。4.3 修改配置文件与启动训练YOLOv5训练需要两个配置文件一个是数据集配置文件描述数据路径和类别一个是模型配置文件定义网络结构。数据集配置文件classroom.yamltrain: datasets/classroom/images/train val: datasets/classroom/images/val nc: 7 names: [raise_hand, writing, reading, looking_at_phone, sleeping, standing, talking]模型配置文件直接用官方自带的yolov5s.yaml把nc改成7就行不需要动网络结构。至于用什么规模的模型我给个建议GPU显存8G以下YOLOv5s训练快部署容易精度尚可GPU显存16G左右YOLOv5m精度明显提升训练时间适中显卡很好且追求极致精度YOLOv5l但训练时间和显存开销大教室场景一般用不上启动训练的命令如下python train.py --data classroom.yaml --weights yolov5s.pt --epochs 100 --batch-size 16 --img 640 --device 0训练结束后权重保存在runs/train/exp/weights/下best.pt是验证集上效果最好的权重last.pt是最后一步的权重。推理时优先用best.pt。5. 推理部署与代码修改让模型在真实场景中跑起来5.1 用detect.py对图片和视频进行推理训练完成后立刻做一次推理测试确认模型在从未见过的教室画面上有可用的表现python detect.py --weights runs/train/exp/weights/best.pt --source test_images/ --conf-thres 0.5--source可以指向图片文件夹、单张图片、视频文件甚至摄像头ID比如0表示笔记本自带摄像头。--conf-thres是置信度阈值默认0.25教室场景建议调到0.4到0.5之间。因为教室目标很密集低阈值会造成大量误检框重叠高阈值可以过滤掉那些看着像但不自信的预测。如果想处理视频流或者实时摄像头可以加--save-txt把每帧的检测结果保存成txt方便后续做行为统计分析。这里有个小坑直接跑视频推理时如果视频分辨率很高帧率会明显下降。可以加--imgsz 640降采样到640分辨率速度和精度能达到一个较好的平衡。5.2 行为检测的后处理逻辑和模块扩展YOLOv5输出的是逐帧的检测结果每个框的坐标、类别、置信度。但行为检测如果只是输出这一帧里有人举手可用性其实不高。真正落地的系统需要做一层后处理——把单帧结果聚合成片段级的行为事件。我自己的实现思路是用队列做滑窗统计每隔几帧输出一次结果把最近3秒钟的检测结果放在一个时间窗口里统计每个学生用检测框的中心坐标作为ID最频繁出现的行为类别作为这一窗口的行为判断。伪代码如下from collections import deque # 用一个字典维护每个目标的历史行为队列 history {} def analyze_behavior(detections, current_time, window_seconds3): results {} for det in detections: obj_id det[id] # 实际项目中可以用跟踪算法生成稳定ID behavior det[class_name] if obj_id not in history: history[obj_id] deque(maxlen30) history[obj_id].append((current_time, behavior)) # 过滤掉超出时间窗口的历史数据 while history[obj_id] and current_time - history[obj_id][0][0] window_seconds: history[obj_id].popleft() # 统计窗口内最频繁的行为 counter Counter([h[1] for h in history[obj_id]]) results[obj_id] counter.most_common(1)[0][0] return results注意这里有个前置条件你需要一个稳定的目标跟踪ID。最简单的做法是直接用YOLOv5的检测框中心点做最近邻匹配但拥挤教室场景下容易串号。进阶做法是接入ByteTrack或DeepSORT跟踪器。我在项目中试过ByteTrack在密集场景下ID切换率明显降低代码量也只是在yolov5的检测结果基础上加一个tack的封装性价比很高。5.3 边缘设备部署树莓派5和NXPi.MX8MP的优化思路很多读者会在树莓派5上部署YOLOv5模型。树莓派5的CPU性能比前代强不少但直接用PyTorch推理速度依旧不理想我实测YOLOv5s在树莓派5上跑640分辨率大概只有2到3 FPS。要让实际可用至少要做到两步优化第一步导出ONNX再转NCNN格式用NCNN的C接口推理。转换命令python export.py --weights best.pt --include onnx # 然后用NCNN工具转换为ncnn.param和ncnn.bin第二步使用--img 416甚至--img 320来推理。教室场景下学生目标相对较大降分辨率对精度影响在可接受范围内但速度能提升三四倍。对于NXPi.MX8MP这类带NPU的边缘平台处理方式和树莓派类似关键是模型转换。IMX8MP的NPU支持量化后的TFLite或者ONNX模型导出后需要用NXP的eIQ Toolkit做量化校准。这里提醒一句量化会掉点尤其对看手机这类小目标掉点可能比较明显。建议在量化之后跑一轮验证集对比mAP变化如果掉点超过3个百分点考虑用YOLOv5s原始精度部署或者换更强的模型。6. 常见问题与排查技巧实录6.1 训练时的经典报错和排查逻辑我在训练YOLOv5的过程中遇到了不少问题挑几个最典型的列出来报错/问题实测原因解决方案CUDA out of memorybatch_size过大或图片分辨率过高调小--batch-size或加--cache换显存为内存AssertionError: train: No labels in ...标注txt缺失或路径指向错误检查images和labels目录是否一一对应文件名是否完全一致mAP0.5一直很低低于0.3标签类别名和yaml对不上或者标注框本身不准检查class_names顺序是否和yaml中一致抽样检查标注框是否贴合目标训练几轮loss变成NaN学习率过高或数据集中有异常标注调低--lr0比如从0.01降到0.001检查是否有宽度或高度为0的标注框每当训练出现诡异问题时我习惯先检查数据再检查参数最后才怀疑代码。大多数情况下问题出在数据集上文件没配对、类别对不上、标注坐标越界等。YOLOv5的train.py启动时会打印标注数量和类别分布花几秒钟看一下就能发现很多隐患。6.2 推理时检测效果不佳的几个优化方向训练完模型在真实教室画面上一测常见的问题是漏检多、误检多、小目标检测不到。针对这些情况我的排查顺序如下漏检多先看置信度阈值是否过高适当降低--conf-thres如果还是漏说明训练样本中该类别的样本量不足回去补标注做数据增强尤其是亮度、色度和翻转增强。误检多优先提高置信度阈值如果高阈值下还是误检大概率是背景太复杂需要采集更多含背景的负样本不包含目标的图片加入训练集。小目标如远处的学生看手机检测不到训练时把--img从640提高到960甚至1280模型能更好识别小目标。代价是训练速度和显存开销会上升。这里有一个我踩过多次的经验值教室行为检测的mAP0.5到0.7之间算合格0.8以上算优秀。不要盲目追求在验证集上刷到0.9以上大概率是数据划分出了问题——训练和验证存在同源重复而不是模型真的那么强。6.3 几个能显著提升体验的实操技巧预处理加速批量推理视频时先把视频抽帧用多线程并发推理再按帧序号重组视频速度比直接推视频流快很多。类别不平衡处理教室场景里写字通常占绝大多数站立和看手机可能很少。训练时可以在--hyp超参数文件里调大稀有类别的loss权重或者用--class-balance开启自动类别平衡。利用早停策略YOLOv5自带--patience参数默认100个epoch不提升就早停。我的习惯是配合--save-period 10每10个epoch存一次权重万一中间过拟合了也能回退。推理结果可视化除了画框还可以在框上标注置信度、在画面左上角叠加各类别人数统计这样演示的时候直观得多。代码里只需要读detect.py生成的txt或直接改plot_one_box函数追加信息。6.4 最后分享一个小技巧如果你手头有91网站代码里提到的各类开源前端资源其实可以顺手把教室行为检测做成一个实时统计看板后端用FastAPI把YOLOv5推理封装成Web接口前端用现成的图表框架展示每个行为类别的实时人数占比。这个方向很适合做成毕业设计展示或者给学院做一个智慧课堂的demo。技术栈上没有新难点就是把已经训练好的模型用WebSocket推流到浏览器再加上一个柱状图而已。我自己实际跑下来的体会是YOLOv5的生态成熟度确实让这个项目变得有手就行但真正拉开差距的从来不是训练命令本身而是你对数据质量的把控和后处理设计的理解。把这两块做扎实了哪怕模型还是YOLOv5s最终效果也能让人眼前一亮。本文还有配套的精品资源点击获取