简介基于PythonYolov5的路面桥梁裂缝检测识别资源是一套可直接运行的毕业设计工程面向计算机视觉、智能交通检测方向的学生与开发者解决道路及桥梁表面裂缝快速检测问题。源码由作者毕业设计整理而来经测试运行成功答辩评审平均分达98分完整覆盖模型训练、验证、推理及结果可视化流程。资源共85个文件压缩包仅1.6MB主要包含Python源文件、YAML模型与训练配置、pyc编译文件、Shell自动化脚本并提供jpeg/png结果截图、Dockerfile和说明文档目录中weights存放模型权重、scripts内置下载脚本、runs/detect保存检测输出方便复现实验适合直接运行和在此基础上二次开发。项目内置yolov5s/m/l/x多种尺寸模型定义包含多种常见数据配置示例以及通用工具函数、训练模块与推理入口结构清晰既可作为课程设计与毕业设计参考也可帮助入门者理解YOLOv5工程架构。目前已有271人浏览学习整体轻量且完整适合快速上手裂缝检测任务。1. 裂缝检测项目为什么值得用 YOLOv5 重做一遍路面和桥梁的裂缝检测识别过去依赖人工目检和超声波抽样成本高且容易漏掉细小裂纹。这几年大家转向“拍摄病害图像 目标检测模型自动找框”而 YOLOv5 几乎是团队上手最快、部署成本最低的候选框架。一个完整的“基于 PythonYOLOv5 路面桥梁裂缝检测识别”项目通常交付物就是源码、模型权重、说明文档、结果截图和数据压缩包拿到后到本地复现至少能把检测置信度、边界框和病害位置输出出来。这个标题里真正值钱的不是 YOLOv5 本身而是围绕它补齐的数据标注、训练参数调优和工程化打包流程。适合想快速验证裂缝识别算法、又要跑通“训练—验证—推理”全链路的 Python 工程师和算法落地岗同事。对已经熟悉 Faster R-CNN 或 SSD 的人来说YOLOv5 的 API 更直接一套配置文件加一个训练命令就能把单类别裂缝检测跑起来不用手写 Dataloader 和 Anchor 生成逻辑这也是它至今仍是路面病害检测项目首选框架的原因。接下来我按自己实际搭建这类工程的习惯把环境、原理、数据、训练到打包逐层拆开讲。2. YOLOv5 运行环境Python、CUDA 与依赖的版本搭配2.1 Python 版本选择与“轮子冲突”的常见来源不管你是打开别人的 YOLOv5 源码压缩包还是从基础仓库开始初始化第一步永远是先把 Python 装对。YOLOv5 官方到了 6.x 和 7.x 版本核心代码兼容 Python 3.8 到 3.10 是没问题的但如果你直接上 Python 3.12很多依赖如torch、torchvision的预编译包可能还认不出你机器的 CUDA 版本。我一般会先装 Python 3.10这是目前 YOLOv5 训练脚本里踩坑最少的选择。另外一个常见冲突点是opencv-python和opencv-contrib-python同时存在。裂缝检测的预处理阶段经常要用cv2.morphologyEx做形态学滤波辅助分析如果site-packages里混装了多个 OpenCV 版本cv2.findContours的返回结构都会变化。建议先卸载再装pip uninstall -y opencv-python opencv-contrib-python pip install opencv-python4.8.1.78 pip install numpy1.24.4逻辑说明先卸载可以避免cv2的二进制文件被后装版本覆盖固定 NumPy 到 1.24.4 是因为部分 Python 3.10 环境下的 PyTorch 版本还没适配 NumPy 2.x。如果你手里的项目代码里用了旧版torchvision.ops.nms的接口NumPy 2.x 会直接报_ARRAY_API not found。2.2 用 conda 建 YOLOv5 独立环境的最小步骤不要把 YOLOv5 装到 base 环境里。路面裂缝检测项目通常会再叠加分割、深度估计等模型依赖会互相打架。以下命令是我在 Windows 和 Linux 上都能稳定复现的最小流程conda create -n yolo-crack python3.10 -y conda activate yolo-crack pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu118 pip install -r requirements.txtrequirements.txt是 YOLOv5 仓库里已有的依赖清单里面包含matplotlib、pandas、pyyaml、requests、scipy、tqdm等。如果你是从标题里那个 .zip 压缩包解压出来的工程先找根目录有没有这个文件如果没有就用下面一行装齐基本依赖pip install matplotlib pandas pyyaml requests scipy tqdm pillow seaborn参数说明PyTorch 的--index-url可以替换成 CPU 版本cpu或 CUDA 12.X关键要和显卡驱动匹配。在命令行里先执行nvidia-smi看驱动支持的最高 CUDA 版本再决定装 cu118 还是 cu121这个顺序不能反否则训练时会出现“CUDA error: no kernel image is available for execution on the device”。2.3 YOLOv5 工程目录里哪些文件会直接决定项目能跑通解压源码包或 clone 工程后我习惯先看文件名再决定从哪个脚本进入。一个规范的 YOLOv5 裂缝检测项目至少应该有train.py、detect.py、val.py、export.py、models/、data/、utils/和runs/目录。runs/train/exp/weights/best.pt是训练后保存的最优权重runs/train/exp/results.csv里记录了每一轮的 mAP、loss 和 Precision/Recall。很多人一上来就执行python detect.py结果报找不到yolov5s.pt原因就是没有事先下载或训练基础权重。python train.py --data bridge_crack.yaml --weights yolov5s.pt --epochs 1这个命令看着简单但它会同时验证三件事数据集路径是否正确、权重文件是否可用、CUDA 是否能被 PyTorch 调用。如果yolov5s.pt不在当前目录脚本会自动去官方源下载如果你没有外网就把别人工程项目里的预训练权重拷到当前目录下。参数--epochs 1不是为了训练而是让数据流水线、类别数、标签格式快速跑一遍这一步能过滤掉大部分“目录结构不对”和“标注文件格式错”的问题。3. YOLOv5 网络结构与裂缝检测关键参数3.1 从输入端到 Backbone 的推理流程路面桥梁裂缝有一个很明显的特点就是目标细长且背景纹理复杂。YOLOv5 的输入端会把任意尺寸图像统一缩放成 640×640 或你指定的尺寸然后通过 Mosaic 增强把四张图拼成一张增加小目标出现的上下文信息。对裂缝这种长条状目标Mosaic 增强比普通随机裁剪有效因为裂缝往往贯穿图像单张裁剪容易把连续裂纹切成若干段导致模型学到的是“碎块”而不是“裂缝整体”。# 示例用 yaml 控制输入尺寸和增强参数 img_size: 640 mosaic: 1.0 mixup: 0.2 copy_paste: 0.0参数说明mosaic表示在每批次中应用马赛克增强的图像比例设为 1.0 就是所有训练图都会参与拼接。copy_paste在裂缝实例分割任务里经常配合标注掩膜使用纯检测项目不必开高因为裂缝边界薄复制粘贴容易产生不自然的断裂感。mixup建议从 0.2 起步太高会让模型学到图像叠加的“重影”从而降低裂缝边缘的定位精度。输入图像进入 Backbone 之后YOLOv5 的 CSPDarknet 结构会通过多次下采样生成 80×80、40×40、20×20 三种尺度的特征图。80×80 负责小目标也就是细窄的裂缝20×20 负责大目标适合标注框跨度比较大的桥面破损区域。理解这个结构后你就能解释为什么 YOLOv5 对细小裂缝容易漏检——小目标的预测集中在高分辨率特征图上训练时如果img_size设置过小比如 320小目标特征会被极度压缩模型只能学到模糊轮廓。3.2 s/m/l/x 四种模型规模怎么选YOLOv5 的yolov5s.pt、yolov5m.pt、yolov5l.pt、yolov5x.pt分别对应深度和宽度不同的一组缩放系数。对路面桥梁裂缝检测来说s和m是性价比最高的两个选择。yolov5s的参数量约 7.2M单张 640×640 图像在 GTX 1080 上推理时间约 6-8ms可以用较低成本跑实时巡检视频yolov5m参数量约 21.2MmAP 比s高 3-5%但显存占用接近翻倍。模型参数量训练显存batch16, 640px优点适合场景YOLOv5s约 7.2M8GB 左右推理快迭代调试效率高快速验证数据集和标签YOLOv5m约 21.2M14GB 左右精度高能处理更多细裂纹正式路面检测交付YOLOv5l约 46.5M20GB 以上精度更高但易过拟合数据量大且背景复杂的桥梁项目个人经验是如果目标是“先跑通再优化”直接用yolov5s完成第一轮数据验证等确认标注质量没问题后再用yolov5m做最终训练。不要在刚拿到数据时直接跑yolov5x否则一次训练十几小时最后发现数据集里有个类别的标签全是错的浪费时间也浪费显存。3.3 推理阶段的置信度阈值、IoU 阈值与 NMS 调参模型训练完成后真正决定结果截图“看起来好不好”的往往不是网络结构而是detect.py里的三个参数。第一个是--conf-thres控制最终输出框的最低置信度。裂缝检测里如果把置信度阈值设成 0.25模型会输出很多低分框截图里全是乱框设成 0.5 又容易把细小裂缝漏掉。我一般先设为 0.25 批量推理然后观察results.png里的误检率如果框体在桥面排水管、伸缩缝处频繁出现再逐步提高到 0.35 或 0.45。第二个参数是--iou-thres它影响 NMS 对重复框的抑制程度。裂缝目标通常轮廓不规则一个真实裂缝可能预测出三四个重叠程度不同的锚框。iou-thres越高保留的重复框越多结果截图里会出现同一裂缝被两个框同时框住设置过低又会把相邻的两条平行裂缝合并成一个框。常规设置为0.45。第三个是--agnostic-nms。默认情况下 NMS 按类别分别进行多类别目标检测中合理但裂缝检测通常只有crack一个类别开与不开差异不大。如果你的项目里同时包含crack、spalling、rebar_exposed多个类别并且两个类别在图像位置上高度重叠建议开启--agnostic-nms让模型在 NMS 阶段只保留一个最有把握的框避免桥梁裂缝和混凝土剥落被同时框出。python detect.py --weights runs/train/exp/weights/best.pt \ --source data/images/val \ --conf-thres 0.35 \ --iou-thres 0.45 \ --save-txt \ --save-conf参数说明--save-txt会把每个检测框的类别、归一化坐标和置信度写入runs/detect/exp/labels下的 txt 文件--save-conf决定 txt 中是否保留置信度数字。这一步对后续做热力图分析很有用不要省略。4. 路面桥梁裂缝数据集的标注与组织4.1 裂缝图像从哪里收集以及标注到什么程度路面桥梁裂缝检测项目最耗时的是数据准备。公开数据集多是欧洲和日本的桥梁裂缝图与国内路面材料、光照条件差别明显迁移效果有限。所以实际工程里通常会用无人机、行车记录仪或病害采集车拍摄目标路段的图像然后按 6:2:2 或 7:2:1 划分训练集、验证集和测试集。标注裂缝时不要试图框住整条断裂带尤其是几十厘米长的贯穿裂纹。较好的策略是沿裂纹走向用有方向的框分段标注每段长度控制在图像宽度的 10% 到 30% 之间。这样做有两个原因第一YOLOv5 的锚框都是水平矩形长宽比无限大时会造成大量无效锚点第二模型学的是局部裂纹纹理而不是“完整裂缝”的宏观形状。如果你标注的是白色虚线框训练后模型在推理时也能输出多个连续小框后续通过坐标排序再拼接成完整病害比一次性预测整条裂纹稳定得多。4.2 目录结构与 YAML 配置文件的严格约束YOLOv5 对数据集的目录结构要求非常死板训练时只会去train和val指定的路径下找图像和标签。最常见的报错是“No labels found in 某路径”根本原因是labels目录没有和images目录平级或者标签文件名与图像文件名不一致。下面是一个能直接跑通的目录结构bridge_crack/ ├── images/ │ ├── train/ │ │ ├── crack_001.jpg │ │ └── crack_002.jpg │ └── val/ │ ├── crack_010.jpg │ └── crack_011.jpg ├── labels/ │ ├── train/ │ │ ├── crack_001.txt │ │ └── crack_002.txt │ └── val/ │ ├── crack_010.txt │ └── crack_011.txt └── bridge_crack.yamlbridge_crack.yaml的内容如下path: ../bridge_crack train: images/train val: images/val nc: 1 names: 0: crackpath是相对于数据集根目录的路径train和val是相对path的目录。nc为类别数这里是单类别crack。如果你的项目里还包含网状裂缝、横向裂缝、纵向裂缝建议在names里分别定义为0: crack_web、1: crack_transverse、2: crack_longitudinal不要用同一个标签混在一起训练否则模型会陷入类别模糊。4.3 标签文件格式与数据清洗技巧YOLOv5 的标签是.txt每行五个数字类别索引、归一化中心点 x、归一化中心点 y、归一化宽 w、归一化高 h。全部数值都在 0 到 1 之间。用 LabelImg 或 X-AnyLabeling 导出的 VOC XML 格式需要转换最容易漏的是“宽高必须是真实标注宽高除以图像宽高”这一步。import os def convert_voc_to_yolo(xml_file, out_file, image_w, image_h): import xml.etree.ElementTree as ET tree ET.parse(xml_file) root tree.getroot() with open(out_file, w, encodingutf-8) as f: for obj in root.findall(object): cls obj.find(name).text if cls ! crack: continue bndbox obj.find(bndbox) xmin float(bndbox.find(xmin).text) ymin float(bndbox.find(ymin).text) xmax float(bndbox.find(xmax).text) ymax float(bndbox.find(ymax).text) x_center (xmin xmax) / 2 / image_w y_center (ymin ymax) / 2 / image_h width (xmax - xmin) / image_w height (ymax - ymin) / image_h f.write(f0 {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}\n)代码逻辑说明该脚本先把 XML 里的左上角和右下角坐标相加除以 2 得到中心点再分别除以图像宽高完成归一化。这里有个坑是很多标注工具的坐标系是左上角为原点但 YOLOv5 的归一化中心点默认也在图像左上角为原点的坐标系下所以不需要额外翻转 y 轴。转换完成后再用一行命令检查哪些框宽高为零awk -F $40 || $50 {print FILENAME} labels/train/*.txt执行结果会打印出所有包含非法框的标签文件。这类问题一旦混进训练集轻则训练 loss 不收敛重则训练中断报RuntimeError: invalid argument 0。5. YOLOv5 训练命令、超参数调优与评估5.1 第一次训练跑通的最小命令训练之前先确定预训练权重。裂缝检测的图像与 COCO 数据集差异较大但仍建议使用 COCO 上预训练的yolov5s.pt。迁移学习会让网络前几层的边缘、纹理提取能力直接复用比随机初始化更快收敛。命令如下python train.py --data bridge_crack.yaml \ --weights yolov5s.pt \ --img 640 \ --batch-size 16 \ --epochs 50 \ --device 0 \ --project runs/train/bridge_crack参数含义--img 640将训练图像统一缩放到 640×640--batch-size 16取决显存大小--device 0指定第一张 GPU。如果显存不足优先降低batch-size其次降低--img不要同时调低二者否则训练出来的模型对高分辨率裂缝图像效果会很差。执行后终端会显示每个 epoch 的 Box Loss、Cls Loss、DOL Loss 以及 mAP0.5。第一次训练重点不是把 mAP 拉到最高而是确认 loss 在稳步下降。如果前十个 epoch 的 loss 像锯齿形跳动很大先检查学习率不要急着加训练轮数。5.2 YOLOv5 超参数文件怎么改YOLOv5 把学习率、数据增强系数单独放在data/hyps/hyp.scratch-low.yaml中。裂缝检测项目里我最常改的是三个lr0、warmup_epochs和mosaic。默认lr0: 0.01对大多数目标检测任务够用但裂缝背景复杂、目标占比小初始学习率太大会让梯度在裂缝边缘区域震荡。我一般改成lr0: 0.005并在前 5 个 epoch 用warmup_epochs: 5.0预热等模型对裂缝的纹理特征有初步响应后再全速优化。超参数默认值裂缝检测建议值影响lr00.010.003 - 0.005控制前期收敛速度过大会导致边界框抖动momentum0.9370.9 - 0.937影响梯度平滑程度warmup_epochs3.05.0让模型先适应裂缝的特殊纹理mosaic1.0根据数据量决定数据量少时开满超过 2 万张可降为 0.8fliplr0.50.5 - 0.8裂缝方向随机翻转提升泛化能力# hyp.crack.yaml 片段 lr0: 0.004 lrf: 0.2 momentum: 0.92 warmup_epochs: 5.0 mosaic: 0.9 fliplr: 0.6 hsv_h: 0.02 hsv_s: 0.6 hsv_v: 0.3改完超参数后在训练命令中追加--hyp hyp.crack.yaml即可生效。这里有一个容易忽略的点hsv_h不要改得太大。桥梁裂缝图像中有些裂缝会呈现淡黄色或棕色色调偏移过大会把裂缝颜色改成与路面背景几乎一致的灰色反而降低模型判断能力。5.3 用 val.py 看结果截图和混淆矩阵训练完成后runs/train/bridge_crack/exp/目录下会生成confusion_matrix.png、results.png、val_batch*_pred.jpg和weights/best.pt。results.png里包含训练和验证的 P、R、mAP 曲线而val_batch*_pred.jpg则是验证集的可视化结果截图能直接显示模型在真实路面桥梁图像上的预测框。python val.py --data bridge_crack.yaml \ --weights runs/train/bridge_crack/exp/weights/best.pt \ --img 640 \ --conf-thres 0.001 \ --iou-thres 0.6 \ --task val \ --save-json--conf-thres 0.001是评估阶段常用的小技巧目的是让低置信度预测也参与 mAP 计算更客观反映模型整体表现。--save-json会生成 COCO 格式的模型评估结果方便用其他工具做进一步分析。我在实际项目里尤其关注验证集上的 Recall路面裂缝漏检比误检危险如果 Recall 低于 85%优先回到数据层面增加多尺度裂缝样本而不是继续调 NMS 参数。6. 推理结果截图、模型导出与 .zip 项目归档技巧6.1 批量推理并自动生成结果截图交付时结果截图不能只在终端里运行一次detect.py那样只保存最后一张图片。更稳妥的方法是写一个批量脚本循环读取验证集所有图像用模型输出预测框后用 OpenCV 把框和置信度画到原图上再按编号保存到results/crack_results/目录。这样生成的截图适合直接放进文档说明里。import cv2 import torch import glob model torch.hub.load(./, custom, pathruns/train/bridge_crack/exp/weights/best.pt, sourcelocal) model.conf 0.35 model.iou 0.45 for img_path in glob.glob(data/images/val/*.jpg): img cv2.imread(img_path) results model(img) boxes results.xyxy[0].cpu().numpy() for x1, y1, x2, y2, conf, cls_id in boxes: label fcrack {conf:.2f} cv2.rectangle(img, (int(x1), int(y1)), (int(x2), int(y2)), (0, 0, 255), 2) cv2.putText(img, label, (int(x1), int(y1) - 6), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 255), 2) out_path img_path.replace(images/val, results/crack_results) cv2.imwrite(out_path, img)代码逻辑说明脚本先加载本地best.pt权重然后遍历验证集每张图把xyxy格式的边界框和置信度绘制在图像右上角最后写到新的结果目录。model.conf和model.iou是在 PyTorch Hub 接口下直接控制推理阈值等价于命令行里的--conf-thres和--iou-thres。6.2 导出 ONNX 部署到边缘设备如果要把裂缝识别模型部署到树莓派 5 或 Jetson 这类边缘设备YOLOv5 的 PyTorch 模型直接推理速度很慢常见做法是导出成 ONNX再用 ONNX Runtime 或 TensorRT 运行。python export.py --weights runs/train/bridge_crack/exp/weights/best.pt \ --include onnx \ --img 640 \ --simplify--simplify会调用 onnx-simplifier 重构计算图去掉一些冗余节点。导出完成后用onnxruntime加载模型时需要处理输入输出的名字YOLOv5 的 ONNX 输出形状通常是[1, 25200, 85]其中 85 等于 5 个边界框属性加 80 个 COCO 类别数。如果你只训练了一个crack类别需要把模型输出通道改成 1 5 的结构否则导出后推理结果无法解析。6.3 .zip 交付时文档、模型和结果截图的组织顺序最后交付的.zip不是把整个训练目录塞进去就行而是要让人照着 README 能一步步复现。我会按四层结构组织code/放源码和训练脚本weights/放best.pt和last.ptdocs/放文档说明results/放验证集结果截图和测试集输出。文档说明里必须写清楚训练命令、数据集目录结构和每个参数能让 mAP 提高多少。这项工程化整理虽然不直接提升算法指标但能够避免一个很常见的问题接手的人不知道你用的hyp.crack.yaml和默认超参数差在哪导致复现结果完全不一致。结果截图也统一放在results/下并在 README 中标注每张图对应的图片名称和检测置信度这样即使推理代码环境变化交付方也能通过对比截图来验证模型行为是否一致。本文还有配套的精品资源点击获取 基于YOLOv5的路面桥梁裂缝检测项目实战解析
简介基于PythonYolov5的路面桥梁裂缝检测识别资源是一套可直接运行的毕业设计工程面向计算机视觉、智能交通检测方向的学生与开发者解决道路及桥梁表面裂缝快速检测问题。源码由作者毕业设计整理而来经测试运行成功答辩评审平均分达98分完整覆盖模型训练、验证、推理及结果可视化流程。资源共85个文件压缩包仅1.6MB主要包含Python源文件、YAML模型与训练配置、pyc编译文件、Shell自动化脚本并提供jpeg/png结果截图、Dockerfile和说明文档目录中weights存放模型权重、scripts内置下载脚本、runs/detect保存检测输出方便复现实验适合直接运行和在此基础上二次开发。项目内置yolov5s/m/l/x多种尺寸模型定义包含多种常见数据配置示例以及通用工具函数、训练模块与推理入口结构清晰既可作为课程设计与毕业设计参考也可帮助入门者理解YOLOv5工程架构。目前已有271人浏览学习整体轻量且完整适合快速上手裂缝检测任务。1. 裂缝检测项目为什么值得用 YOLOv5 重做一遍路面和桥梁的裂缝检测识别过去依赖人工目检和超声波抽样成本高且容易漏掉细小裂纹。这几年大家转向“拍摄病害图像 目标检测模型自动找框”而 YOLOv5 几乎是团队上手最快、部署成本最低的候选框架。一个完整的“基于 PythonYOLOv5 路面桥梁裂缝检测识别”项目通常交付物就是源码、模型权重、说明文档、结果截图和数据压缩包拿到后到本地复现至少能把检测置信度、边界框和病害位置输出出来。这个标题里真正值钱的不是 YOLOv5 本身而是围绕它补齐的数据标注、训练参数调优和工程化打包流程。适合想快速验证裂缝识别算法、又要跑通“训练—验证—推理”全链路的 Python 工程师和算法落地岗同事。对已经熟悉 Faster R-CNN 或 SSD 的人来说YOLOv5 的 API 更直接一套配置文件加一个训练命令就能把单类别裂缝检测跑起来不用手写 Dataloader 和 Anchor 生成逻辑这也是它至今仍是路面病害检测项目首选框架的原因。接下来我按自己实际搭建这类工程的习惯把环境、原理、数据、训练到打包逐层拆开讲。2. YOLOv5 运行环境Python、CUDA 与依赖的版本搭配2.1 Python 版本选择与“轮子冲突”的常见来源不管你是打开别人的 YOLOv5 源码压缩包还是从基础仓库开始初始化第一步永远是先把 Python 装对。YOLOv5 官方到了 6.x 和 7.x 版本核心代码兼容 Python 3.8 到 3.10 是没问题的但如果你直接上 Python 3.12很多依赖如torch、torchvision的预编译包可能还认不出你机器的 CUDA 版本。我一般会先装 Python 3.10这是目前 YOLOv5 训练脚本里踩坑最少的选择。另外一个常见冲突点是opencv-python和opencv-contrib-python同时存在。裂缝检测的预处理阶段经常要用cv2.morphologyEx做形态学滤波辅助分析如果site-packages里混装了多个 OpenCV 版本cv2.findContours的返回结构都会变化。建议先卸载再装pip uninstall -y opencv-python opencv-contrib-python pip install opencv-python4.8.1.78 pip install numpy1.24.4逻辑说明先卸载可以避免cv2的二进制文件被后装版本覆盖固定 NumPy 到 1.24.4 是因为部分 Python 3.10 环境下的 PyTorch 版本还没适配 NumPy 2.x。如果你手里的项目代码里用了旧版torchvision.ops.nms的接口NumPy 2.x 会直接报_ARRAY_API not found。2.2 用 conda 建 YOLOv5 独立环境的最小步骤不要把 YOLOv5 装到 base 环境里。路面裂缝检测项目通常会再叠加分割、深度估计等模型依赖会互相打架。以下命令是我在 Windows 和 Linux 上都能稳定复现的最小流程conda create -n yolo-crack python3.10 -y conda activate yolo-crack pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu118 pip install -r requirements.txtrequirements.txt是 YOLOv5 仓库里已有的依赖清单里面包含matplotlib、pandas、pyyaml、requests、scipy、tqdm等。如果你是从标题里那个 .zip 压缩包解压出来的工程先找根目录有没有这个文件如果没有就用下面一行装齐基本依赖pip install matplotlib pandas pyyaml requests scipy tqdm pillow seaborn参数说明PyTorch 的--index-url可以替换成 CPU 版本cpu或 CUDA 12.X关键要和显卡驱动匹配。在命令行里先执行nvidia-smi看驱动支持的最高 CUDA 版本再决定装 cu118 还是 cu121这个顺序不能反否则训练时会出现“CUDA error: no kernel image is available for execution on the device”。2.3 YOLOv5 工程目录里哪些文件会直接决定项目能跑通解压源码包或 clone 工程后我习惯先看文件名再决定从哪个脚本进入。一个规范的 YOLOv5 裂缝检测项目至少应该有train.py、detect.py、val.py、export.py、models/、data/、utils/和runs/目录。runs/train/exp/weights/best.pt是训练后保存的最优权重runs/train/exp/results.csv里记录了每一轮的 mAP、loss 和 Precision/Recall。很多人一上来就执行python detect.py结果报找不到yolov5s.pt原因就是没有事先下载或训练基础权重。python train.py --data bridge_crack.yaml --weights yolov5s.pt --epochs 1这个命令看着简单但它会同时验证三件事数据集路径是否正确、权重文件是否可用、CUDA 是否能被 PyTorch 调用。如果yolov5s.pt不在当前目录脚本会自动去官方源下载如果你没有外网就把别人工程项目里的预训练权重拷到当前目录下。参数--epochs 1不是为了训练而是让数据流水线、类别数、标签格式快速跑一遍这一步能过滤掉大部分“目录结构不对”和“标注文件格式错”的问题。3. YOLOv5 网络结构与裂缝检测关键参数3.1 从输入端到 Backbone 的推理流程路面桥梁裂缝有一个很明显的特点就是目标细长且背景纹理复杂。YOLOv5 的输入端会把任意尺寸图像统一缩放成 640×640 或你指定的尺寸然后通过 Mosaic 增强把四张图拼成一张增加小目标出现的上下文信息。对裂缝这种长条状目标Mosaic 增强比普通随机裁剪有效因为裂缝往往贯穿图像单张裁剪容易把连续裂纹切成若干段导致模型学到的是“碎块”而不是“裂缝整体”。# 示例用 yaml 控制输入尺寸和增强参数 img_size: 640 mosaic: 1.0 mixup: 0.2 copy_paste: 0.0参数说明mosaic表示在每批次中应用马赛克增强的图像比例设为 1.0 就是所有训练图都会参与拼接。copy_paste在裂缝实例分割任务里经常配合标注掩膜使用纯检测项目不必开高因为裂缝边界薄复制粘贴容易产生不自然的断裂感。mixup建议从 0.2 起步太高会让模型学到图像叠加的“重影”从而降低裂缝边缘的定位精度。输入图像进入 Backbone 之后YOLOv5 的 CSPDarknet 结构会通过多次下采样生成 80×80、40×40、20×20 三种尺度的特征图。80×80 负责小目标也就是细窄的裂缝20×20 负责大目标适合标注框跨度比较大的桥面破损区域。理解这个结构后你就能解释为什么 YOLOv5 对细小裂缝容易漏检——小目标的预测集中在高分辨率特征图上训练时如果img_size设置过小比如 320小目标特征会被极度压缩模型只能学到模糊轮廓。3.2 s/m/l/x 四种模型规模怎么选YOLOv5 的yolov5s.pt、yolov5m.pt、yolov5l.pt、yolov5x.pt分别对应深度和宽度不同的一组缩放系数。对路面桥梁裂缝检测来说s和m是性价比最高的两个选择。yolov5s的参数量约 7.2M单张 640×640 图像在 GTX 1080 上推理时间约 6-8ms可以用较低成本跑实时巡检视频yolov5m参数量约 21.2MmAP 比s高 3-5%但显存占用接近翻倍。模型参数量训练显存batch16, 640px优点适合场景YOLOv5s约 7.2M8GB 左右推理快迭代调试效率高快速验证数据集和标签YOLOv5m约 21.2M14GB 左右精度高能处理更多细裂纹正式路面检测交付YOLOv5l约 46.5M20GB 以上精度更高但易过拟合数据量大且背景复杂的桥梁项目个人经验是如果目标是“先跑通再优化”直接用yolov5s完成第一轮数据验证等确认标注质量没问题后再用yolov5m做最终训练。不要在刚拿到数据时直接跑yolov5x否则一次训练十几小时最后发现数据集里有个类别的标签全是错的浪费时间也浪费显存。3.3 推理阶段的置信度阈值、IoU 阈值与 NMS 调参模型训练完成后真正决定结果截图“看起来好不好”的往往不是网络结构而是detect.py里的三个参数。第一个是--conf-thres控制最终输出框的最低置信度。裂缝检测里如果把置信度阈值设成 0.25模型会输出很多低分框截图里全是乱框设成 0.5 又容易把细小裂缝漏掉。我一般先设为 0.25 批量推理然后观察results.png里的误检率如果框体在桥面排水管、伸缩缝处频繁出现再逐步提高到 0.35 或 0.45。第二个参数是--iou-thres它影响 NMS 对重复框的抑制程度。裂缝目标通常轮廓不规则一个真实裂缝可能预测出三四个重叠程度不同的锚框。iou-thres越高保留的重复框越多结果截图里会出现同一裂缝被两个框同时框住设置过低又会把相邻的两条平行裂缝合并成一个框。常规设置为0.45。第三个是--agnostic-nms。默认情况下 NMS 按类别分别进行多类别目标检测中合理但裂缝检测通常只有crack一个类别开与不开差异不大。如果你的项目里同时包含crack、spalling、rebar_exposed多个类别并且两个类别在图像位置上高度重叠建议开启--agnostic-nms让模型在 NMS 阶段只保留一个最有把握的框避免桥梁裂缝和混凝土剥落被同时框出。python detect.py --weights runs/train/exp/weights/best.pt \ --source data/images/val \ --conf-thres 0.35 \ --iou-thres 0.45 \ --save-txt \ --save-conf参数说明--save-txt会把每个检测框的类别、归一化坐标和置信度写入runs/detect/exp/labels下的 txt 文件--save-conf决定 txt 中是否保留置信度数字。这一步对后续做热力图分析很有用不要省略。4. 路面桥梁裂缝数据集的标注与组织4.1 裂缝图像从哪里收集以及标注到什么程度路面桥梁裂缝检测项目最耗时的是数据准备。公开数据集多是欧洲和日本的桥梁裂缝图与国内路面材料、光照条件差别明显迁移效果有限。所以实际工程里通常会用无人机、行车记录仪或病害采集车拍摄目标路段的图像然后按 6:2:2 或 7:2:1 划分训练集、验证集和测试集。标注裂缝时不要试图框住整条断裂带尤其是几十厘米长的贯穿裂纹。较好的策略是沿裂纹走向用有方向的框分段标注每段长度控制在图像宽度的 10% 到 30% 之间。这样做有两个原因第一YOLOv5 的锚框都是水平矩形长宽比无限大时会造成大量无效锚点第二模型学的是局部裂纹纹理而不是“完整裂缝”的宏观形状。如果你标注的是白色虚线框训练后模型在推理时也能输出多个连续小框后续通过坐标排序再拼接成完整病害比一次性预测整条裂纹稳定得多。4.2 目录结构与 YAML 配置文件的严格约束YOLOv5 对数据集的目录结构要求非常死板训练时只会去train和val指定的路径下找图像和标签。最常见的报错是“No labels found in 某路径”根本原因是labels目录没有和images目录平级或者标签文件名与图像文件名不一致。下面是一个能直接跑通的目录结构bridge_crack/ ├── images/ │ ├── train/ │ │ ├── crack_001.jpg │ │ └── crack_002.jpg │ └── val/ │ ├── crack_010.jpg │ └── crack_011.jpg ├── labels/ │ ├── train/ │ │ ├── crack_001.txt │ │ └── crack_002.txt │ └── val/ │ ├── crack_010.txt │ └── crack_011.txt └── bridge_crack.yamlbridge_crack.yaml的内容如下path: ../bridge_crack train: images/train val: images/val nc: 1 names: 0: crackpath是相对于数据集根目录的路径train和val是相对path的目录。nc为类别数这里是单类别crack。如果你的项目里还包含网状裂缝、横向裂缝、纵向裂缝建议在names里分别定义为0: crack_web、1: crack_transverse、2: crack_longitudinal不要用同一个标签混在一起训练否则模型会陷入类别模糊。4.3 标签文件格式与数据清洗技巧YOLOv5 的标签是.txt每行五个数字类别索引、归一化中心点 x、归一化中心点 y、归一化宽 w、归一化高 h。全部数值都在 0 到 1 之间。用 LabelImg 或 X-AnyLabeling 导出的 VOC XML 格式需要转换最容易漏的是“宽高必须是真实标注宽高除以图像宽高”这一步。import os def convert_voc_to_yolo(xml_file, out_file, image_w, image_h): import xml.etree.ElementTree as ET tree ET.parse(xml_file) root tree.getroot() with open(out_file, w, encodingutf-8) as f: for obj in root.findall(object): cls obj.find(name).text if cls ! crack: continue bndbox obj.find(bndbox) xmin float(bndbox.find(xmin).text) ymin float(bndbox.find(ymin).text) xmax float(bndbox.find(xmax).text) ymax float(bndbox.find(ymax).text) x_center (xmin xmax) / 2 / image_w y_center (ymin ymax) / 2 / image_h width (xmax - xmin) / image_w height (ymax - ymin) / image_h f.write(f0 {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}\n)代码逻辑说明该脚本先把 XML 里的左上角和右下角坐标相加除以 2 得到中心点再分别除以图像宽高完成归一化。这里有个坑是很多标注工具的坐标系是左上角为原点但 YOLOv5 的归一化中心点默认也在图像左上角为原点的坐标系下所以不需要额外翻转 y 轴。转换完成后再用一行命令检查哪些框宽高为零awk -F $40 || $50 {print FILENAME} labels/train/*.txt执行结果会打印出所有包含非法框的标签文件。这类问题一旦混进训练集轻则训练 loss 不收敛重则训练中断报RuntimeError: invalid argument 0。5. YOLOv5 训练命令、超参数调优与评估5.1 第一次训练跑通的最小命令训练之前先确定预训练权重。裂缝检测的图像与 COCO 数据集差异较大但仍建议使用 COCO 上预训练的yolov5s.pt。迁移学习会让网络前几层的边缘、纹理提取能力直接复用比随机初始化更快收敛。命令如下python train.py --data bridge_crack.yaml \ --weights yolov5s.pt \ --img 640 \ --batch-size 16 \ --epochs 50 \ --device 0 \ --project runs/train/bridge_crack参数含义--img 640将训练图像统一缩放到 640×640--batch-size 16取决显存大小--device 0指定第一张 GPU。如果显存不足优先降低batch-size其次降低--img不要同时调低二者否则训练出来的模型对高分辨率裂缝图像效果会很差。执行后终端会显示每个 epoch 的 Box Loss、Cls Loss、DOL Loss 以及 mAP0.5。第一次训练重点不是把 mAP 拉到最高而是确认 loss 在稳步下降。如果前十个 epoch 的 loss 像锯齿形跳动很大先检查学习率不要急着加训练轮数。5.2 YOLOv5 超参数文件怎么改YOLOv5 把学习率、数据增强系数单独放在data/hyps/hyp.scratch-low.yaml中。裂缝检测项目里我最常改的是三个lr0、warmup_epochs和mosaic。默认lr0: 0.01对大多数目标检测任务够用但裂缝背景复杂、目标占比小初始学习率太大会让梯度在裂缝边缘区域震荡。我一般改成lr0: 0.005并在前 5 个 epoch 用warmup_epochs: 5.0预热等模型对裂缝的纹理特征有初步响应后再全速优化。超参数默认值裂缝检测建议值影响lr00.010.003 - 0.005控制前期收敛速度过大会导致边界框抖动momentum0.9370.9 - 0.937影响梯度平滑程度warmup_epochs3.05.0让模型先适应裂缝的特殊纹理mosaic1.0根据数据量决定数据量少时开满超过 2 万张可降为 0.8fliplr0.50.5 - 0.8裂缝方向随机翻转提升泛化能力# hyp.crack.yaml 片段 lr0: 0.004 lrf: 0.2 momentum: 0.92 warmup_epochs: 5.0 mosaic: 0.9 fliplr: 0.6 hsv_h: 0.02 hsv_s: 0.6 hsv_v: 0.3改完超参数后在训练命令中追加--hyp hyp.crack.yaml即可生效。这里有一个容易忽略的点hsv_h不要改得太大。桥梁裂缝图像中有些裂缝会呈现淡黄色或棕色色调偏移过大会把裂缝颜色改成与路面背景几乎一致的灰色反而降低模型判断能力。5.3 用 val.py 看结果截图和混淆矩阵训练完成后runs/train/bridge_crack/exp/目录下会生成confusion_matrix.png、results.png、val_batch*_pred.jpg和weights/best.pt。results.png里包含训练和验证的 P、R、mAP 曲线而val_batch*_pred.jpg则是验证集的可视化结果截图能直接显示模型在真实路面桥梁图像上的预测框。python val.py --data bridge_crack.yaml \ --weights runs/train/bridge_crack/exp/weights/best.pt \ --img 640 \ --conf-thres 0.001 \ --iou-thres 0.6 \ --task val \ --save-json--conf-thres 0.001是评估阶段常用的小技巧目的是让低置信度预测也参与 mAP 计算更客观反映模型整体表现。--save-json会生成 COCO 格式的模型评估结果方便用其他工具做进一步分析。我在实际项目里尤其关注验证集上的 Recall路面裂缝漏检比误检危险如果 Recall 低于 85%优先回到数据层面增加多尺度裂缝样本而不是继续调 NMS 参数。6. 推理结果截图、模型导出与 .zip 项目归档技巧6.1 批量推理并自动生成结果截图交付时结果截图不能只在终端里运行一次detect.py那样只保存最后一张图片。更稳妥的方法是写一个批量脚本循环读取验证集所有图像用模型输出预测框后用 OpenCV 把框和置信度画到原图上再按编号保存到results/crack_results/目录。这样生成的截图适合直接放进文档说明里。import cv2 import torch import glob model torch.hub.load(./, custom, pathruns/train/bridge_crack/exp/weights/best.pt, sourcelocal) model.conf 0.35 model.iou 0.45 for img_path in glob.glob(data/images/val/*.jpg): img cv2.imread(img_path) results model(img) boxes results.xyxy[0].cpu().numpy() for x1, y1, x2, y2, conf, cls_id in boxes: label fcrack {conf:.2f} cv2.rectangle(img, (int(x1), int(y1)), (int(x2), int(y2)), (0, 0, 255), 2) cv2.putText(img, label, (int(x1), int(y1) - 6), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 255), 2) out_path img_path.replace(images/val, results/crack_results) cv2.imwrite(out_path, img)代码逻辑说明脚本先加载本地best.pt权重然后遍历验证集每张图把xyxy格式的边界框和置信度绘制在图像右上角最后写到新的结果目录。model.conf和model.iou是在 PyTorch Hub 接口下直接控制推理阈值等价于命令行里的--conf-thres和--iou-thres。6.2 导出 ONNX 部署到边缘设备如果要把裂缝识别模型部署到树莓派 5 或 Jetson 这类边缘设备YOLOv5 的 PyTorch 模型直接推理速度很慢常见做法是导出成 ONNX再用 ONNX Runtime 或 TensorRT 运行。python export.py --weights runs/train/bridge_crack/exp/weights/best.pt \ --include onnx \ --img 640 \ --simplify--simplify会调用 onnx-simplifier 重构计算图去掉一些冗余节点。导出完成后用onnxruntime加载模型时需要处理输入输出的名字YOLOv5 的 ONNX 输出形状通常是[1, 25200, 85]其中 85 等于 5 个边界框属性加 80 个 COCO 类别数。如果你只训练了一个crack类别需要把模型输出通道改成 1 5 的结构否则导出后推理结果无法解析。6.3 .zip 交付时文档、模型和结果截图的组织顺序最后交付的.zip不是把整个训练目录塞进去就行而是要让人照着 README 能一步步复现。我会按四层结构组织code/放源码和训练脚本weights/放best.pt和last.ptdocs/放文档说明results/放验证集结果截图和测试集输出。文档说明里必须写清楚训练命令、数据集目录结构和每个参数能让 mAP 提高多少。这项工程化整理虽然不直接提升算法指标但能够避免一个很常见的问题接手的人不知道你用的hyp.crack.yaml和默认超参数差在哪导致复现结果完全不一致。结果截图也统一放在results/下并在 README 中标注每张图对应的图片名称和检测置信度这样即使推理代码环境变化交付方也能通过对比截图来验证模型行为是否一致。本文还有配套的精品资源点击获取