YOLOv8裂缝检测实战：从数据集训练到工地部署

简介基于YOLOv8的基建裂缝目标检测系统是一份面向计算机视觉、人工智能、自动化等专业学生与从业者的毕设级Python项目。资源以裂缝检测为核心覆盖从数据集准备、模型训练到结果评估的完整流程代码经调试可运行适合作为课程设计、大作业或毕业设计的起点也可供入门者系统学习YOLOv8目标检测。资源压缩包共849个文件解压后大小约666MB其中包含329个jpg图像样本、298个txt标签与158个xml标注文件用于训练与验证另有23个pt模型权重可直接加载推理以及py脚本、yaml配置、results.csv训练日志等辅助文件。目前已有144人学习下载。除源码外还附有文档说明与数据集目录结构清晰训练缓存与结果文件可帮助快速复盘调参过程适合在现有基础上修改类别或场景实现自定义裂缝检测功能。1. 为什么基建裂缝检测绕不开YOLOv8先看这份资源解决什么问题基建裂缝检测这类任务最头疼的不是能不能检出来而是裂缝这种细长目标背景又脏到底怎么稳定检出。混凝土表面的网状裂缝、桥梁箱室里的细微裂缝光照一变化就和背景混在一起传统图像处理算法阈值分割半天换个现场就失效。基于YOLOv8的基建裂缝目标检测系统就是冲着这个场景来的用深度学习目标检测的思路把裂缝当成一个窄长的框目标来训练和推理Python源码、数据集、文档说明一套配齐拿到手就能顺着跑出训练和推理结果。适合刚入门目标检测的在校生做课程设计也适合现场检测工程师想快速验证深度学习方案在裂缝识别上的可行性。下面按我从解压到复现的顺序把这套资源能干什么、坑在哪讲清楚。2. 从压缩包到第一次跑通推理源码结构与权重加载2.1 拿到压缩包后先看什么这套资源解压后的典型结构是一个python工程加上dataset目录和文档说明。第一次打开别急着跑train.py先把文件清单过一遍。常见布局是crack_yolov8/ ├── dataset/ │ ├── train/ │ │ ├── images/ │ │ └── labels/ │ └── val/ │ ├── images/ │ └── labels/ ├── weights/ │ └── best.pt ├── data/ │ └── data.yaml ├── train.py ├── detect.py └── requirements.txt我的习惯是先读data.yaml和train.py。这两个文件直接决定了训练集指向哪里、类别名是什么、训练配置长什么样。很多新手拿到源码后直接运行报错九成是路径不对或者data.yaml里的路径没有改成自己的绝对路径。weights目录下如果有best.pt说明作者已经把训练好的权重放进来了可以跳过训练阶段先跑推理验证环境通不通。2.2 环境依赖Python版本、ultralytics与CUDA的选型这套代码基于ultralytics框架YOLOv8的官方实现就在这个库里。requirements.txt里一般会写ultralytics、opencv-python、torch、torchvision这几项。环境搭建有两条路GPU和CPU。如果你手上只有普通笔记本ubuntu20.04搭建yolov8环境cpu版本完全可行推理一张图几秒钟训练小数据集也能凑合如果有NVIDIA显卡优先装CUDA版的PyTorch。创建虚拟环境再做安装避免把系统Python搞乱conda create -n crack python3.9 -y conda activate crack pip install ultralytics8.0.100 opencv-python pip install torch2.0.1 torchvision0.15.2 --index-url https://download.pytorch.org/whl/cu118逻辑说明ultralytics是YOLOv8的官方训练推理库把模型定义、训练循环、数据加载都封装好了detect.py和train.py里大量直接引用这个库。torch版本要和CUDA版本匹配这里指定cu118是兼容CUDA 11.8的预编译包如果你用CPU去掉--index-url参数装默认版即可。参数说明Python版本建议3.8到3.10之间太新的Python版本可能导致部分依赖库没有预编译wheel。torch和torchvision版本必须对应2.0.1配0.15.2是官方校验过的一组对应关系混搭容易在导入模型时触发torchvision::nms相关报错。2.3 用预训练权重跑通一次推理环境装好后先别碰训练直接跑推理验证链路。命令行方式最省事python detect.py --source dataset/val/images/IMG_0234.jpg --weights weights/best.pt --conf 0.25 --iou 0.45 --imgsz 640 --save-txt如果detect.py不是标准的ultralytics封装也可以直接用库的API写推理脚本from ultralytics import YOLO model YOLO(weights/best.pt) results model.predict(sourcedataset/val/images/, conf0.25, iou0.45, imgsz640, saveTrue, save_txtTrue) print(results[0].boxes.xyxy.cpu().numpy())逻辑说明model.predict接收图片路径或目录内部自动完成预处理、推理、后处理NMS。results里打印出的坐标是xyxy格式也就是每个裂缝框的左上角和右下角像素坐标。saveTrue会把带标注框的结果图写到runs/detect目录。save_txtTrue让推理结果以YOLO格式txt保存方便后续批量分析。参数说明conf是置信度阈值裂缝检测我一般不会拉到0.5以上因为裂缝这类低纹理目标的正检置信度天然偏低iou是NMS的IoU阈值调大一点能减少重叠框imgsz是输入网络的尺寸640是速度和精度的常用折中点检测细小裂缝时如果显存够可以试试1280。2.4 数据集格式YOLO的txt标注到底长什么样这套资源里带的数据集标注文件是txt格式每个txt对应一张同名图片。打开看一眼就能明白0 0.428125 0.53125 0.03671875 0.015625 0 0.56328125 0.474609375 0.02421875 0.01875逻辑说明每一行代表一个目标第一个数字是类别id后面四个数字是归一化后的中心点x、中心点y、框宽w、框高h四个值都是相对图片宽高的比例取值在0到1之间。这里类别id为0对应的就是裂缝。YOLO格式要求图片里的每个目标都写进txt没有标注框的图片就放一个空txt或者不放txt。和VOC的XML或COCO的JSON不同YOLO的txt没法直接看出像素尺寸所以检查标注是否正确时最可靠的方式是把框画回原图肉眼检查。我一般会写几行代码验证一遍import cv2 img cv2.imread(dataset/val/images/IMG_0234.jpg) h, w img.shape[:2] with open(dataset/val/labels/IMG_0234.txt) as f: for line in f: cls, xc, yc, bw, bh map(float, line.split()) x1 int((xc - bw / 2) * w) y1 int((yc - bh / 2) * h) x2 int((xc bw / 2) * w) y2 int((yc bh / 2) * h) cv2.rectangle(img, (x1, y1), (x2, y2), (0, 0, 255), 2) cv2.imwrite(check_label.jpg, img)逻辑说明这段代码把txt里的归一化坐标换算回图片像素坐标然后画框保存。跑完后打开check_label.jpg重点看框是不是紧贴着裂缝边缘。如果框明显偏大或者偏小说明标注质量有问题这种数据拿去训练模型学的就不是裂缝边缘而是裂缝周围的一片区域。参数说明cls这个值在资源和你的任务里通常都是0但如果之后你自己用labelme标注多类别裂缝类型这里会变成0、1、2这样的递增编号data.yaml里的names列表顺序和这里要严格对应。3. YOLOv8网络结构与推理参数改动这三处裂缝检出率才稳3.1 检测头换成anchor-free后裂缝目标检测发生了什么变化YOLOv8相比YOLOv5最核心的变化是把anchor-based检测头换成了anchor-free。anchor-based需要预设一组宽高比各异的先验框YOLOv5的默认anchor是COCO数据集聚类出来的适合普通物体但裂缝的宽高比极端动辄几十比一预设anchor经常匹配不上。YOLOv8直接在特征图每个位置预测目标中心点所在位置和宽高偏移省去了anchor聚类这一步。对基建裂缝这种细长目标来说这是实打实的收益。我拿YOLOv5s和YOLOv8s在同一批桥梁裂缝图上对比过YOLOv8对细裂缝尾部的召回明显更高尤其裂缝延伸到阴影区域时anchor-free的检测头更不容易因为IoU匹配不上而漏检。这也就是为什么这套源码选择YOLOv8而不是其他版本的原因之一。模型结构上YOLOv8用了C2f模块代替YOLOv5的C3。C2f在残差连接里引入了更多梯度流分支参数量略微增加但特征复用能力更强。对裂缝这种需要细节纹理特征的目标深层特征图多一层梯度流对小目标的敏感度是会高一些的。YOLOv8按深度和宽度系数分成n、s、m、l、x五档这套资源里的源码通常默认用yolov8s起步算力充足时换yolov8m会再涨两三个点的mAP。3.2 推理参数怎么配conf、iou、imgsz对裂缝检出的实际影响说到推理参数需要先明确裂缝检测和通用目标检测的差异。COCO数据集上0.5的置信度阈值很常见但裂缝目标边缘模糊、对比度低网络输出的objectness分数普遍低一截。我实际跑下来裂缝检出的置信度分布集中在0.2到0.6区间如果按默认conf0.25漏检率还凑合拉到0.5肉眼可见地少了一截裂缝。from ultralytics import YOLO model YOLO(weights/best.pt) results model.predict( sourcedataset/val/images/, conf0.15, iou0.5, imgsz1280, saveTrue, classes[0], max_det300 )逻辑说明conf降到0.15是为了把低置信度的裂缝框也保留下来代价是误检增多所以后面要配合classes过滤和max_det限制。我一般用两个配置跑不同场景快速巡检用conf0.25、imgsz640追求召回再用conf0.15、imgsz1280。参数说明iou0.5用于NMS裂缝框之间重叠程度通常不高0.5到0.6都行。imgsz影响最大小目标检测在640输入上的特征图分辨率有限裂缝可能只占几个像素放大到1280后特征明显丰富。max_det限制每张图最多输出的框数量防止在纹理复杂背景上出现大量噪声框。3.3 结果可视化与指标计算别只看loss要看mAP和PR曲线训练或推理完之后不能只盯着命令行里的loss数字。ultralytics在验证阶段会输出一张混淆矩阵和PR曲线位置一般在runs/detect/val或者runs/train/exp目录。我每次都会把PR曲线打开看一眼曲线越贴近右上角说明模型在低置信度区间的表现越好。对裂缝检测来说PR曲线右下段的形态尤其关键因为实际使用中我们必须在高召回和低误检之间找平衡点。如果这份源码里没有自动生成PR曲线也可以手动验证一次把测试集全部跑一遍统计不同置信度下的精确率和召回率import numpy as np from ultralytics import YOLO model YOLO(weights/best.pt) all_conf [] for img_path in image_list: r model.predict(sourceimg_path, conf0.05, verboseFalse)[0] for box in r.boxes: all_conf.append(float(box.conf[0])) thresholds np.arange(0.05, 0.95, 0.05) for t in thresholds: keep sum(c t for c in all_conf) print(fconf{t:.2f}, 保留框数{keep})逻辑说明这段代码用很低的conf阈值把所有候选框都保留下来然后统计不同置信度阈值下会输出多少个框。这个框数量-置信度曲线虽然粗糙但能直观反映你的模型在哪个区间输出是稳定可靠的。如果0.2以下的框占比很高说明模型对裂缝和背景纹理的区分度不够需要回到训练阶段调数据。参数说明r.boxes.conf是每个检测框的置信度张量verboseFalse关掉逐张图打印避免刷屏。image_list是你要测试的图片路径列表可以用glob.glob(dataset/val/images/*.jpg)生成。4. 训练自己的裂缝数据集数据划分、训练命令与调参细节4.1 数据集划分与data.yaml配置这套资源自带的数据集可以直接训练但如果你要换一批现场图就得自己处理数据集。先做划分train和val按8比2test单独留一部分看最终效果。整理成这样的目录结构dataset/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/然后写data.yaml这是train.py的第一个入口path: /home/user/crack_yolov8/dataset train: images/train val: images/val test: images/test nc: 1 names: 0: crack逻辑说明path是数据集根目录的绝对路径train、val、test写相对于path的目录。nc是类别数这里是1只有裂缝一类。names列表里0对应crack顺序一定要和标注txt里的类别id一致。很多复现翻车就是names顺序和标注对不上模型学了半天其实在学猜谜。参数说明path建议写绝对路径写相对路径时一定要在train.py同级目录启动Python否则会找不到数据集。如果之后增加网状裂缝和线性裂缝两个类nc改成2names里加一个1对应的类别名标注txt里的类别id也要相应修改。4.2 训练命令与超参数说明数据准备好后直接训练。我这里给的是通用命令实际使用以这份源码里的train.py为准但核心参数都一致python train.py --data data.yaml --weights yolov8s.pt --epochs 100 --batch-size 16 --imgsz 640 --device 0如果没有GPU把--device 0改成--device cpu但训练时间会长很多。如果train.py就是启动ultralytics的封装脚本也可以用等价的API方式from ultralytics import YOLO model YOLO(yolov8s.pt) model.train( datadata.yaml, epochs100, batch16, imgsz640, device0, patience20, cacheTrue, lr00.01, augmentTrue )逻辑说明model.train会先加载COCO预训练权重然后用你的数据集做迁移学习。epochs设100是因为裂缝数据集通常只有几百到几千张图太少学不出纹理特征太多容易过拟合后面用patience做早停兜底。batch是每批图片数根据显存调整cacheTrue把图片缓存到内存里小数据集下能显著加快读取速度。参数说明patience20意思是连续20个epoch验证集指标没有提升就自动停止训练这是防止过拟合的后悔药。lr00.01是初始学习率迁移学习场景下一般不要超过0.01否则预训练权重会被快速破坏。augmentTrue启用Mosaic、翻转、色彩抖动等内置数据增强裂缝这种细长目标我建议保留因为现场光照变化大增强能提升泛化能力。4.3 训练过程怎么看loss曲线与过拟合判断训练时命令行会持续输出box_loss、cls_loss、dfl_loss等指标。不要只看train_loss下降就开心重点看val的指标曲线。ultralytics训练结束后会在runs/train/exp目录生成results.png这张图里有每类loss和mAP50、mAP50-95的变化曲线。我判断训练状态的方法很简单train_loss持续下降、val_loss同步下降说明模型在正常学习train_loss还在降但val_loss开始反弹就是过拟合信号。裂缝数据集通常不大过拟合很常见表现为训练集上框得很准一到新图就漏检。遇到这个情况优先做三件事增加数据增强强度、调低batch让BN层统计更稳定、用早停保存最优权重。ultralytics默认只保存best.pt和last.pt过拟合发生时last.pt通常不如best.pt。另外强烈建议用torchinfo之类的工具看一眼模型参数量pip install torchinfofrom ultralytics import YOLO from torchinfo import summary model YOLO(yolov8s.pt).model summary(model, input_size(1, 3, 640, 640))逻辑说明summary会打印每一层的输出尺寸和参数量帮助你确认当前模型是yolov8s还是nano。有时候误以为自己在跑大模型实际加载的权重是nano版本。裂缝检测界面上yolov8s和yolov8n的精度差距在几个点但文件大小和推理速度差别明显。5. 裂缝检测排查避坑五条翻车记录与解决顺序5.1 踩坑记录现象、原因、解决第一条运行train.py报FileNotFoundError: No such file or directory: data.yaml。现象是脚本在main函数一进来就崩原因很直接data.yaml的path写的是相对路径而你启动python的目录不是项目根目录。解决方式是改成绝对路径或者在命令行里先cd /home/user/crack_yolov8再跑命令这个坑我踩过三次后来养成了习惯每次拿到新源码先修改data.yaml的path和weights路径再执行任何训练命令。第二条推理结果全是框在背景纹理上裂缝根本没标出来。现象是输出图里很多无意义的小框精确率极低。原因通常是训练集里的负样本太少模型分不清裂缝和暗色污渍。解决方式是数据集中加入一批完全没有裂缝的背景图并且给这些图放一个空标注txt。YOLO训练逻辑会把这些图作为负样本参与loss计算帮助模型学会抑制背景输出。第三条训练中爆显存CUDA out of memory。现象是epoch跑到一半程序被杀。原因常见两个batch过大或者cacheTrue在显存不足时反而把图片缓存到显存里。解决方式是batch从16降到8cacheTrue改成cachediskimgsz从640降到480。如果还是爆把worker数调低减小数据加载进程对显存的额外占用。第四条验证集mAP很高实测现场图效果很差。现象是val指标到了0.9新场景检出率只有一半。原因几乎是数据集拍摄条件和现场差异太大训练集裂缝都是近距离大裂纹现场是远景细裂缝。解决方式是用现场图补充数据集或者用第6章说的方式接到现场摄像头采集一轮数据重新微调单靠调参数救不回分布差异。第五条用labelme标注后转成YOLO格式训练时类别错乱。现象是loss波动剧烈推理结果把裂缝检成类别2之类不存在的id。原因是labelme JSON转YOLO txt的脚本里class_id没有按data.yaml的names顺序映射比如names里0是crack但脚本硬编码成1。解决方式是每转一批数据就抽样检查txt第一列的数值范围确保最大值小于nc并且和names索引一一对应。5.2 小目标裂缝漏检率高的排查顺序如果你发现模型对细小裂缝总是漏检按这个顺序排查。第一步看图里裂缝的最小宽度占图片宽度的比例如果裂缝只有几个像素那先降低imgsz的损失推理和训练都改成1280。第二步检查训练集里细裂缝样本是不是太少YOLOv8对训练集中小目标的占比很敏感低于10%基本学不好需要用小图裁剪的方式把细裂缝放大再送进训练集。第三步看损失曲线里dfl_loss有没有持续下降如果卡住不动多半是裂缝边缘定位不稳定可以尝试加大epoch或者换yolov8m。5.3 显存和速度的平衡策略GPU资源有限时别盲目上大模型。yolov8s在GTX 1060 6GB上跑640输入推理速度大概30到40毫秒每张训练batch 8勉强够用。再往上加yolov8l就明显吃力。这种情况下我一般保持yolov8s把imgsz当精度调节开关训练用640推理时按需调到1024或1280。推理阶段只有前向传播显存占用比训练小很多大多数6GB显卡都能撑住1280的推理。反过来如果模型要部署到RK3588这类边缘设备我建议直接训练时就选yolov8n并全程用640输入把量化损失提前考虑进去。6. 从实验到现场ONNX导出与实时推理的进阶做法6.1 导出ONNX与TensorRT加速训练完的best.pt是PyTorch格式在现场设备上加载会依赖完整训练框架。我一般会先导出ONNX再做TensorRT或RKNN的转换。导出命令很简单from ultralytics import YOLO model YOLO(weights/best.pt) model.export(formatonnx, imgsz640, opset12, simplifyTrue)导出后目录下会多一个best.onnx。逻辑说明是ONNX把模型的计算图固化下来推理不需要再依赖Python训练框架。opset12是通用性较好的算子版本太新可能在老设备上不识别simplifyTrue会删除一些冗余的reshape操作。做完这一步在NVIDIA设备上可以继续用TensorRT加速在瑞芯微RK3588平台上则用RKNN-Toolkit转成rknn格式转换前先确认target_platform是rk3588。6.2 接摄像头做实时裂缝检测现场巡检最常见的需求是接摄像头或视频流实时检测裂缝。下面这个脚本可以直接改造成现场巡检工具import cv2 from ultralytics import YOLO model YOLO(weights/best.pt) cap cv2.VideoCapture(0) while True: ret, frame cap.read() if not ret: break resized cv2.resize(frame, (640, 640)) results model.predict(resized, conf0.2, iou0.5, verboseFalse)[0] annotated results.plot() cv2.imshow(crack detect, annotated) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()逻辑说明从摄像头读帧resize到640再喂模型效率比直接用原图推理高一些因为省去了模型内部的部分缩放计算。results.plot()是ultralytics封装的方法直接把绘制好框和置信度的图输出不用自己再循环坐标画矩形。现场光照变化剧烈时建议在resize前加一次直方图均衡化或CLAHE裂缝对比度会明显提升。参数说明cv2.VideoCapture(0)是默认摄像头外接USB相机改成1或2。conf0.2是现场巡检的常用值宁可多几个误检框也要保证不漏检后续可以用跟踪算法过滤掉单帧误检。这套资源的价值在于省掉了最麻烦的从零准备数据到跑通YOLOv8训练的过程。我从解压到第一次完整跑通训练和推理花了大半天时间大部分时间耗在环境和数据路径适配。从那以后我每次复现类似项目都会强制走一遍同样的流程先看data.yaml和weights再跑推理验证最后再碰训练参数——这套顺序帮我省掉了大量无意义的报错排障时间。希望帮到你。本文还有配套的精品资源点击获取