简介：这是一份基于Python与YOLOv5实现的路面桥梁裂缝检测识别项目，面向计算机相关专业正在完成毕业设计、课程设计或期末大作业的学生，也适合需要YOLOv5实战练习的学习者。项目提供完整可运行的源代码与预训练模型，评审得分99分，能够直接用于路面裂缝、桥梁表面缺陷等目标的检测识别任务。资源包共85个文件，压缩包约1.6MB，主要包含Python源码（如模型定义、检测脚本、工具模块）、23个YAML配置文件（涉及模型结构、训练超参与数据集设置）、Shell脚本（用于自动下载权重）、以及示例图片等，便于对照模型效果与理解配置流程。目前已累计80人学习，说明具备一定的参考价值。通过这份资料，读者可以获得YOLOv5目标检测的完整落地思路：从数据集配置、模型构建、训练调参到图片/摄像头检测均有涵盖，目录结构清晰，有助于高效复现与二次开发。
1. 路面桥梁裂缝检测，为什么我推荐直接用这份 YOLOv5 源码
做过施工质检或者道路巡检相关项目的朋友应该深有体会：裂缝检测这种任务，看着简单，真做起来全是坑。传统图像处理用 Canny 边缘检测或者形态学滤波，晴天还好，一到阴天、有阴影、路面有油渍，误检率能高到没法看。而基于 Python 的 YOLOv5 目标检测方案，本质上是把裂缝当作一种目标框出来，而不是靠灰度阈值硬切，泛化能力完全不在一个量级。
这份毕业设计资源我拆过之后可以负责任地说，它不只是拿来交作业的，代码完整、模型权重齐全，从训练到推理的闭环全都有。它解决的不只是"有没有裂缝"的二分类问题，而是把每条裂缝的位置、大小、走向都能框出来，对后续的裂缝宽度测量、严重程度分级都有直接帮助。适合三类人：正在做毕设的计算机相关专业学生、想练手 YOLOv5 工程落地的新手、以及有道路或桥梁检测需求但不想从零写网络的从业者。
2. 项目结构先摸清：这套代码里到底藏了哪些东西
2.1 从目录反推设计思路
把压缩包解压之后，我习惯先不看 README，直接看目录结构。这份资源走的是典型的 YOLOv5 官方仓库风格，但做了裁剪和定制，目录结构大致是：
├── detect_photo.py # 单张图片检测脚本，日常测试最常用 ├── detect_camera.py # 摄像头实时检测脚本，接 USB 摄像头即可 ├── data/ │ ├── coco128.yaml # COCO 数据集配置 │ ├── coco.yaml # 完整 COCO 配置 │ └── voc.yaml # VOC 格式数据集配置 ├── models/ │ ├── yolov5s.yaml # 小模型结构 │ ├── yolov5m.yaml # 中等模型结构 │ ├── yolov5l.yaml # 大模型结构 │ ├── yolov5x.yaml # 超大模型结构 │ ├── common.py # 网络通用模块 │ ├── yolo.py # YOLOv5 核心检测逻辑 │ └── export.py # 模型导出脚本，可转 ONNX/TorchScript ├── weights/ # 训练好的模型权重，配合 download_weights.sh 使用 ├── runs/ # 训练和检测的输出目录 ├── scripts/ │ └── hubconf.py # 模型加载辅助脚本 ├── utils/ │ ├── datasets.py # 数据集加载与增强逻辑 │ ├── loss.py # 损失函数 │ ├── metrics.py # 评估指标 │ ├── general.py # 通用工具函数 │ └── autoanchor.py # 自动计算 anchor 的脚本 └── requirements.txt # 依赖清单这套结构本身就是一个标准的 YOLOv5 分层逻辑：models负责网络定义，utils负责训练和推理的辅助功能，data管数据集配置，detect_*.py是不同场景下的入口脚本。runs目录用来存放每次训练和检测的日志、权重和结果图片，这个设计对迭代实验特别友好——我自己的项目里也沿用这个习惯，每次跑完模型，输出都自动按时间戳归档，不会互相覆盖。
2.2 detect_photo.py 和 detect_camera.py 的分工逻辑
这两个入口脚本是拆包的钥匙，一个是静态推理，一个是动态推理，它们的定位差异很重要。
detect_photo.py是最常用的入口，核心逻辑是这样的：
import torch import cv2 import os # 加载训练好的模型权重 model = torch.hub.load('.', 'custom', path='weights/best.pt', source='local') def detect_image(img_path, conf_thres=0.25, iou_thres=0.45): # 读取图片并转为 RGB，YOLOv5 训练时用的是 RGB 输入 img = cv2.imread(img_path) img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # 模型推理，返回检测结果 results = model(img_rgb, size=640) # 解析结果：坐标、置信度、类别 boxes = results.xyxy[0].cpu().numpy() # x1, y1, x2, y2, conf, cls for box in boxes: x1, y1, x2, y2, conf, cls = box if conf > conf_thres: # 在图上画矩形框和置信度 cv2.rectangle(img, (int(x1), int(y1)), (int(x2), int(y2)), (0, 255, 0), 2) label = f'crack {conf:.2f}' cv2.putText(img, label, (int(x1), int(y1) - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2) # 保存结果到 runs/detect 目录 os.makedirs('runs/detect', exist_ok=True) save_path = os.path.join('runs/detect', os.path.basename(img_path)) cv2.imwrite(save_path, img) print(f'检测完成，结果保存至 {save_path}') if __name__ == '__main__': detect_image('test.jpg', conf_thres=0.3, iou_thres=0.5)这里重点说明几个参数。conf_thres是置信度阈值，低于这个值的检测框会被过滤掉，裂缝检测场景我一般建议设 0.25 ~ 0.3，因为这个数据集的背景复杂度高，阈值设太高容易漏检细裂缝；iou_thres是 NMS 的 IoU 阈值，控制重叠框的合并力度，裂缝这种细长目标偶尔会出现多个框套同一个物体的情况，0.45 是个比较稳的取值。size=640是输入分辨率，YOLOv5 默认训练尺寸就是 640，改大能提升小裂缝的检出率，但显存占用和推理时间也会线性上涨。
import cv2 import torch def detect_camera(source=0, conf_thres=0.25): # 加载同一套模型权重 model = torch.hub.load('.', 'custom', path='weights/best.pt', source='local') # 打开摄像头，0 表示默认摄像头 cap = cv2.VideoCapture(source) while True: ret, frame = cap.read() if not ret: break # 推理当前帧 results = model(frame, size=640) # 渲染检测结果到画面 rendered = results.render()[0] # 显示实时画面 cv2.imshow('Crack Detection', rendered) # 按 q 退出 if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()这个摄像头推理脚本的思路是"边读帧边检测"，用cv2.VideoCapture循环读帧，每一帧传入模型推理，然后results.render()把检测框直接画到图上。需要注意的一个点是：render()返回的是带标注的新图像，不会修改原始帧，所以内存管理上比较干净。在实景测试时，如果摄像头画面卡顿，优先检查是不是推理速度跟不上帧率，而不是摄像头的问题。
3. 模型与数据配置：YOLOv5 的几个关键选择
3.1 用哪个 backbone：s/m/l/x 的选型逻辑
这套代码里models目录下有四个网络结构文件，对应 YOLOv5 的四个规模版本。它们的区别主要体现在深度和宽度两个维度：
| 模型 | 参数量 | 推理速度(V100) | 精度(mAP) | 适用场景 |
|---|---|---|---|---|
| YOLOv5s | 7.2M | 2.4ms | 37.4 | 低显存、边缘设备 |
| YOLOv5m | 21.2M | 3.2ms | 45.4 | 中等算力，平衡方案 |
| YOLOv5l | 46.5M | 4.6ms | 49.0 | 服务器推理，追求精度 |
| YOLOv5x | 86.7M | 6.9ms | 50.7 | 离线高精度场景 |
对裂缝检测来说，我的真实经验是：如果用的是 GTX 1060 或者 1650 这种 4G 显存的卡，YOLOv5s 是唯一的现实选择——YOLOv5m 虽然精度更高，但 batch size 稍微调大一点就直接 OOM；如果显存 8G 以上，YOLOv5m 是"精度和训练时间"的最优解。另外还要看训练数据量，数据量不足 500 张时，上大模型几乎是必过拟合的，小模型反而泛化更好。
3.2 数据集 YAML 配置和 anchor 调优
data/目录下的 YAML 文件是训练时告诉模型"去哪里找数据、数据是什么结构"的入口。我拆包后看到有coco128.yaml、coco.yaml和voc.yaml，说明这套代码支持 COCO 和 VOC 两种格式的数据集标注。如果自己标注数据，一般推荐转成 YOLO 格式，因为 YOLOv5 原生读 YOLO 格式最方便。
# data/coco128.yaml 简化后的配置示例 train: ./data/coco128/images/train/ # 训练集图片路径 val: ./data/coco128/images/val/ # 验证集图片路径 nc: 1 # 类别数量，这里是 1，裂缝就一类 names: ['crack'] # 类别名称列表nc和names是必须和你的数据对应的两个字段——我们做裂缝检测，如果只分"裂缝"一类，就把nc写成 1，names列表里只写crack；如果想区分"横向裂缝"和"纵向裂缝"，就得改成nc: 2和['transverse', 'longitudinal']。train和val路径既可以是绝对路径，也可以是相对于项目根目录的相对路径，建议用相对路径，换机器跑的时候不会因为路径问题翻车。
anchor 的设置是另一个新手容易忽略的点。YOLOv5 的utils/autoanchor.py会在每次训练开始前自动计算当前数据集的最优 anchor 尺寸。但如果数据集的标注框分布很极端——比如裂缝框特别长、特别窄——默认的自动计算可能不够准。这时候可以手动跑一次：
python utils/autoanchor.py --data data/voc.yaml --img 640这个脚本会重新聚类出与当前数据集最匹配的 anchor 尺寸，并把建议值写进模型配置文件。我一般会在训练大模型前跑一次，然后把结果手动更新到models/yolov5s.yaml的anchors字段里。注意：autoanchor 给出的值是基于当前数据集标注框的统计特征，换数据集必须重新跑，直接沿用官方预训练模型的 anchor 不一定是最优的，实测对裂缝这类细长目标影响最多能差 2~3 个点的 mAP。
4. 复现训练：从零开始跑通自己的裂缝检测模型
4.1 环境搭建的完整路径
先说环境，这套代码对 Python 版本有硬性要求——YOLOv5 官方要求 Python 3.8 以上，实际测试 3.8 和 3.9 最稳，3.10 会踩到一些依赖兼容的坑。完整流程如下：
# 1. 创建独立虚拟环境，避免污染系统 Python conda create -n yolov5 python=3.9 -y conda activate yolov5 # 2. 安装 PyTorch，CPU 版和 GPU 版选一个 # GPU 版（需要先安装 CUDA 驱动和 cuDNN） pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 3. 安装项目依赖 cd 项目根目录 pip install -r requirements.txt关于 PyTorch 版本的选用，一个血泪经验：YOLOv5 的源码对 torch 版本有兼容范围，太新的版本有时会报torch.utils.tensorboard或者torchvision.ops.nms的 API 变更错误。项目配套里如果指定了版本就严格按指定的装；没指定的话，torch 1.13 或 2.0 这代版本兼容性最好，不要一上来就装 2.3 以上的版本。
验证环境是否装好，跑一段最小推理测试：
import torch # 检测 GPU 是否可用 print(torch.cuda.is_available()) # 输出 True 说明 GPU 可用 # 打印 CUDA 版本和 GPU 名称 if torch.cuda.is_available(): print(torch.cuda.get_device_name(0)) print(torch.version.cuda)torch.cuda.is_available()返回False的话，后面训练直接变成"龟速模式"——一个 300 张图的裂缝数据集在 CPU 上可能要跑 4 个小时，GPU 上 20 分钟搞定。没有 GPU 环境的话建议上 Colab 或者租云 GPU 实例，别硬扛。
4.2 预训练权重下载与模型加载路径
这套代码自带download_weights.sh，作用是把 YOLOv5 官方在 COCO 上预训练好的权重拉下来。这个脚本很关键——不是因为它能省训练时间，而是因为加载 COCO 预训练权重做迁移学习，是在小数据集上拿到高精度的重要前提。
# 给脚本添加执行权限 chmod +x download_weights.sh # 执行，下载 YOLOv5s 预训练权重 ./download_weights.sh # 或者直接命令行下载指定模型 python -c "import torch; torch.hub.load('ultralytics/yolov5', 'yolov5s')"上面的脚本会先把 COCO 预训练权重下到本地，然后把权重文件放到weights/目录。用迁移学习的原因很朴素：YOLOv5 的 backbone 在 COCO 上见过 80 类物体的纹理、边缘、形状特征，裂缝虽然不在 COCO 类别里，但边缘纹理的底层特征是可迁移的。从上千万张图里学过的特征提取器，再拿来学裂缝，只需要微调后面几层就行——这能在数据量很小的情况下有效防止过拟合。
训练脚本的标准调用方式如下：
python train.py --data data/voc.yaml --weights weights/yolov5s.pt --batch-size 16 --epochs 100 --img 640关键参数说明：
--weights：预训练权重路径，不传就用随机初始化，同样的 epoch 数，最终 mAP 可能会差 10 个点以上。--batch-size：由显存容量决定，3060 显卡 12G 显存可以上到 32，1660 这种 6G 卡就乖乖用 16。--epochs：裂缝检测数据集通常 100~150 个 epoch 足够，超过之后 loss 就不再下降了，纯浪费时间。--img 640：和训练数据的输入尺寸一致，如果数据集里的裂缝很小，可以改成 960，但对显存压力更大。
训练过程中要盯日志里三个关键指标：box_loss（框坐标回归损失，持续下降是正常的）、cls_loss（分类损失，趋近于 0 说明分类已经学会）、mAP@0.5（泛化性能最直观的指标）。训练结束后，runs/train/目录下会生成weights/best.pt和weights/last.pt，前者是验证集上表现最好的权重，后者是最后一个 epoch 的权重——部署推理时一定用best.pt，不要用last.pt。
4.3 用自己训练的权重做推理验证
训练完成后，把 back 最好权重替换掉推理脚本里原来加载的路径：
python detect_photo.py --weights runs/train/exp/weights/best.pt --source 测试图片.jpg跑完之后去runs/detect/里翻结果，需要重点检查两类错误：一是该检测的裂缝没检出来（漏检），二是把阴影、路面接缝、水渍误判成裂缝（误检）。如果发现漏检多，优先考虑降低conf_thres；如果误检多，就升高conf_thres。这是一个典型的精度-召回率权衡问题，没有绝对的"正确参数"，要在自己的验证集上反复试。
5. 避坑指南：训练和推理中的四个典型翻车现场
5.1 现象：训练刚开始就报CUDA out of memory
这是出镜率最高的问题。一上来直接跑默认的--batch-size 32 --img 640，结果连第一个 epoch 都撑不住就崩了。原因很简单：batch size 超出显存容量，YOLOv5 在 forward 阶段要同时保存整个 batch 的中间特征图。
解决方法是逐步缩小配置，直到能跑起来：
# 先试 batch-size 8 python train.py --data data/voc.yaml --weights weights/yolov5s.pt --batch-size 8 --img 640 # 还不行就同时降分辨率和 batch size python train.py --data data/voc.yaml --weights weights/yolov5s.pt --batch-size 4 --img 480另外一个容易被忽视的技巧是启用梯度累积：--batch-size 8 --accumulate 4，相当于每 16 张图才更新一次梯度，效果约等于 batch size 16，但显存占用只是 8 的水平。
5.2 现象：训练 loss 不下降，一直徘徊在某个值附近
先排除一个低级错误：确认 label 文件没有全空或者类别编号越界。YOLO 格式的标签文件是纯文本，每个标注框一行：class_id x_center y_center width height，坐标是相对于图片宽高的归一化值。如果某张图的 label 文件是空的，模型在这张图上就没有学习信号。
另一个常见原因是学习率设置不当。YOLOv5 默认从0.01起步，配合 cosine 学习率调度。如果发现 loss 在 5 个 epoch 内纹丝不动，可以尝试调低--lr0到0.001，这种问题在自定义数据集上出现频率真的不低。
5.3 现象：训练集精度很高，验证集精度非常差
这是典型的过拟合信号。裂缝数据集往往存在一个通病：训练图片很多来自同一个桥梁或同一段路面，背景纹理高度重复，模型很容易"记住背景"而不是"学会裂缝"。应对手段有两条路：
数据增强是首选，YOLOv5 默认开启 mosaic、flip、hsv 增强，对数据量少的情况帮助很大：
# data/hyps/hyp.scratch.yaml 中提高增强强度 hsv_h: 0.02 # 色调增强 hsv_s: 0.7 # 饱和度增强 hsv_v: 0.5 # 亮度增强 flipud: 0.0 # 上下翻转概率，路面裂缝场景建议不开 fliplr: 0.5 # 左右翻转概率 mosaic: 1.0 # mosaic 增强其中hsv_v: 0.5值得重点注意——室外采集的路面裂缝图片，光照变化很大，把亮度增强开到 0.5 相当于在训练时"模拟"不同光照条件，对提升泛化能力很有帮助。flipud在路面场景不建议开，因为路面裂缝存在方向性，上下翻转会让模型学到错误的方向特征。
如果数据增强后验证集精度仍然上不去，就要考虑换更强的正则化：把--dropout加上，或者干脆换更小的模型（从 m 换到 s）。
5.4 现象：摄像头推理时卡顿明显，画面像幻灯片
当detect_camera.py的推理时间大于帧间隔时，视频流就会明显卡顿。首先要搞清楚瓶颈在哪：是模型推理慢，还是图像预处理占了时间。用简单的计时工具就能定位：
import time # 在 detect_camera.py 中加计时 start = time.time() results = model(frame, size=640) end = time.time() print(f'单帧推理耗时: {end - start:.3f}s')如果单帧耗时超过 0.3 秒（即帧率低于 3FPS），必须先做模型压缩，优先考虑--img 320降低输入分辨率。如果降到 320 后帧率仍然不达标，可以考虑转 ONNX 后用 ONNXRuntime 推理，速度提升在 20%~40% 左右：
python models/export.py --weights weights/best.pt --include onnx --img 6406. 进阶用法：模型裁剪、TensorRT 加速与按需改造
6.1 把检测置信度热力输出变成"裂缝严重程度"分级
很多人做完裂缝检测就停了，但实际工程里，"有没有裂缝"只是第一步，还需要判断"这条裂缝严不严重"。这个需求不用重训网络，直接在推理阶段做后处理逻辑就能实现：
def severity_grade(results, max_len_pixel=640, min_conf=0.3): """ 按检测框尺寸和置信度给裂缝定级 """ boxes = results.xyxy[0].cpu().numpy() grades = [] for box in boxes: x1, y1, x2, y2, conf, cls = box if conf < min_conf: continue # 计算裂缝长度（对角线长度近似） length = ((x2 - x1) ** 2 + (y2 - y1) ** 2) ** 0.5 # 归一化到图片尺寸比例 length_ratio = length / max_len_pixel if length_ratio < 0.1: grades.append('轻度') elif length_ratio < 0.25: grades.append('中度') else: grades.append('重度') return grades这个函数的思路是"以检测框的对角线长度近似裂缝长度"，然后按比例分三档。实际使用中可以根据场景调整阈值——对桥梁这种重要结构，阈值要更敏感；对普通路面，可以放宽一些。除了长度，还可以把框的宽度（裂缝宽度）加入判断：裂缝宽度越大，通常说明路面结构损伤越严重。这些判断逻辑不必改网络结构，在输出端加一层规则即可。
6.2 TensorRT 加速：把推理速度提到 3 倍以上
如果部署设备是 Jetson Nano、TX2 这种边缘设备，光换 ONNX Runtime 还不够。实测过同样一个 YOLOv5s 模型，在 1080Ti 上用 TensorRT FP16 推理，单帧耗时能从 8ms 降到 3ms 以内。转换流程如下：
# 第一步：先导出 ONNX python models/export.py --weights weights/best.pt --include onnx --img 640 # 第二步：用 trtexec 把 ONNX 转成 TensorRT 引擎 /usr/src/tensorrt/bin/trtexec --onnx=weights/best.onnx --saveEngine=weights/best.engine --fp16TensorRT 引擎文件是硬件相关的，在 A 机器上生成的.engine拿到 B 机器上不一定能跑，这是新手最容易忽略的坑。每次换设备部署，都要在新设备上重新走一遍转换流程，不能直接拷贝。
转完后推理代码也要换，推理方式完全不同，用 TensorRT Python API 加载引擎：
import tensorrt as trt import numpy as np # 加载 TensorRT 引擎 def load_engine(engine_path): runtime = trt.Runtime(trt.Logger(trt.Logger.WARNING)) with open(engine_path, 'rb') as f: engine = runtime.deserialize_cuda_engine(f.read()) return engine # 推理前需要把输入输出都转成固定 dtype 的数组 # 输入 [1, 3, 640, 640] float32，输出 [1, 25200, 6]TensorRT 的优化底层逻辑是四点：层融合（把 Conv+BN+ReLU 合并成一个算子）、精度校准（FP16 下用 KL 散度找最佳量化范围）、显存复用（减少显存分配次数）、kernel auto-tuning（为每个算子选最优 CUDA 实现）。对深度学习部署而言，特别是对算力有限的边缘设备，这个优化效果非常直观。
6.3 数据增强策略的深度调优
回到训练侧再补一个技巧：裂缝检测的特殊性在于裂缝是"细线状"目标，常规的随机裁剪很容易把裂缝切到图片边缘甚至切没。YOLOv5 的 mosaic 增强在处理细长目标时不是最优解，我一般会在训练参数里调低 mosaic 概率，同时配合额外的旋转增强：
# hyp.finetune.yaml 中的针对性调整 mosaic: 0.3 # 降低 mosaic 概率，减少细长目标被切碎的概率 degrees: 15.0 # 随机旋转 ±15 度，模拟不同拍摄角度 translate: 0.1 # 平移增强 scale: 0.4 # 缩放增强旋转角度degrees: 15.0对桥梁裂缝这类方向性目标很关键——桥梁上的裂缝往往垂直于受力方向，但如果拍摄角度偏了，模型需要旋转不变性。注意旋转不能无限加大，超过 45 度会让细长目标变形得不像真实裂缝。这类超参数调整没有绝对标准，建议每次改完跑一个完整训练对比 mAP，用数据说话，别凭感觉。我从那以后每次训练前都会强制走一遍数据可视化验证，抽查增强后的图片有没有把裂缝切碎或者变形过头——一张一张看训练集的增强样本大概花十分钟，但能省下一次四小时的无效训练，这笔账怎么算都划算。希望帮到你。
本文还有配套的精品资源，点击获取
