简介这套路面桥梁裂缝检测识别项目基于 Python 与 YOLOv5 构建面向具备一定深度学习基础的学生、研究人员和工程技术人员可服务毕业设计、课程设计、期末大作业及实际巡检场景中的裂缝自动识别。压缩包共 49 个文件约 1.98MB核心包括 YOLOv5 各规模模型配置、Python 图片检测与摄像头检测脚本、导出脚本、coco/voc 数据配置文件、Dockerfile 以及验证用示例图片结构层次清晰方便直接运行和二次开发。目前已有 98 人学习下载。资源在本地完成编译验证模型权重配合检测脚本可快速识别裂缝的形态、大小与位置训练相关配置、说明文档和部署文件则有助于理解 YOLOv5 从数据准备、模型训练到导出的完整流程。对于需要快速落地或扩展桥梁巡检方案的学习者这套轻量级项目具备较高的参考价值。1. Yolov5裂缝检测项目路面桥梁裂纹识别能直接跑通的资源长什么样很多人拿到深度学习毕业设计源码第一反应是先看环境配不配得上、有没有缺文件。这套基于Python和Yolov5的路面桥梁裂缝检测项目源码和模型都是本地编译跑通的连训练好的权重文件都打包在内下载解压就能直接对图片做推理。它解决的问题很具体桥梁和道路表面的裂缝检测模型能框出裂缝位置并给出置信度和类别适用于土木类的毕业设计、课程设计也适合想快速搭一个目标检测Demo的从业者。项目自带模型训练和推理全套流程包含yolov5s、yolov5m、yolov5l三种模型结构配置以及完整的数据集脚本。你需要有一定Python和深度学习基础但不用从零搭环境因为依赖清单和启动脚本都在里面。下一章我会拆开整个项目结构讲清楚每个文件夹在流水线里承担什么角色。2. 项目结构拆解从coco128到自建数据集Yolov5代码库如何组织2.1 代码目录cracks-in-road-bridges-wall.zip 里的真实内容解压后第一眼看到的是根目录下的cracks-in-road-bridges-wall文件夹里面是标准的Yolov5项目布局。models子目录存放的是模型结构定义文件包括yolov5s.yaml、yolov5m.yaml、yolov5l.yaml和yolov5x.yaml四个规格对应从轻量到高精度的四种网络深度。data目录里是数据集配置文件其中coco128.yaml是官方自带的微型数据集配置用于快速验证代码能否正常跑通coco.yaml是完整COCO数据集配置voc.yaml是VOC格式数据集的配置还有一个hyp.finetune.yaml和hyp.scratch.yaml分别对应微调和从头训练的超参数方案。scripts目录中的download_weights.sh脚本作用是从官方源下载预训练权重解决模型初始化和迁移学习问题。根目录还有detect_photo.py和detect_camera.py两个推理脚本——前者针对单张图片的静态检测后者调用摄像头做实时检测。Dockerfile的存在说明这个项目也支持容器化部署方便在无GUI的服务器环境运行。整体就是一个完整的Yolov5工作流没有人为阉割。cracks-in-road-bridges-wall/ ├── data/ │ ├── coco128.yaml # 微型数据集配置用于冒烟测试 │ ├── coco.yaml # 完整COCO数据格式配置 │ ├── voc.yaml # VOC数据格式配置 │ ├── hyp.finetune.yaml # 微调模式超参数 │ └── hyp.scratch.yaml # 从头训练超参数 ├── models/ │ ├── yolov5s.yaml # 轻量级模型结构 │ ├── yolov5m.yaml # 中等规模模型结构 │ ├── yolov5l.yaml # 大规模模型结构 │ └── yolov5x.yaml # 超大模型结构 ├── scripts/ │ └── download_weights.sh # 权重自动下载 ├── detect_photo.py # 单图推理脚本 └── detect_camera.py # 摄像头实时推理脚本代码结构的逻辑非常清楚data目录管数据输入格式models目录管网络结构定义根目录的脚本管推理入口。你不需要修改models下的yaml文件除非要调整网络深度。我一般拿到这种项目会先跑一遍detect_photo.py确认环境没问题再去看hyp.finetune.yaml里的超参数设定。2.2 权重文件与自动下载机制weights目录里有什么weights目录存放的是训练好的权重文件通常以.pt格式存在这是PyTorch的模型序列化格式。Yolov5的推理过程依赖两个文件模型结构配置文件yaml和权重文件pt。结构文件定义网络层数、通道数、anchor尺寸权重文件存储训练得到的参数值。两者缺一不可如果你的模型结构改动过旧权重很可能无法加载。download_weights.sh脚本解决的是权重缺失问题。有些项目只给代码不给权重这个项目把下载脚本和已训练权重都备齐了。脚本内容本质上是拼接URL并调用wget或curl下载。如果你的网络环境不稳定运行脚本会卡住此时可以手动从项目中提供的权重文件直接加载。# 手动下载权重后放置到 weights/ 目录 mkdir -p weights cp ./cracks-in-road-bridges-wall/weights/yolov5s.pt weights/ # 验证权重和模型结构是否匹配 python -c import torch model torch.load(weights/yolov5s.pt, map_locationcpu) print(权重文件包含的键:, list(model.keys())[:5]) 权重文件加载后检查键值是否包含model.0、model.1这类层级前缀如果提示unexpected key说明模型结构和权重版本不对应。常见错误是使用yolov5s结构去加载yolov5l的权重导致embedding维度不匹配直接报错。这个项目自带对应关系但如果你自己下载了其他版本权重就要格外注意版本兼容。2.3 推理脚本解读detect_photo.py的参数与入口逻辑detect_photo.py是单张图片推理的入口脚本。标准Yolov5推理脚本会做以下几件事加载模型、读取图片、前向推理、非极大值抑制NMS、绘制检测框、保存结果。核心参数包括--weights指定权重路径、--source指定图片路径、--conf-thres控制置信度阈值、--iou-thres控制NMS的重叠率阈值。# detect_photo.py 核心调用逻辑 python detect_photo.py \ --weights weights/yolov5s.pt \ --source data/images/test.jpg \ --conf-thres 0.25 \ --iou-thres 0.45 \ --project runs/detect \ --name exp_01 # 参数说明 # --weights模型权重路径一般用训练好的best.pt # --source输入图片路径可以是单张图片或目录 # --conf-thres置信度阈值低于此值的框会被滤除 # --iou-thresNMS的IoU阈值控制重叠框的合并程度 # --project结果保存目录默认是runs/detect推理逻辑上conf-thres的设定非常敏感。阈值设太低比如0.1会出现大量误检框路面纹理、阴影都可能被当作裂缝阈值设太高比如0.7又容易漏掉真实裂缝。裂缝目标的特征本身不像人、车那样显著边缘模糊、对比度低所以0.2到0.3是一个常用区间。爬虫抓取到的项目截图里有检测结果对比图可以看到裂缝边界框标注的置信度在0.4到0.8之间浮动。运行detect_photo.py时如果出现CUDA out of memory说明显卡显存不足可以加--device cpu强制用CPU推理代价是速度变慢。CPU推理一张1080P图片大概需要2到5秒GPU只需要几十毫秒。这个项目在数据集规模不大时CPU也能完成训练只是速度慢到怀疑人生后续我会展开讲。3. 数据准备与标注格式把裂缝图片转成Yolov5能读懂的格式3.1 数据集目录结构与标签文件data/images与data/labels的对应关系Yolov5训练要求数据按照特定目录结构组织。data/images存放原始图片data/labels存放对应的txt标签文件。每张图片的标签文件名与图片文件名保持一致只是扩展名不同。例如001.jpg对应001.txt标签文件每一行的格式是class x_center y_center width height四个数值都是相对于图片宽高的归一化坐标。# 正确的数据集目录结构 dataset/ ├── images/ │ ├── train/ │ │ ├── 001.jpg │ │ └── 002.jpg │ └── val/ │ ├── 003.jpg │ └── 004.jpg └── labels/ ├── train/ │ ├── 001.txt │ └── 002.txt └── val/ ├── 003.txt └── 004.txt标签文件里的坐标必须是有理数不能是整数。比如0.5 0.5 0.2 0.1代表目标中心位于图片正中间宽度占图片宽度的20%高度占图片高度的10%。很多新手把标注软件导出的坐标通常是左上角和右下角坐标直接丢给Yolov5结果是模型训练时loss不收敛。需要先做一次坐标转换将XML或JSON格式的标注转成YOLO格式的txt。这个转换是裂缝检测项目里最常见的第一个坑。3.2 数据配置文件如何把自定义数据集接入train.py写好数据集图片和标签后还要准备一个数据配置文件告诉Yolov5去哪里找图片、有多少个类别、类的名称是什么。项目自带的data/voc.yaml可以作为模板来改。关键字段是path数据集根目录、train训练图片路径、val验证图片路径、nc类别数量和names类别名称列表。# 自定义裂缝数据集的yaml配置示例 path: ./data/crack_dataset # 数据集根目录 train: images/train # 训练集相对路径 val: images/val # 验证集相对路径 nc: 1 # 类别数量这里只有裂缝一类 names: [crack] # 类别名称列表当你要训练自己的裂缝检测模型时只需修改path指向你的数据集根目录按images/train和images/val结构组织图片和标签。类别数量改为你的实际类别数本项目是单类检测如果是背景噪声多的情况可以考虑把数据集分成crack_horizontal、crack_vertical等多类以提升区分度。这个yaml文件的路径会在训练命令中通过--data参数传入注意使用绝对路径更稳妥。3.3 图片预处理与数据增强hyp.scratch.yaml里藏了什么Yolov5在训练时会自动做数据增强控制参数全部集中在hyp.scratch.yaml里。比如hsv_h、hsv_s、hsv_v控制色域变换degrees控制旋转角度flipud和fliplr控制水平垂直翻转概率。裂缝检测场景下真实裂缝的形态多样有横向、纵向、网状适当的旋转和翻转增强可以提升模型对不同走向裂缝的适应能力。# hyp.scratch.yaml 中与裂缝检测相关的增强参数 hsv_h: 0.015 # 色调变化幅度 hsv_s: 0.7 # 饱和度变化幅度 hsv_v: 0.4 # 亮度变化幅度 degrees: 45.0 # 最大旋转角度度 translate: 0.1 # 平移比例 scale: 0.9 # 缩放比例 flipud: 0.0 # 垂直翻转概率裂缝场景建议设为0.5 fliplr: 0.5 # 水平翻转概率 mosaic: 1.0 # 马赛克增强将4张图拼成一张需要注意的是flipud垂直翻转对于桥梁裂缝检测要慎重。桥梁裂缝有上下走向之分垂直翻转会改变裂缝相对桥梁受力方向的位置关系如果训练数据很少这种增强可能引入误导。我个人的做法是先设成0.5看训练效果如果验证集精度不升反降就把它改为0。mosaic增强能增加背景多样性默认开启即可但显存占用也会相应增加。4. 模型训练与超参数调优从yolov5s到可用的裂缝检测权重4.1 训练启动命令从预训练权重微调的正确方式项目训练入口是train.py训练命令的核心参数包括--weights预训练权重、--data数据配置、--hyp超参数、--epochs训练轮数、--batch-size和--img-size。在这个裂缝检测项目中最合理的做法是使用hyp.finetune.yaml微调超参数在yolov5s.pt预训练权重的基础上继续训练而不是从零开始。# 训练裂缝检测模型的推荐命令 python train.py \ --weights weights/yolov5s.pt \ --data data/voc.yaml \ --hyp data/hyp.finetune.yaml \ --epochs 100 \ --batch-size 16 \ --img-size 640 \ --device 0 # --weights预训练权重权重在COCO上的特征提取能力可以迁移到裂缝检测 # --data指向自定义数据集的yaml配置 # --hyp微调超参数学习率相对较低避免破坏已有特征 # --epochs100轮是裂缝检测项目的常见配置 # --batch-size如果显存不够从16降到8或4 # --img-size输入分辨率640是标准值兼顾精度和速度微调的核心思想是用小学习率在已有模型基础上小幅调整。hyp.finetune.yaml中的初始学习率lr0通常是0.001到0.003而hyp.scratch.yaml可能到达0.01。如果你用默认的scratch参数训练已有特征可能被破坏导致前期loss骤降后期又反弹。这个项目特意备了hyp.finetune.yaml就是走迁移学习路线我是建议直接用这个文件的。4.2 训练过程监控loss曲线、P/R/mAP分析与判断依据训练启动后终端会实时输出每一轮的loss值、精度Precision、召回率Recall和mAP。这些指标直接反映模型健康程度。前几轮loss从高到低快速下降是正常现象如果loss出现NaN说明学习率过大或数据标签有问题立即停止训练。# 查看训练日志的关键指标输出 Epoch GPU_mem box_loss obj_loss cls_loss Instances Size 50/100 4.21G 0.0521 0.0135 0 34 640 51/100 4.23G 0.0502 0.0129 0 41 640裂缝检测是单类任务cls_loss通常为0这正常因为只有一类不需分类损失。核心看box_loss和obj_loss两者持续下降说明模型在学习目标位置和置信度。当obj_loss降到0.02以下且验证集的mAP稳定训练可以提前停止。Yolov5会自动保存最佳模型到runs/train/exp/weights/best.pt推理时使用best.pt而不是最后一个epoch的last.pt。4.3 超参数调整经验batch size、学习率与图像分辨率之间的权衡训练中的实际约束往往不是精度而是显存。yolov5s是轻量模型默认batch-size 16在8GB显存的显卡上勉强能跑如果图像分辨率调到640以上显存会快速吃紧。裂缝检测对细粒度特征敏感分辨率太低如320会丢失细小裂缝的纹理信息我建议保持在640不要低于416。显存不足时的降级顺序优先级从高到低 1. batch-size16 - 8 - 4 2. img-size640 - 512 - 416 3. 换更轻的模型yolov5s - yolov5n若项目支持 学习率的经验法则是batch-size翻倍学习率也翻倍。 裂缝检测数据集通常较小几百到几千张学习率不宜过大。--workers参数控制数据加载线程数Windows系统设成0或2即可设太大会因为spawn问题报错。有些人的训练中途死掉是workers问题不是模型问题。如果你使用的是低配机器训练时把--workers设为2--batch-size设为4--device cpu也能跑就是慢我用CPU跑过100轮yolov5s耗时将近14个小时。5. 检测部署与避坑指南摄像头实时推理、Docker环境与常见问题排查5.1 摄像头实时检测detect_camera.py的参数调整detect_camera.py将推理从静态图片扩展到视频流调用摄像头逐帧检测裂缝。核心参数与detect_photo.py一致只是--source不再指定图片路径而是指定摄像头设备编号0默认USB摄像头或视频文件路径。实时检测对推理速度有要求建议把--img-size降至480或416帧率会有明显提升。# 摄像头实时检测 python detect_camera.py \ --weights runs/train/exp/weights/best.pt \ --source 0 \ --conf-thres 0.3 \ --img-size 480 # --source 0表示使用默认摄像头设备 # --conf-thres 0.3实时检测提高阈值减少误报 # --img-size 480降低分辨率换取更高的FPS实时场景和静态图片的置信度阈值逻辑是相反的。静态图片你可以容忍更多误检然后人工筛选摄像头场景误检会产生大量干扰框遮挡视线阻碍判断所以升到0.3是合理的。检测逻辑里Yolov5会间隔抽帧而不是逐帧处理具体看detect_camera.py里的skip_frames逻辑默认每隔2帧检测一次如果你觉得卡顿可以改成每隔3帧。5.2 Docker部署Dockerfile的使用与模型路径挂载项目附带Dockerfile意味着支持容器化部署。这对于桥梁检测现场应用很实用在边缘设备或服务器上不用逐一配置Python环境。Dockerfile的工作流程通常是基于PyTorch官方镜像安装项目依赖复制代码到镜像内暴露8000端口供外部访问。# 构建裂缝检测镜像 docker build -t crack-detection:latest . # 运行容器挂载本地模型和图片目录 docker run -it \ -v /local/weights:/app/weights \ -v /local/images:/app/data/images \ crack-detection:latest \ python detect_photo.py \ --weights /app/weights/best.pt \ --source /app/data/images/test.jpg挂载目录时有一个临时文件权限坑容器内运行的用户ID与宿主机不同生成的结果文件权限会不对宿主机上读取报Permission denied。解决方式是在docker run命令中加--user $(id -u):$(id -g)强制容器以宿主用户身份运行。我实际部署过一次不加这个参数后处理脚本读结果时折腾了二十多分钟。5.3 常见问题排查权重路径错误、NMS阈值、CUDA报错第一个常见问题是模型权重和结构不匹配。用yolov5l的权重去跑yolov5s的配置会报尺寸不一致的RuntimeError。排查方法很简单检查模型配置名是否与权重文件名对应。第二个常见问题是NMS阈值设置不当导致检测框重叠严重。--iou-thres设成0.45是默认值如果你发现同一裂缝被框了两三次手动下调到0.3。第三个问题是Windows下PyTorch的CUDA版本不匹配表现为torch.cuda.is_available()返回False解决方式是重装对应CUDA版本的PyTorch这条命令可以在项目requirement里找到。数据增强和场景翻转也是裂缝检测特有的坑。许多裂缝在竖直方向有明显的形态特征过度翻转会混淆上下方向特征在验证集上表现为precise高但recall低。遇到这种情况可以关闭flipud增强重新训练对比mAP变化。还有一个隐蔽问题标注文件意外包含了背景对象或非裂缝图像导致训练收敛异常排查方式是在训练前对数据集做一次可视化验证把每张图片和对应的标签画在同一张图上人工抽查边界框是否贴合裂纹走向。6. 模型复现与结果验证torch.hub加载和使用mAP评估检测效果hubconf.py是你验证训练权重是否还在正常工作的快捷通道。很多人在模型训练后急于部署但连模型能否成功加载都没验证。hubconf.py的作用就是让Yolov5支持torch.hub.load()方式加载只需要提供权重路径和模型结构就能在任意Python脚本中调用检测函数。写一段独立验证脚本加载训练好的best.pt权重对验证集图片做批量预测统计平均精度和检测框分布。验证结果的重要性优先级是mAP0.5大于mAP0.5:0.95前者反映基本检测能力后者反映框定位精度。裂缝检测项目更关注前者因为裂缝本身没有严格的高斯分布中心。# 复现模型评估流程 import torch model torch.hub.load(./, custom, pathweights/best.pt, sourcelocal) model.eval() results model([data/images/test_01.jpg, data/images/test_02.jpg]) results.print() results.show() # 统计每张图片的检测框数量与置信度分布 for i, pred in enumerate(results.pred): boxes pred[:, :4] confs pred[:, 4] print(f图片{i1}: 检测到{len(boxes)}个裂缝目标, 平均置信度{confs.mean():.3f})torch.hub加载时sourcelocal表示从本地目录加载而不是从GitHub远程下载这是离线环境必需的。如果你执行torch.hub.load(ultralytics/yolov5, yolov5s, pretrainedTrue)代码会联网下载没有外网时直接卡死。这个项目里的hubconf.py写明了sourcelocal的优先级也是考虑到了离线部署场景。验证模型时我习惯额外看一组边界案例亮度极低的桥底阴影图、高曝光下的阳光直射路面图、以及表面附着了水渍的桥梁图。这三类图片最容易暴露模型的泛化短板。如果精度尚可但边界框贴得不够紧密可以回到训练阶段把--img-size从640上调到768代价是训练时间增加和显存占用上升。桥梁裂缝检测是个典型的小目标检测任务细节纹理对分辨率极敏感上调分辨率往往比增加训练轮数更有效。从那以后我每次拿到类似的Yolov5检测项目都会强制自己先跑一遍hubconf.py的加载验证再可视化抽查标签质量最后才动训练参数。这个三步走让我避免过至少五次无效训练希望对你也同样有效。这套源码加模型的结构足够清晰直接复用比自己搭框架省很多事祝你的裂缝检测实验一次跑通。本文还有配套的精品资源点击获取
Yolov5路面桥梁裂缝检测项目实战：从训练到部署完整指南
简介这套路面桥梁裂缝检测识别项目基于 Python 与 YOLOv5 构建面向具备一定深度学习基础的学生、研究人员和工程技术人员可服务毕业设计、课程设计、期末大作业及实际巡检场景中的裂缝自动识别。压缩包共 49 个文件约 1.98MB核心包括 YOLOv5 各规模模型配置、Python 图片检测与摄像头检测脚本、导出脚本、coco/voc 数据配置文件、Dockerfile 以及验证用示例图片结构层次清晰方便直接运行和二次开发。目前已有 98 人学习下载。资源在本地完成编译验证模型权重配合检测脚本可快速识别裂缝的形态、大小与位置训练相关配置、说明文档和部署文件则有助于理解 YOLOv5 从数据准备、模型训练到导出的完整流程。对于需要快速落地或扩展桥梁巡检方案的学习者这套轻量级项目具备较高的参考价值。1. Yolov5裂缝检测项目路面桥梁裂纹识别能直接跑通的资源长什么样很多人拿到深度学习毕业设计源码第一反应是先看环境配不配得上、有没有缺文件。这套基于Python和Yolov5的路面桥梁裂缝检测项目源码和模型都是本地编译跑通的连训练好的权重文件都打包在内下载解压就能直接对图片做推理。它解决的问题很具体桥梁和道路表面的裂缝检测模型能框出裂缝位置并给出置信度和类别适用于土木类的毕业设计、课程设计也适合想快速搭一个目标检测Demo的从业者。项目自带模型训练和推理全套流程包含yolov5s、yolov5m、yolov5l三种模型结构配置以及完整的数据集脚本。你需要有一定Python和深度学习基础但不用从零搭环境因为依赖清单和启动脚本都在里面。下一章我会拆开整个项目结构讲清楚每个文件夹在流水线里承担什么角色。2. 项目结构拆解从coco128到自建数据集Yolov5代码库如何组织2.1 代码目录cracks-in-road-bridges-wall.zip 里的真实内容解压后第一眼看到的是根目录下的cracks-in-road-bridges-wall文件夹里面是标准的Yolov5项目布局。models子目录存放的是模型结构定义文件包括yolov5s.yaml、yolov5m.yaml、yolov5l.yaml和yolov5x.yaml四个规格对应从轻量到高精度的四种网络深度。data目录里是数据集配置文件其中coco128.yaml是官方自带的微型数据集配置用于快速验证代码能否正常跑通coco.yaml是完整COCO数据集配置voc.yaml是VOC格式数据集的配置还有一个hyp.finetune.yaml和hyp.scratch.yaml分别对应微调和从头训练的超参数方案。scripts目录中的download_weights.sh脚本作用是从官方源下载预训练权重解决模型初始化和迁移学习问题。根目录还有detect_photo.py和detect_camera.py两个推理脚本——前者针对单张图片的静态检测后者调用摄像头做实时检测。Dockerfile的存在说明这个项目也支持容器化部署方便在无GUI的服务器环境运行。整体就是一个完整的Yolov5工作流没有人为阉割。cracks-in-road-bridges-wall/ ├── data/ │ ├── coco128.yaml # 微型数据集配置用于冒烟测试 │ ├── coco.yaml # 完整COCO数据格式配置 │ ├── voc.yaml # VOC数据格式配置 │ ├── hyp.finetune.yaml # 微调模式超参数 │ └── hyp.scratch.yaml # 从头训练超参数 ├── models/ │ ├── yolov5s.yaml # 轻量级模型结构 │ ├── yolov5m.yaml # 中等规模模型结构 │ ├── yolov5l.yaml # 大规模模型结构 │ └── yolov5x.yaml # 超大模型结构 ├── scripts/ │ └── download_weights.sh # 权重自动下载 ├── detect_photo.py # 单图推理脚本 └── detect_camera.py # 摄像头实时推理脚本代码结构的逻辑非常清楚data目录管数据输入格式models目录管网络结构定义根目录的脚本管推理入口。你不需要修改models下的yaml文件除非要调整网络深度。我一般拿到这种项目会先跑一遍detect_photo.py确认环境没问题再去看hyp.finetune.yaml里的超参数设定。2.2 权重文件与自动下载机制weights目录里有什么weights目录存放的是训练好的权重文件通常以.pt格式存在这是PyTorch的模型序列化格式。Yolov5的推理过程依赖两个文件模型结构配置文件yaml和权重文件pt。结构文件定义网络层数、通道数、anchor尺寸权重文件存储训练得到的参数值。两者缺一不可如果你的模型结构改动过旧权重很可能无法加载。download_weights.sh脚本解决的是权重缺失问题。有些项目只给代码不给权重这个项目把下载脚本和已训练权重都备齐了。脚本内容本质上是拼接URL并调用wget或curl下载。如果你的网络环境不稳定运行脚本会卡住此时可以手动从项目中提供的权重文件直接加载。# 手动下载权重后放置到 weights/ 目录 mkdir -p weights cp ./cracks-in-road-bridges-wall/weights/yolov5s.pt weights/ # 验证权重和模型结构是否匹配 python -c import torch model torch.load(weights/yolov5s.pt, map_locationcpu) print(权重文件包含的键:, list(model.keys())[:5]) 权重文件加载后检查键值是否包含model.0、model.1这类层级前缀如果提示unexpected key说明模型结构和权重版本不对应。常见错误是使用yolov5s结构去加载yolov5l的权重导致embedding维度不匹配直接报错。这个项目自带对应关系但如果你自己下载了其他版本权重就要格外注意版本兼容。2.3 推理脚本解读detect_photo.py的参数与入口逻辑detect_photo.py是单张图片推理的入口脚本。标准Yolov5推理脚本会做以下几件事加载模型、读取图片、前向推理、非极大值抑制NMS、绘制检测框、保存结果。核心参数包括--weights指定权重路径、--source指定图片路径、--conf-thres控制置信度阈值、--iou-thres控制NMS的重叠率阈值。# detect_photo.py 核心调用逻辑 python detect_photo.py \ --weights weights/yolov5s.pt \ --source data/images/test.jpg \ --conf-thres 0.25 \ --iou-thres 0.45 \ --project runs/detect \ --name exp_01 # 参数说明 # --weights模型权重路径一般用训练好的best.pt # --source输入图片路径可以是单张图片或目录 # --conf-thres置信度阈值低于此值的框会被滤除 # --iou-thresNMS的IoU阈值控制重叠框的合并程度 # --project结果保存目录默认是runs/detect推理逻辑上conf-thres的设定非常敏感。阈值设太低比如0.1会出现大量误检框路面纹理、阴影都可能被当作裂缝阈值设太高比如0.7又容易漏掉真实裂缝。裂缝目标的特征本身不像人、车那样显著边缘模糊、对比度低所以0.2到0.3是一个常用区间。爬虫抓取到的项目截图里有检测结果对比图可以看到裂缝边界框标注的置信度在0.4到0.8之间浮动。运行detect_photo.py时如果出现CUDA out of memory说明显卡显存不足可以加--device cpu强制用CPU推理代价是速度变慢。CPU推理一张1080P图片大概需要2到5秒GPU只需要几十毫秒。这个项目在数据集规模不大时CPU也能完成训练只是速度慢到怀疑人生后续我会展开讲。3. 数据准备与标注格式把裂缝图片转成Yolov5能读懂的格式3.1 数据集目录结构与标签文件data/images与data/labels的对应关系Yolov5训练要求数据按照特定目录结构组织。data/images存放原始图片data/labels存放对应的txt标签文件。每张图片的标签文件名与图片文件名保持一致只是扩展名不同。例如001.jpg对应001.txt标签文件每一行的格式是class x_center y_center width height四个数值都是相对于图片宽高的归一化坐标。# 正确的数据集目录结构 dataset/ ├── images/ │ ├── train/ │ │ ├── 001.jpg │ │ └── 002.jpg │ └── val/ │ ├── 003.jpg │ └── 004.jpg └── labels/ ├── train/ │ ├── 001.txt │ └── 002.txt └── val/ ├── 003.txt └── 004.txt标签文件里的坐标必须是有理数不能是整数。比如0.5 0.5 0.2 0.1代表目标中心位于图片正中间宽度占图片宽度的20%高度占图片高度的10%。很多新手把标注软件导出的坐标通常是左上角和右下角坐标直接丢给Yolov5结果是模型训练时loss不收敛。需要先做一次坐标转换将XML或JSON格式的标注转成YOLO格式的txt。这个转换是裂缝检测项目里最常见的第一个坑。3.2 数据配置文件如何把自定义数据集接入train.py写好数据集图片和标签后还要准备一个数据配置文件告诉Yolov5去哪里找图片、有多少个类别、类的名称是什么。项目自带的data/voc.yaml可以作为模板来改。关键字段是path数据集根目录、train训练图片路径、val验证图片路径、nc类别数量和names类别名称列表。# 自定义裂缝数据集的yaml配置示例 path: ./data/crack_dataset # 数据集根目录 train: images/train # 训练集相对路径 val: images/val # 验证集相对路径 nc: 1 # 类别数量这里只有裂缝一类 names: [crack] # 类别名称列表当你要训练自己的裂缝检测模型时只需修改path指向你的数据集根目录按images/train和images/val结构组织图片和标签。类别数量改为你的实际类别数本项目是单类检测如果是背景噪声多的情况可以考虑把数据集分成crack_horizontal、crack_vertical等多类以提升区分度。这个yaml文件的路径会在训练命令中通过--data参数传入注意使用绝对路径更稳妥。3.3 图片预处理与数据增强hyp.scratch.yaml里藏了什么Yolov5在训练时会自动做数据增强控制参数全部集中在hyp.scratch.yaml里。比如hsv_h、hsv_s、hsv_v控制色域变换degrees控制旋转角度flipud和fliplr控制水平垂直翻转概率。裂缝检测场景下真实裂缝的形态多样有横向、纵向、网状适当的旋转和翻转增强可以提升模型对不同走向裂缝的适应能力。# hyp.scratch.yaml 中与裂缝检测相关的增强参数 hsv_h: 0.015 # 色调变化幅度 hsv_s: 0.7 # 饱和度变化幅度 hsv_v: 0.4 # 亮度变化幅度 degrees: 45.0 # 最大旋转角度度 translate: 0.1 # 平移比例 scale: 0.9 # 缩放比例 flipud: 0.0 # 垂直翻转概率裂缝场景建议设为0.5 fliplr: 0.5 # 水平翻转概率 mosaic: 1.0 # 马赛克增强将4张图拼成一张需要注意的是flipud垂直翻转对于桥梁裂缝检测要慎重。桥梁裂缝有上下走向之分垂直翻转会改变裂缝相对桥梁受力方向的位置关系如果训练数据很少这种增强可能引入误导。我个人的做法是先设成0.5看训练效果如果验证集精度不升反降就把它改为0。mosaic增强能增加背景多样性默认开启即可但显存占用也会相应增加。4. 模型训练与超参数调优从yolov5s到可用的裂缝检测权重4.1 训练启动命令从预训练权重微调的正确方式项目训练入口是train.py训练命令的核心参数包括--weights预训练权重、--data数据配置、--hyp超参数、--epochs训练轮数、--batch-size和--img-size。在这个裂缝检测项目中最合理的做法是使用hyp.finetune.yaml微调超参数在yolov5s.pt预训练权重的基础上继续训练而不是从零开始。# 训练裂缝检测模型的推荐命令 python train.py \ --weights weights/yolov5s.pt \ --data data/voc.yaml \ --hyp data/hyp.finetune.yaml \ --epochs 100 \ --batch-size 16 \ --img-size 640 \ --device 0 # --weights预训练权重权重在COCO上的特征提取能力可以迁移到裂缝检测 # --data指向自定义数据集的yaml配置 # --hyp微调超参数学习率相对较低避免破坏已有特征 # --epochs100轮是裂缝检测项目的常见配置 # --batch-size如果显存不够从16降到8或4 # --img-size输入分辨率640是标准值兼顾精度和速度微调的核心思想是用小学习率在已有模型基础上小幅调整。hyp.finetune.yaml中的初始学习率lr0通常是0.001到0.003而hyp.scratch.yaml可能到达0.01。如果你用默认的scratch参数训练已有特征可能被破坏导致前期loss骤降后期又反弹。这个项目特意备了hyp.finetune.yaml就是走迁移学习路线我是建议直接用这个文件的。4.2 训练过程监控loss曲线、P/R/mAP分析与判断依据训练启动后终端会实时输出每一轮的loss值、精度Precision、召回率Recall和mAP。这些指标直接反映模型健康程度。前几轮loss从高到低快速下降是正常现象如果loss出现NaN说明学习率过大或数据标签有问题立即停止训练。# 查看训练日志的关键指标输出 Epoch GPU_mem box_loss obj_loss cls_loss Instances Size 50/100 4.21G 0.0521 0.0135 0 34 640 51/100 4.23G 0.0502 0.0129 0 41 640裂缝检测是单类任务cls_loss通常为0这正常因为只有一类不需分类损失。核心看box_loss和obj_loss两者持续下降说明模型在学习目标位置和置信度。当obj_loss降到0.02以下且验证集的mAP稳定训练可以提前停止。Yolov5会自动保存最佳模型到runs/train/exp/weights/best.pt推理时使用best.pt而不是最后一个epoch的last.pt。4.3 超参数调整经验batch size、学习率与图像分辨率之间的权衡训练中的实际约束往往不是精度而是显存。yolov5s是轻量模型默认batch-size 16在8GB显存的显卡上勉强能跑如果图像分辨率调到640以上显存会快速吃紧。裂缝检测对细粒度特征敏感分辨率太低如320会丢失细小裂缝的纹理信息我建议保持在640不要低于416。显存不足时的降级顺序优先级从高到低 1. batch-size16 - 8 - 4 2. img-size640 - 512 - 416 3. 换更轻的模型yolov5s - yolov5n若项目支持 学习率的经验法则是batch-size翻倍学习率也翻倍。 裂缝检测数据集通常较小几百到几千张学习率不宜过大。--workers参数控制数据加载线程数Windows系统设成0或2即可设太大会因为spawn问题报错。有些人的训练中途死掉是workers问题不是模型问题。如果你使用的是低配机器训练时把--workers设为2--batch-size设为4--device cpu也能跑就是慢我用CPU跑过100轮yolov5s耗时将近14个小时。5. 检测部署与避坑指南摄像头实时推理、Docker环境与常见问题排查5.1 摄像头实时检测detect_camera.py的参数调整detect_camera.py将推理从静态图片扩展到视频流调用摄像头逐帧检测裂缝。核心参数与detect_photo.py一致只是--source不再指定图片路径而是指定摄像头设备编号0默认USB摄像头或视频文件路径。实时检测对推理速度有要求建议把--img-size降至480或416帧率会有明显提升。# 摄像头实时检测 python detect_camera.py \ --weights runs/train/exp/weights/best.pt \ --source 0 \ --conf-thres 0.3 \ --img-size 480 # --source 0表示使用默认摄像头设备 # --conf-thres 0.3实时检测提高阈值减少误报 # --img-size 480降低分辨率换取更高的FPS实时场景和静态图片的置信度阈值逻辑是相反的。静态图片你可以容忍更多误检然后人工筛选摄像头场景误检会产生大量干扰框遮挡视线阻碍判断所以升到0.3是合理的。检测逻辑里Yolov5会间隔抽帧而不是逐帧处理具体看detect_camera.py里的skip_frames逻辑默认每隔2帧检测一次如果你觉得卡顿可以改成每隔3帧。5.2 Docker部署Dockerfile的使用与模型路径挂载项目附带Dockerfile意味着支持容器化部署。这对于桥梁检测现场应用很实用在边缘设备或服务器上不用逐一配置Python环境。Dockerfile的工作流程通常是基于PyTorch官方镜像安装项目依赖复制代码到镜像内暴露8000端口供外部访问。# 构建裂缝检测镜像 docker build -t crack-detection:latest . # 运行容器挂载本地模型和图片目录 docker run -it \ -v /local/weights:/app/weights \ -v /local/images:/app/data/images \ crack-detection:latest \ python detect_photo.py \ --weights /app/weights/best.pt \ --source /app/data/images/test.jpg挂载目录时有一个临时文件权限坑容器内运行的用户ID与宿主机不同生成的结果文件权限会不对宿主机上读取报Permission denied。解决方式是在docker run命令中加--user $(id -u):$(id -g)强制容器以宿主用户身份运行。我实际部署过一次不加这个参数后处理脚本读结果时折腾了二十多分钟。5.3 常见问题排查权重路径错误、NMS阈值、CUDA报错第一个常见问题是模型权重和结构不匹配。用yolov5l的权重去跑yolov5s的配置会报尺寸不一致的RuntimeError。排查方法很简单检查模型配置名是否与权重文件名对应。第二个常见问题是NMS阈值设置不当导致检测框重叠严重。--iou-thres设成0.45是默认值如果你发现同一裂缝被框了两三次手动下调到0.3。第三个问题是Windows下PyTorch的CUDA版本不匹配表现为torch.cuda.is_available()返回False解决方式是重装对应CUDA版本的PyTorch这条命令可以在项目requirement里找到。数据增强和场景翻转也是裂缝检测特有的坑。许多裂缝在竖直方向有明显的形态特征过度翻转会混淆上下方向特征在验证集上表现为precise高但recall低。遇到这种情况可以关闭flipud增强重新训练对比mAP变化。还有一个隐蔽问题标注文件意外包含了背景对象或非裂缝图像导致训练收敛异常排查方式是在训练前对数据集做一次可视化验证把每张图片和对应的标签画在同一张图上人工抽查边界框是否贴合裂纹走向。6. 模型复现与结果验证torch.hub加载和使用mAP评估检测效果hubconf.py是你验证训练权重是否还在正常工作的快捷通道。很多人在模型训练后急于部署但连模型能否成功加载都没验证。hubconf.py的作用就是让Yolov5支持torch.hub.load()方式加载只需要提供权重路径和模型结构就能在任意Python脚本中调用检测函数。写一段独立验证脚本加载训练好的best.pt权重对验证集图片做批量预测统计平均精度和检测框分布。验证结果的重要性优先级是mAP0.5大于mAP0.5:0.95前者反映基本检测能力后者反映框定位精度。裂缝检测项目更关注前者因为裂缝本身没有严格的高斯分布中心。# 复现模型评估流程 import torch model torch.hub.load(./, custom, pathweights/best.pt, sourcelocal) model.eval() results model([data/images/test_01.jpg, data/images/test_02.jpg]) results.print() results.show() # 统计每张图片的检测框数量与置信度分布 for i, pred in enumerate(results.pred): boxes pred[:, :4] confs pred[:, 4] print(f图片{i1}: 检测到{len(boxes)}个裂缝目标, 平均置信度{confs.mean():.3f})torch.hub加载时sourcelocal表示从本地目录加载而不是从GitHub远程下载这是离线环境必需的。如果你执行torch.hub.load(ultralytics/yolov5, yolov5s, pretrainedTrue)代码会联网下载没有外网时直接卡死。这个项目里的hubconf.py写明了sourcelocal的优先级也是考虑到了离线部署场景。验证模型时我习惯额外看一组边界案例亮度极低的桥底阴影图、高曝光下的阳光直射路面图、以及表面附着了水渍的桥梁图。这三类图片最容易暴露模型的泛化短板。如果精度尚可但边界框贴得不够紧密可以回到训练阶段把--img-size从640上调到768代价是训练时间增加和显存占用上升。桥梁裂缝检测是个典型的小目标检测任务细节纹理对分辨率极敏感上调分辨率往往比增加训练轮数更有效。从那以后我每次拿到类似的Yolov5检测项目都会强制自己先跑一遍hubconf.py的加载验证再可视化抽查标签质量最后才动训练参数。这个三步走让我避免过至少五次无效训练希望对你也同样有效。这套源码加模型的结构足够清晰直接复用比自己搭框架省很多事祝你的裂缝检测实验一次跑通。本文还有配套的精品资源点击获取
