YOLOv8智慧教室人数统计：CPU部署、模型微调与PyQt5界面实战

简介基于YOLOv8的智慧教室人数统计应用是一份面向毕业设计和课程设计的完整项目涵盖源码、可视化界面、完整数据集与部署教程适用于计算机视觉、人工智能等专业学生及需要快速搭建目标检测演示的开发者。项目代码已经测试通过支持生成核心指标曲线、混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果和标签分布图能直观展示模型训练效果为答辩评审提供可信依据。压缩包共8个文件以Python脚本、PyTorch模型权重和说明文档为主其中3个py文件对应训练、检测和可视化页面模块3个pt文件为训练好的模型权重2个txt文件包含使用说明与资源标识信息压缩后总大小约15.91MB。目前已有58人学习下载可拿来即用也可在现有代码基础上修改以扩展功能适合作为毕设、课设或初期立项演示项目。1. 这个项目在解决什么一个教室、一台老电脑也能跑起来的人数统计很多教室这两年装的所谓智能考勤本质还是三种老方案人肉点名、红外传感器数进出、或者用贴纸二维码打卡。人肉点名慢红外只知道有人没人二维码只能说明人到了不能说明教室里此刻到底有多少人。而在摄像头画面上做实时人数统计用 YOLOv8 已经不算新技术可一旦真把它放进一间没有独立显卡、只有老 CPU 的教室电脑里跑起来还要带一个能点按钮看结果的可视化界面就会撞上数据、训练、界面、部署这四堵墙。这个题目拆开来说就是把智慧教室人数统计应用从数据集整理、模型微调、界面开发到部署踩坑完整过一遍。适合正在纠结毕设能不能这么做、课程设计怎么交差的学生也适合想在教室场景快速验证一套人数统计原型的工程师。先提醒一句你网上看到的很多指标和参数在这个场景下要改一半。2. 先想清楚三件事为什么是 YOLOv8、交付物是什么、数据集从哪来2.1 为什么是 YOLOv8与 Faster R-CNN、SSD 在教室场景的对比做目标检测能选的开源框架很多但教室这个场景有自己的特殊性目标密集、后排人头小、光照变化大、摄像头位置基本固定。早期我见过有人用 Faster R-CNN 做教室考勤精度确实过得去但训练和推理都慢CPU 上单帧推理近一秒完全没法做实时统计SSD 速度快一些但对小目标的召回率差后排学生坐在那里框出来的往往是半个身子而不是一个人。方案推理速度CPU后排小目标部署生态二次开发成本Faster R-CNN慢约 0.5s/帧较好一般高SSD中等差一般中YOLOv8快约 80~150ms/帧好完善低对比下来YOLOv8 的优势不在某个单项指标上而在综合体验。它原生是 anchor-free 结构对尺度变化不敏感教室摄像头拍到的画面里第一排学生占画面高度三分之一最后一排学生可能只有 30 像素这种尺度跨度正是 anchor-free 的舒适区。更重要的是 ultralytics 这个包把训练、验证、导出、推理封装成一条命令部署环节省掉大量体力活。我选它的核心理由就是毕设或者小工程里最怕的不是模型效果差而是卡在环境配置和格式转换上YOLOv8 在这方面的生态成熟度目前没有对手。2.2 一个能毕业的项目骨架目录结构、训练脚本、界面、部署文档拿到这类标题的资源第一件事不是跑代码而是先看项目的目录骨架。常见做法是一个工程文件夹里分四块数据集、训练脚本、可视化界面、部署文档。即使你没拿到别人的包自己也应该按这个结构组织后面每一步操作都有地方放东西。classroom_count/ ├── datasets/ # 数据集图片、标签、划分好的 train 和 val │ └── classroom/ │ ├── images/ │ ├── labels/ │ └── data.yaml ├── runs/ # 训练输出权重、曲线图、验证结果 ├── src/ │ ├── train.py # 训练入口 │ ├── detect.py # 单张图片 / 视频推理 │ └── ui_main.py # PyQt5 可视化界面 ├── docs/ │ └── deploy.md # 部署教程 └── requirements.txt命令和说明我都写在这段里你可能注意到数据集、界面、部署文档这三样恰好就是这类应用的基本盘。训练脚本一般独立成文件因为训练和推理的环境依赖不同后续做模型改进时也不会污染界面代码。界面文件单独放理由在后面讲线程时会说明。部署教程放到独立目录等你训练完模型、在另一台机器上重新搭环境时省得翻聊天记录和旧笔记。2.3 把原始照片变成训练集Labelme 标注与 VOC 转 YOLO 格式脚本提示数据集是整个项目里最不值钱也最值钱的部分。不值钱是因为教室图片网上就能拍值钱是因为标注质量直接决定模型上限后面所有的调参都不能弥补标注错误。我一般标注用 Labelme安装和启动命令就两行启动后把图片目录拖进窗口用多边形把每个人框出来。这里有个常见做法像素级精细标注没有必要检测框用矩形就够类别统一填 person。pip install labelme labelme标注完每张图片会生成一个同名 JSON 文件里面存的是多边形坐标。但 YOLOv8 要的标签是归一化后的中心点坐标和宽高存在与图片同名的 .txt 文件里所以需要一个转换脚本。下面这段是我在多个项目里复用过的关键逻辑是读取 JSON 里的形状坐标算出最小外接矩形再除以图片宽高得到归一化值。import json import os def convert_labelme_json(json_path, img_w, img_h, out_txt): with open(json_path, r, encodingutf-8) as f: data json.load(f) lines [] for shape in data[shapes]: if shape[label] ! person: continue points shape[points] xs [p[0] for p in points] ys [p[1] for p in points] x_min, x_max min(xs), max(xs) y_min, y_max min(ys), max(ys) # 转成 yolo 格式中心点 x, y, 宽, 高都要除以图片尺寸 cx (x_min x_max) / 2.0 / img_w cy (y_min y_max) / 2.0 / img_h w (x_max - x_min) / img_w h (y_max - y_min) / img_h # 防止裁剪时把坐标裁到图片外 cx max(0.0, min(cx, 1.0)) cy max(0.0, min(cy, 1.0)) w max(0.0, min(w, 1.0)) h max(0.0, min(h, 1.0)) lines.append(f0 {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}) with open(out_txt, w) as f: f.write(\n.join(lines))这段脚本里有三个地方值得说一下。第一个是类别索引固定写成了 0因为当前只有 person 一类如果后续加了 teacher 类别就要改成从 0 开始的映射字典。第二个是坐标钳制的四行很多人漏掉结果标注目标有一半在画面外训练时模型会被边缘的半个框干扰。第三个是归一化YOLO 训练要求所有坐标在 0 到 1 之间习惯先转归一化再做数据增强顺序不要反。2.4 数据增强该开多少教室小目标场景下的四项建议很多教程会教你开启所有增强来泛化但智慧教室这个场景有别的问题后排人头本来就小如果用 mosaic 增强把四张图拼在一起后排人头经常被拼接线切成两半标签还在模型学出来的特征就是“半个人头也算”。所以我在处理数据集用于 YOLOv8 训练时会把默认增强改掉具体建议如下mosaic 从默认的 1.0 降到 0.5让小目标被切碎的概率降低一半。水平翻转开垂直翻转不要开教室里没有人倒立。亮度、对比度扰动开到 0.3 左右教室有晴天拉窗帘、阴天开灯的情况这个扰动很有用。scale 增强要克制默认的 0.5 可以保持但上下不要超过 0.7否则模型会把人缩小成噪点。这里还涉及一个数据划分的问题按整个数据集随机分 train 和 val而不是按视频时间段分。同一段视频前后帧太相似随机划分会把几乎相同的画面同时放进去导致验证结果虚高。我踩过一次这个坑后面所有教室项目都改成按视频片段划分先抽帧、再以片段为单位分配。收集数据时还有一个反向技巧故意采集十几分钟没有人的空教室画面标注文件留空也就是空 label训练脚本会把这些当负样本。这个操作对降低误检非常有效后面避坑章节会展开讲。3. 训练自己的教室模型环境搭建、命令模板与损失曲线解读3.1 Ubuntu20.04 CPU 跑 YOLOv8环境搭建与硬件边界如果你手头只有一台 CPU 电脑别急着买显卡可以先把环境搭起来跑通最小流程。以下命令在 Ubuntu20.04 上验证过Python 版本建议选 3.10因为 Ultralytics 对 3.8 以下的支持在逐渐弱化。conda create -n yolov8 python3.10 -y conda activate yolov8 pip install ultralytics opencv-python python -c from ultralytics import YOLO; print(ok)最后一行命令如果输出 ok说明环境没问题。这里我要坦诚说一句CPU 版本能跑但你要接受它的上限。推理一张分辨率 640 的教室图片用最轻量的 yolov8n 大约需要 80 到 150 毫秒训练就另说了CPU 上训 100 个 epoch 可能需要十几个小时效率太低。常见做法是用云 GPU 或学校的服务器做训练把训练好的 best.pt 拿回本地 CPU 机器做推理演示。我遇到过一个学生用 CPU 硬训了两天一夜结果因为忘记打开缓存中途断电全部白干。所以训练环节我给你两个救命的参数在训练命令里加 cacheTrue以及在 epochs 设置后加 patience 提前停止。如果你有一块 GTX1660Ti 这类老显卡那训练体验会好很多6GB 显存跑 yolov8n 或 yolov8s 都够batch 设 16 左右不会爆显存。3.2 从预训练权重微调一条可复现的训练命令与参数表不要在 ImageNet 预训练模型上从零训直接用 YOLOv8 自带的 COCO 预训练权重做微调收敛快得多。COCO 里有 person 类模型天生认识人你只需要让它适应教室的视角和光照。训练命令如下yolo taskdetect modetrain \ modelyolov8n.pt \ data/home/user/classroom_count/datasets/classroom/data.yaml \ epochs120 \ imgsz640 \ batch16 \ lr00.001 \ cacheTrue \ patience20 \ plotsTrue这里每个参数都不是摆设挑五个关键的展开说。epochs 设 120是因为教室数据集通常只有几千张再多就会过拟合patience20 的意思是连续 20 轮验证指标不提升就提前停多数情况下模型在第 60 到 90 轮就收敛了。imgsz 是输入分辨率640 是默认均衡值后排人头实在太小的时候可以试 960但训练时间和显存占用逼近两倍CPU 推理更是会明显变慢。batch16 受显存限制如果你的是 8GB 以下可以降到 8 并同步把 lr0 降到 0.0005。lr0 这里选 0.001 而不是默认的 0.01因为微调场景下学习率太大很容易让预训练权重瞬间崩掉也就是常见的 loss 从 2 直接跳到 20 再回不来。还有一点容易被忽略data.yaml 里的路径最好写绝对路径因为训练命令里中文路径或相对路径时偶尔会出现数据集加载失败但报错不明确的情况。我一般写完 data.yaml 先跑一遍验证加载确认类别数和图片数量是预期值再开训练。3.3 训练监控把 results.csv 画成损失函数曲线图训练开始后ultralytics 会在 runs/detect/train 下生成 results.csv里面每一行是一个 epoch 的指标包括 train/box_loss、train/cls_loss、metrics/mAP50、metrics/mAP50-95 等。看训练趋势不一定要用 TensorBoard用 pandas 加 matplotlib 几行就能画出来。import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(runs/detect/train/results.csv) # 画 box_loss观察是否收敛 plt.figure(figsize(10, 4)) plt.plot(df[train/box_loss], labeltrain box loss) plt.plot(df[val/box_loss], labelval box loss) plt.xlabel(epoch) plt.ylabel(loss) plt.legend() plt.title(Box Loss Curve) plt.savefig(box_loss.png, dpi150)这段代码读取 results.csv 并绘制训练集与验证集的 box loss 曲线。我要特别强调一种现象如果 val/box_loss 在某个点之后开始掉头向上而 train/box_loss 还在往下降那就是过拟合了不需要再调参直接回到训练命令把 epochs 减半或者加大数据增强就能解决。mAP50 与 mAP50-95 的区别也要看懂mAP50 只评估 IoU 大于 0.5 的预测框符合人数统计的容错需求mAP50-95 则把阈值从 0.5 一路提升到 0.95 取平均指标更严格但教室里框出头部中心点比框出完整身体更难这项数值不用太焦虑。3.4 训练不收敛时怎么定位输出文件与现象对照训练日志只能告诉你结果不好不能告诉你为什么不好这是标准的黑匣子。我的做法是优先看图不看数字。训练过程中开启 plotsTrue 会在 runs/detect/train 下生成三个关键文件train_batch0.jpg、val_batch0_labels.jpg、val_batch0_pred.jpg。第一个文件展示了送入训练器的增强后图片如果你看到图片里标注框明显偏移、或者有超过一半的框贴边那基本可以断定是数据问题。第二个文件是验证集标注的真实框用来看类别和坐标是否正确。第三个文件是模型预测结果在训练的早期阶段它通常是什么都框不出来的这是正常现象不用慌张。如果这三个文件都正常但 mAP50 始终不到 0.6下一步去 labels 目录里做一次统计把每个标签文件的框数量打印出来看看有没有某张图标注了 20 个人而其他图都是两三个人。这种极端不均衡会让模型优化方向混乱解决办法就是对类别做重采样或者删掉标注数异常的图片。目标检测不像分类超过画面承受能力的密集标注模型往往会把边框学成了互相重叠的噪声。4. 可视化界面与实时推理PyQt5 骨架与置信度参数调校4.1 推理前的最后一道闸门conf、iou、imgsz 三个参数怎么设界面这部分是这类项目能不能拿高分的分水岭。终端里跑通的人一抓一大把稳定又美观的可视化界面才是亮点。但让人表演翻车的也正是在这里问题通常不是模型不行而是推理参数没调好。YOLOv8 推理时有三个参数我需要单独拧出来讲。conf 是置信度阈值默认 0.25。在教室场景里后排学生只占 30 像素模型给出的置信度普遍偏低如果保持 0.25后排会被大量漏检。我一般先调到 0.1 试跑一段视频如果发现把角落的窗帘、黑板下沿误认成人再往回升到 0.2 左右。目标检测追求召回而人数统计更看重精确宁可漏检也不要误检所以 0.15 到 0.2 是教室场景的常见落点。iou 是 NMS 的阈值控制两个重叠框是否合并默认 0.7 在人群密集时会出现同一个学生被框两次的情况降到 0.5 可以缓解。imgsz 在推理时可以和训练时不一致CPU 上用 480 能明显提速代价是后排小目标会更难识别这一点看你的硬件取舍。4.2 用一个 QThread 封装摄像头推流避免界面卡死PyQt5 界面新手最容易犯的错误是把摄像头读帧和模型推理全塞进主线程。OpenCV 的 VideoCapture.read() 是阻塞的等待摄像头返回一帧的时间不稳定模型推理又要几百毫秒两个阻塞操作叠加界面就会表现为点一下按钮就整个卡住。解决方式很标准把读帧和推理丢进 QThread通过信号把结果传回主线程。import sys import cv2 from PyQt5.QtCore import QThread, pyqtSignal from PyQt5.QtWidgets import QApplication, QLabel, QPushButton, QVBoxLayout, QWidget from ultralytics import YOLO class DetectThread(QThread): frame_ready pyqtSignal(object) def __init__(self, model_path, source0): super().__init__() self.cap cv2.VideoCapture(source) self.model YOLO(model_path) self.running False def run(self): self.running True while self.running: ret, frame self.cap.read() if not ret: break # 推理conf/iou 按 4.1 节的原则设置 results self.model.predict(frame, conf0.18, iou0.5, imgsz640) self.frame_ready.emit(results[0].plot()) self.cap.release() def stop(self): self.running False逻辑不复杂QThread 的 run 方法里循环读帧在阻塞读帧的过程里模型推理也在工作线程中主线程只负责接收处理完的画面并刷新 QLabel。这个代码里有一个需要特别注意的坑不要在 run 内部直接修改任何 QLabel 或窗口控件的文本Qt 的界面控件不是线程安全的必须通过 frame_ready 信号传回主线程并绑定到槽函数里再做 setPixmap。我还习惯在 stop 方法里加一个 running 标志而不是直接 terminate 线程因为强制终止线程时摄像头资源经常来不及释放下一次启动会提示摄像头被占用。关闭窗口时也要做两步先调 stop()再调用 wait() 等线程真正结束否则程序退出时偶尔会崩溃报错信息还看不懂。4.3 从“检测多少框”到“统计多少人”取帧与均值平滑模型输出的检测框数量不等于当前教室人数因为摄像头一秒有 25 帧如果每一帧都刷新人数界面上的数字会跳个不停这帧 27 人下一帧 26 人再下一帧 29 人。原因可能是某帧有人低头挡住了脸或者画面上有人刚好叠在一起。常见做法是维护一个长度为 30 左右的滑动窗口对最近 N 帧的检测框数量做统计取中位数而不是平均值。平均值的毛病在于一个突然的误检会把数字拉高一大截过三四秒才恢复中位数则对单帧异常有天然的抵抗力。from collections import deque class PeopleCounter: def __init__(self, window_size30): self.samples deque(maxlenwindow_size) def update(self, count): self.samples.append(count) sorted_samples sorted(self.samples) return sorted_samples[len(sorted_samples) // 2]这个窗口大小 30 对应约一秒的实时画面数字既不会频繁跳动又能在一两秒内真实反映教室内的人员变化。这里有一个取舍窗口越短反应越快但对遮挡和瞬间出入的噪声越敏感窗口越长数字越稳定但人已经走出教室数字还停在原值。教室人数统计通常不会要求毫秒级响应我一般用的是 30 帧你觉得卡顿感太强可以放到 15。4.4 离线测试脚本先让逻辑跑通再连摄像头可视化界面的调试如果直接对着摄像头会非常痛苦因为画面内容不受你控制问题难以复现。所以我在做界面之前一定会先有一个离线视频测试脚本把录好的教室视频喂进去同时输出标注后的视频文件。from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) results model.predict( sourcetest_video.mp4, conf0.18, iou0.5, saveTrue, save_txtFalse, showFalse, )这段代码会把检测结果保存为一个新的 mp4 文件在 runs/detect/predict 目录下。用离线脚本的好处是参数调整的结果可以反复对比同样的视频、不同的置信度一帧一帧看误检漏检清清楚楚。等离线结果满意了再接入 UI界面开发时碰到的就只是界面问题不会和模型问题搅在一起。5. 避坑记录五次线上翻车与对应的处理方案5.1 现象CPU 推理只有 2 FPS教室一节课都数不完原因用了一个别人打包的模型里面对应的 imgsz 是 1280而且模型本身是 yolov8mCPU 跑这个组合基本就是幻灯片。还有一个隐藏问题代码在每一帧都重新加载了一次模型相当于每帧执行一次模型初始化。解决把模型换成 yolov8n 的 best.ptimgsz 降到 640一旦降到 640 还不够快就再降到 480。推理前把模型对象创建在循环外部只在程序启动时加载一次。我在 CPU 机器上的经验是yolov8n imgsz640 约 3 FPSimgsz480 约 5 FPS能勉强做到一两秒更新一次人数这对统计场景已经完全够用不一定非要 30FPS 实时。5.2 现象模型把窗帘当成人半小时报一次 120 人原因训练集里全是有人坐着的教室照片模型没学过“没有人但教室还在”的画面。拉升的窗帘有波浪褶皱颜色和肤色接近很容易成为误检来源。解决回到数据集加拍两三百张没有人的空教室照片标签全部为空。训练脚本会自动把空标签当负样本。我当时为了快速见效在推理参数里直接把 conf 从 0.18 提到 0.35误检确实少了大半但后排学生也被滤掉了不少。真正的解法还是负样本这个坑提醒我目标检测的数据集不仅要包含要找的目标还要包含容易混淆的干扰物体。5.3 现象训练 loss 一直不降mAP 停在 0.5 左右不动原因检查了 labels 文件夹发现标注框的类别索引写的是 1而 data.yaml 里类别数写的是 2。为什么会有这种乌龙因为转换脚本里 hardcode 过类别 0后来有人想加 teacher 类改成从 1 开始却忘了 person 应该还是 0。解决训练前打印 labels 目录下的任意三个 txt 文件第一列只能是 0。同时打开 images 目录里的训练图片标注框必须紧紧包住人而不是包住半个桌子。这个坑的本质是工具链里多个脚本对类别定义不一致解决方式是在转换脚本里写一个类别映射字典之后只能通过这个字典修改不要到处 hardcode。5.4 现象点下“开始检测”按钮界面立刻无响应只能强杀进程原因按钮的点击槽函数里直接调用了摄像头读取摄像头初始化失败时会一直阻塞等待界面主线程被卡死。这是 PyQt 开发里最典型的新手问题。解决把摄像头初始化和读取全部放到 QThread 里主线程只通过信号接收结果。另外还要注意摄像头的 index笔记本自带摄像头通常是 0USB 摄像头可能是 1 或 2如果摄像头 index 错误程序不一定报错但会表现为黑屏或者长时间无响应。我的习惯是提供两个入口参数界面加一个下拉框选择摄像头编号省得用户反复改代码。5.5 现象换一间教室立刻失效白天晚上表现天差地别原因训练集只在一间教室采集而且全部是白天开灯的数据。模型把那个教室的墙角、黑板颜色、窗帘光照特征当成了一部分“人”的特征换教室就泛化失败。解决收集数据时至少去三个不同的教室覆盖白天、黄昏、夜晚灯光三种光照还要采集投影幕布开启和关闭两种状态。如果项目进度不允许可以在推理前对画面做自适应亮度均衡OpenCV 的 CLAHE 能缓解一部分光照差异。另外在 YOLOv8 的训练增强里把 hsv_h、hsv_s、hsv_v 各调到 0.02 左右也能让模型不那么依赖颜色信息。6. 进阶从“能跑”到“可靠”用这三个手段验证再交差6.1 先做离线视频回放把 mAP 拆成漏检和误检mAP 是一堆框的综合指标但教室人数统计真正要回答的问题是屏幕上的数字和真实人数差多少。我的做法是录三段 10 分钟以上的教室视频人工数出每一帧的真实人数和模型输出做对齐算出平均绝对误差。这个数字比 mAP 更能说服答辩老师也比单纯的效果演示可信。6.2 ONNX 导出与边缘设备部署给毕设答辩加一个亮点如果你的目标是让这个应用更接近工业落地可以再做一步把 best.pt 导出成 ONNX 格式再在 RK3588 这类带 NPU 的边缘设备上做部署。yolo export modelruns/detect/train/weights/best.pt formatonnx imgsz640 opset12导出后的 ONNX 模型可以用 onnxruntime 直接推理也可以再接 RKNN-Toolkit 转成 NPU 能跑的格式。这里有个血泪经验转 INT8 量化后教室后排的小人头精度会掉得很明显mAP50 可能下降 0.1 到 0.3如果现场演示时发现小目标大量漏检优先检查量化校准数据集是否包含了夜间画面。边缘部署的工程量比跑通一个电脑端界面要多一倍但它能把项目从“课程设计”提升到“可交付产品”的质感。结尾说一个我自己的习惯每次调完一次模型我会把训练命令、数据集改动、推理参数变化和由此带来的效果差异记在项目根目录的更新日志里。这个习惯帮我救回过很多次回退决策也让我在被问到“你这个效果怎么复现”时能几秒钟就给出完整链路。依赖记忆做项目是最贵的项目。希望这篇笔记能帮你在做 YOLOv8 智慧教室人数统计时少走几段弯路。本文还有配套的精品资源点击获取