Python+Yolov5裂缝检测实战：从源码运行到训练部署全流程

简介：这份资源面向计算机视觉方向的学生与开发者，提供一套基于Python与Yolov5实现路面、桥梁裂缝检测识别的完整项目源码及配套模型权重，可用于毕业设计、期末大作业、课程设计或算法入门实践，帮助读者快速跑通从数据配置到推理检测的全流程。压缩包共85个文件，约1.58MB，以py脚本、yaml配置、pyc缓存为主，辅以sh权重下载脚本、Dockerfile部署文件及少量jpg、png、jpeg示例图片，涵盖模型定义、数据配置、训练与检测脚本等模块。目前已有179人学习下载。项目源码经本地编译验证可运行，评审分达98分，内容经助教审定，难度适中；读者可据此掌握Yolov5网络结构、数据集yaml配置、权重加载与图片、摄像头检测等关键环节，并借助目录中models、utils、data等模块理解工程组织方式，为后续调参与二次开发提供参考。

1. 拿到这套 Python+Yolov5 裂缝检测源码，先别急着 pip install

路面和桥梁裂缝检测这个方向，这两年从传统图像处理往深度学习迁移已经非常彻底。你手上如果有一份基于 Python+Yolov5 的裂缝检测识别源码加权重模型，本质上拿到的是一个已经跑通的端到端目标检测工程：输入一张路面或桥梁的实拍图，输出裂缝的边界框、类别和置信度。它解决的不是"裂缝有多宽"这种定量问题，而是"图里有没有裂缝、在哪、大概多大范围"的定位问题，这对巡检初筛、批量图片归档、毕业设计和期末大作业来说刚好够用。

这套资源适合三类人：一是做道路桥梁方向毕业设计、需要可运行 demo 和可复现指标的学生；二是想拿一个真实工业场景数据集练 YOLOv5 全流程的算法新手；三是需要快速搭一个裂缝检测基线、再往上叠自己模块的从业者。它不适合指望开箱即得 SOTA 精度的人，也不适合完全没碰过 Python 环境的人——环境这关该踩的坑一个都不会少。下面按"资源是什么、怎么跑起来、坑在哪、怎么往上改"的顺序拆开讲。

2. 拆开压缩包：目录结构、权重加载与推理链路

2.1 目录里每个文件夹到底管什么

解压后你会看到一套标准的 YOLOv5 工程骨架，加上几个为裂缝场景定制的脚本。先认清结构再动手，能省掉大量"文件找不到"的低级报错。

weights目录和download_weights.sh是这套资源的关键——它把预训练权重和裂缝场景微调权重分开管理。hyp.finetune.yaml是微调超参，hyp.scratch.yaml是从零训练超参，这个区分很重要，后面训练章节会展开。

2.2 权重加载与一次推理的最小闭环

先别管训练，第一步是让模型在一张图上出结果，确认环境和权重都对。常见做法是先建虚拟环境，再跑推理脚本。

# 建独立环境，避免和系统 Python 打架 conda create -n crack python=3.8 -y conda activate crack # 装依赖，torch 版本要和 CUDA 对齐，没 GPU 就装 CPU 版 pip install torch==1.12.1 torchvision==0.13.1 --extra-index-url https://download.pytorch.org/whl/cu113 pip install -r requirements.txt # 拉取权重（脚本里通常是 wget 或 curl 下载 .pt 文件） bash weights/download_weights.sh

依赖装完，跑单图推理：

python detect_photo.py --weights weights/best.pt --source data/images/test_crack.jpg --conf 0.25 --img-size 640

这里几个参数直接决定结果好坏。--weights指向裂缝微调权重，不是官方 COCO 权重，用错了会检测出一堆无关类别。--conf 0.25是置信度阈值，裂缝这种细长目标建议先给低一点，宁可多检也别漏检，后面再靠 NMS 和人工复核收敛。--img-size 640是推理分辨率，裂缝在图中占比小的时候，把它提到 1280 往往能明显改善小目标召回，代价是显存和耗时上升。

推理脚本内部走的是标准链路：letterbox 缩放保持长宽比、归一化、前向推理、NMS 去重、坐标反映射回原图、画框保存到runs/detect/。如果你发现框的位置整体偏移，八成是 letterbox 的 padding 计算和反映射对不上，这是自己改预处理时最容易翻车的地方。

2.3 摄像头实时推理怎么接

detect_camera.py把 source 换成摄像头编号即可：

python detect_camera.py --weights weights/best.pt --source 0 --conf 0.3 --view-img

--source 0是默认摄像头，--view-img开实时窗口。实时场景下--img-size别开太大，640 在普通笔记本上勉强能到 15 到 20 FPS，开到 1280 基本就卡成幻灯片。如果要做巡检车上的边缘部署，正确路径是先用export.py导出 ONNX 或 TensorRT，再挂到推理引擎上，而不是硬跑 PyTorch。

3. 用自己的裂缝数据训练：数据集配置与超参怎么设

3.1 数据集目录与 yaml 配置

YOLOv5 对数据组织有固定要求：图片和标签分目录，标签是每行class x_center y_center width height的归一化 txt。裂缝场景通常就一个类别crack，所以类别数nc: 1。

crack_dataset/ images/ train/ val/ labels/ train/ val/

对应的 yaml 这样写：

# data/crack.yaml path: ../crack_dataset train: images/train val: images/val nc: 1 names: ['crack']

path用相对路径时，是相对train.py所在目录解析的，这点经常把人绕晕。稳妥做法是写绝对路径，或者确认你从项目根目录启动训练。nc和names必须和标签里的类别索引严格对应，标签里出现1而nc是 1（只有索引 0），训练会直接报索引越界。

3.2 微调还是从零训：hyp 文件的选择逻辑

资源里给了hyp.finetune.yaml和hyp.scratch.yaml两套超参，这不是摆设。裂缝数据集通常几千张量级，从零训容易过拟合且收敛慢，正确姿势是加载预训练权重做微调。

# 微调：加载预训练权重，用 finetune 超参 python train.py --data data/crack.yaml --weights weights/yolov5s.pt \ --cfg models/yolov5s.yaml --hyp data/hyp.finetune.yaml \ --epochs 100 --batch-size 16 --img-size 640 --device 0

关键参数逐个说。--weights给预训练权重而不是空，这是微调的核心。--hyp选 finetune 版本，它的初始学习率更低（常见 0.003 量级）、warmup 更短，避免把预训练学到的特征一把冲掉。--batch-size 16在 8G 显存上跑 640 分辨率差不多是上限，显存不够就降到 8 并配合--accumulate做梯度累积。--img-size训练和推理最好一致，训练 640 推理 1280 会有尺度失配，精度掉得莫名其妙。

从零训才用hyp.scratch.yaml，学习率更高、warmup 更长，适合数据量上万且和 COCO 分布差异极大的情况。裂缝检测一般用不上。

3.3 anchor 重聚类：小目标召回的关键一步

YOLOv5 默认 anchor 是在 COCO 上聚出来的，裂缝又细又长，和 COCO 目标形状差很远。不重聚类 anchor，小裂缝召回会明显偏低。项目里utils/autoanchor.py就是干这个的，训练启动时会自动检查 anchor 和数据的匹配度，匹配度低会提示重算。

# 单独跑 anchor 聚类，看当前 anchor 对裂缝数据的适配情况 python utils/autoanchor.py --data data/crack.yaml --weights weights/yolov5s.pt

输出里的Best Possible Recall（BPR）如果低于 0.98，说明 anchor 明显不匹配，应该让训练脚本自动重算，或者手动把聚类结果写回 yaml。这一步是很多"训练 loss 正常但小裂缝检不出"问题的根因，别跳过。

4. 训练与推理的避坑排查：五个真实翻车现场

4.1 现象：训练 loss 一直不降，mAP 卡在 0.0x

原因通常是标签格式错了。YOLOv5 要的是归一化中心点加宽高，很多人直接塞了 VOC 的xmin ymin xmax ymax像素坐标，模型学不到任何东西。也可能是类别索引从 1 开始，而nc: 1只认索引 0。

解决：写个脚本抽查标签，确认每行五个值、后四个都在 0 到 1 之间、类别索引从 0 开始。归一化坐标乘回图像宽高应该落在图内，超出范围说明标注或转换有 bug。

4.2 现象：显存爆了，报 CUDA out of memory

原因不一定是 batch 太大，也可能是--img-size开太高，或者 dataloader 的workers太多导致内存和显存一起涨。

解决：先把--batch-size减半，再把--img-size从 1280 降到 640，还不行就--workers 2。用nvidia-smi盯着显存曲线，确认是训练峰值爆还是推理阶段爆，两者处理方式不同。

4.3 现象：推理结果框位置整体偏移或框比目标大一圈

原因是预处理和反映射不一致。自己改过 letterbox 的 padding、或者推理时--img-size和训练不一致，都会导致坐标映射错位。

解决：回到官方 letterbox 实现，确认缩放比例和 padding 在前后处理里用的是同一组值。训练和推理分辨率尽量对齐，非要改就同步改两边的缩放逻辑。

4.4 现象：验证集 mAP 很高，实际图片上啥都检不出

原因是验证集和真实场景分布不一致，或者过拟合。裂缝数据集如果验证集是从同一批图里随机切的，指标会虚高。

解决：验证集按拍摄路段、光照条件、相机型号分层切分，别随机切。真实场景测试图单独留一批，永远不参与训练和验证，用它做最终判断。

4.5 现象：download_weights.sh跑完权重文件是 0 字节或损坏

原因是下载中断或链接失效，脚本没做校验。

解决：手动确认.pt文件大小合理（yolov5s 通常十几 MB 量级），用python -c "import torch; torch.load('weights/best.pt')"验证能否加载。加载报错就重新下，别硬跑，损坏权重会报一堆看不懂的 key 错误。

5. 从能跑到好用：导出部署与精度验证的收尾技巧

跑通训练和推理只是及格线，真正让这套资源在答辩或项目里站住脚的是两件事：把模型导出成可部署格式，以及用一套可信的验证流程证明它确实work。

先说导出。PyTorch 权重在服务器上跑没问题，但要嵌到巡检设备或做成独立 demo，ONNX 是更通用的选择：

# 导出 ONNX，opset 12 兼容性较好，dynamic 支持变长输入 python export.py --weights weights/best.pt --include onnx --opset 12 --img-size 640 640 # 验证导出结果和原模型输出一致 python export.py --weights weights/best.pt --include onnx --img-size 640 640 --verify

--opset 12是兼容性和算子支持的平衡点，太低有些算子不支持，太高部分推理引擎还没跟上。--verify会跑一遍前后向对比，确认导出没引入数值偏差，这一步别省，我见过太多导出后精度悄悄掉一截的案例。要上 TensorRT 就把--include换成engine，但注意 engine 和具体 GPU 架构绑定，换卡要重新导。

再说验证。答辩或交付时，光说"能检测"没用，得拿数字说话。建议固定一套评估流程：留一批从未参与训练的真实场景图，跑批量推理，统计召回和误检。

# 批量推理整个测试目录，保存带框结果 python detect_photo.py --weights weights/best.pt --source test_real/ \ --conf 0.25 --img-size 1280 --save-txt --project runs/final_eval

--save-txt会把每张图的检测框存成 txt，方便你写脚本和人工标注对比算指标。--img-size 1280在最终评估时用高分辨率，把训练时 640 漏掉的小裂缝捞回来。评估时重点看两类错误：漏检（裂缝存在但没框）和误检（把接缝、阴影、水渍当成裂缝）。裂缝场景误检往往比漏检更影响观感，如果误检多，优先提高--conf到 0.4 以上，或者补一批负样本（无裂缝的路面图）进训练集，让模型学会"这不是裂缝"。

一个我踩过的坑：早期我只用 mAP 判断模型好坏，结果 mAP 0.85 的模型在实拍图上误检一堆。后来养成习惯，任何模型上线前都强制走一遍"真实场景图 + 人工过目 + 分类统计误检来源"的流程，指标只是参考，眼睛看到的才算数。这套裂缝检测资源本身已经把工程骨架搭好了，你要做的是把数据这关和验证这关补扎实，它就能从"能跑的 demo"变成"敢拿出手的项目"。希望帮到你。

本文还有配套的精品资源，点击获取