基于YOLO11的课堂行为检测系统：训练、部署与PyQt5 GUI实现全解析

简介：基于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系统举例：

装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 python=3.10 -y conda activate yolo11 pip install ultralytics PyQt5 opencv-python numpy==1.26.4 pip install torch --index-url https://download.pytorch.org/whl/cu121

先装ultralytics和PyQt5，再单独装torch。第一段命令里的numpy==1.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, conf=0.45): results = model.predict( source=frame, conf=conf, # 置信度阈值，低于该值的结果被丢弃 iou=0.5, # NMS的IoU阈值，控制相邻框去重力度 device="0", # 使用GPU，填"cpu"则在CPU上推理 verbose=False # 关闭逐帧日志，避免GUI卡顿 ) return results[0].plot() # 返回绘制好检测框的BGR图像

代码里的conf是过滤低置信度检测框的闸门，课堂场景建议默认0.45，太低会把误检的框放进来，太高会漏掉遮挡状态下置信度不高的举手动作。iou=0.5是NMS去重时的交并比阈值，两个框重叠超过这个比例就只保留置信度更高的那个。device="0"指第一块GPU，没有GPU时改为"cpu"，注意CPU推理时帧率会明显下降，摄像头模式建议把分辨率压到640。results[0].plot()返回的BGR图像可以直接交给GUI显示。

3.3 推理参数与反馈：置信度阈值、检测框与统计面板

界面上的交互通常围绕下面几个参数展开，懂参数含义才能调出满意的效果：

检测框绘制完成后，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 \ data=D:/classroom_behavior/datasets/classroom/data.yaml \ model=yolo11s.pt \ epochs=100 \ batch=16 \ imgsz=640 \ device=0 \ patience=20

model=yolo11s.pt会先下载预训练权重，用它做初始化能极大加快收敛。epochs=100对2000张图的数据量是合理区间，训练到后面如果验证集损失不再下降，patience=20会自动早停。imgsz=640是训练输入分辨率，如果你的课堂图片里后排学生占比小，建议调成960甚至1280，代价是显存占用和训练时长明显增加。batch=16需要约8G以上显存，显存不够就降到8，同时把imgsz同步降低。

这里有一个自己的血泪经验：不要盲目加大imgsz而忽略batch，两者共同决定单次迭代的显存峰值。8G显存跑imgsz=640, batch=16是安全的，但imgsz=1280时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值会同时受数据难度、类别数量、标注质量影响，课堂场景小目标多、遮挡多，mAP@0.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，而项目环境已经装了一个不同版本的PyQt5，pip在解析依赖时卡住或直接覆盖了原本的界面库。解决：给标注工具单独建一个虚拟环境，不跟主项目混用：conda create -n labelme python=3.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(source=frame, conf=0.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 model=weights/best.pt format=onnx imgsz=640

导出后得到best.onnx，可以用ONNX Runtime在CPU上部署，摆脱PyTorch和GPU依赖。需要注意的是导出的imgsz必须和训练时保持一致，否则检测框位置会有偏差。ONNX模型跑推理时不需要加载PyTorch权重，内存占用和启动速度都会改善，适合放到服务器上做批量行为分析。

这套资源最实际的用法，是先拿它当参照系——跑通它，理解GUI和模型是怎么衔接的，再用自己的教室数据替换掉数据集，把模型训练到满足你的场景为止。我从那以后每次拿到训练好的模型，都强制自己先跑一遍验证集、看一眼混淆矩阵再放进GUI，这一步救了我不止一次。希望帮到你。

本文还有配套的精品资源，点击获取