简介基于YOLOv8与PyQt5的课堂检测系统资源包面向教育技术研究人员、教师及计算机视觉开发者针对传统课堂监控依赖人力、效率低下的痛点提供一套无需编程基础即可轻松上手的实时课堂行为检测方案。包体共2000个文件容量720.34MB以1975个txt标注文件为核心配合11个Python脚本、7个xml配置、6个yaml模型定义及1个css样式完整覆盖了数据标注、模型训练、界面构建与系统部署流程已有109人学习下载。资源内不仅包含yolo2coco.py、xml2txt.py等数据格式转换工具还提供setup.py、split_data.py等环境配置与数据集划分脚本UiMain.py、ui_sources.py等代码则清晰展示PyQt5图形界面的实现逻辑yaml文件可用于调整YOLOv8训练参数。从数据准备到模型训练再到界面交互全链路细节均有代码支撑。这套完整工程既可作为课堂行为检测的落地工具也是学习YOLOv8与PyQt5集成开发的优质范例适合直接复现或二次扩展。1. 课堂检测系统为什么 YOLOv8 PyQt5 是工作量最小的组合“课堂检测”这四个字在 YOLOv8 这类目标检测模型看来其实是一组清晰的行为坐标举手、低头玩手机、趴在桌上睡觉、转身说话每一类都能标注成一个边界框。先用 YOLOv8 在自建课堂数据集上训练出行为检测模型再用 PyQt5 包一个能选视频、开摄像头、实时出框的桌面程序后端模型和前端界面的工作量就都被压缩到了一个中型项目的水平。这篇文章写给教育信息化方向的工程师和做课堂录播、教学督导项目的团队前半部分把 YOLOv8 从环境配置到训练参数讲透后半部分用一个最小可运行的 PyQt5 界面把模型接进去最后把部署到 RK3588 这类边缘设备的路径也交代清楚。没有编程基础的老师也能靠打包好的可执行程序完成日常检测这正是这套组合最省力的地方。2. 环境与数据先让 YOLOv8 训练链路在本地跑通2.1 安装 Python、PyTorch、ultralytics 与 PyQt5 的先后顺序自己做过的课堂检测项目里最常见的失败不是模型训练不起来而是环境装得一团乱麻。我的做法是先用 venv 隔离避免把 conda 全局环境弄脏。Python 建议选 3.9 到 3.11因为 torch 和 ultralytics 在这个区间配合最稳定装完再升级反而容易踩 Qt 兼容问题。在命令行里执行python -m venv classroom_venv # Windows classroom_venv\Scripts\activate # Linux / macOS source classroom_venv/bin/activate pip install --upgrade pip pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics pip install pyqt5 pyqt5-tools--index-url只对 PyTorch 生效ultralytics 和 pyqt5 走默认源即可。先装 torch 再装 ultralytics 是有顺序讲究的ultralytics 在导入时会检查 torch 版本后装 torch 容易把依赖解析回退到 CPU 版本。装完后建议马上验证两行python -c import torch; print(torch.cuda.is_available()) python -c from ultralytics import YOLO; print(YOLO.__name__)第一行输出True说明 CUDA 可用。如果输出False优先检查 nvidia-smi 里的驱动和 CUDA 版本而不是重装 torch。PyQt5 的验证更简单能导入就算成功python -c from PyQt5.QtWidgets import QApplication; print(qt ok)这里要补充一句如果系统里同时装过 OpenCV 的桌面版本PyQt5 偶尔会报 “Qt platform plugin could not be initialized”。这不是代码问题是 OpenCV 自带的 Qt 动态库和你后装的 PyQt5 冲突。我踩过这个坑处理方式是固定 pyqt5 版本重装或者临时设置QT_QPA_PLATFORMoffscreen把逻辑层跑通界面层的问题后面单独定位。2.2 课堂行为类别怎么定、标注工具怎么选课堂检测的场景有一个特殊性行为类别不能拍脑袋定太多。常见做法是把行为压缩到 46 类例如举手raise_hand、玩手机phone、趴桌睡觉sleep、阅读read、书写write最多再加一个“站立或走动”做课堂纪律分析。类别标签越多标注成本和模型翻车概率同步上升因为不少行为在 640 分辨率下长得几乎一样强行细分只会让训练损失曲线好看实测识别反而不准。标注工具我一般推荐用 CVAT 的网页版多人协作方便单人小批量数据用 LabelImg 也能对付。无论选哪个导出格式一定选 YOLO 格式也就是每张图片对应一个同名 txt每行是class_id x_center y_center width height坐标全部归一化到 01。手工标注时有一条血泪经验课堂图片里学生头部往往被桌椅遮挡半截框不要紧贴可见像素而是按“完整身体占位”的意识去框否则模型学到的是半个身体的特征到了真实教室视频里反而不会用。2.3 目录规范与 data.yaml 的最小配置ultralytics 对数据目录没有强制约束但自己定好规范能省很多事。我习惯的结构是classroom/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── classroom.yamltrain 和 val 的图片目录放 jpglabels 目录放同名 txt。图片和标签的 basename 必须完全一致否则训练时会有一大批图片被静默跳过这是新手最容易犯又不自知的问题。data.yaml 内容如下path: ./classroom train: images/train val: images/val nc: 5 names: 0: raise_hand 1: phone 2: sleep 3: read 4: write几个细节值得注意path用相对路径时训练命令要在 classroom 的上级目录执行否则相对路径指向错误nc必须和 names 列表长度一致多写少写都会在训练阶段报类别数不匹配训练集和验证集建议按 8:2 或 9:1 划分。课堂视频连续性很强切分时最好按“不同节课、不同机位”分而不是把同一段视频的连续帧随机拆开否则验证结果会虚高部署时直接打回原形。2.4 先用官方权重跑通一个最小管道数据集还没准备好也可以先验证环境。下载官方 yolov8n.pt 并不需要额外手段通过 ultralytics 自带模块就能完成from ultralytics import YOLO model YOLO(yolov8n.pt) results model(https://ultralytics.com/images/bus.jpg) results[0].show()能弹出窗口画一堆框就证明模型加载、推理、图像显示三条链路都通了。这一步是全篇文章里玄学最少的环节如果它没通过后面谈训练调参都是空中楼阁。这个最小管道通过后再正式进入训练环节。3. 用自己的数据集训练课堂行为模型训练命令、参数边界与损失曲线3.1 训练命令与最少参数集数据目录就绪后一条命令即可开始yolo detect train modelyolov8s.pt dataclassroom.yaml epochs200 imgsz640 batch16 device0 projectruns/classroom nameexp_01参数解释model是预训练权重小规模课堂数据集用yolov8s起步足够data指向 2.3 节的 yamlepochs不建议低于 100行为类别和 COCO 的 80 类差异太大太少训练不够充分imgsz默认 640用于课堂实拍时如果学生离镜头远可以先试 960代价是训练时间和显存上升batch受显存制约如果你用 GTX 1660 Ti 这种 6GB 显存卡跑 YOLOv8batch16极易爆显存保守调到 8 更稳。命令执行后进度条里的box_loss、cls_loss和mAP50会实时滚动不要被第一轮的低 mAP 吓到正常收敛普遍要从第 50 轮才开始明显。在显存不够用的时候有两个可接受的应对一是把batch降为 4 或 8同时把epochs略微增加到 240 来补偿二是给 ultralytics 显式指定workers把数据加载进程数调低避免 CPU 争抢导致训练速度变慢。记住一点课堂数据集通常只有几百到两三千张图batch 16 和 batch 8 的最终精度差距远小于数据质量差距。3.2 关键参数调优imgsz、batch、cache 与数据增强固定数据量下影响模型最终表现的三类主要参数分别是输入分辨率、训练批量和数据增强。输入分辨率直接决定小目标召回率教室全景图里一个学生可能只占 40×80 像素640 分辨率下玩手机的手部更是只有 20 像素见方。这种情况我建议把 imgsz 提到 960 或 1280并配合rectTrue按长宽比分批填充既保住小目标又不至于让显存爆炸。yolo detect train modelyolov8m.pt dataclassroom.yaml epochs300 imgsz960 rectTrue cacheTrue batch8cacheTrue会把预处理过的图像缓存到内存对反复读取少量训练样本的情况提速明显但内存低于 16GB 时慎用缓存写盘反而更慢。数据增强方面ultralytics 默认开着马赛克增强、翻转和随机色域课堂这类稳定场景建议保留平移和轻微旋转左右翻转保持默认即可因为左右翻转不会改变“举手”“玩手机”的语义。如果出现验证分数反复震荡优先把mosaic0.5调掉过强的马赛克在小数据集上容易打乱课堂布局让模型学到碎片化的上下文。我见过不少人把cls_loss和box_loss的权重拆出来手调结果越调越差。除非你明确知道某个类别的漏检代价更高比如“玩手机”需要零容忍否则第一版训练不要动损失权重等混淆矩阵出来再决定要不要针对某一类做加权。3.3 借损失曲线判断训练健康度并挑权重训练完成后输出目录runs/classroom/exp_01下会生成results.png里面包含 box_loss、cls_loss、dfl_loss 的训练和验证曲线。课堂项目里我主要看两条线训练 loss 和验证 loss。如果两者同步下降且验证 loss 持续低于训练 loss说明模型还没吃饱加 epochs 或加数据都能继续涨点如果训练 loss 降到很低但验证 loss 在第 80 轮左右开始反弹基本可以判定过拟合此时优先加水增强或随机失活而不是换更大的模型。关于选权重.pt文件会保留最后一轮best.pt是根据验证集 mAP 自动挑出的最优权重。多数情况下直接用best.pt即可。若追求推理时的极致速度可以在训练后做一步模型蒸馏或用yolov8n重新跑但不建议在精度还没满足需求之前就换轻量模型那是本末倒置。3.4 一个可视化补充热力图不是必需但能解释翻车YOLOv8 本身不直接给出热力图但如果你想确认模型到底在看图像的哪个区域可以借用 grad-CAM 一类的工具观察特征激活。它在排查“模型把讲台上的粉笔盒误判成手机”这类样本时很有用。对课堂检测这个场景我通常只在模型出现系统性误判时才做热力图分析比如后排学生大面积漏检时看模型是否把注意力放在前排。平时交付验证用损失曲线加混淆矩阵已经足够热力图更多是自己心里有底不建议写进交付文档。4. 用 PyQt5 把模型包成一个能双击运行的桌面工具4.1 界面布局与打开摄像头的最小骨架PyQt5 界面设计不需要花哨核心就是一个显示画面的 QLabel、一个“打开视频文件”按钮、一个“打开摄像头”按钮、一个“开始检测”按钮和一个“停止”按钮。QMainWindow 作为顶层容器中央挂一个 QWidget往里面塞 QVBoxLayout。我常用的代码骨架如下import sys import cv2 from ultralytics import YOLO from PyQt5.QtWidgets import (QApplication, QMainWindow, QLabel, QPushButton, QVBoxLayout, QWidget, QFileDialog) from PyQt5.QtCore import Qt class ClassroomWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle(课堂行为检测) self.video_label QLabel(视频区域) self.video_label.setAlignment(Qt.AlignCenter) self.video_label.setMinimumSize(960, 540) self.btn_file QPushButton(打开视频文件) self.btn_cam QPushButton(打开摄像头) self.btn_start QPushButton(开始检测) self.btn_stop QPushButton(停止) central QWidget() layout QVBoxLayout(central) layout.addWidget(self.video_label) layout.addWidget(self.btn_file) layout.addWidget(self.btn_cam) layout.addWidget(self.btn_start) layout.addWidget(self.btn_stop) self.setCentralWidget(central) self.btn_file.clicked.connect(self.on_open_file) def on_open_file(self): path, _ QFileDialog.getOpenFileName(self, 选择视频, , 视频文件 (*.mp4 *.avi)) if path: self.video_label.setText(path) if __name__ __main__: app QApplication(sys.argv) win ClassroomWindow() win.show() sys.exit(app.exec_())这段代码先解决“窗口能打开”的问题。QFileDialog的返回过滤可以按需增加 mp4、avi、mov 等格式。按钮的 clicked 信号还没接检测逻辑先把界面独立跑通再往里接线程这样排查问题时能分清是界面问题还是模型问题。4.2 检测线程为什么不能把推理写进按钮回调直接把 YOLO 推理写进按钮回调是 PyQt5 界面卡死最常见的根源。原因很简单PyQt5 的 UI 事件循环和推理循环在同一线程时cv2 的read()一旦在等帧整个窗口就无法重绘、无法响应点击。正确做法是把视频读帧和模型推理都放进 QThread通过信号把一帧一帧的图像回传。下面是一个能直接复用的检测线程import time import cv2 from ultralytics import YOLO from PyQt5.QtCore import QThread, pyqtSignal from PyQt5.QtGui import QImage class DetectThread(QThread): frame_ready pyqtSignal(QImage) def __init__(self, source0, weightsbest.pt, parentNone): super().__init__(parent) self.source source self.model YOLO(weights) self.running True def run(self): cap cv2.VideoCapture(self.source) while self.running: ret, frame cap.read() if not ret: break results self.model(frame, conf0.35, imgsz640, verboseFalse) frame results[0].plot() frame cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) h, w, ch frame.shape qimg QImage(frame.data, w, h, ch * w, QImage.Format_RGB888) qimg qimg.copy() self.frame_ready.emit(qimg) cap.release()几个参数要说明白conf0.35是置信度阈值课堂检测里偏低一点更合适因为远处学生的框置信度天然不高阈值调太高会把后排全滤掉imgsz640要和训练时的分辨率保持一致前面用 960 训练的模型这里就该填 960verboseFalse禁止逐帧打印否则控制台会被日志刷爆。qimg qimg.copy()这行几乎不可省QImage 不持有frame.data的所有权信号触发后 numpy 数组一旦被释放界面就画不出图这是新手最容易翻车的地方。在主窗口里启动线程self.thread DetectThread(source0, weightsruns/classroom/exp_01/weights/best.pt) self.thread.frame_ready.connect(self.update_frame) self.thread.start() def update_frame(self, qimg): self.video_label.setPixmap(QPixmap.fromImage(qimg).scaled( self.video_label.size(), Qt.KeepAspectRatio))setPixmap更新画面时scaled保证画面不拉伸变形。停止检测不能粗暴调用thread.terminate()那会把线程直接杀死摄像头句柄和模型处于半释放状态更稳妥的做法是把running置为 False然后thread.wait()让线程读完当前帧自然退出。4.3 视频文件与摄像头双入口以及帧率控制接入摄像头时source0接入本地视频时source视频路径。这里常见做法是保留两个入口摄像头用于实时督导本地视频用于回放分析。不管是哪条入口都需要显式控制推理帧率否则显卡满载、CPU 占用飙升界面也不流畅。class DetectThread(QThread): frame_ready pyqtSignal(QImage) def run(self): cap cv2.VideoCapture(self.source) interval 1.0 / 10.0 while self.running: t0 time.time() ret, frame cap.read() if not ret: break results self.model(frame, conf0.35, imgsz640, verboseFalse) frame results[0].plot() frame cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) h, w, ch frame.shape qimg QImage(frame.data, w, h, ch * w, QImage.Format_RGB888) qimg qimg.copy() self.frame_ready.emit(qimg) elapsed time.time() - t0 if elapsed interval: time.sleep(interval - elapsed) cap.release()实测里 YOLOv8s 在 GTX 1660 Ti 上推理 640 分辨率画面大约需要 4070ms10 FPS 的上限足够人眼判断课堂行为也避免 CPU 长时间跑满。若需要更高帧率把模型换成 yolov8n或者降低 imgsz二者取舍很直接不用纠结。4.4 行为统计面板显示每类目标的实时数量YOLO 自带的results[0].plot()已经画了一层框。想显示“当前课堂举手人数3玩手机人数5”可以另起一个 QLabel 接收统计信号。统计逻辑放在线程里做每跑完一帧就把results[0].boxes.cls归总成字典发出去。这里有个细节线程发信号的频率要和帧率一致一旦信号发太快界面主线程来不及重绘QImage 信号队列会堆积画面越来越卡。最简单的缓解手段是让统计信号同一帧只发一次或直接把统计文本通过cv2.putText画进上一帧的图里输出省去多线程同步的麻烦。5. 避坑手册课堂检测系统最常见的五个坑5.1 PyQt5 一启动就报 Qt platform plugin 错误现象安装好 pyqt5运行任意一个包含 QApplication 的窗口控制台直接报 “Could not load the Qt platform plugin xcb” 或 Windows 下的同类提示。原因大多是同时安装了 opencv-python 和 pyqt5OpenCV 自带的 Qt 动态库和 PyQt5 的绑定互相冲突也有少部分是 venv 路径里带中文或空格Qt 找不到插件目录。解决第一步固定版本重装。我试过比较稳的组合是 Python 3.10 opencv-python 4.8 系列 pyqt5 5.15.9冲突概率最低。如果固定版本后仍报错在代码最前面设置os.environ[QT_QPA_PLATFORM] offscreen先测逻辑界面问题后面单独排查。项目路径尽量用纯英文这个细节常被忽略。5.2 训练时 CUDA out of memory但设置的 batch 明明不大现象训练到第十轮左右报 CUDA out of memory进程直接退出。原因显存占用不只是 batch 决定的。imgsz 从 640 提到 960 后单张图显存占用翻倍以上再叠加cacheTrue的预取机制显存压力会集中在训练中段暴露出来。如果后台还开着 PyQt5 调试窗口或浏览器显存更紧张。解决把 imgsz 降回 640batch 从默认值调小到 8 或 4训练命令加workers2缓解预处理线程占用。启动训练前用nvidia-smi看一眼显存占用把无关进程结束掉再开始。如果数据量和类别数都允许换 yolov8n 做原型验证确认流程后再换大模型。5.3 点击开始检测后界面黑屏、窗口无响应现象点击“开始检测”后QLabel 上没有画面窗口一直转圈。原因推理写在了主线程视频帧读取被阻塞界面无法重绘或者 QThread 只传递了 numpy 数组QPixmap 在主线程里转换时原始数据已经被释放。解决检查推理代码是否在按钮回调里直接执行如果是把推理整个迁移到 QThread。确认在发信号前用了qimg.copy()保证图像数据生命周期正常。顺手在update_frame里加一行打印如果一直不进来问题大概率在线程没能启动而不是绘制逻辑本身。5.4 训练 mAP 正常但部署到真实教室后远处学生全检不到现象mAP50 到 0.85模拟测试效果也好拉到真实教室后发现后排学生几乎全漏检。原因这是课堂检测里最高频的翻车点——数据分布与推理分辨率不匹配。训练素材多为近景截图部署时摄像头从教室后方俯拍一个学生可能只有 40 像素高模型从未见过这种尺度。解决先做推理端补救把 imgsz 从 640 提到 960 或 1280有时立竿见影。如果仍不行需要针对真实机位补拍数据加入远距离样本训练时打开multi_scaleTrue让模型见到不同尺度的目标。数据采集阶段尽量按实际摄像头机位拍这比任何调参都重要。5.5 停止检测后摄像头仍然占用再次启动报设备被占用现象点击停止按钮后摄像头指示灯还亮着再次启动时提示摄像头已被占用。原因QThread 的 run 循环里存在阻塞读取即使主线程已经置runningFalse也要等当前cap.read()返回。如果停止后直接杀掉线程句柄没有释放摄像头自然收不回。解决停止逻辑按顺序来先self.thread.running False再self.thread.wait(2000)让线程安全退出并执行cap.release()。如果用的是老旧摄像头型号长时间等待帧会卡住 run就需要给VideoCapture设置超时或在wait()后强制结束并弹窗提示。6. 导出、部署到 RK3588 与最后的验证手段6.1 从 PyTorch 权重导出为 ONNX 并衔接边缘部署如果项目最终要跑在学校机房的老机器上PyQt5 桌面端直接用 best.pt 就够如果要部署到 RK3588 这类带 NPU 的边缘盒子需要做中间格式转换。常规路径是先导出 ONNX再用 RKNN-Toolkit2 转成 rknn命令如下yolo export modelruns/classroom/exp_01/weights/best.pt formatonnx opset12 imgsz640导出后用 onnxruntime 做一次快速验证import onnxruntime as ort import cv2 sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) img cv2.imread(sample.jpg) img cv2.resize(img, (640, 640)) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img img.transpose((2, 0, 1))[None].astype(float32) / 255.0 out sess.run(None, {sess.get_inputs()[0].name: img}) print(out[0].shape)这段验证只关心流程通不通不追求画框。ONNX 输出是形状如(1, 84, 8400)的三维张量其中 84 对应 COCO 类别的 4 个框属性加 80 类如果你按前文定义 5 个类训练输出形状会变成(1, 9, 8400)8400 是三种尺度下的候选框总数。实际手工解析这个张量需要自己做阈值过滤、NMS 和坐标还原我做过一次以后发现直接复用 ultralytics 的 ONNX 推理入口更省心所以除非对延迟极端敏感否则不建议手动解析。对于 RK3588可以在板上直接推理 RKNN 格式也可以使用 onnxruntime-lite 跑 ONNX 模型。如果同时接入四路摄像头且帧率压力大优先转成 rknn 用 NPU 加速如果只是单路CPU 跑 YOLOv8n 基本够用没必要为了“用上 NPU”而牺牲检测精度。这里提醒一句rknn 的模型转换结果和 ONNX 的数值精度有差异转换完要用同一段测试视频重新验证一轮不能直接沿用桌面端指标。6.2 行为统计回归用一段带标注的“金标准”视频做验证回归测试不能省。我的习惯是准备一段 60 秒的教室实拍片段人工逐帧或逐关键帧标出真实出现的五类行为再跑系统对比。比较项不是逐帧 mAP而是三个业务指标举手行为检测率、玩手机行为检测率、整体误报数。这一测试能弥补 mAP 的盲区因为 mAP 在类别不平衡时容易被头部类别带跑真实课堂里“阅读”和“书写”出现的帧数远大于“玩手机”mAP 高不代表玩手机这类重要行为检得准。from ultralytics import YOLO model YOLO(best.pt) tp, fp, total 0, 0, 0 with open(golden_annotations.txt) as f: for line in f: img_path, label line.strip().split(,) results model(img_path, conf0.35) dets [int(box.cls[0]) for box in results[0].boxes] if results[0].boxes else [] if label phone and 1 in dets: tp 1 elif label phone: fp 1 print(fphone: tp{tp}, fp{fp})这个脚本只演示玩手机一个类别真实验证时把五类都枚举进去。统计结果若检测率低于 80%优先看漏检样本是近景还是远景再回到 5.4 节的决策路线去补数据或调分辨率误报偏多则把 conf 阈值提高 0.05 再试。还要注意不同课室的采光差异远大于算法差异第一次部署到一个新教室先用一段 5 分钟视频快速评估别直接全量接入。6.3 跑完一版后真正值得做的三个优化模型训练完、系统能跑不等于交付结束。真正有价值的优化集中在三个方向第一对频繁漏检的类别做难例挖掘——把漏检的图片收集起来拼成负样本二次微调这是低成本提升课堂行为识别率最有效的手段第二在 PyQt5 端增加行为统计报表导出把每节课的举手次数、玩手机时长按时间轴写入 CSV这往往是教育信息化项目验收时的加分项第三如果数据量持续上升考虑用更强的 YOLOv8l 做教师模型把知识蒸馏到轻量模型上让 RK3588 的 NPU 负载更低。这三个方向里投入产出比最高的其实是第二个因为它不碰模型只是把已有的检测结果转化成业务价值。6.4 最后留一个自检习惯跑完整个流程后我通常会做一次“最小化重放”从新机器环境、新装依赖、准备数据、训练到打开 PyQt5 界面点两下全流程不再依赖任何人就能跑通。如果中途任何一步需要查文档说明该把相应环节写进项目 README 或做成一键脚本。多年的检测项目经验告诉我系统崩在哪里往往是最不起眼的环节比如打包可执行程序后模型路径写死比如新机器没装运行库。养成在交付前做一次全新环境重放的习惯能少走很多弯路希望帮到你。提示如果你用 GPU 版本 PyTorch 训练同时又要跑 RKNN 转换记得先关闭桌面端训练进程因为 NPU 工具链和大模型训练同时开机经常会出现原因不明的内存竞争和转换中断。本文还有配套的精品资源点击获取