简介基于YOLO11深度学习的课堂行为检测系统面向计算机、人工智能、自动化等专业的学生与开发者可完成举手、阅读、书写、使用手机、低头、趴在桌上六类课堂行为识别并配有PyQt5图形界面适合毕业设计、课程作业或实战项目二次开发。压缩包共2000个文件主体为1991个txt标注文件及若干xml、yaml配置文件另有Python源码如val.py与训练模型、评估曲线、演示视频等整体约603.51MB覆盖数据、训练、验证、部署全流程。已有502人学习下载。资源内附带安装使用教程与已训练好的模型开箱即用提供标注好的2000余张数据集和完整的评估指标曲线便于理解模型性能代码经作者测试运行成功可在此基础上修改实现其他功能适合初学者进阶和项目演示。1. 能开箱即用的YOLO11课堂行为检测从训练到GUI的一条完整链路YOLO11的检测能力本身已经没有太多悬念Ultralytics生态里它已经是默认的新起点真正让深度学习项目停在演示阶段的原因往往是模型跑通了却没有一个能让非技术用户直接操作的入口。这个学生课堂行为检测系统把YOLO11、2000多张标注好的课堂图片、训练好的权重和PyQt5界面打包在一起装好依赖就能对图片、视频、摄像头实时识别行为类别并统计次数。它适合三类人本科毕设需要一个完整演示系统的学生想快速出课设成果的开发者以及想用行为分析辅助教学的老师和教务人员。拿到手先跑通再谈训练和改参数这是我对所有带GUI的检测项目一贯的顺序。2. 为什么是YOLO11网络结构改动、部署成本与这套系统的组成2.1 YOLO11相比上一代改了什么C3k2、C2PSA与检测头YOLO11的核心改动集中在三个位置。Backbone里部分C2f模块换成了C3k2卷积核尺寸和分支结构做了调整计算量比YOLOv8同规格更低同时引入了C2PSA模块它是基于自注意力机制的卷积结构能在不显著增加推理耗时的前提下增强对全局上下文的建模。Detect head仍然沿用anchor-free解耦头的设计分类分支和回归分支分离损失函数延续了DFL CIoU那套组合。这些改动意味着什么对课堂行为检测这个场景来说后排学生的人头在640分辨率下只有几十个像素属于典型的小目标密集场景。C2PSA带来的全局上下文建模能力有助于在遮挡和重叠的情况下把「低头」「趴桌」「举手」这类姿态区分开。选YOLO11不是因为刷榜而是它在同等精度档位下模型文件更小、推理更快CPU也能跑出可用帧率。对一套要交给非技术用户使用的GUI系统来说部署省事比刷高点几个点的mAP重要得多。2.2 这套系统的组成与数据成本2000张标注图够不够用整套系统由四个部分构成基于ultralytics库的Python推理后端、PyQt5写的桌面GUI、标注好的课堂行为数据集、以及已经训练完成的.pt权重文件。推理后端负责加载权重、预处理图像、执行推理、解析结果GUI负责文件选择、摄像头调用、结果绘制和统计展示数据集和权重则是开箱即用的底气。2000多张标注图对课堂这个受限场景够用前提是类别不要超过十个。常见的行为类别包括举手、低头、趴桌、玩手机、写宇、听讲、起立等六到八类具体以资源里的classes.txt为准。这个类别集合基本覆盖了课堂行为分析的主流需求。训练时建议用yolo11s.pt作为预训练权重做迁移学习而不是从零训练因为从零训练需要的数据量至少是现在的五倍。数据拆分上我一般会按8:1:1切分train、val、test切分时保证每个类别在每个集合里都有样本避免某个不常见行为恰好全被分到验证集里。2.3 环境依赖清单PyQt5、ultralytics与CUDA怎么配依赖版本是这类资源第一个卡人的地方。下表是我常用的配置组合按Windows系统举例依赖包版本思路用途Python3.9~3.11兼容ultralytics与PyQt5的稳妥区间ultralytics8.3.x及以上YOLO11训练、推理、模型管理PyTorch2.xGPU版或CPU版深度学习推理后端PyQt55.15.x桌面GUI框架opencv-python4.x图像读取与格式转换numpy1.24~1.26数组运算避免2.0版本接口变更装PyTorch时先确认机器有没有NVIDIA显卡。有显卡就装CUDA版没有就直接装CPU版。GPU版和CPU版的推理速度差距在一个数量级以上但CPU版至少保证系统能跑通这对演示环境不确定的情况很重要。PyQt5如果通过conda安装报错改成pip安装通常能解决依赖冲突。装完后在Python里执行import torch; print(torch.cuda.is_available())返回True说明GPU可用返回False则确认当前走的是CPU路径。3. 开箱即用PyQt5界面启动、三种推理方式与置信度参数3.1 启动前准备工作首次安装依赖与权重路径拿到资源后先做两件事解压到全英文路径然后创建虚拟环境装依赖。Windows下常见的坑是用户名带中文或路径里有空格ultralytics在读取数据集索引时对这类路径处理不友好直接导致训练阶段报错推理阶段也有概率出问题。建议把整个项目放在类似D:\classroom_behavior的位置。conda create -n yolo11 python3.10 -y conda activate yolo11 pip install ultralytics PyQt5 opencv-python numpy1.26.4 pip install torch --index-url https://download.pytorch.org/whl/cu121先装ultralytics和PyQt5再单独装torch。第一段命令里的numpy1.26.4是为了避开numpy 2.0的接口变动ultralytics在旧版numpy下运行更稳定。第二段命令指定了CUDA 12.1的torch源如果你的显卡驱动较老可以换成cu118版本。装完验证一下torch.cuda.is_available()然后进入项目目录执行python main.py即可看到GUI主窗口。3.2 三种推理方式图片、视频文件、实时摄像头GUI主界面通常会提供三个入口选择图片、选择视频文件、打开摄像头。对应代码里的处理逻辑基本一致核心是把输入帧交给检测函数再把绘制了检测框的结果渲染到界面。下面这段是推理模块最常见的写法import cv2 from ultralytics import YOLO model YOLO(weights/best.pt) # 加载训练好的行为检测权重 def process_frame(frame, conf0.45): results model.predict( sourceframe, confconf, # 置信度阈值低于该值的结果被丢弃 iou0.5, # NMS的IoU阈值控制相邻框去重力度 device0, # 使用GPU填cpu则在CPU上推理 verboseFalse # 关闭逐帧日志避免GUI卡顿 ) return results[0].plot() # 返回绘制好检测框的BGR图像代码里的conf是过滤低置信度检测框的闸门课堂场景建议默认0.45太低会把误检的框放进来太高会漏掉遮挡状态下置信度不高的举手动作。iou0.5是NMS去重时的交并比阈值两个框重叠超过这个比例就只保留置信度更高的那个。device0指第一块GPU没有GPU时改为cpu注意CPU推理时帧率会明显下降摄像头模式建议把分辨率压到640。results[0].plot()返回的BGR图像可以直接交给GUI显示。3.3 推理参数与反馈置信度阈值、检测框与统计面板界面上的交互通常围绕下面几个参数展开懂参数含义才能调出满意的效果参数推荐区间作用调参方向conf0.35~0.55置信度过滤误检多就调高漏检多就调低iou0.4~0.6重叠框抑制密集场景适当调低防粘连devicecpu / 0推理后端有GPU优先用0imgsz640~1280输入分辨率后排小目标多时调到960或1280检测框绘制完成后GUI的统计面板按类别累加次数。这个统计逻辑不复杂但要注意按帧累计时同一目标会被重复计数课堂场景想拿到接近真实的人次要么按帧率做去重要么按时间窗口抽样统计。资源自带的演示视频展示了这三种输入模式下的效果跑一遍视频就能直观看到置信度调整前后检测结果的差异。3.4 界面卡死的根源PyQt5主线程与推理线程的分离第一次跑起来的人大多会踩同一个坑点击「开始检测」后界面变成白屏或黑屏拖不动也关不掉。原因是检测逻辑被直接放在了GUI主线程里执行推理耗时导致Qt事件循环被阻塞现象就是假死。正确做法是用QThread把推理过程放进工作线程通过信号把结果帧传回主线程刷新界面。后面进阶章节会给一套可以直接粘进项目的线程模板这里先记住结论PyQt5界面和深度学习推理必须分线程否则无论什么配置都躲不过界面无响应。注意OpenCV读取的图像是BGR格式给PyQt5的QLabel显示前需要转换成RGB并封装成QImage否则画面会偏蓝偏绿这是另一个高频问题。4. 训练复现数据集结构、训练命令与评估曲线判定4.1 数据集目录结构与YOLO标注格式说明想在自己的课堂场景复现这套系统先要理解数据集的目录组织方式。YOLO系列对数据集的约定非常固定项目里通常长这样datasets/classroom/ ├── images/ │ ├── train/ # 约1600张 │ ├── val/ # 约200张 │ └── test/ # 约200张 ├── labels/ │ ├── train/ # 与图片同名后缀.txt │ ├── val/ │ └── test/ └── data.yaml # 数据配置images和labels目录必须一一对应训练时程序按data.yaml里的路径去查找图片和标注。图片名和标注文件名完全相同只是扩展名不同这是YOLO格式最基本的一条规则。标注文件的每一行代表一个目标框格式为类别ID 中心点x 中心点y 框宽 框高 4 0.621094 0.328125 0.056250 0.093750四个坐标值全部归一化到0到1之间除以图片宽度和高度。比如第二行表示类别ID为4目标中心位于图片横向62.1%、纵向32.8%的位置。做数据检查时我一般会写个小脚本扫一遍所有txt文件确认没有坐标小于0或大于1的情况因为标注工具导出异常会导致训练时loss出现NaN。标注好的数据不要轻易改动目录结构除非你同时修改data.yaml里的路径。4.2 训练命令与关键超参数训练命令以ultralytics的标准CLI写法为准资源带的教程里也会给一份可执行的配置。核心命令如下cd D:\classroom_behavior yolo detect train \ dataD:/classroom_behavior/datasets/classroom/data.yaml \ modelyolo11s.pt \ epochs100 \ batch16 \ imgsz640 \ device0 \ patience20modelyolo11s.pt会先下载预训练权重用它做初始化能极大加快收敛。epochs100对2000张图的数据量是合理区间训练到后面如果验证集损失不再下降patience20会自动早停。imgsz640是训练输入分辨率如果你的课堂图片里后排学生占比小建议调成960甚至1280代价是显存占用和训练时长明显增加。batch16需要约8G以上显存显存不够就降到8同时把imgsz同步降低。这里有一个自己的血泪经验不要盲目加大imgsz而忽略batch两者共同决定单次迭代的显存峰值。8G显存跑imgsz640, batch16是安全的但imgsz1280时batch必须降到4以下。Ultralytics默认开启了马赛克增强对小目标训练有正面效果但最后一个epoch会自动关闭马赛克做精调这是官方内置的机制不需要手动干预。4.3 评估指标曲线怎么看判断模型是否真的训练成功训练结束后runs/detect/train目录下会生成一系列文件。weights/best.pt和weights/last.pt是模型权重results.png汇总了训练和验证的loss曲线与指标曲线confusion_matrix.png是混淆矩阵PR_curve.png是精确率召回率曲线。判断训练是否成功我一般按下面三个顺序看第一看results.png里的val/box_loss和val/dfl_loss。这两条曲线应该持续下降并且尾部趋于平缓如果验证损失在后期掉头上升说明模型开始过拟合此时best.pt往往出现在验证损失最低点附近。第二看confusion_matrix.png。对角线上的数字应该明显大于非对角线如果某个类别的行几乎全部分散在其他列里说明这个类别的训练样本太少或者标注质量有问题加数据比调参更有效。第三看PR_curve.png曲线下的面积越大越好面积偏小说明模型在低置信度区间存在大量误检使用时就得把置信度阈值往上提。不要只看训练集的loss那个值即使模型过拟合也会持续下降不具备参考价值。验证集的mAP值会同时受数据难度、类别数量、标注质量影响课堂场景小目标多、遮挡多mAP0.5能到0.85以上已经算可用模型不要拿它跟行人检测那种大目标公开数据集对比然后自我怀疑。5. 避坑手记环境配置到界面显示的五个真实踩坑5.1 数据集加载失败中文路径导致的玄学报错现象运行训练命令后提示数据集不存在或者Dataset not found但路径明明是对的。原因Windows用户名是中文项目解压到了C:\用户\张三\Desktop这类路径ultralytics的YOLO格式索引在某些版本里对非ASCII路径处理不完整。解决把整个项目移动到盘符根目录下的纯英文路径比如D:\yolo11_classroom同时确认data.yaml里写的是绝对路径而不是相对路径。5.2 GUI界面黑屏不刷新QThread使用姿势不对现象点击开始检测后界面固定住不动或者整个窗口白屏。原因推理逻辑直接写在主线程里PyQt5的Qt事件循环被阻塞界面无法重绘。解决把model.predict()放进QThread的run()方法里通过pyqtSignal把处理好的QImage信号发射到主线程槽函数中更新QLabel。这不是优化项而是必改项只要在GUI里跑深度学习推理就必须做线程分离。5.3 中文标签全变方块字体文件没指定现象检测框上的「举手」「低头」等中文标签显示成一排方框或乱码。原因cv2和PIL的默认字体不支持中文绘制文字时找不到中文字形。解决在绘制标签代码里显式指定中文字体文件路径Windows下用C:/Windows/Fonts/msyh.ttc微软雅黑绘制函数里设置字体对象后再写入文本。资源里的GUI如果用了Qt自带的绘图接口可以直接用QFont(微软雅黑, 10)解决。5.4 明明有NVIDIA显卡训练却慢得离谱装了CPU版PyTorch现象训练时显卡利用率看不到波动loss下降速度极慢跑一个epoch需要几十分钟。原因pip默认安装的torch是CPU版本torch.cuda.is_available()返回False模型全程在CPU上跑。解决先执行上面提到的那一行验证代码确认CUDA不可用后根据显卡驱动版本选择对应的CUDA源重新安装torch比如pip install torch --index-url https://download.pytorch.org/whl/cu121装完再检查一次is_available()。5.5 labelme安装卡死PyQt5依赖冲突的解法现象想打开标注工具重新看看标签执行pip install labelme后报PyQt5冲突或者安装后打不开。原因labelme内部依赖特定版本的PyQt5而项目环境已经装了一个不同版本的PyQt5pip在解析依赖时卡住或直接覆盖了原本的界面库。解决给标注工具单独建一个虚拟环境不跟主项目混用conda create -n labelme python3.8然后pip install labelme。如果只是查看标签而不需要重新标注直接打开labels目录下的txt文件看坐标数字就够了不需要跑GUI工具。6. 进阶替换模型、导出ONNX与GUI多线程改造6.1 给GUI加置信度滑杆与行为统计曲线资源自带的GUI能完成基础检测和统计但实际演示时置信度阈值每次都要重启程序才改得了很麻烦。我一般会把conf参数绑定到一个QSlider上滑动即触发重新推理并刷新检测画面。下面是一套可以直接复用的QThread模板把推理放进去是改造的第一步import cv2 from PyQt5.QtCore import QThread, pyqtSignal from PyQt5.QtGui import QImage, QPixmap class InferenceThread(QThread): frame_signal pyqtSignal(QImage) def __init__(self, model, source): super().__init__() self.model model self.source source def run(self): for frame in self.source: # 摄像头按帧循环 results self.model.predict(sourceframe, conf0.45) drawed results[0].plot() # BGR格式的检测结果帧 rgb cv2.cvtColor(drawed, cv2.COLOR_BGR2RGB) h, w, ch rgb.shape qimg QImage(rgb.data, w, h, ch * w, QImage.Format_RGB888) self.frame_signal.emit(qimg)这个模板把BGR转RGB、封装QImage、信号发射三件事一次性做完。QImage(rgb.data, w, h, ch * w, QImage.Format_RGB888)里的ch * w是每行字节数必须按实际像素宽度乘通道数计算写错会导致画面倾斜。滑杆到统计曲线的联动可以在这个信号槽函数里用列表记录每10帧的各类别计数然后调用QPainter画一个简单的趋势折线到另一块画布上不复杂但演示效果很加分。6.2 换掉默认权重用自己的数据训练并导出ONNX资源里自带的权重是作者在2000多张图上训练出来的拿到你自己的教室场景时场景光线和座位布局不同行为类别的分布也会变单独演示没问题但要真正用起来就需要用自己的数据训练。训练流程按前面第4章的命令走一遍训练完成后把runs/detect/train/weights/best.pt复制到项目weights目录下替换原来的文件重命名成best.pt即可GUI不用改任何代码。训练数据量不足时可以在原有标注数据基础上加自己的图片用资源里带的预训练权重继续训练这样不会从头学起。如果后续要把模型集成到Web服务或者其他平台ultralytics支持导出成ONNX格式yolo export modelweights/best.pt formatonnx imgsz640导出后得到best.onnx可以用ONNX Runtime在CPU上部署摆脱PyTorch和GPU依赖。需要注意的是导出的imgsz必须和训练时保持一致否则检测框位置会有偏差。ONNX模型跑推理时不需要加载PyTorch权重内存占用和启动速度都会改善适合放到服务器上做批量行为分析。这套资源最实际的用法是先拿它当参照系——跑通它理解GUI和模型是怎么衔接的再用自己的教室数据替换掉数据集把模型训练到满足你的场景为止。我从那以后每次拿到训练好的模型都强制自己先跑一遍验证集、看一眼混淆矩阵再放进GUI这一步救了我不止一次。希望帮到你。本文还有配套的精品资源点击获取
