YOLOv8教室窗户破损识别：从数据标注到部署的完整实战拆解

简介：基于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", encoding="utf-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", encoding="utf-8") as f: f.write("\n".join(lines)) if __name__ == "__main__": os.makedirs("labels", exist_ok=True) 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(f"dataset/images/{split}", exist_ok=True) os.makedirs(f"dataset/labels/{split}", exist_ok=True) for img in imgs: base = os.path.basename(img)[:-4] os.rename(img, f"dataset/images/{split}/{base}.jpg") os.rename(f"all_labels/{base}.txt", f"dataset/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_window

path决定训练时去哪个根目录找图片，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 python=3.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 \ model=weights/yolov8s.pt \ data=dataset/data.yaml \ epochs=80 \ imgsz=640 \ batch=16 \ device=0 \ patience=20 \ cache=True

每个参数都能在答辩时解释：model是起步权重，yolov8s是small规模，比nano精度高，比medium的显存压力小。教室窗户破损不是高速运动目标，s的检测速度完全够用，是性价比最稳的起点。epochs是总训练轮数，单类任务80轮足够，下面的patience会帮你提前停。imgsz=640是输入分辨率，别为了提速改到320，窗户裂纹是细长目标，分辨率一降特征就模糊，宁可batch小一点也要保住imgsz。batch是显存和速度的平衡，以GTX 1660 Ti这种6G显存卡为例，yolov8s配640分辨率，batch取8到16之间，报CUDA out of memory就往下降。device=0表示用第一块GPU，CPU机器改成device=cpu。patience=20是验证集指标连续20轮不涨就早停，防止无效训练。cache=True把数据集一次性缓存到内存，每一轮训练不再重复读磁盘，对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( source="test_images/room_01.jpg", # 单张图或整个文件夹 conf=0.35, # 置信度阈值，低于该值的目标被过滤 imgsz=640, save=True, # 把画好检测框的结果图保存到 runs/detect/predict name="infer_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之后转成整数，是为了后面界面画框直接可以用。参数里conf=0.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( source=img_path, conf=self.conf_thres, imgsz=640, verbose=False # 关闭逐帧日志，控制台不被刷屏 ) 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

两个关键点：verbose=False在部署环境里很重要，没人想在演示时看着控制台疯狂刷推理日志；返回的detections是纯Python字典列表，界面拿到后转成Qt的QPainter矩形或Streamlit的st.image都可以，和UI细节完全解耦。全局只创建一次WindowDetector，不要在每个按钮回调里重新加载一次YOLO权重，模型加载是一次性开销，放按钮里会让第一次点击慢好几秒。

注意：如果界面里允许用户手动改置信度，就把conf_thres做成构造参数传进来或单独提供setter，不要写死在predict调用里。演示时现场调阈值是常见的加分操作。

4.3 目录组织、依赖清单与启动方式

一个能交差的毕设系统，交付目录建议长成下面这样，不依赖IDE，命令行就能跑：

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_thres=0.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，之后所有指标全变成nan，best.pt永远保存不出来，整个训练等于白跑。

原因：最常见的是标签里有宽度或高度为0的退化框，转换脚本的过滤条件没写；其次是学习率对当前数据量来说过高，模型参数在早期就发散了。

解决：先回到转换脚本，扫描labels目录下有没有“0 0.5 0.5 0 0”这种宽高为零的行，有就把对应txt删掉重新生成。然后训练命令加一个lr0=0.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 detections

UI线程只负责等待结果，每次推理结束调一次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、翻转、色域变换，训练命令可以再加augment=True并调大hsv_h、degrees等增强参数。第二招迁移学习冻结backbone，只训练检测头：

yolo detect train \ model=weights/yolov8s.pt \ data=dataset/data.yaml \ epochs=80 \ freeze=10

freeze=10表示冻结backbone骨干网络，核心思想是底层特征仍然来自ImageNet预训练权重，不跟着小数据集乱学，让neck和head只去适配破损任务的差异。数据少时这一招比堆epochs有效得多，后面数据攒够了再去掉freeze全量微调。

6. 从交差到加分：用mAP和损失曲线验证模型，再导出ONNX

6.1 用结果曲线和mAP验证模型真本事

训练完别急着演示，先用验证集给模型打分：

yolo detect val model=runs/detect/train/weights/best.pt data=dataset/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(x="epoch", y=["train/box_loss", "val/box_loss"], title="loss curve") plt.savefig("loss_curve.png")

val loss先降后升就是过拟合的直接信号，对应5.5的处理方式。图放进答辩PPT里，比贴一堆终端日志有说服力。

6.2 导出ONNX模型，为嵌入式部署留后路

模型权重只有ultralytics能读，导出ONNX后任何支持ONNX Runtime的设备都能跑。这是答辩加分点，说明你考虑了部署落地：

yolo export model=runs/detect/train/weights/best.pt format=onnx imgsz=640

导出后在runs/detect/train/weights下得到best.onnx，用onnxruntime在CPU上推理，完全脱离torch，依赖极轻。后续想上rk3588这类板子，也是从onnx再转一步。虽然毕设不一定用到，但面试被问“能不能跑边缘设备”时，这条路径你心里有数。

我自己的习惯是，拿到任何一套这类系统，第一件事不是打开app.py，而是先跑通推理脚本，确认权重和数据都没问题，再碰界面。这个顺序能省掉一半的排查时间。教室窗户破损识别不算热门方向，但它把目标检测从标数据到部署的整体流程完整走了一遍，这套方法论拿到别的检测任务一样用。希望帮到你。

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