简介一份基于YOLOv8的居民楼外立面瓷砖脱落检测项目面向计算机视觉、人工智能相关专业的本科生与研究生可直接用于毕业设计、课程设计或初期项目演示。资源覆盖数据准备、模型训练、可视化交互与部署说明整体操作门槛较低简单部署即可运行压缩包共8个文件包含3个Python脚本分别对应可视化界面、视频检测和训练流程、3个模型权重文件含预训练权重与训练完成的最优权重以及2个说明文档完整代码与数据集一并纳入总体积15.91MB轻量方便。目前已有38人学习下载。除直接训练和检测外资源运行后可生成核心指标曲线、混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果与标签分布图可为毕业答辩或课程验收提供有力支撑。配套部署教程能帮助新用户按指引快速跑通代码结构清晰也便于二次修改、更换数据集或扩展检测目标。1. 基于YOLOv8的居民楼外立面瓷砖脱落项目拆完跑通答辩图全齐毕设做到四月最怕的不是模型效果差而是拿到一个目标检测项目环境装不上、依赖对不上、数据一跑就报错。我最近拆的这份《基于YOLOv8的居民楼外立面瓷砖脱落》属于拿来就能跑的完整闭包源码、可视化界面、完整数据集和部署教程打包在一起核心任务就是把外立面瓷砖脱落区域用目标检测框出来是计算机视觉里很典型的缺陷检测场景。训练完会自动产出损失函数曲线、混淆矩阵、F1 分数曲线、精确率-召回率曲线、验证集预测结果和标签分布图答辩要摆的图基本不用自己补。适合计科、人工智能、自动化、电子信息专业的毕设、课程设计和期末大作业也适合显卡配置一般的同学——默认走 yolov8n推理快、显存占用小。下文按拆结构、配环境、跑训练、调推理、避坑、答辩讲图推进照着走一遍基本能复现。2. 资源结构与选型三个 Py 脚本、两份权重先看清分工再动手解压拿到压缩包后第一件事不是跑代码而是读 README.txt。这类打包资源里说明书决定你能不能一次跑通——它一般写清了 Python 版本、依赖安装顺序和运行入口。我见过太多人跳过 README 直接跑脚本结果连入口文件都找错。剩下核心文件分三类训练脚本、推理脚本、可视化界面脚本外加 yolov8n.pt、best.pt、yolo11n.pt 三份权重和一套数据集。2.1 文件清单与脚本分工train_mode.py、Detection_video.py、Visual_interface.py 各管一段先把文件级的职责拉一张表后面按图索骥文件职责使用时机README.txt部署说明、运行顺序解压后第一件事train_mode.py训练入口调用 ultralytics 训练首次运行或重新训练Detection_video.py图片/视频推理与画框验证模型效果Visual_interface.py可视化交互界面演示、答辩现场yolov8n.ptCOCO 预训练权重训练起点best.pt微调后的最佳权重直接推理yolo11n.pt更新版本的预训练权重对比实验dataset/训练集、验证集、data.yaml训练数据train_mode.py 是整条流水线的起点内部通常就是一句YOLO(yolov8n.pt).train(...)负责把预训练权重拿到外立面数据集上微调Detection_video.py 是推理入口读取 best.pt 对图片或视频做检测并画框Visual_interface.py 是演示用的 GUI通常基于 PyQt5封装了选文件、跑推理、显示结果三件事答辩时不用敲命令行点几下鼠标就能出图。这个分工对毕设很合理训练和推理解耦训练环境崩了不影响演示现场只需要界面脚本加 best.pt。你如果基础还行想改方向——比如把瓷砖脱落换成外墙裂缝、渗水痕迹——只需要换数据集和标签类别脚本主体不用动改动成本主要花在标注上。运行顺序我建议严格按README → 训练 → 视频推理 → 界面来先验证模型是好的再去动界面否则界面报错你会分不清是模型问题还是 UI 问题。2.2 模型选型为什么默认给 yolov8n.ptyolo11n.pt 又是干嘛的网上常有人问 yolov8 网络结构图长什么样拆开其实就三块CSPDarknet 做骨干提特征PAN-FPN 做多尺度融合最后是 anchor-free 的解耦检测头直接输出类别和边框回归。YOLOv8 按规模分成 n、s、m、l、x 五档nano 最轻参数量最小、推理最快论文里描述结构时可以直接写Backbone 采用 CSPDarknet 结构Neck 采用 PAN-FPN 聚合多尺度特征Head 采用解耦头分别预测类别与边界框。这份资源默认用 yolov8n.pt 做训练起点是合理的。原因有二一是外立面瓷砖脱落是单类别缺陷检测脱落区域在画面里通常占几十到几百像素不是小目标密集场景nano 的容量足够二是毕设机器千奇百怪很多人拿的是入门显卡甚至纯 CPUnano 在 640 分辨率下训练8GB 显存能跑CPU 硬扛也能出结果只是慢。如果你的机器显存有余可以换成 yolov8s.pt 对比一轮通常 mAP 能涨两三个点代价是训练时间翻倍——这类对比数据正好写进论文的消融实验里。yolo11n.pt 是 ultralytics 后续版本引入的新结构权重同一套from ultralytics import YOLO接口直接能加载结构比 v8 更精简。我的建议是主线用 yolov8n 出 best.pt 保底yolo11n 留着做对比实验别一上来就换版本差异容易引入变量。两份权重的加载方式一模一样区别只在骨架细节和预训练分布换权重只改一行代码不影响整体流程。2.3 数据集结构外立面瓷砖脱落这类缺陷数据的标注与组织数据集是 YOLO 标准组织方式图片和标签按 train/val 分开放dataset/ ├── train/ │ ├── images/ │ │ ├── 0001.jpg │ │ └── ... │ └── labels/ │ ├── 0001.txt │ └── ... ├── val/ │ ├── images/ │ └── labels/ └── data.yaml图片和标签必须同名只是后缀不同。txt 里每一行对应一个目标框0 0.5234 0.5128 0.3125 0.1874一行五个数类别 id、归一化中心点 x、归一化中心点 y、归一化框宽、归一化框高。归一化就是除以整图的宽高所以坐标都在 0 到 1 之间跟图片分辨率无关。data.yaml 里声明类别数量和数据路径train: dataset/train/images val: dataset/val/images nc: 1 names: 0: tile_fall注意 yaml 里 train/val 写的是图片目录ultralytics 会自动去同级 labels 目录找标签所以目录结构别乱动。瓷砖脱落这类缺陷的标注有两个特点一是同一张图经常有多块脱落区域一行一个框一个 txt 可能几十行二是脱落边缘不规则标注时常用矩形近似边界对不齐是正常的不用追求像素级贴合。拿到数据集后我一般先做一次人工核对防止标签错位——写个小脚本把框画回原图import cv2 img cv2.imread(dataset/train/images/0001.jpg) h, w img.shape[:2] with open(dataset/train/labels/0001.txt) as f: for line in f: cls, cx, cy, bw, bh map(float, line.split()) x1 int((cx - bw / 2) * w) y1 int((cy - bh / 2) * h) x2 int((cx bw / 2) * w) y2 int((cy bh / 2) * h) cv2.rectangle(img, (x1, y1), (x2, y2), (0, 0, 255), 2) cv2.imwrite(check.jpg, img)这段代码把 txt 里的归一化坐标换算回像素坐标画框保存。cls 变量这里没用到多类别场景可以据此给不同类画不同颜色。第一次跑数据集最好都过一遍这个检查比训练到一半发现标签错位再返工省事得多。提示ultralytics 默认开了 mosaic 数据增强对不规则缺陷有时会拼出语义混乱的样本。如果训练曲线震荡明显可以在 train 参数里加close_mosaic10最后 10 轮关闭 mosaic收敛会更稳。3. 环境配置与训练torch、ultralytics 版本对齐跑通 train_mode.py 并盯住三个产出物yolov8 环境配置是毕设翻车重灾区九成问题出在 torch 的 CUDA 版本和 ultralytics 依赖冲突上。我的习惯是先用 conda 把环境隔离出来再装依赖最后用一条命令验证 GPU 真的可用。别图省事直接 pip 到 base 环境项目一多就打架。3.1 环境安装conda 隔离、CUDA 匹配、一条命令验证conda create -n yolo python3.10 -y conda activate yolo pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics opencv-python pip install pyqt5第一行创建干净环境Python 3.10 是目前 ultralytics 兼容性最好的版本之一3.11、3.12 也能跑但个别依赖在 3.12 下要现场编译容易报错。第三行--index-url指定 PyTorch 官方源cu118 对应 CUDA 11.8如果显卡驱动是较新的 12.x可以换成 cu121 或 cu124和你机器上nvidia-smi显示的驱动版本对应上。先执行nvidia-smi确认驱动再看 CUDA 版本避免装完才发现对不上。装完先验证再训练import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else CPU only)这段代码输出三样东西torch 版本、CUDA 是否可用、设备名。如果cuda.is_available()返回 False训练会静默走 CPUyolov8n 在 CPU 上 150 轮可能要跑十多个小时所以这一步必须确认。没有 NVIDIA 显卡就装 CPU 版 torch小数据集加 nano 模型也能出结果只是 patience 早停要设得保守时间有限建议先把 epochs 降到 50 验证流程。3.2 train_mode.py 的关键参数epochs、imgsz、batch、device 怎么改train_mode.py 内部一般是 ultralytics 的标准训练调用核心参数如下from ultralytics import YOLO if __name__ __main__: model YOLO(yolov8n.pt) # 预训练权重路径 results model.train( datadataset/data.yaml, # 数据集配置 epochs150, # 训练轮数 imgsz640, # 输入分辨率 batch16, # 批量大小 device0, # GPU 设备号CPU 写 cpu patience20, # 早停轮数 seed42, # 随机种子 projectruns/train, # 输出根目录 nametile_fall, # 本次实验名 )几个参数按影响优先级排batch 和 imgsz 决定显存8GB 显存推荐 batch8、imgsz6402GB 老卡只能 batch4、imgsz480。epochs 决定训练时长和过拟合风险150 轮配合 patience20验证集 20 轮不涨自动停能省不少时间。seed 固定后结果可复现答辩时如果中途改过代码导致指标变化你能解释是随机性还是代码问题。参数影响参考值epochs训练时长、过拟合100-200imgsz显存、小目标精度480-640batch显存最大头4-16deviceCPU/GPU 选择0 或 cpupatience早停阈值15-30seed复现性42lr0初始学习率默认 0.01不用动close_mosaic最后 N 轮关 mosaic10workers数据加载进程数Windows 设 0train_mode.py 里如果写死了值直接改文件有些版本抽成了命令行参数用python train_mode.py --batch 8 --imgsz 640覆盖。Windows 上记得把 workers 设成 0否则 DataLoader 多进程经常崩出 BrokenPipeError这是 yolov8 在 Windows 下的经典翻车点。训练一次外立面这种单类数据GTX 1660 级别大概两三小时A 系列显卡快得多。训练日志里注意每个 epoch 末尾的 mAP50 和 mAP50-95mAP50 对这类缺陷检测是主指标0.85 以上答辩就够用了。3.3 训练产出物best.pt、损失曲线和混淆矩阵在哪、怎么看训练结束后进runs/train/tile_fall/几个文件直接对应答辩要展示的图文件内容答辩怎么用weights/best.pt验证集指标最好的权重推理、演示weights/last.pt最后一轮权重对比用results.pngloss 与 mAP 曲线讲收敛过程confusion_matrix.png混淆矩阵讲分错情况F1_curve.pngF1 分数曲线选阈值PR_curve.png精确率-召回率曲线讲 APval_batch*_pred.jpg验证集预测图展示实际效果labels.jpg标签分布图讲数据集构成yolov8 画损失函数曲线图是自动的results.png 里包含 train/val 的 box_loss、cls_loss、dfl_loss还有精确率、召回率和 mAP。看这张图有个判断过拟合的习惯性动作train loss 持续下降、val loss 走平或回升说明模型在背训练集best.pt 大概率是早停前那一轮泛化会变差。训练完先别急着跑界面用下面这段代码确认 best.pt 能正常加载和推理from ultralytics import YOLO model YOLO(runs/train/tile_fall/weights/best.pt) r model.predict(sourcedataset/val/images/0001.jpg, conf0.35) print(r[0].boxes.cls) # 类别 id print(r[0].boxes.conf) # 置信度 print(len(r[0].boxes)) # 检测框数量predict 的 conf 是置信度阈值0.35 是缺陷检测里比较常规的起点。boxes.cls 返回的 tensor 里每个元素是类别 id单类场景全是 0conf 是每个框的分数如果全部低于阈值len 会是 0说明阈值太高或模型没学到该类。确认没问题后把 best.pt 复制一份到脚本同级目录后面界面和视频推理都指向这份。4. 可视化界面与视频检测Visual_interface.py 和 Detection_video.py 的换权实操资源里的可视化界面和视频检测是两个不同入口。界面脚本给答辩演示用视频脚本给效果验证用它们加载同一个 best.pt改动逻辑也几乎一样换权重、调阈值、改路径。先把这两个脚本跑通再考虑换数据换场景。4.1 Visual_interface.pyPyQt 界面里选文件、推理、画框的三步回调这类毕设界面九成是 PyQt5 写的结构一般是主窗口放按钮触发文件选择QLabel 显示原图QLabel 显示结果中间是推理逻辑。核心回调大概长这样import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QFileDialog, QLabel from ultralytics import YOLO class MainWindow(QMainWindow): def __init__(self): super().__init__() self.model YOLO(best.pt) # 想换权重只改这一行 def open_image(self): path, _ QFileDialog.getOpenFileName( self, 选择图片, , Images (*.jpg *.png)) if not path: return results self.model.predict(sourcepath, conf0.35) annotated results[0].plot() # 画好框的 BGR 图像 # 转 RGB 后交给 QPixmap 显示到 QLabel app QApplication(sys.argv) win MainWindow() win.show() sys.exit(app.exec_())逻辑说明QFileDialog 弹出系统文件选择框拿到路径交给 predict每个 results 对象对应一张图plot() 把检测框、类别名和置信度画回图上返回的是 BGR 格式的 numpy 数组显示前要转成 RGB否则颜色会偏蓝红互换。这里有个小细节YOLO(best.pt)是相对路径脚本和权重不在同一目录时找不到文件建议直接用绝对路径或把 best.pt 复制到脚本同级目录。界面脚本还有两个常见问题。一是 conf 写死成 0.5现场新图光照不同框就少了答辩演示前我会把 conf 降到 0.25 到 0.35宁可多画几个框也不要出现什么都没检测出来的尴尬。二是推理在 UI 线程里执行大图推理会卡界面几秒如果资源里没做多线程演示时选好图等一下再点别狂点按钮。4.2 Detection_video.py视频推理的帧循环与 conf、iou 参数视频推理有两种写法一是逐帧读取再逐帧预测二是把视频路径直接传给 predict。逐帧写法适合演示和录屏import cv2 from ultralytics import YOLO model YOLO(best.pt) cap cv2.VideoCapture(demo.mp4) while cap.isOpened(): ret, frame cap.read() if not ret: break results model.predict(sourceframe, conf0.35, iou0.5, verboseFalse) annotated results[0].plot() cv2.imshow(tile fall detection, annotated) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这段循环里predict 每次只处理单帧verboseFalse关掉日志刷屏iou 是 NMS 阈值0.5 是默认值如果发现同一个脱落区域被反复框出好几个重叠框把 iou 调到 0.6 或 0.7重叠框会被压掉。逐帧预测速度取决于机器nano 在 GTX 1660 上大概 30-50ms 一帧能跑出十几帧的实时效果如果卡到没法看最简单的优化是跳帧比如每读两帧才预测一帧frame_idx 0 while cap.isOpened(): ret, frame cap.read() if not ret: break if frame_idx % 2 0: results model.predict(sourceframe, conf0.35, verboseFalse) annotated results[0].plot() cv2.imshow(tile fall detection, annotated) frame_idx 1 if cv2.waitKey(1) 0xFF ord(q): break跳帧后画面会有轻微掉帧感但演示流畅度明显提升。如果想保存结果视频用 cv2.VideoWriter 写 mp4编码器用 mp4v帧率设和原视频一致。另一种省事写法是model.predict(sourcedemo.mp4, conf0.35, saveTrue)ultralytics 内部按视频流处理自动在 runs/detect/predict 下生成结果视频。它的优点是快缺点是中间过程不可见。演示用逐帧循环出片用 save 模式各有用途。4.3 换权推理best.pt、yolov8n.pt、yolo11n.pt 的边界三份权重对应三个使用场景别混着用权重训练数据适合场景yolov8n.ptCOCO 80 类训练起点不直接推理best.pt外立面数据集正式推理、演示yolo11n.ptCOCO 新版本消融对比实验yolov8n.pt 认得 80 个日常类别不认得瓷砖脱落——拿它推外立面出来的只会是 person、car 这类无关框。best.pt 是微调过的类别 id 和 data.yaml 里的 tile_fall 对齐这才是推理的正确选择。yolo11n.pt 做消融重新训一轮就有了 baseline 之外的对比数据。换权重在代码里就是一行YOLO(best.pt)改成YOLO(yolo11n.pt)。但注意两点一是 best.pt 序列化时带的是训练时的模型配置升级 ultralytics 大版本后加载可能报 KeyError二是换回预训练权重推理时类别名是 COCO 的 80 类画框显示的名字对不上场景这是正常的。实操里我判断权重是否给对就看推理结果的类别 id 和置信度分布best.pt 输出全是 0 类、置信度 0.5 上下浮动yolov8n.pt 输出各种 COCO 类别、置信度参差不齐。如果答辩想多讲一句部署扩展还可以用yolo export把 best.pt 导成 ONNX说明模型可迁移到边缘设备一行命令的事不改变主流程。5. 避坑与排查六个翻车现场按现象对原因找对策这一章是血泪经验的集合以下六个坑我不止一次见过有的机器问题、有的版本问题、有的数据问题全部按现象 → 原因 → 解决记录照着比对能省掉大半天排查时间。5.1 现象torch.cuda.is_available() 返回 False训练日志里全程 CPU原因pip 默认装的是 CPU 版 torch或者装的 CUDA 版本和显卡驱动不匹配。最常见的是直接pip install torch装出 CPU 版训练慢到怀疑人生。解决卸载重装指定 CUDA 版本pip uninstall torch torchvision -y pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118装完再跑一遍 3.1 的验证代码看到 True 再训练。如果是驱动太老先更新显卡驱动或者认命装 CPU 版、跑小轮数。5.2 现象训练一启动就报 No labels found in ...或 mAP 曲线全程贴地原因data.yaml 路径写错或 train/val 的 images 和 labels 没同名对齐。yaml 路径是相对当前工作目录解析的换个目录跑 train_mode.py 路径就失效了。解决先把 data.yaml 改成语料库里的绝对路径或统一在项目根目录下运行脚本。然后核对 images 和 labels 是否同名——图片是 0001.jpg标签必须是 0001.txt多一个空格都不行。最后看标签文件内容是否为空空文件不报错但会让 mAP 一直是 0。用 2.3 的画框脚本抽查十张图基本能定位。5.3 现象cv2.VideoCapture 或 cv2.imread 打不开文件返回 None 但不报错原因路径带中文或特殊字符OpenCV 老版本对中文路径支持差某些视频编码格式 OpenCV 没带解码器。解决把数据文件全部复制到纯英文目录再跑最省事。图片可以用 imdecode 绕过去import cv2 import numpy as np img cv2.imdecode(np.fromfile(D:/毕设/图片/01.jpg, dtypenp.uint8), cv2.IMREAD_COLOR)np.fromfile不受中文路径限制imdecode 读成 BGR 图像。视频目前没有同等简单的绕法我的习惯是复制到D:/yolo/demo.mp4这种纯英文路径再推理。毕设现场如果演示路径有中文提前把目录名改掉别赌运气。5.4 现象训练跑到几个 epoch 后报 CUDA out of memory 崩掉原因batch 和 imgsz 叠加超出显存。很多人不动默认 batch166GB 显存跑 640 分辨率就爆了。解决batch 降到 8 甚至 4imgsz 降到 480这两个是显存绝对大头。也可以在代码开头加import torch torch.cuda.empty_cache()这句不会增加显存但能清掉上次运行的残留缓存有时能多顶几个 epoch。真正稳妥的是先看显存再倒推参数每 GB 显存大约对应 batch2 的 640 输入8GB 卡上 batch16 是极限别顶着跑。5.5 现象加载 best.pt 或 yolo11n.pt 报 KeyError / AttributeError原因权重是用某个版本的 ultralytics 训练保存的你现在用的版本结构变了模型配置 key 对不上。ultralytics 8.x 迭代很快跨大版本加载旧权重是高频事故。解决锁定版本项目里固定装同一版pip install ultralytics8.2.0权重怎么训出来就怎么加载别升级。如果已经升级退回原训练环境加载再重新导出。我现在的习惯是环境建好后第一时间pip freeze存一份权重和版本绑定成一对换机器时先装同版本再谈优化。5.6 现象best.pt 在验证集上效果很好换到现场新图漏检一大片原因模型过拟合了训练集的光照、角度和建筑风格分布或 conf 阈值定太高。缺陷检测特别容易出这个情况——实验室指标好看是分布一致的结果现场图一换置信度整体掉阈值 0.5 一卡就全没了。解决先降到 conf0.25 看边界如果还大量漏检继续降直到明显误检把临界值作为部署阈值。更正规的做法是额外攒一批没参与训练的新图手动标一部分当外部验证集算 F1 后取最优置信度。这在答辩里反而是加分项说明你做过泛化验证不只是跑通了脚本。6. 答辩前的指标验证F1、PR 曲线和混淆矩阵的正确打开方式训练完不要急着截图先搞清楚每张图怎么讲。results.png 里的损失函数曲线是开场白指出 train 和 val 的 box_loss、cls_loss 同步下降、最终走平说明收敛没有明显过拟合——这是 yolov8 项目的标准叙事。如果 val loss 有回升迹象就顺势补一句用了 patience 早停best.pt 取的是验证集最优轮能挡掉多数追问。F1_curve 的横轴是置信度阈值纵轴是 F1峰值对应的阈值就是最佳操作点答辩时可以说取 F1 曲线峰值对应的阈值作为默认检测阈值比随口说 conf0.35 有说服力。PR_curve 的曲线下面积约等于 AP单类场景 AP 就是 mAP曲线下降平缓说明模型在不同阈值下都稳如果曲线贴着右边缘往下掉说明高置信度样本太少类别特征学得不够。混淆矩阵重点看主对角线和 background 列。单类场景矩阵是 2x2 加 background主对角线数值是真实脱落被正确检出的比例background 列有值说明把非脱落区域误检成了脱落。答辩时别只说准确率高要会解释背景误检来源——边缘阴影、外墙污渍、窗户边框这些都是真实场景里的难例。标签分布图证明数据覆盖了不同楼层高度和光照条件不是只拍了几栋楼。验证集预测结果图直接摆给评委看标注框、类别、置信度都画在上面是全篇最直观的成果图。演示顺序建议现场用 Visual_interface.py 选两张验证集图片再用 Detection_video.py 播一段没训练过的新视频提前录屏保存。加分项可以做 yolov8 可视化热力图但 ultralytics 没直接封装需要扒 backbone 中间层输出工作量不小时间紧就别碰。从那以后我每次训练完都强制走一遍加载 best.pt → 验证集随机抽 20 张 → 新图 10 张 → 录一段视频的四连验证确认指标和实际表现一致才敢交差。这份资源把源码、数据集、可视化界面和部署教程都打包好了按上面顺序走半天就能跑通剩下的时间留给调参和答辩预演。希望帮到你。本文还有配套的精品资源点击获取