简介基于Python与YOLOv8的路面、桥梁及墙体裂缝识别项目是一份可直接运行的深度学习源码包面向计算机视觉初学者、土木工程检测相关学生及AI应用开发者。项目采用目标检测方式自动标出裂缝区域针对路面、桥梁、墙体三类场景可替代人工目视巡检降低主观误差、提升检测效率。压缩包共78个文件包含26个yaml配置模型与数据参数、21个py脚本训练、预测与可视化、18个pyc编译文件并配有jpg/png/jpeg测试图像及2个md文档整体仅2.55MB目录结构清晰便于初学者快速定位所需模块。代码经本地编译通过评审分在95分以上文档详细说明项目思路与运行方法附带预测脚本输入测试图片即可快速查看识别效果。目前已有296人学习下载适合课程设计、毕业设计或YOLOv8入门实战参考。1. 从桥检现场说起PythonYOLOv8裂缝识别这个高分项目到底解决什么问题桥检车停在桥下工程师举着相机拍箱梁底板晚上回办公室在 2 万张照片里用眼睛找裂缝——这是很多道路、桥梁养护单位的真实工作流。人工看图的效率低且漏检率高一张 1 米跨度的照片里一条 30 厘米长、2 毫米宽的细微裂缝很容易被忽略。基于 PythonYOLOv8 的裂缝识别项目就是用目标检测模型替代肉眼初筛输入一张路面、桥面或墙体照片模型输出每个裂缝的位置框与置信度人工只复核置信度较高的结果。它的价值不是“全自动替代检测员”而是把人从“逐张看图”变成“只看可疑框”把一个人一天处理 500 张图的工作量提升到 3000 张以上。适合做毕业设计、课程设计也适合养护单位做一套可离线运行的原型系统。2. 裂缝检测为什么选 YOLOv8把“细长线”建模成检测框的全过程2.1 裂缝是“框”不是“线”先想清楚检测任务的输出形式裂缝在图像里是细长、连续、低对比度的暗色区域传统做法是边缘检测加形态学比如 Canny 算子加连通域分析。这套方法在干净的实验室混凝土试块上效果不错一遇到桥梁底板的阴影、水渍、模板接缝边缘检测会把纹理噪声全部当成裂缝误检率高到没法用。语义分割能把裂缝像素精确标出来但标注成本太高——一张 4000×3000 的图要逐像素描边工期上不可行。目标检测的选择是工程折中用矩形框把裂缝围住标注一块矩形几秒钟就够模型输出也便于下游做统计比如每条裂缝的中心点、所在区域、置信度排序。细长裂缝的矩形框里包含大量背景这确实是固有缺点但初筛场景下并不致命。框比裂缝大说明没有漏检置信度结合框的宽高比可以辅助剔除部分误检。YOLOv8 在近几年成为这类目标检测任务的事实标准相比 YOLOv5 的优势很直接anchor-free 结构去掉了一堆手动调 anchor 的先验参数C2f 模块让特征提取更平稳解耦的检测头把分类和回归分支分开训练、收敛更快。对裂缝这种前景占比极小的数据集anchor-free 尤其重要不需要针对细长目标的宽高比去手工设计 anchor。2.2 数据集从哪里来公开裂缝集打底、自采数据补盲区常见做法是先用公开裂缝数据集把模型跑起来再补充自己场景的照片。公开数据集比较常用的是 CFD混凝土裂缝检测像素级标注、CrackForest北京路面裂缝这类学术集特点是数量少但标注质量高直接拿来做深度学习训练会因样本量太小而严重过拟合。我的建议是只用来做验证集或迁移学习的预热主力数据还是要自采一批路面、桥面、墙体照片并转成 YOLO 格式。自采数据时要注意覆盖三类差异拍摄距离与角度俯拍、斜拍、贴近拍、光线条件晴天直射、阴天散射、阴影、夜间补光、背景纹理混凝土、沥青、瓷砖、涂料墙、钢筋外露。标注工具用 LabelImg 或 Labelme 都行LabelImg 直接导出 Pascal VOC 格式后要转成 YOLO 需要的 txt 格式每一行是class x_center y_center width height四个坐标值都归一化到 0 到 1 之间。import os import xml.etree.ElementTree as ET def voc_to_yolo(xml_path, out_dir, class_names): tree ET.parse(xml_path) root tree.getroot() w int(root.find(size/width).text) h int(root.find(size/height).text) lines [] for obj in root.findall(object): name obj.find(name).text if name not in class_names: continue cls_id class_names.index(name) b obj.find(bndbox) xmin float(b.find(xmin).text) ymin float(b.find(ymin).text) xmax float(b.find(xmax).text) ymax float(b.find(ymax).text) x_center (xmin xmax) / 2 / w y_center (ymin ymax) / 2 / h box_w (xmax - xmin) / w box_h (ymax - ymin) / h lines.append(f{cls_id} {x_center:.6f} {y_center:.6f} {box_w:.6f} {box_h:.6f}) out_path os.path.join(out_dir, os.path.basename(xml_path).replace(.xml, .txt)) with open(out_path, w, encodingutf-8) as f: f.write(\n.join(lines)) if __name__ __main__: class_names [crack] # 按实际标注类别修改 for xml in os.listdir(annotations): voc_to_yolo(os.path.join(annotations, xml), labels/train, class_names)这段脚本把 Pascal VOC 的绝对像素坐标(xmin, ymin, xmax, ymax)转换成 YOLO 的归一化中心点坐标加宽高。除以图像实际宽高w和h是关键步骤如果忘记归一化训练时标签会变成一个大到离谱的框Loss 直接混乱。运行前把标注文件放到annotations/目录输出目录labels/train要提前建好脚本不会自动创建。类别设计上裂缝识别一般只保留一个crack类。不需要把桥裂缝、路面裂缝、墙体裂缝分开训练因为裂缝在视觉特征上高度相似强行分多个类只会稀释本来就少的样本。如果甲方一定要分类报告可以在后处理里按图片来源道路照片、桥梁照片、墙面照片来分而不是让模型分。2.3 模型版本与硬件选型gtx1660ti 这类卡怎么选YOLOv8 有 n/s/m/l/x 五个版本从 n 到 x 参数量依次增加精度依次提升速度依次下降。裂缝检测的现实是裂缝是极端小目标提高输入分辨率比增大模型更有效。以 gtx1660ti 这种 6GB 显存的卡为例选yolov8s在 640 分辨率、batch 16 下训练是稳的用yolov8m就得上 batch 8 并把 mosaic 增强提前关闭。如果没有 NVIDIA 显卡只能 CPU 训练直接用yolov8n宁可模型小一点也要保证批次能跑起来CPU 下 100 张图、50 轮也够出个能看的结果。模型参数量级6G 显存 batch 参考适用场景yolov8n约 3Mbatch 32CPU 训练、快速验证yolov8s约 11Mbatch 16多数裂缝项目的主力选择yolov8m约 26Mbatch 8样本量大且背景复杂yolov8l/x43M 以上需要 12G 以上不推荐用于裂缝初筛训练前要写一个数据配置文件data.yaml指向训练集与验证集的图片路径并声明类别下面是一个可以直接用的例子# data.yaml path: ./crack_data train: images/train val: images/val names: 0: crackpath是数据集根目录train和val是相对根目录的图片文件夹路径ultralytics 会自动去同名labels文件夹里找标签。注意names列表的下标必须从 0 开始并且顺序跟前面标注脚本里的class_names完全一致否则训练时会把类别标签对应错位。最后是数据划分。把所有图片按 8:1:1 分成训练、验证、测试三个目录划分时按“裂缝实体”而不是按“文件”分组。同一条裂缝被两张照片拍到如果一张进训练一张进验证验证分数会虚高得离谱这个问题到避坑章节再展开。3. 用 ultralytics 把模型训练起来环境配置、命令与结果判读3.1 环境配置Python 版本、CUDA 与 ultralytics 安装训练的第一步是准备 Python 环境。建议用 Python 3.8 到 3.10版本太新偶尔会遇到部分依赖轮子没编译好的情况不差那一个版本号稳定优先。安装 Python 时记得勾选 Add to PATH否则在终端里敲 python 会提示找不到命令。装好后用 conda 或 venv 建一个独立环境别把包直接装进系统 Python换项目时依赖冲突会很难受。在终端里依次执行# 创建并激活虚拟环境conda 方案 conda create -n crack python3.10 -y conda activate crack # 安装 GPU 版 PyTorch这里以 CUDA 11.8 为例 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 安装 ultralytics pip install ultralytics # 验证安装能输出版本号即成功 python -c from ultralytics import YOLO; print(YOLO.__version__)第一行创建了一个名为 crack 的虚拟环境Python 版本锁定 3.10。第二行是重点PyTorch 的 GPU 版和 CPU 版安装命令不一样--index-url指定 CUDA 11.8 的轮子源。如果直接pip install torch装了 CPU 版训练时会看到 GPU unavailable 的提示速度差 20 倍以上。最后一行验证导入能正常输出版本号说明链路是通的。如果是 N 卡但不确定该装哪个 CUDA 版本打开终端敲nvidia-smi右上角 CUDA Version 大于等于 11.8 就装 cu118比如 gtx1660ti 装 CUDA 11.8 完全够用。如果你的卡比较老CUDA 版本读到 10.2 或更低就要找对应版本的 torch 轮子先确认再动手。3.2 最小训练命令与关键参数裂缝场景改哪几个环境就绪后ultralytics 把整个训练流程封装到了一行命令里。核心是把数据配置、预训练权重、训练轮数、输入分辨率、批次大小这几个参数喂进去yolo detect train \ datacrack_data/data.yaml \ modelyolov8s.pt \ epochs100 \ imgsz1024 \ batch16 \ patience15 \ close_mosaic10 \ projectruns \ namecrack_smodelyolov8s.pt是拿 COCO 上预训练的权重做起点迁移学习能大幅缩短收敛时间。强烈不建议用随机初始化的yolov8s.yaml从头训练裂缝数据量通常不够。project和name决定训练日志和权重存到runs/crack_s/目录下同一批实验跑多个版本时它们就是实验区分器。参数裂缝项目的推荐值为什么这么设imgsz1024裂缝是细长小目标分辨率提高后小目标召回明显提升代价是显存与训练时间增加batch166G 显存下 imgsz1024 的 s 模型上限显存不足就降到 8patience15验证指标连续 15 轮不提升就提前停防止无效等待close_mosaic10最后 10 轮关闭 mosaic 增强避免训练后期模型被拼接裂缝误导epochs10020 到 40 轮往往就收敛了100 是给 early stop 留出余量这里特别强调close_mosaic参数。裂缝被 mosaic 拼成四格后边界信息是断裂的模型后期会学会“看到碎片就当裂缝”最后关掉 mosaic 让模型回归到真实完整图上微调验证分数通常会再涨一点。训练完成后runs/crack_s/目录下会有weights/best.pt和weights/last.pt推理、导出、部署一律用best.pt。提示data.yaml 里类别名只影响日志显示真正决定标签的是 names 列表的下标顺序。改显示名不改下标训练时类别对应关系不会变但会让日志很难读。3.3 训练结果怎么判读损失曲线图、PR 曲线、混淆矩阵训练时终端里打印的box_loss、cls_loss、dfl_loss在下降还不代表效果好。真正的判读要看验证结果。训练结束后runs/crack_s/目录下自动生成的results.png就是 yolov8 画损失函数曲线图里面包含训练损失、验证损失、Precision、Recall、mAP50、mAP50-95 六张子图。判读顺序我按重要性排看验证损失曲线是否和训练损失一起下降。验证损失在某一轮后反弹上行说明过拟合已经开始即便 best.pt 停在过拟合前后续继续加轮数也没意义。看 mAP50 是否大于 0.6这是裂缝初筛场景的可接受下限。低于 0.3 基本是数据或配置问题先别调参回头查标签。看混淆矩阵confusion_matrix.png如果背景类被大量误判成 crack说明假阳性高后处理阶段要把置信度阈值往上调。验证建议单独跑一遍训练中的验证带增强分数不完全反映真实水平yolo detect val \ modelruns/crack_s/weights/best.pt \ datacrack_data/data.yaml \ imgsz1024yolo detect val会把验证集图片全部跑一遍输出val_batch_pred.jpg这样的可视化图。我的习惯是训练完先不看指标翻这些预测图画框的位置。框画得对不对、框有没有完整包住裂缝远比数字重要。指标会骗人画框不会。4. 把模型用起来批量出报告、摄像头实时检测与边缘设备部署4.1 批量推理脚本图片文件夹出结果落 CSV 报告模型训练完成后的第一件事不是写 Web 系统而是写一个批量脚本把相机拍的高清照片文件夹全部跑一遍输出带框的图片和一个 CSV 汇总表。这对应真实巡检场景白天拍了 5000 张脚本晚上跑完第二天上午只复核可疑框。import csv from pathlib import Path from ultralytics import YOLO model YOLO(runs/crack_s/weights/best.pt) src_dir Path(raw_photos) out_dir Path(inference_result) out_dir.mkdir(exist_okTrue) rows [] for img_path in sorted(src_dir.glob(*.jpg)): result model.predict(str(img_path), conf0.25, imgsz1024, saveTrue)[0] boxes result.boxes for i in range(len(boxes)): x1, y1, x2, y2 boxes.xyxy[i].tolist() conf float(boxes.conf[i]) rows.append([img_path.name, int(x1), int(y1), int(x2), int(y2), round(conf, 4)]) with open(out_dir / report.csv, w, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerow([image, x1, y1, x2, y2, confidence]) writer.writerows(rows)conf0.25是置信度阈值批量初筛场景建议给低一点宁可多画几个假框让检测员扫一眼也别漏检。saveTrue会把画好框的图存到runs/detect/predict目录带框原图与 CSV 配合使用。CSV 里保留每一条框的坐标和置信度足够下游按“每张图最多 top3 可疑框”的顺序让检测员复核。脚本没有用多线程加速因为瓶颈通常在显存一次只喂一张图最稳如果显存有富余可以给model.predict加batch4提速。4.2 摄像头实时检测把模型接到视频流上巡检现场经常要对着桥梁侧面拍一段视频或者用摄像头扫墙面。YOLOv8 的推理接口可以直接吃视频帧代码很薄import cv2 from ultralytics import YOLO model YOLO(runs/crack_s/weights/best.pt) cap cv2.VideoCapture(0) # 0 表示本机摄像头也可以换视频文件路径 while cap.isOpened(): ok, frame cap.read() if not ok: break result model.predict(frame, conf0.3, imgsz640, verboseFalse)[0] annotated result.plot() # 画框并返回新图像 cv2.imshow(crack detection, annotated) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这里imgsz640是为速度做的妥协实时流如果还用 1024 分辨率显存占用和推理延迟都会明显上升640 对细小裂缝的召回确实有损失。所以在实时场景里我的做法是两段式先粗检测遇到置信度在 0.2 到 0.3 之间的模糊框时把原图该区域裁出来再跑一次 1024 分辨率的二次确认。这个“粗筛 二次确认”的设计在裂缝场景里比单纯调阈值可靠。verboseFalse必须带上否则每帧都会在终端刷一行推理日志时间长了直接拖慢程序。4.3 轻量化部署导出 ONNX 与 RK3588 边缘盒子的常见路线很多裂缝识别系统最后跑在巡检车里的边缘小主机或者无人机机载板子上。RK3588 这类带 NPU 的板子是主流选择但原生 PyTorch 模型在板子上跑不动需要导出成 ONNX 再转换为 RKNN 格式。yolo export \ modelruns/crack_s/weights/best.pt \ formatonnx \ imgsz1024 \ opset12导出命令里formatonnx是目标格式opset12是固定值。opset版本太新时 RKNN 工具链会报不支持的算子错误12 是兼容性和算子覆盖度的平衡点。导出后得到一个.onnx文件后续在 PC 上用 rknn-toolkit2 做模型转换和量化推理这一步依赖 RK3588 的 NPU 工具链板子端还要装配套的运行库。量化时先收集 200 张左右覆盖各种光照的裂缝图片做校准集比工具链自带的默认校准效果好得多。导出成功后要先在 PC 上确认 ONNX 没有把精度弄丢再上板子。用同一个权重分别跑 PyTorch 和 ONNX对比框数量与置信度import onnxruntime # 需要 pip install onnxruntime from ultralytics import YOLO pt_model YOLO(runs/crack_s/weights/best.pt) onnx_model YOLO(runs/crack_s/weights/best.onnx) img raw_photos/test_01.jpg pt pt_model.predict(img, conf0.25, verboseFalse)[0] ox onnx_model.predict(img, conf0.25, verboseFalse)[0] print(pt boxes:, pt.boxes.xyxy.shape[0], onnx boxes:, ox.boxes.xyxy.shape[0])ultralytics 的 YOLO 类能直接加载.onnx路径但机器上要先装 onnxruntime。框数量差异大于 20% 说明导出链路有问题先去检查 opset 和动态尺寸设置再去折腾 RKNN 量化顺序不要颠倒。5. 裂缝识别项目必踩的 5 个坑现象、原因与解决办法5.1 小目标漏检imgsz640 训练出来的模型只找得到大裂缝现象模型在训练集上 mAP 不错一到实际现场细小裂缝全部漏检画出来的框只围着少数几条粗大裂缝。原因裂缝宽度在 4000×3000 原图中往往只有 2 到 3 像素缩放到 640 后直接退化成了 0.5 像素不到的亚像素目标特征完全消失。解决训练和推理都提升到 imgsz1024再高到 1280 对 6G 显存压力太大不推荐如果 1024 还不够把原图切成 patch 再做检测具体做法在最后一章给出。5.2 白天训练的模型下雨天夜里一测就翻车现象验证集分数漂亮拿到现场换了光照和角度后漏检率翻倍看起来像模型失灵。原因采集数据时全部是晴天上午拍的模型学到的是“特定光照下的暗色条纹”而不是“裂缝本身”。解决强制扩充训练集把自采照片做 HSV 亮度随机扰动hsv_v0.4、随机对比度拉伸再补拍一部分阴影和夜间补光的样本。这条坑最隐蔽表面上是模型泛化问题实际是数据分布覆盖问题光照一变模型直接翻车。5.3 6G 显存训练到一半 CUDA out of memory现象训练过程前几十个 batch 正常突然报CUDA out of memory然后进程退出。原因imgsz1024 加 batch16 再加上开着的 mosaic 增强显存峰值比预想的高也可能是 Windows 下其他程序占用了显存。解决batch 降到 8 或 4或者把cacheTrue关掉磁盘缓存有时会在数据加载阶段额外占用显存实在不行换yolov8n。还有个容易忽略的脏数据问题数据集里混入异常大的图ultralytics 在 resize 后可能瞬间吃掉大量显存先清理花屏图和超大分辨率图。5.4 验证集 mAP 虚高模型却像没有泛化能力现象训练时验证集 mAP 到了 0.85拿一张全新的照片一测检出率很差。原因数据划分时按单张文件随机切同一个裂缝被拍进多张照片这些照片同时出现在训练集和验证集验证信息泄漏了。解决划分前先对裂缝实体去重同一道裂缝的所有照片进同一个集合按图片文件前缀或拍摄时间分组以组为单位按 8:1:1 划分而不是按单张文件划分。这条坑在桥梁逐个构件拍照时的数据里特别常见同一个构件正反两面都被拍下来天然就是重复样本。5.5 导出 RKNN 或转 ONNX 之后精度暴跌现象yolo export 命令成功板子上推理速度也达标但检出率掉到不到原来的一半。原因两处。一是量化的校准集本身就是训练集图片没有覆盖现场光照量化后的激活值范围跟实际不匹配二是 opset 版本过新部分算子被工具链以异常精度实现。解决校准集用 200 张“模型没见过”的真实场景照片转换时优先尝试 fp16 而不是 int8精度损失小一个量级如果还是不对先回到上一步验证 ONNX 本身的精度把问题定位在“导出问题”还是“量化问题”不要直接怀疑模型。6. 再进一步让裂缝识别真正进现场的两个土办法和一个反思6.1 大图切片检测不要暴力把整张照片缩到 1024桥梁底板照片动辄 4000×3000就算 imgsz1024 也把细节压缩了四倍。土办法是把原图切成 800×800 的 patch相邻 patch 重叠 100 像素防止裂缝被切开每个 patch 单独过模型再把所有框按原图坐标合并重叠区域用 NMS 去掉重复框。这种方法在显存不增加的前提下把有效分辨率翻了几倍小裂缝召回率提升明显代价是推理时间线性增加。实现就是两层循环切图加坐标换算不需要重型依赖。6.2 加一层 P2 检测头和针对性数据增强比改 head 更值热词里常看到 yolov8 head 改进的思路我的经验是裂缝任务上改注意力机制或者换检测头不如给模型提供更高分辨率的浅层特征。P2 头让模型在 160×160 特征图上做检测对 2 到 3 像素宽的裂缝是直接的增益。数据增强方面mosaic 会切断裂缝训练后期必须关掉反而随机旋转和 HSV 扰动对低对比度裂缝更有效属于“有效但有代价”的增强策略。用 yolov8 可视化热力图检查模型注意力时如果注意力集中在裂缝本身而不是背景纹理上说明训练方向是对的。6.3 验证模型最可靠的方法是留出一批没见过的现场照片训练结束别急着交差把验证集里分数最高的权重跑一遍当时没有参与训练的真实巡检照片数一数漏检和误检各占多少。在说服甲方或导师之前先让现场的检测员把模型画框的照片翻一遍看框有没有落在水渍、钢筋阴影、模板接缝上。文档说明里把数据集来源、标注规范、训练参数和复现步骤写清楚比堆一堆网络结构图有用得多。这是我自己吃过亏之后养成的习惯先看画框再看指标最后才是调参数。希望帮到你。本文还有配套的精品资源点击获取