简介面向计算机专业毕业设计场景的路面与桥梁裂缝检测项目基于Python与YOLOv5实现目标检测适合需要完成课程设计、期末大作业或入门YOLO实战的学生。项目代码经过完整调试配有模型权重与推理/训练脚本可直接运行并观察检测效果。资源包共85个文件核心为py、yaml、pyc三类。py代码负责模型构建、训练与检测流程yaml提供网络与数据配置pyc为编译缓存另含sh下载脚本、jpg/png等示例图片与Dockerfile便于环境部署。压缩包整体约1.6MB结构紧凑覆盖从数据配置到模型导出的常见环节。目前已有77人学习下载。下载后可获得可复现的YOLOv5裂缝识别流程、模型文件、数据组织参考及部署提示适合作为毕业设计主体功能演示或项目实战练习的起点。1. 路面桥梁裂缝检测这套 YOLOv5 项目能直接跑通吗路面裂缝检测这个毕业设计选题每年都有一批人栽在同一个地方数据集找了一堆标注格式对不上训练跑到一半显存爆掉最后导师问起来只能说“代码能跑但效果不行”。这套基于 Python YOLOv5 的裂缝检测项目把源码、预训练模型、数据配置和训练脚本收在一个压缩包里评审 99 分代码是完整可运行的那种不是半成品。它适合两类人一类是计算机相关专业正在做毕业设计、课程设计或期末大作业的学生需要一套能讲清原理、能改参数、能复现结果的项目另一类是刚接触目标检测的开发者想用一套完整流程把 YOLOv5 跑通再往自己的数据集上迁移。下文按我从下载到复现的真实路径把环境、数据、训练和排查逐层拆开全文没有需要“再做一步”的隐藏步骤。2. 拆解 YOLOv5 源码结构从 detect 脚本到模型文件一条完整的检测流水线2.1 项目根目录每个文件夹是干什么的先分清主次打开压缩包第一眼会被一堆文件和目录吓到实际上真正核心的就五块models/放模型结构定义utils/放训练和推理的工具函数data/放数据集配置和超参数根目录的detect_photo.py和detect_camera.py是推理入口weights/放预训练权重和下载脚本。搞清楚这几块后面的操作才不会迷路。. ├── weights/ # 预训练权重目录 │ └── download_weights.sh # 批量下载官方预训练权重的脚本 ├── data/ # 数据配置与超参数 │ ├── coco.yaml # COCO 数据集的类别与路径配置 │ ├── coco128.yaml # 小规模 COCO 子集用于快速验证 │ ├── voc.yaml # VOC 格式数据集配置 │ ├── hyp.scratch.yaml # 从零训练的超参数 │ └── hyp.finetune.yaml # 微调阶段的超参数 ├── models/ # 模型结构定义 │ ├── yolov5s.yaml # small 版本速度最快 │ ├── yolov5m.yaml # medium 版本速度和精度均衡 │ ├── yolov5l.yaml # large 版本精度优先 │ ├── yolov5x.yaml # xlarge最重 │ ├── yolo.py # Detect 头与模型组装逻辑 │ ├── common.py # Conv、Bottleneck、SPP 等基础模块 │ └── experimental.py # 实验性模块 ├── utils/ # 工具函数 │ ├── datasets.py # 数据加载与增强 │ ├── loss.py # 损失函数计算 │ ├── autoanchor.py # 自动计算最佳锚框 │ ├── general.py # 通用工具包含检查环境依赖 │ ├── metrics.py # mAP、PR 曲线等评估指标 │ ├── plots.py # 绘制训练曲线 │ └── torch_utils.py # 模型保存、加载、设备管理 ├── detect_photo.py # 单张图片/图片目录推理 ├── detect_camera.py # 摄像头实时推理 ├── train.py # 训练入口根目录常用命名 ├── hubconf.py # 供 PyTorch Hub 加载模型 ├── scripts/ # 辅助脚本 └── runs/ # 训练输出目录权重、日志、曲线这套目录沿用了 YOLOv5 官方仓库的经典布局好处是社区资料多遇到问题搜“yolov5 报错关键词”基本都有答案。我拿到项目的第一步不是急着跑而是先看两个文件weights/download_weights.sh和data/hyp.scratch.yaml。前者决定模型能不能加载后者决定训练效果的上限。2.2 detect_photo.py 与 detect_camera.py两种推理入口的差异项目给了两个推理脚本对应两种落地场景。detect_photo.py适合离线批量检测比如给一组桥梁巡检图片跑裂缝识别detect_camera.py适合现场实时检测比如架一个摄像头对着路面拍。两者都调用models/yolo.py里的模型加载逻辑区别只在数据来源和帧处理方式。# detect_photo.py 的核心推理逻辑简化 import torch from models.experimental import attempt_load from utils.general import check_img_size, non_max_suppression # 加载模型权重weights/best.pt 是训练完成后保存的最佳模型 model attempt_load(weights/best.pt, map_locationcpu) model.eval() # 输入图片尺寸会被缩放到 640x640这是 YOLOv5 默认推理尺寸 img_size 640 # 置信度阈值 0.25低于这个值的框会被过滤 conf_thres 0.25 # NMS 的 IoU 阈值 0.45重叠超过这个值的框会被合并 iou_thres 0.45 # 对单张图片做前向推理 results model(img, img_size) # 非极大值抑制去掉重复框 pred non_max_suppression(results, conf_thres, iou_thres)这段代码里真正影响检测效果的是conf_thres和iou_thres。裂缝这种细长目标有个特点同一个裂缝会被模型预测出多个重叠框iou_thres设得太小比如 0.3会导致一条裂缝被拆成好几段设得太大比如 0.7又可能把相邻的两条裂缝合并成一个框。我一般会在 0.4~0.5 之间调。detect_camera.py的逻辑类似只是把img换成摄像头的一帧画面同时加了一个FPS统计方便判断实时性。2.3 模型配置文件与 anchors选 yolov5s 还是 yolov5lmodels/下四个 yaml 文件对应 YOLOv5 的四个体积档位裂缝检测这种任务不需要特别大的模型因为裂缝形态相对固定背景也单一用yolov5s就够。我的选型原则是先用yolov5s把流程跑通确认数据和标注没问题再考虑换yolov5m提精度。模型配置参数量级推理速度适合场景yolov5s.yaml最小最快实时检测、低显存显卡、快速验证yolov5m.yaml中等中等精度和速度均衡多数毕业设计够用yolov5l.yaml较大较慢复杂背景、小目标密集场景yolov5x.yaml最大最慢追求极致精度显存 8G 以上模型配置文件里一个关键部分是 anchors。YOLOv5 在训练时会用utils/autoanchor.py自动重新计算数据集的锚框不需要手动设。但如果你的裂缝图片尺寸和 COCO 数据集差异很大比如全是 4000x3000 的巡检大图我建议在训练前先跑一次 autoanchor把 anchors 适配到你的数据分布上否则小裂缝可能一直检测不到。3. 搭建可复现的 Python 环境conda、依赖与数据准备3.1 conda 环境与 PyTorch 安装没有 GPU 也能跑这套项目依赖 PyTorch 和一堆 Python 包直接往系统 Python 里装容易把环境搞乱。我习惯用 conda 建独立环境每一步都有后悔药。# 创建 Python 3.8 环境yolov5 官方对 3.8 支持最稳 conda create -n crack python3.8 -y conda activate crack # 安装 PyTorch CPU 版本无 GPU 也能训练只是慢 # 如果有 N 卡把 cpu 换成 cu118 就是 CUDA 11.8 版本 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 安装项目依赖requirements.txt 在项目根目录 pip install -r requirements.txt这里有个常见误区requirements.txt里通常包含opencv-python、numpy、matplotlib、pyyaml、tqdm等包如果 pip 安装过程中报错某个包编译失败优先检查 Python 版本是不是太高。Python 3.10 以上容易出现numpy版本不兼容降到 3.8 能避掉大部分玄学问题。没有 GPU 的同学别慌CPU 训练裂缝模型不是不能跑只是慢后面会讲怎么把训练时间压下来。3.2 数据集目录怎么摆images、labels 与 data/*.yaml 的对应关系YOLOv5 的数据集组织方式是 images 和 labels 分离每张图片对应一个同名的 txt 标注文件。裂缝检测的数据集可以自己标注也可以找公开的路面裂缝数据集转成 YOLO 格式。项目里data/coco128.yaml是官方自带的 128 张图片小数据集用来验证环境通不通。# 推荐的数据集目录结构 datasets/ ├── images/ │ ├── train/ # 训练图片 │ └── val/ # 验证图片 └── labels/ ├── train/ # 训练标注txt └── val/ # 验证标注txt标签文件是纯文本每行一个目标格式为class_id x_center y_center width height四个坐标值都是归一化到 0~1 的小数。比如一条裂缝在图片正中间、宽占 0.2、高占 0.05对应的标签行就是0 0.5 0.5 0.2 0.05。这个格式是 YOLO 系模型的通用语言项目里data/voc.yaml的存在意味着你也可以把 VOC 格式的 XML 标注转成 txt转换脚本在utils/datasets.py里有现成的逻辑可参考。拿到项目后第一件事把自己的裂缝图片按上面结构放好然后用data/coco128.yaml当模板改一个自己的 yaml。注意 yaml 里的train和val路径要写绝对路径YOLOv5 对相对路径的支持不太稳定这是我踩过的坑。3.3 下载预训练权重checkpoint 与模型文件的对应weights/目录下的download_weights.sh脚本是用来拉取官方预训练权重的。用预训练权重做初始化比自己从零训练收敛快得多尤其裂缝数据集通常只有几百到几千张图从零训练很容易过拟合。# 进入 weights 目录执行脚本下载官方权重 cd weights bash download_weights.sh # 脚本执行后应有类似下面的文件 # yolov5s.pt # 对应 models/yolov5s.yaml # yolov5m.pt # 对应 models/yolov5m.yaml下载完权重后要记住一个对应关系yolov5s.pt只能搭配models/yolov5s.yaml使用混搭会报结构不匹配的错误。如果网络下载慢可以手动下载对应的.pt文件放进weights/目录文件名必须和models/下的 yaml 前缀一致。训练的时候代码会根据--weights参数加载预训练权重同时根据--cfg参数读模型结构这两个参数必须配对。4. 训练裂缝检测模型命令、超参数与结果验证4.1 一条完整的训练命令从 train.py 到日志输出环境配好、数据放好之后训练命令是整套项目里最值得反复研究的部分。项目根目录的训练入口会读取data/下的 yaml 配置和models/下的结构定义把数据、模型、超参串在一起。# 在项目根目录执行训练自己的裂缝数据集 python train.py \ --weights weights/yolov5s.pt \ --cfg models/yolov5s.yaml \ --data data/crack.yaml \ --hyp data/hyp.scratch.yaml \ --epochs 100 \ --batch-size 8 \ --img-size 640 \ --device 0参数含义逐个说--weights指定预训练权重路径--cfg指定模型结构--data指向你的数据集配置--hyp指向超参数文件--epochs是训练轮数--batch-size是每次迭代的图片数--img-size是输入尺寸--device 0表示用第一块 GPUCPU 训练就改成--device cpu。这段命令跑起来后runs/train/exp目录下会逐步生成weights/best.pt、weights/last.pt、losses.png、results.png等文件。best.pt是验证集上表现最好的模型last.pt是最后一轮的模型最终部署用best.pt。我习惯每 10 轮看一眼results.png如果 loss 在降但 mAP 不动大概率是标注有问题不是模型问题。4.2 超参数调优hyp.scratch.yaml 里的 lr、batch、anchordata/hyp.scratch.yaml是整个项目里最值得手工改的文件。它管着学习率、数据增强强度、损失函数权重等一堆参数。裂缝检测和通用目标检测有个重要区别裂缝是细长条目标占图片面积比例很小默认超参数是为 COCO 这种大目标数据集调的直接照搬效果不会差但也没到最好。# hyp.scratch.yaml 关键参数示意 lr0: 0.01 # 初始学习率训练不稳定时降到 0.005 lrf: 0.2 # 学习率最终衰减到初始值的 0.2 倍 momentum: 0.937 # SGD 动量 weight_decay: 0.0005 # 权重衰减防过拟合 warmup_epochs: 3.0 # 前 3 轮 warmup学习率从 0 逐渐升到 lr0 box: 0.05 # 框回归损失的权重 cls: 0.5 # 分类损失权重 obj: 1.0 # 目标存在性损失权重 hsv_h: 0.015 # 色调随机变化幅度 hsv_s: 0.7 # 饱和度随机变化幅度 hsv_v: 0.4 # 明度随机变化幅度我调参时先动lr0如果训练前 10 轮 loss 震荡不下降把lr0降到 0.005 通常能稳住。batch-size也很关键显存不够就把 batch 调小但 batch 太小会导致 loss 曲线毛刺多我一般会同步把lr0也调小。裂缝检测场景我还会把hsv_s调低一点因为路面和桥梁的颜色本来就灰扑扑的过强的饱和度增强反而让模型学偏。4.3 训练损失曲线怎么读box_loss、obj_loss、cls_loss 各自代表什么训练结束后会生成results.png里面有四张曲线图box_loss是预测框和真实框的位置偏差obj_loss是目标置信度损失cls_loss是分类损失最后一张是 mAP。读懂这四张图就能判断训练有没有问题。# 查看训练结果的曲线图直接用图片查看器打开 open runs/train/exp/results.png # macOS # 或 xdg-open runs/train/exp/results.png # Linux正常情况是三条 loss 曲线都平稳下降mAP 曲线平稳上升。如果box_loss降了但obj_loss一直横着不动说明模型找不到裂缝目标问题在数据标注比如标签文件里坐标全是 0 或者类别 id 写错。如果三条 loss 都在降但 mAP 上不去考虑是否类别不平衡裂缝图里负样本太多要在数据层面加一些完全不包含裂缝的背景图让模型学会“没有裂缝时什么都不框”。5. 避坑手册裂缝检测从训练到部署的五个血泪坑坑 1训练直接报错CUDA out of memory现象执行训练命令后几秒终端直接报显存不足程序退出。原因YOLOv5 默认的 batch-size 是按 COCO 数据集的大图设计的裂缝图片如果分辨率很高比如 4000x3000batch16 会瞬间吃满显存。另外一个隐藏原因是--workers数据加载线程数太高每个线程也会占一部分显存。解决先把--batch-size降到 4 或 2同时把--workers降到 1 或 0。如果显存还很紧张把--img-size从 640 降到 512。注意改小输入尺寸后模型的检测精度会略降但对裂缝这种大目标影响不大属于性价比很高的折中。坑 2label 文件和图片对不上loss 出现 NaN现象训练 loss 值突然变成nan随后模型权重全部损坏无法继续训练。原因标签文件里出现了不合法数值比如坐标值大于 1、宽度或高度为 0、类别 id 超过类别总数。这通常是因为标注工具导出的坐标没做归一化或者有些图片没有对应标签文件。解决写一个脚本扫描所有 txt 标签检查每行是否满足class x_center y_center width height五个字段且所有数值在 0~1 之间class 除外。我一般会在训练前跑一遍这个检查把异常行直接过滤掉避免训练到一半翻车。坑 3训练不收敛loss 曲线像心电图现象loss 曲线上下剧烈震荡训练 50 轮了 mAP 还在 0.1 以下徘徊。原因最常见的是学习率太大YOLOv5 默认lr00.01在 COCO 上没问题但裂缝数据集小模型容易震荡。另一个原因是 batch-size 太小且没同步降低学习率导致梯度估计不稳定。解决把lr0降到 0.001warmup_epochs从 3 提到 5先让模型在小学习率下稳定下来。如果还震荡检查数据增强参数把hsv_h、hsv_s、hsv_v调低 50%减少增强带来的噪声。坑 4模型跑起来了但裂缝框出来是歪七扭八的四边形现象推理结果里裂缝检测框虽然是矩形框但把非裂缝区域也框进去了或者同一个裂缝被反复框了多次。原因矩形框本身无法完美贴合裂缝这种细长不规则目标这是 YOLO 系列算法的固有限制。每个裂缝都框成矩形但一条弯弯曲曲的裂缝矩形框会覆盖大量非裂缝区域导致 IoU 偏低又被 NMS 反复合并。解决两条路。一是把--conf-thres调高到 0.4 以上减少误检框二是接受矩形框表达输出检测结果时同时给出置信度分数在后处理里用分数做二次过滤。如果毕业设计需要展示分割效果可以考虑在 YOLOv5 基础上加一层分割头或者换用 YOLOv5-seg 变体但那就超出这个项目的范围了。坑 5weights/download_weights.sh下载超时训练无法开始现象执行脚本后长时间无响应最后报连接超时weights/目录下没有生成任何.pt文件。原因脚本里的下载地址是官方托管地址网络不稳定的时候容易失败尤其是大文件下载到一半断掉。解决别反复重跑脚本直接用下载工具把yolov5s.pt单独下下来放进weights/目录。下载完成后校验一下文件大小yolov5s.pt大约 14 MB 左右如果只有几 KB 说明下载不完整加载时会报EOFError。6. 收尾技巧用 detect_camera.py 做实时检测顺便把模型导成 TorchScript训练出best.pt之后整个项目就到了“能交差”的阶段但我想多说一句把模型从 Python 脚本里解放出来做成一个脱离训练环境的部署形态才是让这段代码真正有含金量的地方。项目里的detect_camera.py已经给了实时检测的入口但它默认加载的是.pt权重文件依赖训练环境里的所有 Python 包。我习惯的做法是先把模型导出成 TorchScript这样在没有pip install -r requirements.txt的机器上也能跑部署成本低很多。# 导出 TorchScript 格式一行命令搞定 python models/export.py --weights weights/best.pt --img-size 640 --include torchscript导出成功后会在weights/下生成best.torchscript这个文件是自包含的推理时不依赖原始模型定义。加载方式也很简单attempt_load可以直接识别 TorchScript 文件。实时检测的帧率瓶颈通常不在模型而在图像缩放和 NMSdetect_camera.py里默认的输入尺寸是 640如果摄像头分辨率高可以先用代码把画面缩放到 640 再送入模型能明显提升 FPS。# detect_camera.py 里推荐的推理循环骨架 import cv2 import torch # 加载 TorchScript 模型避免依赖 models/ 下的源码 model torch.jit.load(weights/best.torchscript) model.eval() cap cv2.VideoCapture(0) # 0 表示默认摄像头 while cap.isOpened(): ret, frame cap.read() if not ret: break # 统一缩放到 640x640减少计算量 img cv2.resize(frame, (640, 640)) # 前向推理 NMS逻辑和 detect_photo.py 一致 results model(img) # 绘制检测框并显示帧率会显示在窗口左上角 cv2.imshow(Crack Detection, frame) if cv2.waitKey(1) 0xFF ord(q): break参数说明torch.jit.load加载 TorchScript 模型cv2.VideoCapture(0)打开默认摄像头resize到 640 是为了匹配训练时的输入尺寸。如果摄像头画面是竖屏注意resize会拉伸变形建议先做 letterbox 填充而不是直接拉伸否则裂缝的宽高比会失真检测精度下降。从那以后我每拿到一个 YOLOv5 项目都会强制走一遍“先跑通小数据集验证环境再换自己数据训练最后导出部署格式”的流程。这套裂缝检测项目我已经完整复现过直接用是没问题的但如果你把它当成黑匣子只是跑通答辩时导师问一句“你的模型在低分辨率下为什么误检率升高”你就接不住了。把这套源码从头到尾读一遍尤其是我在第 2 章提到的utils/autoanchor.py和models/yolo.py你对 YOLOv5 的理解会超过 80% 的同届同学。希望这个拆解过程帮到你。本文还有配套的精品资源点击获取