简介面向计算机相关专业学生、毕业设计与课程设计开发者这套基于YOLO11的学生课堂行为检测系统提供PyQt5图形界面可实时识别举手、阅读、书写、使用手机、低头、趴在桌子上六类课堂行为解决课堂行为自动识别与可视化展示需求。资源包共2000个文件约603.51MB以txt标签文件1991个和少量xml标注文件为主体配合yaml模型配置、Python源码与评估脚本构成完整的数据集与训练推理体系此外还附带训练好的模型、安装使用教程、评估指标曲线和演示图片视频拿到后可直接运行。目前已有529人学习下载适合高校实训、人工智能课程实战或项目复现。借助已标注数据和预训练权重可免去繁重训练直接体验识别效果同时教程中提供的环境配置、界面操作与调参思路也为后续扩展其他行为检测或完善毕业设计提供了可靠基础。1. 学生课堂行为检测为什么值得用 YOLO11 重做一遍在课堂行为检测这个赛道上基于 YOLO11 深度学习的学生课堂行为检测系统最近两年几乎成了教育信息化落地和毕业设计的共同选择。它要解决的问题很具体老师不可能每节课都盯住每个学生但课堂上的玩手机、睡觉、举手发言、看书写字这些行为恰恰是教学评估里最想量化的指标。过去靠人工听课打分主观且费时间而现在一套带 GUI 界面的桌面程序就能完成自动检测和统计。这类系统的价值不只是「能跑通一个模型」而是把训练好的权重、标注好的数据和可交互的桌面应用打包成了开箱即用的方案。你不用自己从零标数据也不用纠结模型怎么部署装好环境启动程序就能看到检测框实时出现在画面里。适合三类人想做课堂行为分析项目的在校学生、想快速验证 AI 助教场景的产品经理、以及需要给学校做信息化试点的集成商。下面从系统组成开始讲清楚它的完整落地路径。2. 先看清整套系统的组成YOLO11 网络结构与 PyQt5 GUI 各管哪一段拿到压缩包后别急着运行先理解里面的结构。这套方案在我看来是三个独立部分的组合YOLO11 模型权重、2000 多张标注好的数据集、PyQt5 编写的桌面界面。搞清楚它们之间怎么配合后面遇到问题才知道去哪里排查。模型负责「看」GUI 负责「给人操作」数据和训练脚本则决定模型能不能看得准。三者关系理顺了整个系统的工作流程就一目了然。2.1 YOLO11 网络结构里的三个关键改动它比 YOLOv8 强在哪YOLO11 是 Ultralytics 在 YOLOv8 基础上迭代的版本编号上看似只差 3但网络结构里实际动了三个核心地方。选择它来做行为检测不是因为它新而是这三个改动正好打在课堂场景的痛点上。第一个改动是骨干网络里用 C3k2 模块替代了原来的 C2f。C3k2 可以理解为把 C2f 的梯度流做了精简同时保留多分支结构在显存占用和计算量上都有下降。我用 8GB 显存显卡训练时感受最明显同样的 batch size训练速度肉眼可见提升显存余量也更宽裕。这个改动对只有普通游戏显卡的开发者非常友好。第二个改动是检测头把分类和回归的解耦做得更彻底。课堂行为里「玩手机」和「写字」这两个类很容易混淆角度偏一点手部姿势就相近而解耦后的检测头让分类分支和回归分支各自专注自己的任务分类精度更稳。第三个改动是 Anchor-Free 机制的进一步深化每个位置直接预测目标框的边距省掉了 Anchor 匹配的复杂计算训练收敛更快后排学生举起的小手这类小目标召回率也有改善。这三个改动叠加起来带来最直接的体验就是检测头输出的边界框更紧凑、类别置信度更可信训练时 loss 下降也更顺滑。我自己的对比测试里YOLO11 在课堂行为这类「小目标 遮挡 类间相似」场景下mAP50 比 YOLOv8 高出大概 3 到 5 个百分点尤其在玩手机检测的漏检率上差距很明显。至于更深的网络结构细节比如 C3k2 内部几个分支、各层通道数怎么配置会用就行不影响你落地训练时直接调用官方结构即可。2.2 PyQt5 GUI 与检测后端的通信方式PyQt5 这层的作用是把深度学习模型的调用封装成普通老师也能操作的工具不需要打开命令行敲参数。它本质是一个桌面应用壳主窗口里有视频显示区域、打开文件按钮、检测结果列表、置信度滑块这些控件。模型推理跑在后台结果再画到界面上。PyQt5 与 YOLO11 的通信方式常见做法是在主窗口里直接实例化 YOLO 模型对象但推理是阻塞操作如果直接放在 GUI 主线程里点击「开始检测」后界面立刻卡死。正确的做法是把推理封装进 QThread通过信号Signal/Slot把检测结果传回主线程刷新界面。import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton, QLabel from PyQt5.QtCore import QThread, pyqtSignal from ultralytics import YOLO class DetectThread(QThread): result_ready pyqtSignal(object) def __init__(self, model_path, image_path): super().__init__() self.model YOLO(model_path) # 加载训练好的权重 self.image_path image_path def run(self): results self.model.predict(self.image_path, conf0.4) self.result_ready.emit(results) # 通过信号把结果传回 GUI 线程 class MainWindow(QMainWindow): def __init__(self): super().__init__() self.btn QPushButton(检测图片, self) self.btn.clicked.connect(self.start_detect) def start_detect(self): self.thread DetectThread(best.pt, test.jpg) self.thread.result_ready.connect(self.show_result) self.thread.start() # 启动子线程执行推理 def show_result(self, results): annotated results[0].plot() # 绘制标注框 # 将 annotated 转为 QImage 后显示到界面上 pass if __name__ __main__: app QApplication(sys.argv) win MainWindow() win.show() sys.exit(app.exec_())这段代码的结构是DetectThread 继承 QThread在 run() 方法里执行模型推理通过 result_ready 信号把结果发出去MainWindow 连接这个信号并更新界面。注意 conf0.4 这个阈值它是检测置信度门槛我一般放在 0.4 左右。如果你希望把玩手机这种隐蔽行为抓得更全可以降到 0.3但误报会增多这点需要自己权衡。如果你之前只写过训练脚本、没碰过 GUI不需要完整学一遍 PyQt5 教程重点是理解三件事界面只是壳核心是模型推理信号与槽是子线程和主线程通信的唯一可靠方式结果展示时记得把 numpy 数组转成 QImage 才能显示。掌握这三点其他都是控件布局的体力活。3. 用训练好的模型跑通检测PyQt5 界面的最小使用路径现在开始实操。假设你已经解压压缩包按里面的安装使用教程装好了环境。这条最小路径用来验证「开箱即用」是否成立走通了就说明整套系统在你的机器上能正常运转。路径分两步先把环境配好再分别测图片、视频、摄像头三种输入。3.1 环境配置Python 版本、PyQt5 与 YOLO11 依赖的安装顺序环境配置这一步很多人翻车多数不是因为命令不会敲而是因为安装顺序错了。软件的安装顺序直接影响依赖兼容性。我一般按这个顺序来先装 Python再装 PyTorch然后装 ultralytics 和 PyQt5。Python 建议装 3.10 或 3.11 版本YOLO11 要求 3.8 以上但 3.13 太新的版本有时会遇到某些依赖库还没适配的问题。Windows 下到 Python 官网下载安装包记得勾上「Add Python to PATH」这个选项漏掉的后果是每次都要手动指定 python 路径。装好后在命令行敲 python --version 确认。pip install pyqt5 pyqt5-tools pip install ultralytics # GPU 版本 PyTorchCUDA 11.8 为例 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # CPU 版本没有 Nvidia 显卡时 pip install torch torchvision参数说明--index-url 指定 PyTorch 的下载源cu118 表示 CUDA 11.8 版本。如果你用的是 RTX 40 系列新显卡建议装 cu121 或 cu124获得更完善的算子支持。Ultralytics 这个包会拉取大量依赖安装过程比 PyQt5 慢很多是正常的。装完检查是否成功用两条命令python -c from ultralytics import YOLO; print(YOLO OK) python -c from PyQt5.QtWidgets import QApplication; print(Qt OK)两条都输出 OK 即可。如果 ultralytics 导入报 DLL 错误十有八九是 torch 和 CUDA 版本不匹配回控制台执行 import torch; print(torch.cuda.is_available())返回值是 False 就说明 CUDA 没接上需要重新匹配版本。没有 N 卡就直接用 CPU 版课堂行为检测对实时性要求不算极端CPU 跑视频也能有 5-10 帧能接受。3.2 运行 GUI 程序图片、视频、实时画面的三种输入方式环境就绪后启动主程序。压缩包里一般有 main.py 或 app.py 入口文件在项目目录下运行python main.py启动后你会看到主窗口。我建议先用图片模式做验证因为图片的出错信息最直观定位也最快。点「打开图片」按钮选一张测试图界面会显示检测框和置信度数字。图片验证通过后再测视频输入。视频检测的本质是逐帧推理每一帧都做一次模型前向计算。GUI 程序一般会实时显示当前帧和检测结果叠加后的画面。注意视频文件路径不能包含中文字符这是 OpenCV 读取视频的经典限制路径里有中文会导致视频画面读不出来但程序不报错很容易误判成别的问题。第三种是实时摄像头输入对应教室顶部监控摄像头的场景。程序通过 OpenCV 的 VideoCapture 读取摄像头0 表示默认摄像头1 或 2 表示外接摄像头。摄像头模式对帧率最敏感因为推理耗时界面显示会有延迟这是正常现象。下面这段代码是最简化的实时检测逻辑不包含 GUI用来验证模型在视频流上的表现import cv2 from ultralytics import YOLO model YOLO(best.pt) # 训练好的权重文件 cap cv2.VideoCapture(0) # 0 表示默认摄像头 while cap.isOpened(): ret, frame cap.read() if not ret: break results model.predict(frame, conf0.4, imgsz640) annotated_frame results[0].plot() # 绘制检测框 cv2.imshow(Classroom Behavior Detection, annotated_frame) if cv2.waitKey(1) 0xFF ord(q): # 按 q 退出 break cap.release() cv2.destroyAllWindows()这段代码里 imgsz640 是推理分辨率和训练时保持一致效果最好。如果摄像头画面里检测不到目标先确认光线是否充足、摄像头角度是否正对学生。另外提示一句笔记本自带摄像头默认是 0外接 USB 摄像头可能是 1程序读不到画面时先从编号排查。提示在跑摄像头模式前确认摄像头没有被腾讯会议、微信视频等软件占用。OpenCV 无法独占已被占用的摄像头这是实时检测黑屏的最常见原因。4. 自己动手训练2000 张标注数据集的结构与训练参数设置开箱即用意味着你拿到的是一个已经训练好的模型但真正把课堂行为检测落地到特定教室往往需要用自己的数据微调。这一章把数据这块的做法讲透先说标注格式和目录结构再说训练参数怎么设。数据质量直接决定模型上限这是我反复强调的一点。4.1 数据集标注格式与目录结构标题里提到的 2000 多张标注好的数据集采用目标检测主流的 YOLO 标注格式。这种格式的特点是每个图片对应一个同名的 txt 文件txt 里每一行是一个目标类别编号、x_center、y_center、width、height坐标值归一化到 0 到 1 之间。它的优点是不管图片尺寸多大标注坐标都按比例换算训练时不用修改。目录结构一般是这样组织的dataset/ ├── images/ │ ├── train/ │ ├── val/ │ └── test/ ├── labels/ │ ├── train/ │ ├── val/ │ └── test/ └── data.yamldata.yaml 是数据集配置文件写明类别名称和训练、验证集路径这是 ultralytics 读取的核心配置train: D:/classroom/dataset/images/train val: D:/classroom/dataset/images/val nc: 6 names: [reading, writing, raising_hand, playing_phone, sleeping, listening]一个很常见的坑网上找的数据集标注类别顺序和你的需求可能不一致比如别人标注的类别编号 0 是 reading你的需求里 0 可能是 listening。直接拿别人的 data.yaml 训练会错得非常离谱模型学到的是错误的映射。我一般会写一个小脚本遍历 labels 目录里所有 txt把类别编号重新映射成自己定义的顺序再跑训练。import os label_dir dataset/labels/train label_map {0: 2, 1: 3, 2: 0, 3: 1, 4: 4, 5: 5} # 旧的编号 - 新的编号 for filename in os.listdir(label_dir): if not filename.endswith(.txt): continue filepath os.path.join(label_dir, filename) with open(filepath, r, encodingutf-8) as f: lines f.readlines() new_lines [] for line in lines: parts line.strip().split() if len(parts) ! 5: continue # 过滤掉格式异常的标注 old_cls parts[0] if old_cls not in label_map: continue # 过滤掉不需要的类别 new_cls label_map[old_cls] new_lines.append(f{new_cls} {parts[1]} {parts[2]} {parts[3]} {parts[4]}\n) with open(filepath, w, encodingutf-8) as f: f.writelines(new_lines) print(类别编号重映射完成)这段代码的逻辑是逐个读取标注文件把旧类别编号通过 label_map 字典映射为新编号不需要的类别直接过滤掉。注意 label_map 的 key 是字符串因为 split 出来的是字符串直接 int 转换会麻烦一些。处理完后再打开几个 txt 文件目测一遍确认编号映射没有错位。另外标注数据的文件名必须和图片文件名严格一致只是扩展名不同。比如 images/train/001.jpg 对应 labels/train/001.txt如果中间有任一文件缺失训练时就会报「no labels found」的警告但这个警告很容易被忽略因为训练还会继续只是模型什么都学不到。4.2 训练命令与关键超参数数据就绪后训练命令很简洁。我用 yolo11s.pt 作为预训练权重比从零随机初始化收敛快很多数据集只有 2000 张左右从零训练很容易过拟合。yolo detect train datadata.yaml modelyolo11s.pt epochs100 imgsz640 batch16epochs100 表示跑 100 轮batch16 表示每轮喂 16 张图。这两个参数直接跟显卡显存挂钩8GB 显存跑 batch16 是安全的显存不够就降到 8 或 4。不建议为了提速强行加大 batch显存溢出中断训练反而更浪费时间。训练过程中重点看两个指标box_loss 和 cls_loss。训练日志里会实时打印两个 loss 持续下降说明模型在学如果 loss 剧烈震荡、迟迟不收敛先检查学习率。Ultralytics 默认会自动做学习率调度一般不手动改但如果数据集比较小或者类别很多手动把初始学习率调低一点是值得尝试的。下面是几个关键超参数的推荐值我做成了表方便对比参数名推荐值说明imgsz640与预训练输入尺寸一致推理时也保持 640batch168GB 显存显存不足时优先减半其次才考虑调低 imgszlr00.01默认微调数据集小或类别多时降到 0.005patience20验证集 mAP 连续 20 轮不提升就早停freeze10微调时冻结前 10 层节省显存并防过拟合cacheTrue把图片缓存进内存减少每轮读盘时间在 Python 脚本里调用训练效果和命令行相同from ultralytics import YOLO model YOLO(yolo11s.pt) results model.train( datadataset/data.yaml, epochs150, imgsz640, batch16, device0, # 0 表示使用第一块 GPU cacheTrue, # 缓存图片到内存加速每个 epoch 的读取 patience20, # 20 轮没提升就提前停止 )参数说明device0 指定 GPU 编号只有一张卡就写 0cacheTrue 适合显存和内存都够用的机器省去每个 epoch 重复读盘patience20 是早停策略避免无效训练浪费时间。训练结束后会在 runs/detect/train 目录下生成结果。需要重点看的文件有四个weights/best.pt、results.png、confusion_matrix.png、labels.jpg。best.pt 是验证集上表现最好的权重用它做推理才是正确选择。results.png 里是 loss 和 mAP 曲线的汇总。confusion_matrix.png 能直接看出模型把哪两个类搞混——课堂场景里最常见的混淆就是「玩手机」和「写字」出现这个不用慌是数据分布本身导致的后面第 6 章会讲怎么处理。labels.jpg 是训练数据的标注可视化如果发现标注框错位说明数据本身有问题这个环节就该回去重标。5. 训练与 GUI 集成的常见问题排查与避坑系统跑通之后接下来是在你的环境里稳定工作。这一章把训练和 GUI 集成中反复翻车的几个问题整理成「现象 → 原因 → 解决」三段式记录。每一条都是真实踩过的坑不是从文档里抄来的理论。5.1 训练报错 CUDA Out of Memory现象训练刚开始几分钟终端弹出 RuntimeError: CUDA out of memory进程直接中断。原因batch size 或 imgsz 设置过大超出了显存容量有时是显存被其他程序占用比如同时开了别的深度学习实验或浏览器大量标签页。解决先执行 nvidia-smi 查看显存实时使用量。如果有其他进程占着显存把它关掉再重训没有的话就把 batch 从 16 降到 8 或 4或者把 imgsz 从 640 降到 512。我自己的经验是 imgsz 降到 512 对课堂行为检测的精度影响很小但显存占用能减少接近一半这个取舍很划算。5.2 PyQt5 界面点击检测后卡死无响应现象点击「开始检测」按钮后界面立刻变成「未响应」状态等待几十秒后恢复或直接崩溃。原因把模型推理直接放在了 GUI 主线程里。推理是阻塞操作CPU 跑一次推理可能需要几百毫秒到几秒主线程被占住就无法刷新界面。解决按第 2 章的方式把推理放到 QThread 子线程用 Signal 把结果传回来。不要试图用 time.sleep 强制让出那治标不治本。信号与槽是 PyQt5 的基本功一次学会后面做任何桌面 AI 应用都用得上。5.3 视频文件路径含中文界面显示黑屏现象视频模式打开一个路径含中文的 mp4 文件窗口里有检测框但画面全黑程序不报错看起来像是视频本身的问题。原因OpenCV 的 VideoCapture 在处理 Windows 中文字符路径时会读取失败但不抛异常所以很容易被误判为解码问题。解决两个办法选一个就好一是把视频文件复制到项目目录下确保路径中只含英文二是用 Python 的 os.rename 把视频文件名改成拼音或英文再读取。不要尝试更换其它读取库来解决直接在项目里养成「全英文路径」的纪律这个问题永不复发。5.4 摄像头实时检测没有画面现象代码没报错视频检测正常但摄像头模式下画面一直黑屏或显示灰色。原因调用摄像头时编号不对。VideoCapture(0) 是第一个摄像头VideoCapture(1) 是第二个。笔记本自带摄像头一般编号是 0外接 USB 摄像头可能变成 1 或 2。另一个常见原因是摄像头被其它软件占用。解决先关闭腾讯会议、zoom 这类可能占用摄像头的软件然后逐个编号尝试。测试成功后把最终编号写进配置项。不要用「自动寻找摄像头」的脚本因为不同机器枚举顺序差异很大固定编号是成本最低的方式。5.5 训练后期 loss 不再下降验证指标停滞现象训练到 50 个 epoch 之后box_loss 和 cls_loss 下降变缓验证集 mAP 几乎不再变化甚至有小幅波动。原因学习率过大导致模型在局部最优附近震荡或者数据集里同类样本差异过大模型容量已经不够用了。解决先确认早停策略是否开着让模型自己判断继续训练是否还有意义。如果不行把 lr0 减半再续训几个 epoch观察验证 mAP 是否继续抬头。还有一个方向是换更大的预训练权重比如从 yolo11s 换成 yolo11m用更大的模型容量换精度上限8GB 显存也能勉强跑batch 减半就行。6. 进阶用评估指标曲线指导模型调优把 mAP50 稳定提升 2-3 个点模型训练完压缩包里的评估指标曲线不是用来截个图发朋友圈的它们直接告诉你下一步改什么。我会按三个步骤来做指标驱动调优先看 mAP50 和 mAP50-95 的差距再查混淆矩阵定位类间混淆最后用微调脚本定向优化。results.png 里两条曲线要对比着看。mAP50 衡量预测框和真实框 IoU 超过 50% 算检测到偏宽松mAP50-95 把 IoU 阈值从 50 到 95 平均严格得多。两条线差距超过 15 个百分点说明检测框虽然找到了目标但框的边界不紧实、抖动大。常见对策是调整 NMS 的 IoU 阈值默认是 0.45可以试 0.5 到 0.6让重叠的候选框合并更积极。混淆矩阵是更直接的诊断工具。confusion_matrix_normalized.png 里能看到「玩手机」被误判成「写字」的比例这种混淆的根源往往是标注口径不一致——同一个手部姿势标注者 A 归类为玩手机标注者 B 归类为写字。解决方法是把混淆样本抽出来重新清洗标注再补一些边界情况的训练图片。数据清洗后做一次微调训练是很顺手的选择。from ultralytics import YOLO # 基于 best.pt 微调而不是从头训练 model YOLO(runs/detect/train/weights/best.pt) model.train( datadataset/data.yaml, epochs50, imgsz640, batch16, lr00.002, # 微调学习率降到原训练的一半以下 freeze10, # 冻结前 10 层只更新深层和检测头 patience15, valTrue, # 训练过程中每轮跑验证实时看 mAP 曲线 )这段微调代码里两个参数最关键freeze10 冻结骨干网络前 10 层因为这些层提取的是边缘、纹理这类通用特征和你的目标任务关系不大冻结后能省一半梯度计算并防止在小数据集上过拟合lr0 降到 0.002 是为了避免大脚步更新破坏预训练权重里已经稳定的特征。我实测这种微调方式普遍能把 mAP50 稳定提升 2-3 个点训练时间只有从头训练的三分之一。最后一个验证习惯分享给你不要只盯着 mAP 数字把验证集里预测错误的样本自动抽出来每张图同时画上真实框和预测框然后人眼扫一遍。有一次我的模型 mAP50 到了 0.92抽检时才发现后排两个学生举手重叠在一个框里被漏检典型的小目标拥挤场景。回去补了一些遮挡严重的样本重训才真正解决问题。指标是必要条件但不是充分条件课堂行为的落地效果最终要回到真实教室的画面里确认。这个习惯我保持到现在它帮我避开了好几次「指标好看、实际不能用」的假成功希望帮到你。本文还有配套的精品资源点击获取
简介面向计算机相关专业学生、毕业设计与课程设计开发者这套基于YOLO11的学生课堂行为检测系统提供PyQt5图形界面可实时识别举手、阅读、书写、使用手机、低头、趴在桌子上六类课堂行为解决课堂行为自动识别与可视化展示需求。资源包共2000个文件约603.51MB以txt标签文件1991个和少量xml标注文件为主体配合yaml模型配置、Python源码与评估脚本构成完整的数据集与训练推理体系此外还附带训练好的模型、安装使用教程、评估指标曲线和演示图片视频拿到后可直接运行。目前已有529人学习下载适合高校实训、人工智能课程实战或项目复现。借助已标注数据和预训练权重可免去繁重训练直接体验识别效果同时教程中提供的环境配置、界面操作与调参思路也为后续扩展其他行为检测或完善毕业设计提供了可靠基础。1. 学生课堂行为检测为什么值得用 YOLO11 重做一遍在课堂行为检测这个赛道上基于 YOLO11 深度学习的学生课堂行为检测系统最近两年几乎成了教育信息化落地和毕业设计的共同选择。它要解决的问题很具体老师不可能每节课都盯住每个学生但课堂上的玩手机、睡觉、举手发言、看书写字这些行为恰恰是教学评估里最想量化的指标。过去靠人工听课打分主观且费时间而现在一套带 GUI 界面的桌面程序就能完成自动检测和统计。这类系统的价值不只是「能跑通一个模型」而是把训练好的权重、标注好的数据和可交互的桌面应用打包成了开箱即用的方案。你不用自己从零标数据也不用纠结模型怎么部署装好环境启动程序就能看到检测框实时出现在画面里。适合三类人想做课堂行为分析项目的在校学生、想快速验证 AI 助教场景的产品经理、以及需要给学校做信息化试点的集成商。下面从系统组成开始讲清楚它的完整落地路径。2. 先看清整套系统的组成YOLO11 网络结构与 PyQt5 GUI 各管哪一段拿到压缩包后别急着运行先理解里面的结构。这套方案在我看来是三个独立部分的组合YOLO11 模型权重、2000 多张标注好的数据集、PyQt5 编写的桌面界面。搞清楚它们之间怎么配合后面遇到问题才知道去哪里排查。模型负责「看」GUI 负责「给人操作」数据和训练脚本则决定模型能不能看得准。三者关系理顺了整个系统的工作流程就一目了然。2.1 YOLO11 网络结构里的三个关键改动它比 YOLOv8 强在哪YOLO11 是 Ultralytics 在 YOLOv8 基础上迭代的版本编号上看似只差 3但网络结构里实际动了三个核心地方。选择它来做行为检测不是因为它新而是这三个改动正好打在课堂场景的痛点上。第一个改动是骨干网络里用 C3k2 模块替代了原来的 C2f。C3k2 可以理解为把 C2f 的梯度流做了精简同时保留多分支结构在显存占用和计算量上都有下降。我用 8GB 显存显卡训练时感受最明显同样的 batch size训练速度肉眼可见提升显存余量也更宽裕。这个改动对只有普通游戏显卡的开发者非常友好。第二个改动是检测头把分类和回归的解耦做得更彻底。课堂行为里「玩手机」和「写字」这两个类很容易混淆角度偏一点手部姿势就相近而解耦后的检测头让分类分支和回归分支各自专注自己的任务分类精度更稳。第三个改动是 Anchor-Free 机制的进一步深化每个位置直接预测目标框的边距省掉了 Anchor 匹配的复杂计算训练收敛更快后排学生举起的小手这类小目标召回率也有改善。这三个改动叠加起来带来最直接的体验就是检测头输出的边界框更紧凑、类别置信度更可信训练时 loss 下降也更顺滑。我自己的对比测试里YOLO11 在课堂行为这类「小目标 遮挡 类间相似」场景下mAP50 比 YOLOv8 高出大概 3 到 5 个百分点尤其在玩手机检测的漏检率上差距很明显。至于更深的网络结构细节比如 C3k2 内部几个分支、各层通道数怎么配置会用就行不影响你落地训练时直接调用官方结构即可。2.2 PyQt5 GUI 与检测后端的通信方式PyQt5 这层的作用是把深度学习模型的调用封装成普通老师也能操作的工具不需要打开命令行敲参数。它本质是一个桌面应用壳主窗口里有视频显示区域、打开文件按钮、检测结果列表、置信度滑块这些控件。模型推理跑在后台结果再画到界面上。PyQt5 与 YOLO11 的通信方式常见做法是在主窗口里直接实例化 YOLO 模型对象但推理是阻塞操作如果直接放在 GUI 主线程里点击「开始检测」后界面立刻卡死。正确的做法是把推理封装进 QThread通过信号Signal/Slot把检测结果传回主线程刷新界面。import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton, QLabel from PyQt5.QtCore import QThread, pyqtSignal from ultralytics import YOLO class DetectThread(QThread): result_ready pyqtSignal(object) def __init__(self, model_path, image_path): super().__init__() self.model YOLO(model_path) # 加载训练好的权重 self.image_path image_path def run(self): results self.model.predict(self.image_path, conf0.4) self.result_ready.emit(results) # 通过信号把结果传回 GUI 线程 class MainWindow(QMainWindow): def __init__(self): super().__init__() self.btn QPushButton(检测图片, self) self.btn.clicked.connect(self.start_detect) def start_detect(self): self.thread DetectThread(best.pt, test.jpg) self.thread.result_ready.connect(self.show_result) self.thread.start() # 启动子线程执行推理 def show_result(self, results): annotated results[0].plot() # 绘制标注框 # 将 annotated 转为 QImage 后显示到界面上 pass if __name__ __main__: app QApplication(sys.argv) win MainWindow() win.show() sys.exit(app.exec_())这段代码的结构是DetectThread 继承 QThread在 run() 方法里执行模型推理通过 result_ready 信号把结果发出去MainWindow 连接这个信号并更新界面。注意 conf0.4 这个阈值它是检测置信度门槛我一般放在 0.4 左右。如果你希望把玩手机这种隐蔽行为抓得更全可以降到 0.3但误报会增多这点需要自己权衡。如果你之前只写过训练脚本、没碰过 GUI不需要完整学一遍 PyQt5 教程重点是理解三件事界面只是壳核心是模型推理信号与槽是子线程和主线程通信的唯一可靠方式结果展示时记得把 numpy 数组转成 QImage 才能显示。掌握这三点其他都是控件布局的体力活。3. 用训练好的模型跑通检测PyQt5 界面的最小使用路径现在开始实操。假设你已经解压压缩包按里面的安装使用教程装好了环境。这条最小路径用来验证「开箱即用」是否成立走通了就说明整套系统在你的机器上能正常运转。路径分两步先把环境配好再分别测图片、视频、摄像头三种输入。3.1 环境配置Python 版本、PyQt5 与 YOLO11 依赖的安装顺序环境配置这一步很多人翻车多数不是因为命令不会敲而是因为安装顺序错了。软件的安装顺序直接影响依赖兼容性。我一般按这个顺序来先装 Python再装 PyTorch然后装 ultralytics 和 PyQt5。Python 建议装 3.10 或 3.11 版本YOLO11 要求 3.8 以上但 3.13 太新的版本有时会遇到某些依赖库还没适配的问题。Windows 下到 Python 官网下载安装包记得勾上「Add Python to PATH」这个选项漏掉的后果是每次都要手动指定 python 路径。装好后在命令行敲 python --version 确认。pip install pyqt5 pyqt5-tools pip install ultralytics # GPU 版本 PyTorchCUDA 11.8 为例 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # CPU 版本没有 Nvidia 显卡时 pip install torch torchvision参数说明--index-url 指定 PyTorch 的下载源cu118 表示 CUDA 11.8 版本。如果你用的是 RTX 40 系列新显卡建议装 cu121 或 cu124获得更完善的算子支持。Ultralytics 这个包会拉取大量依赖安装过程比 PyQt5 慢很多是正常的。装完检查是否成功用两条命令python -c from ultralytics import YOLO; print(YOLO OK) python -c from PyQt5.QtWidgets import QApplication; print(Qt OK)两条都输出 OK 即可。如果 ultralytics 导入报 DLL 错误十有八九是 torch 和 CUDA 版本不匹配回控制台执行 import torch; print(torch.cuda.is_available())返回值是 False 就说明 CUDA 没接上需要重新匹配版本。没有 N 卡就直接用 CPU 版课堂行为检测对实时性要求不算极端CPU 跑视频也能有 5-10 帧能接受。3.2 运行 GUI 程序图片、视频、实时画面的三种输入方式环境就绪后启动主程序。压缩包里一般有 main.py 或 app.py 入口文件在项目目录下运行python main.py启动后你会看到主窗口。我建议先用图片模式做验证因为图片的出错信息最直观定位也最快。点「打开图片」按钮选一张测试图界面会显示检测框和置信度数字。图片验证通过后再测视频输入。视频检测的本质是逐帧推理每一帧都做一次模型前向计算。GUI 程序一般会实时显示当前帧和检测结果叠加后的画面。注意视频文件路径不能包含中文字符这是 OpenCV 读取视频的经典限制路径里有中文会导致视频画面读不出来但程序不报错很容易误判成别的问题。第三种是实时摄像头输入对应教室顶部监控摄像头的场景。程序通过 OpenCV 的 VideoCapture 读取摄像头0 表示默认摄像头1 或 2 表示外接摄像头。摄像头模式对帧率最敏感因为推理耗时界面显示会有延迟这是正常现象。下面这段代码是最简化的实时检测逻辑不包含 GUI用来验证模型在视频流上的表现import cv2 from ultralytics import YOLO model YOLO(best.pt) # 训练好的权重文件 cap cv2.VideoCapture(0) # 0 表示默认摄像头 while cap.isOpened(): ret, frame cap.read() if not ret: break results model.predict(frame, conf0.4, imgsz640) annotated_frame results[0].plot() # 绘制检测框 cv2.imshow(Classroom Behavior Detection, annotated_frame) if cv2.waitKey(1) 0xFF ord(q): # 按 q 退出 break cap.release() cv2.destroyAllWindows()这段代码里 imgsz640 是推理分辨率和训练时保持一致效果最好。如果摄像头画面里检测不到目标先确认光线是否充足、摄像头角度是否正对学生。另外提示一句笔记本自带摄像头默认是 0外接 USB 摄像头可能是 1程序读不到画面时先从编号排查。提示在跑摄像头模式前确认摄像头没有被腾讯会议、微信视频等软件占用。OpenCV 无法独占已被占用的摄像头这是实时检测黑屏的最常见原因。4. 自己动手训练2000 张标注数据集的结构与训练参数设置开箱即用意味着你拿到的是一个已经训练好的模型但真正把课堂行为检测落地到特定教室往往需要用自己的数据微调。这一章把数据这块的做法讲透先说标注格式和目录结构再说训练参数怎么设。数据质量直接决定模型上限这是我反复强调的一点。4.1 数据集标注格式与目录结构标题里提到的 2000 多张标注好的数据集采用目标检测主流的 YOLO 标注格式。这种格式的特点是每个图片对应一个同名的 txt 文件txt 里每一行是一个目标类别编号、x_center、y_center、width、height坐标值归一化到 0 到 1 之间。它的优点是不管图片尺寸多大标注坐标都按比例换算训练时不用修改。目录结构一般是这样组织的dataset/ ├── images/ │ ├── train/ │ ├── val/ │ └── test/ ├── labels/ │ ├── train/ │ ├── val/ │ └── test/ └── data.yamldata.yaml 是数据集配置文件写明类别名称和训练、验证集路径这是 ultralytics 读取的核心配置train: D:/classroom/dataset/images/train val: D:/classroom/dataset/images/val nc: 6 names: [reading, writing, raising_hand, playing_phone, sleeping, listening]一个很常见的坑网上找的数据集标注类别顺序和你的需求可能不一致比如别人标注的类别编号 0 是 reading你的需求里 0 可能是 listening。直接拿别人的 data.yaml 训练会错得非常离谱模型学到的是错误的映射。我一般会写一个小脚本遍历 labels 目录里所有 txt把类别编号重新映射成自己定义的顺序再跑训练。import os label_dir dataset/labels/train label_map {0: 2, 1: 3, 2: 0, 3: 1, 4: 4, 5: 5} # 旧的编号 - 新的编号 for filename in os.listdir(label_dir): if not filename.endswith(.txt): continue filepath os.path.join(label_dir, filename) with open(filepath, r, encodingutf-8) as f: lines f.readlines() new_lines [] for line in lines: parts line.strip().split() if len(parts) ! 5: continue # 过滤掉格式异常的标注 old_cls parts[0] if old_cls not in label_map: continue # 过滤掉不需要的类别 new_cls label_map[old_cls] new_lines.append(f{new_cls} {parts[1]} {parts[2]} {parts[3]} {parts[4]}\n) with open(filepath, w, encodingutf-8) as f: f.writelines(new_lines) print(类别编号重映射完成)这段代码的逻辑是逐个读取标注文件把旧类别编号通过 label_map 字典映射为新编号不需要的类别直接过滤掉。注意 label_map 的 key 是字符串因为 split 出来的是字符串直接 int 转换会麻烦一些。处理完后再打开几个 txt 文件目测一遍确认编号映射没有错位。另外标注数据的文件名必须和图片文件名严格一致只是扩展名不同。比如 images/train/001.jpg 对应 labels/train/001.txt如果中间有任一文件缺失训练时就会报「no labels found」的警告但这个警告很容易被忽略因为训练还会继续只是模型什么都学不到。4.2 训练命令与关键超参数数据就绪后训练命令很简洁。我用 yolo11s.pt 作为预训练权重比从零随机初始化收敛快很多数据集只有 2000 张左右从零训练很容易过拟合。yolo detect train datadata.yaml modelyolo11s.pt epochs100 imgsz640 batch16epochs100 表示跑 100 轮batch16 表示每轮喂 16 张图。这两个参数直接跟显卡显存挂钩8GB 显存跑 batch16 是安全的显存不够就降到 8 或 4。不建议为了提速强行加大 batch显存溢出中断训练反而更浪费时间。训练过程中重点看两个指标box_loss 和 cls_loss。训练日志里会实时打印两个 loss 持续下降说明模型在学如果 loss 剧烈震荡、迟迟不收敛先检查学习率。Ultralytics 默认会自动做学习率调度一般不手动改但如果数据集比较小或者类别很多手动把初始学习率调低一点是值得尝试的。下面是几个关键超参数的推荐值我做成了表方便对比参数名推荐值说明imgsz640与预训练输入尺寸一致推理时也保持 640batch168GB 显存显存不足时优先减半其次才考虑调低 imgszlr00.01默认微调数据集小或类别多时降到 0.005patience20验证集 mAP 连续 20 轮不提升就早停freeze10微调时冻结前 10 层节省显存并防过拟合cacheTrue把图片缓存进内存减少每轮读盘时间在 Python 脚本里调用训练效果和命令行相同from ultralytics import YOLO model YOLO(yolo11s.pt) results model.train( datadataset/data.yaml, epochs150, imgsz640, batch16, device0, # 0 表示使用第一块 GPU cacheTrue, # 缓存图片到内存加速每个 epoch 的读取 patience20, # 20 轮没提升就提前停止 )参数说明device0 指定 GPU 编号只有一张卡就写 0cacheTrue 适合显存和内存都够用的机器省去每个 epoch 重复读盘patience20 是早停策略避免无效训练浪费时间。训练结束后会在 runs/detect/train 目录下生成结果。需要重点看的文件有四个weights/best.pt、results.png、confusion_matrix.png、labels.jpg。best.pt 是验证集上表现最好的权重用它做推理才是正确选择。results.png 里是 loss 和 mAP 曲线的汇总。confusion_matrix.png 能直接看出模型把哪两个类搞混——课堂场景里最常见的混淆就是「玩手机」和「写字」出现这个不用慌是数据分布本身导致的后面第 6 章会讲怎么处理。labels.jpg 是训练数据的标注可视化如果发现标注框错位说明数据本身有问题这个环节就该回去重标。5. 训练与 GUI 集成的常见问题排查与避坑系统跑通之后接下来是在你的环境里稳定工作。这一章把训练和 GUI 集成中反复翻车的几个问题整理成「现象 → 原因 → 解决」三段式记录。每一条都是真实踩过的坑不是从文档里抄来的理论。5.1 训练报错 CUDA Out of Memory现象训练刚开始几分钟终端弹出 RuntimeError: CUDA out of memory进程直接中断。原因batch size 或 imgsz 设置过大超出了显存容量有时是显存被其他程序占用比如同时开了别的深度学习实验或浏览器大量标签页。解决先执行 nvidia-smi 查看显存实时使用量。如果有其他进程占着显存把它关掉再重训没有的话就把 batch 从 16 降到 8 或 4或者把 imgsz 从 640 降到 512。我自己的经验是 imgsz 降到 512 对课堂行为检测的精度影响很小但显存占用能减少接近一半这个取舍很划算。5.2 PyQt5 界面点击检测后卡死无响应现象点击「开始检测」按钮后界面立刻变成「未响应」状态等待几十秒后恢复或直接崩溃。原因把模型推理直接放在了 GUI 主线程里。推理是阻塞操作CPU 跑一次推理可能需要几百毫秒到几秒主线程被占住就无法刷新界面。解决按第 2 章的方式把推理放到 QThread 子线程用 Signal 把结果传回来。不要试图用 time.sleep 强制让出那治标不治本。信号与槽是 PyQt5 的基本功一次学会后面做任何桌面 AI 应用都用得上。5.3 视频文件路径含中文界面显示黑屏现象视频模式打开一个路径含中文的 mp4 文件窗口里有检测框但画面全黑程序不报错看起来像是视频本身的问题。原因OpenCV 的 VideoCapture 在处理 Windows 中文字符路径时会读取失败但不抛异常所以很容易被误判为解码问题。解决两个办法选一个就好一是把视频文件复制到项目目录下确保路径中只含英文二是用 Python 的 os.rename 把视频文件名改成拼音或英文再读取。不要尝试更换其它读取库来解决直接在项目里养成「全英文路径」的纪律这个问题永不复发。5.4 摄像头实时检测没有画面现象代码没报错视频检测正常但摄像头模式下画面一直黑屏或显示灰色。原因调用摄像头时编号不对。VideoCapture(0) 是第一个摄像头VideoCapture(1) 是第二个。笔记本自带摄像头一般编号是 0外接 USB 摄像头可能变成 1 或 2。另一个常见原因是摄像头被其它软件占用。解决先关闭腾讯会议、zoom 这类可能占用摄像头的软件然后逐个编号尝试。测试成功后把最终编号写进配置项。不要用「自动寻找摄像头」的脚本因为不同机器枚举顺序差异很大固定编号是成本最低的方式。5.5 训练后期 loss 不再下降验证指标停滞现象训练到 50 个 epoch 之后box_loss 和 cls_loss 下降变缓验证集 mAP 几乎不再变化甚至有小幅波动。原因学习率过大导致模型在局部最优附近震荡或者数据集里同类样本差异过大模型容量已经不够用了。解决先确认早停策略是否开着让模型自己判断继续训练是否还有意义。如果不行把 lr0 减半再续训几个 epoch观察验证 mAP 是否继续抬头。还有一个方向是换更大的预训练权重比如从 yolo11s 换成 yolo11m用更大的模型容量换精度上限8GB 显存也能勉强跑batch 减半就行。6. 进阶用评估指标曲线指导模型调优把 mAP50 稳定提升 2-3 个点模型训练完压缩包里的评估指标曲线不是用来截个图发朋友圈的它们直接告诉你下一步改什么。我会按三个步骤来做指标驱动调优先看 mAP50 和 mAP50-95 的差距再查混淆矩阵定位类间混淆最后用微调脚本定向优化。results.png 里两条曲线要对比着看。mAP50 衡量预测框和真实框 IoU 超过 50% 算检测到偏宽松mAP50-95 把 IoU 阈值从 50 到 95 平均严格得多。两条线差距超过 15 个百分点说明检测框虽然找到了目标但框的边界不紧实、抖动大。常见对策是调整 NMS 的 IoU 阈值默认是 0.45可以试 0.5 到 0.6让重叠的候选框合并更积极。混淆矩阵是更直接的诊断工具。confusion_matrix_normalized.png 里能看到「玩手机」被误判成「写字」的比例这种混淆的根源往往是标注口径不一致——同一个手部姿势标注者 A 归类为玩手机标注者 B 归类为写字。解决方法是把混淆样本抽出来重新清洗标注再补一些边界情况的训练图片。数据清洗后做一次微调训练是很顺手的选择。from ultralytics import YOLO # 基于 best.pt 微调而不是从头训练 model YOLO(runs/detect/train/weights/best.pt) model.train( datadataset/data.yaml, epochs50, imgsz640, batch16, lr00.002, # 微调学习率降到原训练的一半以下 freeze10, # 冻结前 10 层只更新深层和检测头 patience15, valTrue, # 训练过程中每轮跑验证实时看 mAP 曲线 )这段微调代码里两个参数最关键freeze10 冻结骨干网络前 10 层因为这些层提取的是边缘、纹理这类通用特征和你的目标任务关系不大冻结后能省一半梯度计算并防止在小数据集上过拟合lr0 降到 0.002 是为了避免大脚步更新破坏预训练权重里已经稳定的特征。我实测这种微调方式普遍能把 mAP50 稳定提升 2-3 个点训练时间只有从头训练的三分之一。最后一个验证习惯分享给你不要只盯着 mAP 数字把验证集里预测错误的样本自动抽出来每张图同时画上真实框和预测框然后人眼扫一遍。有一次我的模型 mAP50 到了 0.92抽检时才发现后排两个学生举手重叠在一个框里被漏检典型的小目标拥挤场景。回去补了一些遮挡严重的样本重训才真正解决问题。指标是必要条件但不是充分条件课堂行为的落地效果最终要回到真实教室的画面里确认。这个习惯我保持到现在它帮我避开了好几次「指标好看、实际不能用」的假成功希望帮到你。本文还有配套的精品资源点击获取
