简介基于YOLOv8的教室窗户破损识别系统是一套面向毕业设计、课程设计的完整目标检测项目适用计算机视觉、人工智能等方向的学生快速搭建并演示检测效果。压缩包共含8个文件以3个Python源码文件、3个PyTorch模型权重文件和2个说明文档为主体整体仅15.91MB轻量便于部署。源码涵盖模型训练、视频检测与可视化界面等模块权重文件包含yolov8n.pt、best.pt以支持直接推理说明文档则提供部署引导。项目附带完整数据集与可视化页面可自动生成核心指标曲线、混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果及标签分布图便于在答辩或汇报中展示训练质量与分析过程。目前已有41人学习适合需要快速验证YOLOv8检测流程或完成课设、毕设演示的读者下载参考。1. YOLOv8教室窗户破损识别一套能直接交差的毕设系统拆解先把结论放在前面教室窗户破损识别是一个很适合当作目标检测选题的任务因为破损区域在画面里特征明确、场景固定而YOLOv8在同类缺陷检测上的表现足够稳定不需要企业级工程技巧就能训练出能演示的模型。标题这套系统把源码、可视化界面、完整数据集和部署教程打包在一个zip里装上依赖就能跑通训练到推理的全流程适合正在赶毕业设计或课程设计的学生也适合想拿现成方案快速验证破损检测想法的工程人员。不过“简单部署即可运行”不等于双击就完事。环境配置、数据格式、训练参数、界面调用每一步都有几个容易翻车的细节。这篇笔记按一线工程师的习惯把这个方案拆给你看从数据组织讲到训练命令从界面封装讲到部署避坑最后落在模型验证和导出上。新手能按步骤跟下来熟手也能在参数和边界问题上省点时间。2. 把数据做干净窗户破损识别的前置工作与数据集组织2.1 破损识别不是普通目标检测类别定义与YOLOv8的结构匹配度教室窗户破损和行人检测有个本质区别它的目标不是完整物体而是一块不规则的局部区域。裂纹细长、破洞形状随意、整块玻璃缺失时又只能拍到窗框这些形态差异很大。如果把整扇窗户框起来标一个“破损”框模型会同时学到大量正常玻璃的特征正样本框内的背景占比过高训练时容易被带偏。常见做法是只框住破损发生的区域让标签框和视觉特征尽量重合。这个任务因此特别吃标注一致性。同一张破损图有人框裂纹主体有人把裂纹加周边阴影一起框模型会在不同分布之间摇摆训练完的检出率忽高忽低。我一般会在标注前定一条硬规则玻璃明显碎裂、或贯穿性裂纹长度超过窗框宽度三分之一的区域统一标成broken_window单个点状小坑如果面积不到整扇窗的百分之五先跳过不标。规则定死后不同人标注的结果也基本能对齐。类别数我强烈建议只开一类“破损”不要顺手把“窗户关闭”“窗户开启”也标进来。多类别在答辩时听起来丰富但标注量成倍增加而且开启和破损两种状态经常同时出现类别语义重叠模型学起来更乱。选YOLOv8来做这类检测看重的主要是它的多尺度特征融合能力。YOLOv8的backbone用C2f模块替换了YOLOv5里的C3配合SPPF池化和neck部分的PAN-FPN结构深层语义特征和浅层边缘纹理特征能在同一层输出里汇聚。窗户裂纹是细长目标浅层特征里的边缘纹理最关键深层特征负责判断这到底是不是破损两层叠加后的检出率在类似缺陷数据集上明显优于同体量的YOLOv5。网络结构图里最值得看的是neck部分的特征拼接层破损框大小差异较大小框靠浅层特征大框靠深层语义PAN-FPN正好覆盖这个范围。2.2 用labelme标注后转YOLO格式转换脚本与四个边界坑标注工具常见的方案是labelme纯Python包pip install labelme就能用标注结果存成JSON肉眼可查。但YOLOv8训练不认这种标注格式只认一行一个目标的txt格式是“类别id 中心x 中心y 宽 高”所有坐标都按图像宽高归一化到0到1之间。拿到JSON后的第一件事就是写转换脚本。import json import os from glob import glob # labelme 的 JSON 转 YOLO 的 txt # 类别映射0 代表破损区域和后面 data.yaml 里 names 的顺序一致 CLASS_MAP {broken_window: 0} def labelme_to_yolo(json_path: str, out_dir: str): with open(json_path, r, encodingutf-8) as f: data json.load(f) img_w int(data[imageWidth]) img_h int(data[imageHeight]) if img_w 0 or img_h 0: return # 宽高为0说明原图损坏直接跳过避免除零 txt_name os.path.basename(json_path).replace(.json, .txt) lines [] for shape in data[shapes]: label shape[label] if label not in CLASS_MAP: continue # 类别名不匹配就忽略比如误标了 window 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) box_w x_max - x_min box_h y_max - y_min if box_w 2 or box_h 2: continue # 过滤退化框宽高为0的框会让训练直接出NaN x_center (x_min x_max) / 2 / img_w y_center (y_min y_max) / 2 / img_h w box_w / img_w h box_h / img_h # 边缘坐标夹到 0~1防止标注多边形画出图片边界 x_center max(0.0, min(1.0, x_center)) y_center max(0.0, min(1.0, y_center)) w max(0.0, min(1.0, w)) h max(0.0, min(1.0, h)) lines.append(f{CLASS_MAP[label]} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}) with open(os.path.join(out_dir, txt_name), w, encodingutf-8) as f: f.write(\n.join(lines)) if __name__ __main__: os.makedirs(labels, exist_okTrue) for json_file in glob(labelme_json/*.json): labelme_to_yolo(json_file, labels)代码逻辑分四步先读原图宽高用于后面坐标归一化然后遍历shapes里的每个标注取最小外接矩形再把矩形从像素坐标转成归一化的中心点加宽高最后写进同名txt。过滤退化框和越界夹取是容易漏的两步缺了它们训练时轻则丢目标重则loss直接罢工。参数说明CLASS_MAP是唯一需要你按自己的标注改的地方图里写“裂纹”就改成{裂纹: 0}但要保证和后面data.yaml的names对得上。输入路径labelme_json和输出路径labels都按自己的目录改。跑完脚本别急着训练随机抽三张图把txt用记事本打开核对每行是不是“0 0.5 0.5 0.3 0.4”这种结构再把txt和原图叠在一起看框的位置对不对。这一步能拦住一半以上的训练报错。2.3 数据划分与data.yaml训练前最后一步数据转换完成后按YOLOv8约定成俗的目录结构摆放images和labels两棵平行树各自分train和val子目录。图片放images/train对应的txt放labels/train文件名必须一致。常见划分比例是85%训练、15%验证训练集大一点验证集保证能看到模型在没见过的图上的表现。dataset/ ├── data.yaml ├── images/ │ ├── train/ │ │ ├── classroom_001.jpg │ │ └── ... │ └── val/ │ └── ... └── labels/ ├── train/ │ ├── classroom_001.txt │ └── ... └── val/ └── ...划分时要注意同名成对移动图走了txt没走训练时就会报图片对应标签缺失。我习惯用一段固定随机种子的脚本做划分保证换机器重跑结果一致import os import random from glob import glob # 对图片做 85/15 随机划分jpg 和同名 txt 必须一起移动 random.seed(42) images glob(all_images/*.jpg) random.shuffle(images) val_count int(len(images) * 0.15) val_images images[:val_count] train_images images[val_count:] for split, imgs in [(train, train_images), (val, val_images)]: os.makedirs(fdataset/images/{split}, exist_okTrue) os.makedirs(fdataset/labels/{split}, exist_okTrue) for img in imgs: base os.path.basename(img)[:-4] os.rename(img, fdataset/images/{split}/{base}.jpg) os.rename(fall_labels/{base}.txt, fdataset/labels/{split}/{base}.txt)random.seed(42)这行不是装饰固定种子后每次划分结果完全一样答辩时重跑演示不会越跑越偏。划分完数一下两个目录的文件数图片和txt数量对不上多半是哪里漏了空标签文件。最后是data.yaml训练命令和数据集的唯一接口path: dataset # 相对路径以执行训练命令的目录为基准 train: images/train val: images/val nc: 1 # 类别数和 CLASS_MAP 长度一致 names: 0: broken_windowpath决定训练时去哪个根目录找图片train和val再相对path拼接。如果训练报错说找不到图片目录先检查path和train拼出来的完整路径是否存在写上绝对路径能绕过这个问题但zip换目录后要记得改回相对路径。3. 训练自己的数据集环境配置、训练命令与推理验证3.1 Ubuntu 20.04上搭建YOLOv8环境CPU版和GPU版两条路标题说“简单部署即可运行”前提是先把环境跑通。YOLOv8的训练和推理都走ultralytics这个官方库安装方式很统一。常见做法是用conda建独立虚拟环境Python选3.9最稳3.10和3.11也能跑但有些老版本PySide6界面项目在3.11下会有兼容问题统一用3.9少折腾。# 创建虚拟环境名字随意yolov8 就行 conda create -n yolov8 python3.9 -y conda activate yolov8 # CPU 版直接装 ultralytics会自动带 CPU 版 torch pip install ultralytics # GPU 版先装与驱动匹配的 torch再装 ultralytics pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics很多人的机器没有NVIDIA独显Ubuntu 20.04上CPU版训练完全能跑只是慢。一个epoch在CPU上可能要几分钟GPU上几十秒毕设数据量小CPU硬扛也能出结果。CPU版唯一要注意的是batch别调太大内存会先爆。GPU版真正麻烦的是torch和CUDA版本匹配装之前先nvidia-smi看一眼驱动支持的CUDA版本再选对应的cu版本驱动版本太低时import torch会直接报显卡驱动不匹配。装完之后不要急着开训练先验证环境python -c import ultralytics; from ultralytics import YOLO; print(ultralytics.__version__)能打印版本号就说明ultralytics装好了。第一次运行YOLO时预训练权重比如yolov8s.pt会被ultralytics自动下载到当前目录这个过程对网络状况比较敏感下载不顺畅时会反复重试看起来像卡死实际是个黑匣子。稳妥的办法是让项目里的weights目录预先放好一份yolov8s.pt训练命令直接指定本地路径绕开自动下载。你拿到的那套源码包里如果有weights文件夹优先用里面的权重版本和依赖对得上。3.2 训练命令与参数含义GTX 1660 Ti级别的机器怎么设数据就绪后训练命令本身不复杂。我通常用的是下面这条直接改路径就能跑yolo detect train \ modelweights/yolov8s.pt \ datadataset/data.yaml \ epochs80 \ imgsz640 \ batch16 \ device0 \ patience20 \ cacheTrue每个参数都能在答辩时解释model是起步权重yolov8s是small规模比nano精度高比medium的显存压力小。教室窗户破损不是高速运动目标s的检测速度完全够用是性价比最稳的起点。epochs是总训练轮数单类任务80轮足够下面的patience会帮你提前停。imgsz640是输入分辨率别为了提速改到320窗户裂纹是细长目标分辨率一降特征就模糊宁可batch小一点也要保住imgsz。batch是显存和速度的平衡以GTX 1660 Ti这种6G显存卡为例yolov8s配640分辨率batch取8到16之间报CUDA out of memory就往下降。device0表示用第一块GPUCPU机器改成devicecpu。patience20是验证集指标连续20轮不涨就早停防止无效训练。cacheTrue把数据集一次性缓存到内存每一轮训练不再重复读磁盘对Windows机器效果尤其明显。这套参数也可以写进一个config.yaml用yolo detect train -f config.yaml指定但毕设场景没必要命令行直接看得到全部参数演示时好讲。训练过程中看runs/detect/train目录下的进度loss曲线每轮都会打印。如果train_loss一路下降但val_loss开始反弹八成是过拟合回到数据增强那部分处理。3.3 用训练好的best.pt跑推理最小推理脚本训练输出在runs/detect/train下里面的weights文件夹有两个权重best.pt是验证集上表现最好的last.pt是最后一轮的。部署和界面调用都认best.pt不要图省事拿last.pt两者差别在大轮数训练后很明显。from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) results model.predict( sourcetest_images/room_01.jpg, # 单张图或整个文件夹 conf0.35, # 置信度阈值低于该值的目标被过滤 imgsz640, saveTrue, # 把画好检测框的结果图保存到 runs/detect/predict nameinfer_demo ) for r in results: for box in r.boxes: x1, y1, x2, y2 box.xyxy[0].tolist() score float(box.conf[0]) print(f破损区域: ({int(x1)},{int(y1)})-({int(x2)},{int(y2)}) 置信度{score:.2f})predict返回的results是一个列表每个元素对应一张输入图。r.boxes里是检测框、置信度和类别编号xyxy[0]是左上角和右下角坐标tolist之后转成整数是为了后面界面画框直接可以用。参数里conf0.35是经验起点破损检测宁可漏掉模糊的小裂纹也不要满屏误检如果演示时发现虚警多把conf抬到0.45再跑一次。跑完之后去runs/detect/predict翻检测结果图重点看三类错误把正常窗户框成破损的叫误检明显破损没被框出来的叫漏检框的位置偏了一半的是定位不准。误检多调conf漏检多回数据集补样本定位偏则检查标注框有没有贴合裂纹区域。这套排查顺序比盲目调epochs高效得多。4. 可视化界面与部署把模型封装成能交差的系统4.1 界面技术选型桌面端PySide6还是浏览器端Streamlit标题里的“可视化界面”没限定形态市面上这类系统两种做法都常见。第一种是PySide6/PyQt桌面窗口左边图片选择区中间检测画面右边置信度和坐标列表按钮风格像传统软件答辩演示时观感稳定缺点是依赖Qt环境换机器要装PySide6。第二种是Streamlit浏览器界面十几行代码就能出一个带上传按钮的网页内置摄像头调用也方便缺点是每次推理刷新页面有延迟连续操作体验比桌面端差点。我的判断标准很直接看部署教程里的启动命令。教程写python app.py的是PySide6路线写streamlit run app.py的是Streamlit路线。自己选型时如果演示需要视频流或摄像头实时检测优先PySide6如果只是逐张选图看效果Streamlit出活最快。课程设计答辩大多数是静态演示两条路都能走选哪条取决于你更熟悉Qt布局还是Python页面脚本。4.2 把推理封装成独立类界面调用的核心代码界面代码最忌讳把YOLO推理逻辑直接写在按钮回调里。推理一次要一两秒期间窗口事件循环被阻塞表现出来就是转圈假死。常见做法是做一个独立检测类界面只负责接收它的返回值互相不干扰。from ultralytics import YOLO class WindowDetector: 把 YOLO 推理包一层界面只调用 detect_image不碰底层细节 def __init__(self, weights_path: str, conf_thres: float 0.4): self.model YOLO(weights_path) self.conf_thres conf_thres def detect_image(self, img_path: str): results self.model.predict( sourceimg_path, confself.conf_thres, imgsz640, verboseFalse # 关闭逐帧日志控制台不被刷屏 ) detections [] for box in results[0].boxes: x1, y1, x2, y2 box.xyxy[0].tolist() detections.append({ bbox: [int(x1), int(y1), int(x2), int(y2)], score: round(float(box.conf[0]), 3), label: broken_window }) return detections两个关键点verboseFalse在部署环境里很重要没人想在演示时看着控制台疯狂刷推理日志返回的detections是纯Python字典列表界面拿到后转成Qt的QPainter矩形或Streamlit的st.image都可以和UI细节完全解耦。全局只创建一次WindowDetector不要在每个按钮回调里重新加载一次YOLO权重模型加载是一次性开销放按钮里会让第一次点击慢好几秒。注意如果界面里允许用户手动改置信度就把conf_thres做成构造参数传进来或单独提供setter不要写死在predict调用里。演示时现场调阈值是常见的加分操作。4.3 目录组织、依赖清单与启动方式一个能交差的毕设系统交付目录建议长成下面这样不依赖IDE命令行就能跑文件/目录作用weights/best.pt训练好的模型权重界面和推理脚本共用detector.pyWindowDetector检测类封装app.py界面入口python app.py启动dataset/完整数据集可重新训练验证requirements.txt依赖清单新机器装环境用README.md启动步骤、参数说明、目录结构requirements.txt锁三个关键依赖就行ultralytics、PySide6或streamlit、opencv-python。版本号建议写成而不是否则新机器上容易和系统已有库冲突。装依赖和启动各一条命令pip install -r requirements.txt python app.py如果界面走的是Streamlit第二条命令是streamlit run app.py这是部署教程里最该写清的一句话写错了整篇教程跑不通。app.py的主入口是个固定三段式import sys from PySide6.QtWidgets import QApplication from detector import WindowDetector if __name__ __main__: detector WindowDetector(weights/best.pt, conf_thres0.4) app QApplication(sys.argv) main_window MainWindow(detector) # MainWindow 来自你的界面文件 main_window.show() sys.exit(app.exec_())先创建detector再传给窗口类让窗口加载时就能拿到推理实例。路径敏感的问题也在这里处理模型路径别写C:\Users...这种绝对路径zip解压到别的目录就找不到权重。用Path(file).parent拼接相对路径程序在哪都能被启动。这一步是“简单部署即可运行”的关键让解压位置不影响运行。5. 避坑从训练到部署最常见的5个翻车现场5.1 训练loss变成NaN先查标签再降学习率现象训练刚开始一两个epoch终端里显示的box_loss就是nan之后所有指标全变成nanbest.pt永远保存不出来整个训练等于白跑。原因最常见的是标签里有宽度或高度为0的退化框转换脚本的过滤条件没写其次是学习率对当前数据量来说过高模型参数在早期就发散了。解决先回到转换脚本扫描labels目录下有没有“0 0.5 0.5 0 0”这种宽高为零的行有就把对应txt删掉重新生成。然后训练命令加一个lr00.001参数默认学习率一般是0.01小数据集上容易炸。改完还出nan把batch调小一半再看第一轮loss是收敛还是继续发散。这条是血泪经验我见过太多人先调模型结构最后发现就是标签里有个零宽框。5.2 检测框乱飘误检高负样本和置信度阈值现象模型在没破损的窗户上框出一堆框窗帘褶皱、窗框阴影、黑板反光全被识别成破损检测画面看起来像在乱抓。原因训练集里全是正样本模型没见过“没有破损的教室”长什么样于是把纹理异常都当作目标。解决往数据集里补一批完全没有破损的教室窗户照片对应的txt文件保持为空一个目标都不标。YOLO支持空标签训练这些负样本会明确告诉模型“这种画面里没有目标”。另一个直接见效的手段是推理时把conf从0.25抬高到0.4或0.45破损检测不需要追求每条细小裂纹都检出减少虚警比多检出更重要门卫场景宁可漏报轻微裂纹也不该把正常窗户报成破损。5.3 界面卡死与CUDA out of memory线程与缓存管理现象界面里连续点几张图第一次正常第三张直接报CUDA out of memory窗口跟着假死只能强杀进程。原因推理被放在界面主线程模型阻塞了窗口绘制同时连续推理产生大量中间张量显存没被及时释放。解决推理切到单独线程用QThread或concurrent.futures的ThreadPoolExecutor都行。检测类里在返回前释放显存缓存import torch # 在 WindowDetector.detect_image 的 return 之前加一行 torch.cuda.empty_cache() return detectionsUI线程只负责等待结果每次推理结束调一次empty_cache连续推理几十张也不会撑爆显存。CPU机器没这个问题但线程分离一样要做否则窗口照旧卡死。5.4 换一台机器跑不起来环境一致性现象开发机跑得好好的拷到另一台电脑python app.py报ModuleNotFoundError: No module named ultralytics或PySide6导入失败。原因zip里通常只装源码和数据环境依赖需要目标机器自己装。部署教程里如果漏了requirements.txt这一步新机器就是跑不起来。解决不要在目标机器上手动一个一个pip install直接执行pip install -r requirements.txt依赖版本统一锁好。要注意老机器还是32位系统时装不了新版torch只跑CPU推理的话强制装CPU版本。把这些步骤写进部署教程能少很多“换台电脑就崩”的尴尬。5.5 数据集小、模型过拟合数据增强和freeze现象训练集只有两三百张图训练时train loss降得很漂亮val loss先降后反弹在没见过的教室照片上效果差。原因数据量撑不起模型自由度模型开始死记训练图。解决第一招数据增强YOLOv8默认开了mosaic、翻转、色域变换训练命令可以再加augmentTrue并调大hsv_h、degrees等增强参数。第二招迁移学习冻结backbone只训练检测头yolo detect train \ modelweights/yolov8s.pt \ datadataset/data.yaml \ epochs80 \ freeze10freeze10表示冻结backbone骨干网络核心思想是底层特征仍然来自ImageNet预训练权重不跟着小数据集乱学让neck和head只去适配破损任务的差异。数据少时这一招比堆epochs有效得多后面数据攒够了再去掉freeze全量微调。6. 从交差到加分用mAP和损失曲线验证模型再导出ONNX6.1 用结果曲线和mAP验证模型真本事训练完别急着演示先用验证集给模型打分yolo detect val modelruns/detect/train/weights/best.pt datadataset/data.yaml输出里重点看mAP50和mAP50-95。教室窗户破损任务看mAP50就够了因为对定位精度的要求不像自动驾驶那么苛刻框压住破损区域就算合格。mAP50超过0.7是可交差的水平低于0.5说明数据或参数有问题回去查标注一致性。指标这东西多少带点玄学但值低到一定程度就是实打实的数据问题。训练过程的损失曲线也能画出来不用自己造轮子results.csv已经把每个epoch的train/box_loss和val/box_loss记好了import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(runs/detect/train/results.csv) df[epoch] range(len(df)) df.plot(xepoch, y[train/box_loss, val/box_loss], titleloss curve) plt.savefig(loss_curve.png)val loss先降后升就是过拟合的直接信号对应5.5的处理方式。图放进答辩PPT里比贴一堆终端日志有说服力。6.2 导出ONNX模型为嵌入式部署留后路模型权重只有ultralytics能读导出ONNX后任何支持ONNX Runtime的设备都能跑。这是答辩加分点说明你考虑了部署落地yolo export modelruns/detect/train/weights/best.pt formatonnx imgsz640导出后在runs/detect/train/weights下得到best.onnx用onnxruntime在CPU上推理完全脱离torch依赖极轻。后续想上rk3588这类板子也是从onnx再转一步。虽然毕设不一定用到但面试被问“能不能跑边缘设备”时这条路径你心里有数。我自己的习惯是拿到任何一套这类系统第一件事不是打开app.py而是先跑通推理脚本确认权重和数据都没问题再碰界面。这个顺序能省掉一半的排查时间。教室窗户破损识别不算热门方向但它把目标检测从标数据到部署的整体流程完整走了一遍这套方法论拿到别的检测任务一样用。希望帮到你。本文还有配套的精品资源点击获取