基于YOLOv5的裂缝检测完整工程实践与训练指南

简介一套基于PythonYolov5的路面桥梁墙体裂缝检测识别系统包含完整源码与配套文档面向计算机视觉、目标检测方向的学生、教师及企业开发者可满足课程设计、毕业设计或项目初期算法验证需求。压缩包共53个文件大小约2.06MB其中yaml文件用于模型结构与训练参数配置py/pyc文件组成核心检测代码sh脚本辅助权重下载与运行环境准备并附有测试图片、Dockerfile及docx/pptx/md说明文档覆盖从环境搭建到推理检测的完整流程。目前已有292人浏览学习代码由资深算法工程师整理结构清晰、注释规范并经过运行验证。除图片和摄像头检测脚本外还提供权重下载脚本、数据集标注配置、模型结构定义及结果截图配合文档说明读者可完整上手并理解路面、桥梁、墙体裂缝检测的实现细节。1. 裂缝检测不是玄学这套 YOLOv5 源码包解决的是「从哪里下手」路面、桥梁、墙体表面的裂缝检测是计算机视觉里一个典型的小目标、低对比度、强噪声场景。裂缝往往是细长条状的深色纹理和背景的阴影、水渍、沥青颗粒混在一起用传统图像处理的边缘检测、阈值分割去做换一张光照条件不同的图就翻车。用 YOLOv5 做这件事思路是把裂缝当成普通的目标框去回归训练一个端到端的检测模型。这个资源包的价值在于它不是只丢给你一份论文或一个半成品 train.py而是把完整工程、数据配置、迁移学习超参数、单图推理和摄像头推理脚本一次性给了你。适合三类人做毕业设计或课程设计的学生、想快速在自有图片上验证裂缝检测效果的在职人员、以及刚入门目标检测想找一个能跑通全流程范例的初学者。2. 拆开压缩包工程结构、环境初始化与最小推理2.1 拿到压缩包先做三件事查目录、看文档、理文件解压后第一时间别急着跑 train.py先把目录结构过一遍。这个包里的东西分四块第一块是文档readme.docx 和 readme.pptx里面是项目的整体说明、运行流程和结果截图建议按顺序读一遍尤其注意作者标注的环境版本和运行顺序第二块是工程本体包括 data、models、scripts、utils 这些 YOLOv5 标准目录第三块是权重管理weights 目录下放的是 download_weights.sh 脚本真正的 .pt 权重文件需要手动拉取第四块是推理入口detect_photo.py 处理单张图片detect_camera.py 接摄像头做实时检测。我一般会把压缩包里的文件按「数据、模型、脚本、文档」四个维度归档一遍对照 readme 检查有没有缺文件。这里最容易踩的坑是不要直接从压缩包内双击运行脚本Python 脚本的相对路径全部依赖工程根目录必须先完整解压到某个工作目录才能保证 data、models、weights 这些相对路径不飘。另外路径里不要带中文和空格YOLOv5 的配置文件解析对路径里的特殊字符非常敏感后面训练报错很多时候溯源到这里就断了。具体到工程文件data 目录下值得留意的是 coco128.yaml、coco.yaml、voc.yaml 三份数据配置和 hyp.scratch.yaml、hyp.finetune.yaml 两份超参数文件。coco128.yaml 是 YOLOv5 官方自带的微型数据集配置文件只有 128 张图跑一遍训练流程验证代码正确性够用但不适合真正训裂缝模型coco.yaml 和 voc.yaml 是通用数据格式的模板真正训练时你要复制一份改成自己的数据集路径和类别数。hyp.finetune.yaml 是微调专用超参学习率、增强强度都比 hyp.scratch.yaml 更保守这个区别在第四章会展开讲。2.2 Python 环境初始化版本选择与依赖安装的实操顺序这套代码基于 YOLOv5对 Python 版本的要求不算苛刻但也不是随便什么版本都能跑。综合兼容性考虑我建议 Python 3.8 或 3.9PyTorch 用 1.10 以上即可如果你的显卡驱动支持 CUDA 11.3那就直接装对应版本的 PyTorch。没有 N 卡的人也不用慌CPU 版本可以跑推理和训练只是速度慢几倍到十几倍对于课程设计和验证流程来说仍然是可以接受的。环境搭建我习惯用 venv 而不是 conda因为 conda 默认源在某些网络环境下容易拉取失败而 venv 配合 pip 换源是更可控的组合。操作顺序如下# 1. 创建虚拟环境python3.8 请替换成你本机实际路径 python -m venv yolov5_env # 2. 激活虚拟环境Windows 执行 activate.batLinux/macOS 执行 source activate yolov5_env\Scripts\activate # 3. 升级 pip 并安装依赖 python -m pip install --upgrade pip pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这里每一步都有说头。第一步创建虚拟环境的目的很直接YOLOv5 依赖的 numpy、opencv-python、torch 版本跨度大如果直接装进系统 Python很容易把别的项目环境搞乱。第二步激活虚拟环境后命令行提示符前面会出现(yolov5_env)字样这时候 pip 装的包才会进这个独立环境而不是污染系统环境。第三步的-i参数指定清华镜像源是解决 pip 下载超时的最常见手段如果你在海外或网络环境特殊不加这个参数反而更快按自己的实际网络情况来。依赖装完以后建议手动验证一下关键包的版本。很多奇怪的报错不是代码问题而是 torch 和 torchvision 版本不匹配。验证命令很简单python -c import torch; print(torch.__version__) python -c import cv2; print(cv2.__version__)如果 torch 能导入但报找不到 DLL 或者 CUDA 不可用大概率是 torch 和 CUDA 驱动版本不匹配重新安装对应版本的 torch 即可。这个环节我每次都会做30 秒的事能省后面排查半天。2.3 最小推理验证用预训练权重跑一张图确认环境可用环境配置完成后的第一件事不是训练而是推理。先让模型跑起来确认整条链路是通的然后再谈训练和调参。这个包的 weights 目录下没有直接放权重文件只有一个 download_weights.sh 脚本你需要先执行它拉取预训练权重cd weights bash download_weights.sh脚本会按 YOLOv5 官方地址下载 yolov5s.pt、yolov5m.pt、yolov5l.pt、yolov5x.pt 四份权重文件大小从十几 MB 到两百多 MB 不等。如果你的网络拉取 GitHub 资源不稳定可以手动去 YOLOv5 官方仓库的 release 页面下载 yolov5s.pt 放到 weights 目录效果一样。下载完成后用自带的推理脚本跑一张测试图# 在工程根目录执行指定权重和图片路径 python detect_photo.py --weights weights/yolov5s.pt --source screenshot/5.png--weights指定模型权重--source指定输入图片。跑通后会在 runs/detect 目录下生成标注了检测框的结果图。如果你在工程根目录打开它看到图上的目标被框住了说明环境链路没问题可以进入下一步——准备自己的裂缝数据。这一步的意义在于把「环境问题」和「算法问题」隔离开如果连预训练权重的推理都跑不通说明是环境配置问题先解决环境如果能跑通但裂缝检测效果差才轮到数据和质量的问题。3. 迁移学习选型裂缝检测为什么非要踩在预训练权重上起步3.1 裂缝目标的视觉特性和 COCO 预训练特征的适配逻辑裂缝检测和常规目标检测有一个本质区别常规目标如人、车、猫狗有清晰的轮廓、丰富的纹理和稳定的颜色分布裂缝则是低对比度的细长暗色结构宽度可能只有几个像素长度却跨越几十上百像素背景里还有大量与裂缝视觉特征高度相似的干扰物——沥青路面上的裂纹状纹理、墙体上的划痕、桥梁表面的水渍痕迹。这种目标特性决定了从零训练一个裂缝检测器收敛极慢且很容易陷在局部最优里。迁移学习的逻辑是把在大规模数据集上预训练的模型拿过来做起点。YOLOv5 官方提供的 yolov5s.pt 是在 COCO 数据集上训练好的权重COCO 包含 80 个类别、二十多万张图像模型在 backbone 部分已经学到了非常通用的边缘、纹理、形状特征表达能力。裂缝虽然不在 COCO 的 80 类里但裂缝的本质是边缘和纹理的异常组合预训练模型对边缘和纹理的提取能力可以直接迁移过来。这就是为什么这套包里作者同时放了 hyp.scratch.yaml 和 hyp.finetune.yaml 两份超参数文件——前者对应从零训练学习率大、数据增强激进后者对应迁移学习微调学习率小、增强温和。对裂缝检测这种数据量通常只有几百到几千张的小样本场景微调是唯一现实的选择。3.2 三份数据配置文件的真实用途与修改边界data 目录下的 coco128.yaml、coco.yaml、voc.yaml 很多初学者会混淆搞不清楚该改哪个、该用哪个。先说结论不要直接改这三份文件而是复制一份再改。coco128.yaml 是 YOLOv5 官方自带的微型数据集128 张 COCO 子集图片专门用来做流程验证。你可以在它上面跑一个 2 个 epoch 的训练确认训练代码能跑通但不要指望它训出能用的裂缝模型。coco.yaml 和 voc.yaml 是两种数据格式的模板里面定义的路径和类别数都是别人的直接用会报「class 数量不匹配」之类的错误。真正训练时你需要新建一份自己的数据配置文件比如命名为 crack.yaml。它的核心内容只有四个部分train 和 val 路径指向你的图片目录nc 是类别数量names 是类别名称列表。在裂缝检测场景里很多人会把路面裂缝、桥梁裂缝、墙体裂缝分别作为三个类别来做检测如果你的标注数据也是这样划分的那 nc 就写 3names 写[road_crack, bridge_crack, wall_crack]。如果你的数据是混合标注的所有裂缝统一算一类那 nc 写 1 就行。这个选择没有对错取决于你的标注数据是怎么打的——这一点要在标注阶段就定下来而不是训练前才纠结。3.3 weights 脚本与模型规模选择的边界条件download_weights.sh 会拉取 yolov5s/m/l/x 四个尺度的权重。这四个模型对应同一个网络结构的不同深度和宽度倍率yolov5s 最小最快yolov5x 最大最准但显存占用也最高。对于裂缝检测我的建议很直接显存小于 6GB 就老老实实用 yolov5s显存 8GB 以上可以试 yolov5m。原因是裂缝是细长小目标模型容量太小提取不了足够的细节特征但模型容量越大对显存的要求越苛刻而且裂缝数据集通常很小模型太大会快速过拟合。我在 1080Ti 上跑过 yolov5m 训裂缝batch-size 开到 16 就到顶了再大直接 OOM。如果你想知道为什么权重脚本里四个模型都有而不是只留一个原因很简单工程完整性。作者交付的是学习资源包不是生产部署包把全套权重拉取脚本放进来是为了让使用者能自由切换模型规模做对比实验。实际训练时你只会用到其中一到两个其余的是留给你做横向对比的。4. 训练落地数据组织、超参数语义与训练命令参数精讲4.1 标签格式与目录结构YOLO 格式不是玄学是硬规范YOLOv5 的数据组织方式是「images 放图片、labels 放标签同名的 .jpg 和 .txt 一一对应」。标签文件是纯文本每一行代表一个目标框格式是class x_center y_center width height四个坐标值全部相对于图片宽度和高度归一化取值在 0 到 1 之间。比如一张 640×480 的图片里有一个裂缝框左上角坐标是 (160, 240)宽高是 (320, 120)那这一行写的内容是类别id、x_center320/6400.5、y_center300/4800.625、width320/6400.5、height120/4800.25。# 对应 data/crack.yaml 中 nc3 的单类别示例 0 0.500000 0.625000 0.500000 0.250000这份文件要保证和图片同名同路径图片在images/train/下叫0001.jpg标签就必须在labels/train/下叫0001.txt。很多人的训练 loss 不降或者 mAP 一直为 0排查到最后发现是 labels 目录名拼错或者标签文件后缀大小写不一致。目录层级上train 和 val 下各放一套 images 和 labels配置文件的路径写的是images/train这一级YOLOv5 会自动把images替换成labels去找标签文件。整个过程里面最耗时间的是标注环节。推荐用 LabelImg 或 labelme 标注导出时选 YOLO 格式。如果你已经有 VOC 格式的 xml 标注或者 COCO 格式的 json 标注需要写转换脚本。下面这段是把 VOC xml 转成 YOLO txt 的常见做法参数含义直接写在注释里import xml.etree.ElementTree as ET import os def voc_to_yolo(xml_path, out_dir, class_list): xml_path: VOC格式标注文件路径 out_dir: 输出YOLO标签目录 class_list: 类别名列表顺序决定类别id tree ET.parse(xml_path) root tree.getroot() size root.find(size) img_w int(size.find(width).text) img_h int(size.find(height).text) names [] boxes [] for obj in root.iter(object): name obj.find(name).text if name not in class_list: continue cls_id class_list.index(name) xmlbox obj.find(bndbox) xmin int(xmlbox.find(xmin).text) ymin int(xmlbox.find(ymin).text) xmax int(xmlbox.find(xmax).text) ymax int(xmlbox.find(ymax).text) # 计算YOLO格式需要的归一化中心坐标和宽高 x_center ((xmin xmax) / 2) / img_w y_center ((ymin ymax) / 2) / img_h w (xmax - xmin) / img_w h (ymax - ymin) / img_h names.append(f{cls_id} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}) out_path os.path.join(out_dir, os.path.basename(xml_path).replace(.xml, .txt)) with open(out_path, w) as f: f.write(\n.join(names)) # 使用示例 voc_to_yolo(annotations/0001.xml, labels/train, [road_crack, bridge_crack, wall_crack])这段代码的逻辑不复杂核心是把 VOC 格式里的 xmin/ymin/xmax/ymax 四个绝对像素坐标换算成相对图片宽高的中心点坐标和宽高比例。class_list 的参数顺序决定了类别 id必须和配置文件里的 names 保持一致。转换完成后别忘了随机抽几张图把标注框画回去检查——这一步能发现 90% 的标签坐标错位问题比如 xml 里的坐标是相对于原图还是相对于 crop 后的图这类坑非常隐蔽。4.2 训练命令逐参数拆解超参数不是玄学是约束数据准备就绪后训练命令的写法决定了整个训练过程的效率和稳定性。下面给出一个适合裂缝检测微调的完整命令逐项说明参数含义python train.py \ --data data/crack.yaml \ --weights weights/yolov5s.pt \ --hyp hyp.finetune.yaml \ --epochs 100 \ --batch-size 16 \ --img 640 \ --device 0 \ --patience 30 \ --workers 4 \ --cache逐项拆解。--data指向你自己的数据配置文件--weights指向预训练权重微调就必须用这个参数不写就是从零训练效果天差地别--hyp指定超参数文件这里用 hyp.finetune.yaml 而不是 hyp.scratch.yaml因为微调需要更小的学习率和更温和的数据增强--epochs是训练轮数裂缝检测数据集小100 轮足够收敛再多就开始过拟合了--batch-size受显存约束16 是一个在 8GB 显存下比较稳妥的值显存小就降到 8 或 4--img是输入分辨率640 是精度和速度的平衡点想提高小目标召回率可以试 1280但显存占用会翻四倍--device 0指定用第一张显卡没有 GPU 就写--device cpu--patience 30是早停机制连续 30 轮验证集精度不提升就自动停止避免无效训练浪费电费--workers 4是数据加载线程数Windows 上写成 0 最稳原因在避坑章节讲--cache是把图片缓存进内存训练速度能提升 30% 以上前提是你的内存够大。训练启动后你会看到终端每隔一个 batch 打印一次 loss 值。我判断训练是否正常的标准很简单前 10 轮看 loss 是否整体下降不要求每轮都降但趋势必须是向下的10 轮之后看 box_loss 和 cls_loss 是否稳定在某个量级附近震荡。如果 loss 从头到尾几乎不动先检查学习率是不是太小或数据集路径是不是空的——后者更常见路径写错导致 YOLOv5 静默加载了 0 张图训练在空数据上进行loss 自然纹丝不动。4.3 训练产物解读best.pt 和 last.pt 怎么选、怎么看训练完成后runs/train/exp 目录下会生成一系列文件。weights 子目录下有两个权重文件best.pt 是验证集上精度最高的模型last.pt 是最后一轮的模型。绝大多数情况下直接用 best.pt 做推理和测试因为 last.pt 很可能已经过拟合了。results.png 是一张综合曲线图包含 train/val 的 box_loss、cls_loss 和 mAP 曲线我每次训练完第一件事就是看这张图判断模型是否收敛、有没有过拟合。如果 train loss 持续下降但 val loss 开始回升那就是明显的过拟合信号说明训练轮数太多或数据增强太弱重新训练时减少 epochs 或换 hyp.scratch.yaml 让增强更强一些。训练产物还有 confusion_matrix.png 和 labels.jpg前者是混淆矩阵能直观看到哪些类别互相混淆后者是标注框的可视化分布能看出你的数据里目标框的尺寸分布和位置分布。对裂缝检测来说如果 labels.jpg 里显示大量目标框宽度远大于高度、长宽比极端这是正常现象——裂缝就是长条形的。但如果你发现大量框集中在图片边缘那说明标注阶段有系统偏差需要回看标注。5. 避坑指南裂缝检测训练最常见的五个翻车现场5.1 loss 能降但 mAP 始终为 0召回率上不去现象训练过程看起来一切正常loss 稳健下降但验证集 mAP 一直停留在 0 附近。原因绝大多数情况是标签文件里的类别 id 越界。比如你的 crack.yaml 里 nc1但某个 txt 文件第一行写的是2 0.5 0.5 0.2 0.2模型去预测类别 2 却发现索引越界整个训练就乱了。另一个常见原因是标签坐标没有归一化某一行写的是像素值而不是 0 到 1 之间的比例模型看到的标签全在图片外面。解决训练前用脚本扫一遍所有标签文件检查类别 id 最大值是否小于 nc坐标值是否都在 0 到 1 之间。最直接的方法是把标签画回图片上看一眼框的位置不对就是格式问题。5.2 训练到一半显存溢出跑了一小时全白费现象训练开始正常跑到第 20 轮左右报CUDA out of memory前面的进度全部丢失。原因显存占用不是恒定的。前向传播和反向传播的中间变量会在 batch 内累积某些 batch 的图片尺寸经过 mosaic 增强后会比较大YOLOv5 的 mosaic 会把四张图拼在一起一张超大图直接撑爆显存。解决把 batch-size 减半重来或者把--img从 640 降到 512。如果还想保精度打开--cache让图片预加载到内存减少显存里存放原始图像数据的开销。我的经验是宁可 batch-size 小一点多跑几轮也不要 OOM 导致重来。5.3 裂缝细长目标大量漏检模型倾向于框大片区域现象推理时模型输出的框非常大把整条裂缝连同周围背景一起框住或者根本检测不到细小的裂缝。原因YOLOv5 默认的 anchor 尺寸是针对 COCO 数据集的常规目标设计的最小 anchor 是 10×13对宽度只有几个像素的细长裂缝来说还是太大。而且输入分辨率 640 意味着像素级别的细节在多次下采样后会丢失。解决提高输入分辨率到 1280代价是显存占用大增或者用--evolve参数在训练集上重新进化 anchor让 anchor 适配裂缝的尺寸分布。常见做法是先跑一轮python train.py ... --evolve生成自定义 anchor然后用生成的 yaml 重训。效果最明显的是前者分辨率上去了小目标自然更清晰。5.4 训练集 loss 很好看验证集上一塌糊涂现象train loss 曲线完美下降val loss 却在高位震荡mAP 曲线波动剧烈没有上升趋势。原因过拟合 数据增强不当的双重作用。hyp.finetune.yaml 里如果 mosaic 和 mixup 的增强强度不够模型在小数据集上会快速背下训练集特征完全没学到泛化能力。另外训练集和验证集如果来自不同场景比如训练集全是白天拍的验证集有夜间图分布差异会直接体现在指标上。解决增强 hyp.finetune.yaml 里的mosaic: 1.0和flipud: 0.5这类参数让模型看到更多样的样本更关键的是检查数据集划分确保同一场景的图片不会全部落在训练集导致验证集分布偏移。我习惯按拍摄场景划分数据而不是按文件随机切分。5.5 Windows 下 DataLoader 卡死或报 BrokenPipeError现象训练启动后dataloader 进程报错或整个程序无响应杀掉重试依然如此。原因YOLOv5 的--workers参数在 Windows 上默认值不兼容。Windows 的多进程数据加载机制和 Linux 不一样workers 大于 0 时子进程可能出现资源抢占或端口冲突报错信息往往是BrokenPipeError或Dataloader worker (pid(s)) exited unexpectedly。解决把--workers 0写进训练命令数据加载放在主进程里做速度慢一点但非常稳定。或者用if __name__ __main__:包裹训练入口这是 PyTorch 在 Windows 上多进程的标准用法。这个坑在 Linux 上不会遇到但在 Windows 上几乎是必现的。6. 推理与进阶从单张图片到摄像头实时检测的落地技巧6.1 理解两个推理脚本的差异这个包给了两个推理脚本detect_photo.py 和 detect_camera.py分别面向图片和摄像头流。detect_photo.py 的核心逻辑是加载模型、读取图片、推理、保存结果。要改的无非是几处--weights换成你训练好的 best.pt--source指向你要检测的图片或图片目录。输出结果会保存在 runs/detect 下每次运行生成一个新的 exp 目录不会覆盖已有结果这是 YOLOv5 的默认行为。detect_camera.py 走的是 cv2.VideoCapture 的读取链路。它每读一帧就推一次模型推理结果叠加在画面左上角。实际使用中你需要关注两点一是延迟摄像头推理的帧率取决于模型大小和 GPU 性能yolov5s 在 1080Ti 上能做到 30 帧以上yolov5m 会掉到十几帧二是置信度阈值detect_camera.py 默认的--conf-thres 0.25在摄像头场景下会产生大量误检框因为画面中纹理和光照变化会把裂缝的相似特征放大我一般会提到 0.4 到 0.5 之间用召回率换精确率减少误报干扰。6.2 用 torchscript 或 ONNX 导出拿推理速度训练好的模型不一定只跑在 Python 环境里。工程里带了 models/export.py 脚本支持导出 TorchScript、ONNX、TensorRT 等格式。TorchScript 的好处是不依赖 Python 环境和 YOLOv5 源码用 libtorch 就能跑适合 C 部署ONNX 的优点是中间格式可以转给 OpenVINO、TensorRT 这些推理引擎用。导出命令如下python models/export.py --weights runs/train/exp/weights/best.pt --include torchscript onnx导出时要注意输入尺寸要和训练时保持一致否则输出的坐标会偏移。导出完成后如果你做的是桥梁检测可以试试把 ONNX 模型放到 OpenVINO 上用 CPU 跑推理速度在普通 i5 上能到 20 到 30 毫秒一帧比直接跑 PyTorch 快好几倍——这个优化对边缘设备部署非常有用。6.3 一点实际经验我自己踩过最大的坑是训练之前没有检查标签和图片的对应关系训完一轮后才发现训练集的标注有三分之一是错的坐标平移了几个像素导致模型学到的边界偏移。从那以后我每次新开一个数据集都会强制先随机抽二十张图把标注框画回去肉眼过一遍再进训练流程这个习惯帮我省下了大量返工时间。这个包里文档和代码的结构都比较完整按上面流程走一遍从环境搭建到训练出自己的裂缝检测模型落地是很快的事。希望帮到你。本文还有配套的精品资源点击获取