简介基于YOLOv8的居民楼外立面瓷砖脱落检测项目是一套面向毕业设计、课程设计及目标检测初学者的完整解决方案。项目代码经实际测试通过内含源码、标注数据集、可视化交互界面与部署说明覆盖模型训练、视频检测到结果分析的全流程。压缩包共8个文件其中3个Python脚本分别对应模型训练、视频检测和可视化页面3个模型权重文件包含预训练权重与训练后的最佳模型2个文本文件提供说明与引导整体仅15.91MB结构紧凑、易于移植。目前已有38人学习下载适合需要快速搭建完整检测方案、节省调试时间的用户。借助项目可直接生成核心指标曲线、混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果及标签分布图为答辩或课程汇报提供直观支撑配套数据集与部署教程简单部署即可运行。1. 基于YOLOv8的居民楼外立面瓷砖脱落这套带界面的检测包解决什么问题做居民楼外立面瓷砖脱落检测很多人第一反应是堆模型、刷精度真跑一遍就会发现这类项目的难点根本不在训练那一小时而是从“楼下随手拍的照片”到“能画框的软件”这条完整链路。基于 YOLOv8 的居民楼外立面瓷砖脱落项目打包的正是这条链路数据集、标注格式、训练配置、可视化界面和部署教程都齐了下载后按步骤把环境配好就能跑不需要自己从零写检测逻辑。它解决的场景很具体——外立面巡检里“瓷砖鼓包、开裂、脱落风险区”的自动发现适合正在做毕业设计或课程设计的学生也适合想快速验证“视觉检测外墙缺陷是否可行”的工程团队。你拿到的不是一份冷冰冰的权重文件而是一套能当场演示的完整方案。2. 瓷砖脱落数据集怎么做来源、标注规范与预处理脚本2.1 数据来源自拍、无人机与公开图库怎么组合拿到手的完整数据集里一般已经有几百张标注好的图片但这些图大概率只是“能跑通”的程度。外立面瓷砖脱落有个特点脱落区域在远拍照片里往往只有几十个像素而且墙面纹理、光照方向、窗户反光都会干扰模型。要让模型真正在陌生楼栋上也能用数据分布比数据总量更关键。常见做法是补三类数据。第一类是自己用手机或长焦相机在楼下仰拍这是最容易做的第二类是有条件的话用无人机绕楼飞一圈拍到平视和俯视视角因为巡检场景里无人机视角和你站在楼下仰拍看到的纹理完全不同第三类是找公开的建筑外立面图库只挑内容是普通居民楼外墙、且没有明显脱落的图片当负样本这能显著降低误检。需要注意网上下载的图片要确认使用许可且尽量别让验证集里混入和训练集同角度同楼栋的图否则精度虚高后面实测一测就露馅。2.2 标注规范什么算“脱落”什么不该标进去标注标准不统一是这类项目里最隐蔽的数据质量坑。我一般会把目标定义成两类一类是“脱落”指瓷砖整块缺失、表层剥落露出基层、或者边角明显翘起另一类是“开裂”指砖面出现裂缝但还没掉下来。如果数据集里只有单类就把开裂也并入脱落但前提是模型输出的语义要和你最终想用的一致。不该标进去的包括墙面水渍、阴影、空调外机、窗户反光、爬藤植物、施工脚手架。这些在照片里看起来很像缺陷标进去只会让模型学到错误特征。标注框的规则是“包住脱落区域的最小矩形”宁可每条边稍微往外放一两像素也不要切到缺陷边缘对密集脱落区域要单独标出每个小框不要用一个大框把一整片都框进去否则模型学到的是“这一片整块都是目标”定位精度会变差。一个实用的检查方法是先标完 100 张回头再扫一遍前后标准不一致是标注最大的隐形杀手。2.3 预处理脚本把标注转换成 YOLO 格式的干净代码YOLOv8 训练需要的是 txt 标注文件每行一个目标格式是“类别id 中心点x 中心点y 宽 高”全部归一化到 0~1。如果数据集里给的是 XMLVOC 格式或者你自己用工具标了 XML可以用下面这段脚本做转换。import os import xml.etree.ElementTree as ET from pathlib import Path def voc_to_yolo(xml_path, out_txt, class_map): tree ET.parse(xml_path) root tree.getroot() size root.find(size) w int(size.find(width).text) h int(size.find(height).text) lines [] for obj in root.iter(object): name obj.find(name).text if name not in class_map: continue box obj.find(bndbox) x1 float(box.find(xmin).text) y1 float(box.find(ymin).text) x2 float(box.find(xmax).text) y2 float(box.find(ymax).text) # 标注软件常产生几像素越界先裁到图像范围内 x1 max(0, min(x1, w - 1)) y1 max(0, min(y1, h - 1)) x2 max(1, min(x2, w)) y2 max(1, min(y2, h)) # 过滤掉宽或高小于2像素的脏框 if x2 - x1 2 or y2 - y1 2: continue cx (x1 x2) / 2 / w cy (y1 y2) / 2 / h bw (x2 - x1) / w bh (y2 - y1) / h cls_id class_map[name] lines.append(f{cls_id} {cx:.6f} {cy:.6f} {bw:.6f} {bh:.6f}) with open(out_txt, w) as f: f.write(\n.join(lines) \n) class_map {falling: 0, crack: 1} voc_to_yolo(annotations/001.xml, labels/train/001.txt, class_map)这段逻辑很直接把 VOC 的像素坐标转成 YOLO 需要的归一化中心点和宽高。参数说明里最需要注意的是越界裁剪和最小尺寸过滤很多标注工具导出时会有几个像素的越界不裁会导致训练时边框比例异常宽度小于 2 像素的框基本都是误标或无效小点留着只会给损失函数添乱。转换完成后用 labelImg 直接输出 YOLO 格式也可以省掉转换这一步但批量整理数据集时还是脚本更可控出错能重跑。2.4 数据增强哪些能用哪些会让模型学歪YOLOv8 自带一套增强参数在训练 yaml 或命令行里都能调。针对外立面场景我的建议是水平翻转可以开因为左右对称的楼面在现实里很常见亮度扰动可以开因为不同朝向的楼面光照差异很大小角度旋转控制在 ±10 度以内现实中的外墙横平竖直旋转角度太大会制造现实中不存在的纹理方向。要小心的增强是 Mosaic。YOLOv8 默认把 Mosaic 开到 1.0四张图拼在一起训练确实能提升小目标鲁棒性但在瓷砖这种重复纹理上Mosaic 拼图会切碎瓷砖的排列规律模型容易把拼接缝当成边缘特征。我一般把 mosaic 设成 0.5让它和原图各占一半。还有一个常见误用是加高斯模糊模拟雾天这会让模型学到的特征是“模糊”而不是“脱落”实拍一测就会翻车。合理起步参数可以这样设fliplr0.5hsv_h0.015hsv_s0.5hsv_v0.4mosaic0.5。3. YOLOv8 训练与调参从环境配置到看懂损失曲线3.1 环境版本Python、PyTorch、ultralytics 怎么配套这套方案的运行环境要求不高常见配置就能跑。Python 用 3.8 到 3.11 之间都行PyTorch 装 2.x 版本对应 CUDA 11.8 或 12.1。安装顺序有个血泪经验先装 PyTorch再装 ultralytics顺序反了容易出现依赖冲突。命令如下conda create -n facade python3.10 conda activate facade pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics第一行创建虚拟环境第二行激活第三行装 GPU 版 PyTorch。如果你机器上没有 NVIDIA 显卡直接把第三行改成pip install torch torchvision即可CPU 版能跑只是训练慢不少。GTX 1660Ti 这种 6GB 显存的显卡跑 yolov8s 完全没问题batch 设 8 到 16 都行。装完可以用yolo version验证 ultralytics 是否正常能打印版本号就说明环境通了。3.2 数据集配置文件与模型选型YOLOv8 训练前要准备一个数据集描述文件一般是 yaml 后缀里面指定图片路径、验证集路径和类别名。下面是一个可直接用的模板path: D:/datasets/facade train: images/train val: images/val nc: 2 names: 0: falling 1: crackpath 是数据集根目录train 和 val 相对于 path 来写。nc 是类别数量names 的顺序必须和标注 txt 里的类别 id 严格对应这是最容易埋雷的地方——很多数据集给的标注文件里类别 id 和 names 顺序对不上训练时模型会学得一头雾水。模型选型方面我建议从 yolov8s 起步而不是 yolov8n。n 模型速度快但参数量少对瓷砖脱落这种小目标场景漏检偏多s 是精度和速度的平衡点GTX 1660Ti 上推理一张 640 的图大概 30 到 50 毫秒完全够演示用。3.3 训练命令与超参数说明训练命令可以直接用 ultralytics 的 CLI也可以写 Python 脚本调用。命令行方式最直观yolo detect train \ datafacade.yaml \ modelyolov8s.pt \ epochs100 \ imgsz640 \ batch16 \ device0 \ patience20 \ optimizerAdamW \ lr00.001 \ projectruns/facade \ nameexp参数逐一说modelyolov8s.pt 会加载 COCO 预训练权重第一次运行会自动下载这个预训练能显著加速收敛别用随机初始化的权重从头训epochs100 对几百张的小数据集足够配合 patience20 的早期停止实际可能 40 到 60 轮就停了imgsz640 是输入尺寸显存够就调到 1280因为脱落区域经常是小目标640 下细节损失大optimizer 选 AdamW中小数据集上比 SGD 更稳不容易出现损失震荡lr00.001 是起步学习率用小数据集时千万不要用默认的 0.01很容易前期就发散。3.4 从 runs 目录读训练日志与损失函数曲线图训练结束后所有产物都在 runs/facade/exp 下weights 里有 best.pt 和 last.pt前者是验证集上表现最好的权重后者是最后一轮的权重部署用 best.pt根目录下还有 results.csv记录每个 epoch 的损失和各种指标。用脚本把损失曲线和 mAP 曲线画出来是判断训练是否正常最直接的方式。import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(runs/facade/exp/results.csv) print(df.columns) fig, axes plt.subplots(1, 2, figsize(12, 4)) axes[0].plot(df[epoch], df[train/box_loss], labeltrain box loss) axes[0].plot(df[epoch], df[val/box_loss], labelval box loss) axes[0].set_xlabel(epoch) axes[0].legend() axes[1].plot(df[epoch], df[metrics/mAP50(B)], labelmAP0.5) axes[1].plot(df[epoch], df[metrics/mAP50-95(B)], labelmAP0.5:0.95) axes[1].set_xlabel(epoch) axes[1].legend() plt.show()这里有个细节要提醒不同版本的 ultralytics 在 results.csv 里的列名可能会有细微差异比如带不带后缀“(B)”所以代码里我先执行了print(df.columns)确认实际列名后再画。判断训练是否正常的标准是train loss 平稳下降val loss 跟着下降且没有大幅反弹mAP0.5 在 20 轮后开始明显爬升。如果出现 train loss 降、val loss 震荡不降多半是标注不一致或者验证集和训练集分布差距太大这时候加数据比调参更管用。4. 可视化界面部署把模型封装成能点鼠标的检测工具4.1 界面选型PyQt5 单机版还是 Web 版标题里强调“可视化界面、简单部署即可运行”这个要求下我一般首推 PyQt5/PySide6 单机版。理由很实际不需要写前端不需要起服务双击 exe 或直接跑 Python 脚本就出窗口摄像头、文件对话框、画框这些操作 PyQt 的生态都很成熟。选 PyQt5 还是 PySide6 差别不大PySide6 是官方 LGPL 协议商用更友好但网上资料 PyQt5 存量更多毕设遇到问题好搜。如果是做工程演示给多人看Web 版也有价值用 Flask/FastAPI 把推理接口包一层前端传图片返回标注结果。但 Web 版意味着你要同时维护后端和前端部署时还要处理端口、浏览器兼容和“下载即跑”这个目标冲突。折中方案是先用 PyQt5 把单机版跑通如果后面确实需要网页演示再把 Detector 类原样搬到 Flask 路由里模型封装层不用改。对比项PyQt5 单机版Flask/FastAPI Web 版部署难度低装依赖直接跑中需起服务加开端口界面成本拖控件写槽函数要写 HTML/JS 或模板摄像头接入简单OpenCV 直接读需要 WebRTC 或视频上传适合场景毕设演示、本地巡检工具多客户端访问、远程演示4.2 推理封装Detector 类与核心参数不管界面技术选什么都建议先把推理逻辑封装成一个独立的类。这样做的好处是界面代码里不会出现 model.predict 满天飞后面换模型、加日志、导出 ONNX 都只改这一个类。下面是一个通用封装import torch from ultralytics import YOLO class FacadeDetector: def __init__(self, weights_path, conf0.25, iou0.45): self.device cuda:0 if torch.cuda.is_available() else cpu self.model YOLO(weights_path) self.conf conf self.iou iou def predict(self, source): results self.model.predict( sourcesource, confself.conf, iouself.iou, deviceself.device, verboseFalse ) boxes results[0].boxes return ( boxes.xyxy.cpu().numpy(), boxes.cls.cpu().numpy(), boxes.conf.cpu().numpy() ) detector FacadeDetector(runs/facade/exp/weights/best.pt, conf0.30)逻辑说明init里自动检测 GPU 是否可用有显卡用 cuda没有就退回 cpu这是“简单部署”的关键——换台没显卡的电脑也不会崩predict 方法统一返回三个数组预测框坐标x1 y1 x2 y2、类别 id 和置信度。conf 参数值得细说默认 0.25 在演示时容易把空调外机、阴影误检成脱落我一般界面里设成 0.30如果误检还多就往上调到 0.4代价是漏掉一些低置信度的真实脱落实操时按现场照片调一次就行。4.3 主界面逻辑选图、视频流与线程处理界面部分最核心的问题不是画框而是别把推理放在主线程里。PyQt 的主线程负责刷新界面如果直接在主线程里跑模型推理拖窗口会卡成幻灯片这是这类项目最常见的演示事故。用 QThread 把摄像头检测循环放到子线程通过信号把处理完的画面传回主线程更新显示界面就流畅了。from PyQt5.QtCore import QThread, pyqtSignal import cv2 class DetectThread(QThread): frame_ready pyqtSignal(object) def __init__(self, detector): super().__init__() self.detector detector self.running True def run(self): cap cv2.VideoCapture(0) while self.running: ok, frame cap.read() if not ok: continue boxes, cls_ids, confs self.detector.predict(frame) for box, cls_id, score in zip(boxes, cls_ids, confs): x1, y1, x2, y2 box.astype(int) cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 0, 255), 2) cv2.putText(frame, ffalling {score:.2f}, (x1, y1 - 6), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 255), 2) self.frame_ready.emit(frame) def stop(self): self.running False self.wait()这段代码的思路是DetectThread 里循环读摄像头帧调用 FacadeDetector.predict 拿到检测结果直接把框和置信度画在帧上然后通过 frame_ready 信号把帧交给主界面的槽函数去更新 QLabel。如果只做单张图片检测根本不用启线程QFileDialog 拿图片路径detector.predict 一下把结果画到 QLabel 上即可。视频文件检测同理把 VideoCapture(0) 换成视频文件路径就能跑。界面整体三层架构界面层只管显示和按钮事件Detector 层管推理YOLO 模型在最底下。别图省事在按钮回调里直接调 model.predict后面想加批量导出、历史记录、参数调整会非常后悔。5. 避坑清单训练到部署最常翻车的 5 个点5.1 训练时 loss 变成 NaN现象前几个 epoch 正常突然某个 epoch 之后损失变成 nan后面所有指标也跟着全是 nan。原因最常见的是学习率太高小数据集上默认的 0.01 经常让模型前期就发散其次是训练集里有损坏图片比如全黑、全白或者 EXIF 方向信息错乱的 JPEG这些图输入网络后会产生异常梯度。解决先把 lr0 降到 0.0005 到 0.001 区间AdamW 配小学习率在几百张图的数据集上基本不会翻车同时写一段脚本扫一遍训练集计算每张图的像素均值和标准差把全黑全白的坏图剔除。两件事都做了还是 nan再检查是不是数据增强里开了过大的 brightness 范围把 hsv_v 降到 0.4 以内。5.2 验证集精度高但实拍检测几乎全漏现象训练时 mAP0.5 到了 0.85 以上结果拿手机去楼下实拍一测模型要么啥都检不出来要么框的位置完全不对。原因训练集和验证集来自同一个楼栋甚至同一批照片的连续帧模型实际上“背”下了这个楼面的纹理特征换一栋楼纹理一变就失效。这是外立面检测项目最容易骗到自己的坑。解决验证集必须包含至少一栋完全没有参与训练的楼栋拍摄角度和距离也要贴近真实巡检习惯——如果你是站在楼下拍的训练集里就不能全是无人机平视图。我一般会把数据按楼栋切分而不是按文件随机切分保证同楼栋的图只出现在训练集或只出现在验证集。5.3 小目标脱落区域完全检测不到现象远拍照片里脱落只有十几个像素模型直接无视近拍的能检测出来稍远一点就消失。原因输入图像缩放到 640 后小目标的特征在骨干网络里被池化掉了。瓷砖脱落本质上是一个小目标密集场景这是模型层面的结构性短板调 conf 阈值没有用。解决第一个办法是把 imgsz 提到 1280显存不够就降 batch第二个更有效的办法是切片训练把大图裁成多个 512x512 的 patch 再送进模型相当于让模型在更小的视野里看细节标注坐标需要按切片偏移换算一次。YOLOv8 的 head 部分如果要改动常见方向是添加针对小目标的检测头但那是进阶玩法数据切片能解决大部分问题。5.4 训练时显存溢出直接 OOM现象命令行里刚跑几个 step 就报 CUDA out of memory进程退出。原因batch 设置太大、imgsz 太大、workers 开太多三者叠加把显存瞬间打满。GTX 1660Ti 只有 6GB 显存按 16 的 batch 跑 1280 的图基本必炸。解决6GB 显存的安全组合是 yolov8s imgsz640 batch8这个组合实测能稳定训练想用 1280 的输入就把 batch 降到 4。还有一个容易被忽略的参数是 workers数据加载线程太多会占用额外显存做缓存设置为 2 或 4 比较稳妥。5.5 CPU 推理太慢界面像幻灯片现象没有显卡的电脑上单张 640 的图推理要 800 毫秒到 1 秒界面一帧一帧卡得没法演示。原因PyTorch 的 float32 模型在 CPU 上用通用算子计算没有针对 x86 指令集做深度优化慢是正常的。解决导出 ONNX 再用 OpenVINO 跑是性价比最高的方案CPU 上通常能比 PyTorch 快 2 到 4 倍。导出命令很简单yolo export modelruns/facade/exp/weights/best.pt formatonnx imgsz640导出后 OpenVINO 加载 ONNX 做推理画面流畅度会质变。如果后面想部署到 RK3588 这类嵌入式开发板流程是先导出 ONNX再转成 RKNN 格式做 int8 量化单张推理能压到几十毫秒级别。这里提醒一句导出时的 imgsz 必须和训练时一致否则输入尺寸不匹配会直接报错。6. 批量检测与工程验收离线脚本、ONNX 导出和验收口径6.1 批量检测脚本是最实用的收尾工具。界面适合演示但真要统计一栋楼、一个小区的外立面风险点你不可能一张张点开界面看。常见做法是写一个离线脚本遍历文件夹里的所有图片把检测结果汇总成一张表格数量、置信度、位置信息一目了然。from pathlib import Path import cv2 import pandas as pd detector FacadeDetector(runs/facade/exp/weights/best.pt, conf0.35) rows [] for img_path in Path(test_facades).glob(*.jpg): img cv2.imread(str(img_path)) boxes, cls_ids, confs detector.predict(img) rows.append({ image: img_path.name, falling_count: int((cls_ids 0).sum()), max_conf: float(confs.max()) if len(confs) else 0.0, }) df pd.DataFrame(rows) df.to_csv(facade_report.csv, indexFalse)脚本里把 conf 提到了 0.35因为离线批量检测没有实时性压力宁可多漏几个低置信度框也要把误检压住导出的表格才有人愿意看。falling_count 记录每张图的脱落框数量实际巡检时这个数字可以换算成风险密度但更大价值在于让模型输出可追溯。6.2 关于 ONNX 导出前面避坑清单里给过命令这里补充硬件部署的细节。导出 ONNX 后在 x86 机器上用 OpenVINO 推理是成本最低的加速方案如果想在 RK3588 这类带 NPU 的开发板上一体化部署需要按板卡的 SDK 流程把 ONNX 转成 RKNN量化校准集最好从你自己数据里抽 50 张典型图片直接拿公开图库做校准会让精度掉得很难看。GTX 1660Ti 这类老显卡跑 yolov8s 的 Float32 模型就够用不用额外折腾 TensorRT收益不大还费时间。6.3 验收口径这件事做的人很少但恰恰是最能证明“这个方案值得投入”的一步。我给自己定的标准是至少拿两栋没参与训练的楼每栋从不同距离拍 20 张以上人工标注一遍再和模型的输出比对IoU 大于 0.5 算检出。漏检率低于 20%、误报框平均每张不超过 2 个才算是可演示、可交付的状态。做完这些你心里会对这套方案的真实能力有底而不是停留在训练日志里的 mAP 数字上。说一个我自己的教训最早做类似项目时图省事只用一面墙的数据训练验证集精度刷得挺高结果换一栋楼就翻车。后来老老实实补拍了多栋楼、多角度、多光照条件的照片重新标注切分模型才算真正能用。这个方向值不值得做答案是值得但前提是你先补齐数据分布和验收这两块短板。希望帮到你。本文还有配套的精品资源点击获取