简介面向毕业设计、课程设计场景基于YOLOv8的交通道路裂缝识别系统资源包提供了一套可直接运行的完整方案。资源共8个文件、压缩包仅15.91MB其中包含3个Python源码文件可视化界面、视频检测、模型训练、3个模型权重文件以及2个txt说明文档部署说明清晰便于快速上手。代码已经测试通过不仅支持图片与视频裂缝识别还能自动生成核心指标曲线、混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果和标签分布图为毕设答辩或项目汇报提供直观可信的图表支持。已有39人浏览学习适合计算机相关专业学生、老师或企业员工下载使用。借助现成的完整数据集与说明文档可快速完成环境搭建、模型训练和结果分析无论是毕业设计初期的方案验证还是课程设计的完整实现都能获得清晰的实践路径也便于在此基础上二次开发。1. 用 YOLOv8 做道路裂缝识别难点不在模型而在工程落地道路裂缝检测在交通基础设施巡检里是个真实存在的高频需求桥梁、隧道、市政路面都需要定期排查。传统人工巡检效率低而基于深度学习的目标检测方案里YOLOv8 因为部署简单、推理速度快、精度足够成了毕设和课程设计里最常被选中的方案。之所以说难点不在模型是因为用 YOLOv8 训练一个裂缝检测模型本质上是「准备数据 跑通训练脚本」两件事但实际落地时环境配置冲突、数据集标注格式转换、GUI 界面与模型推理的线程阻塞、打包后路径失效这几个问题才是真正消耗时间的部分。这篇文章会按「环境搭建 → 数据集处理 → 模型训练 → 可视化界面 → 部署打包」这条完整链路展开所有命令和代码都基于 Windows PyTorch 这套最常见的组合。无论你是要交毕设还是做课程设计按这个顺序能少踩很多坑。2. YOLOv8 环境配置与依赖安装先解决跑不起来的问题YOLOv8 底层依赖 PyTorch而 PyTorch 的安装版本直接决定了你能不能调用 GPU。很多人第一步就卡在「装了 CPU 版 PyTorch训练慢得没法看」或者「CUDA 版本和 PyTorch 不匹配import 直接报错」。2.1 conda 创建独立环境避免依赖冲突不建议直接在 base 环境里装因为 OpenCV、numpy、matplotlib 这些库的版本互相牵连装多了很容易出现「装 A 库把 B 库的依赖顶掉」的问题。用 conda 建一个独立环境最稳妥。conda create -n crack_yolo python3.9 -y conda activate crack_yoloPython 3.9 是兼容性最好的版本。3.10 以上在 Windows 上编译某些依赖容易出问题3.8 以下又太老3.9 是最稳妥的选择。2.2 安装 PyTorchGPU 版和 CPU 版的选择先查看自己的显卡支持什么版本的 CUDAnvidia-smi看右上角的 CUDA Version比如显示 12.1就说明驱动支持到 CUDA 12.1。然后去 PyTorch 官网选对应的安装命令。如果显卡是 GTX 1660 Ti 这种老卡注意显存只有 6Gbatch size 不能设太大后面训练参数部分会细说。安装命令示例CUDA 11.8 版本pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118安装完成后验证是否真的能用 GPUimport torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))torch.cuda.is_available()返回True才算成功。如果返回False大概率是 PyTorch 装成了 CPU 版卸载重装即可。这一步不要跳过很多人训练到一半才发现用的 CPU白白浪费几小时。2.3 安装 YOLOv8 及剩余依赖YOLOv8 通过 ultralytics 这个包来使用一行命令装完pip install ultralytics pip install labelimglabelimg 是标注工具后面标注数据集用得到。ultralytics 包会自动拉取 opencv-python、matplotlib、pandas、tqdm 等依赖不需要手动一个个装。装完后用一个小测试确认安装成功yolo predict modelyolov8n.pt sourcehttps://ultralytics.com/images/bus.jpg能输出检测结果图说明环境基本通了。这一步能过滤掉 90% 的环境问题包括缺少 DLL、OpenCV 版本冲突、numpy 版本过高等各类报错。3. 裂缝数据集准备与标注质量比数量更关键模型识别裂缝的精度上限不是由模型决定的而是由数据集决定的。YOLOv8 训练自己的数据集不需要海量图片几百张标注良好的图就能训练出一个能用于毕设演示的效果但前提是数据分布要合理、标注要准确。3.1 数据集来源与筛选策略常见的公开数据集有 CFDCrack Forest Dataset、Crack500、DeepCrack这些都能在 GitHub 或学术网站上找到。但直接用公开数据集有个问题很多数据集的标注是像素级分割掩码而目标检测需要的是边界框。所以通常的做法是从公开数据集中挑选裂缝特征明显的图片用 labelimg 重新标注自己拍摄路面裂缝照片手机拍摄即可重点覆盖不同光照、不同裂缝形态网上搜索「道路裂缝图片」「bridge crack dataset」等关键词抓取注意筛选清晰度高的避坑提示不要把几千张图片全部塞进训练集。裂缝检测的难点在于「小目标」和「背景干扰」与其追求数量不如保证每张图里的裂缝清晰、标注框紧贴裂缝边缘。200-300 张图片、每张图标注 1-3 个裂缝框训练 100 轮左右效果就能看。3.2 使用 labelimg 标注并导出 YOLO 格式labelimg 默认标注格式是 Pascal VOCXML 文件需要转换成 YOLO 格式TXT 文件。YOLO 格式每个标注文件对应一张图片每行内容为类别ID x_center y_center width height四个坐标值都是归一化到 [0,1] 的。打开 labelimg 后要做三件事labelimg在 「PascalVOC」 处点击切换成 「YOLO」 格式点击 「Open Dir」 选择图片文件夹点击 「Change Save Dir」 选择标注文件输出文件夹标注时快捷键W创建框D下一张A上一张。裂缝标注的要点是框要尽量贴合裂缝的实际范围不要留太多背景也不要把整张图都框住。裂缝形状细长一个框不够就多个框。标注完成后检查一下输出文件img_001.jpg img_001.txt打开 txt 文件内容应该是类似0 0.532 0.438 0.245 0.067这里的0是类别 ID如果只检测一种裂缝类别数就是 1ID 固定为 0。后面三个值是归一化后的中心点 x、y 和宽高。3.3 划分训练集、验证集、测试集并整理目录结构YOLOv8 训练要求的目录结构如下dataset/ ├── images/ │ ├── train/ │ ├── val/ │ └── test/ ├── labels/ │ ├── train/ │ ├── val/ │ └── test/ └── data.yaml写一个简单的 Python 脚本自动划分import os import random import shutil # 原始图片和标注文件目录 image_dir raw_images label_dir raw_labels # 新目录 base dataset for split in [train, val, test]: os.makedirs(f{base}/images/{split}, exist_okTrue) os.makedirs(f{base}/labels/{split}, exist_okTrue) images [f for f in os.listdir(image_dir) if f.endswith(.jpg)] random.shuffle(images) # 按 8:1:1 划分 train_num int(len(images) * 0.8) val_num int(len(images) * 0.1) for i, img in enumerate(images): label img.replace(.jpg, .txt) if i train_num: split train elif i train_num val_num: split val else: split test shutil.copy(f{image_dir}/{img}, f{base}/images/{split}/{img}) shutil.copy(f{label_dir}/{label}, f{base}/labels/{split}/{label}) print(f划分完成: train {train_num}, val {val_num}, test {len(images) - train_num - val_num})随机种子没固定每次跑划分结果不同。如果后续要对比不同模型的精度建议先random.seed(42)再 shuffle保证每次实验的数据划分一致性。3.4 编写 data.yaml 配置文件在 dataset 目录下创建data.yamlpath: C:/Users/your_name/dataset train: images/train val: images/val test: images/test nc: 1 names: [crack]path是数据集根目录的绝对路径Windows 下注意用正斜杠或者双反斜杠。路径写错是最常见的报错来源之一YOLOv8 的报错信息通常提示找不到图片这时候优先检查这里。nc是类别数量只有裂缝这一类就写 1。names是类别名称列表顺序要和标注时对应上。4. 用 YOLOv8 训练裂缝检测模型参数与训练曲线解读数据集准备好之后训练本身反而是最机械的一步。ultralytics 把训练过程封装得很简单真正需要花时间理解的是参数选择和训练过程中的调优信号。4.1 训练命令与核心参数说明在 crack_yolo 环境下执行训练代码和参数说明如下from ultralytics import YOLO # 加载预训练权重 model YOLO(yolov8n.pt) # 开始训练 model.train( dataC:/Users/your_name/dataset/data.yaml, epochs100, imgsz640, batch8, device0, workers4, lr00.01, patience20, namecrack_train )参数逐项说明参数建议值说明epochs100训练轮数裂缝检测 100 轮足够收敛imgsz640输入图片尺寸YOLOv8 默认 640显存不足可降为 512batch8批大小6G 显存建议 8-16显存溢出就调小device0GPU 编号CPU 训练填cpu但速度慢几十倍workers4数据加载线程数Windows 下不要超过 8lr00.01初始学习率使用预训练权重时 0.01 是安全的默认值patience20早停耐心值验证集 20 轮没提升就自动停止数据集比较小的话batch 可以从 4 开始试显存够再往上加。workers在 Windows 上设置过高的后果是训练启动时卡住甚至报 DataLoader worker 相关的错4 是安全值。4.2 训练过程怎么看损失函数曲线训练开始后终端会实时打印每个 batch 的损失值训练结束后自动在runs/detect/crack_train/目录下生成results.png包含四张关键曲线train/box_loss和val/box_loss边界框回归损失持续下降说明模型在学「裂缝位置在哪」train/cls_loss和val/cls_loss分类损失下降说明模型在学「这是不是裂缝」metrics/precision和metrics/recall精确率和召回率趋势向上metrics/mAP50IoU 阈值 0.5 下的平均精度裂缝检测这个值到 0.7 以上就能用正常情况是前 20 轮 loss 快速下降之后进入平台期缓慢下降。如果train/box_loss一直降但val/box_loss掉头上升说明过拟合了需要增加数据量或者调大patience早停。如果 loss 从头到尾纹丝不动先看数据集里的标注文件是否为空或者格式错误。4.3 用验证集测试模型效果训练完成后加载最佳权重进行验证model YOLO(runs/detect/crack_train/weights/best.pt) results model.val(dataC:/Users/your_name/dataset/data.yaml) print(results.box.map) # mAP50 值 print(results.box.map50) # mAP50-95 值验证输出的核心指标里map50是裂缝检测最常用的指标map是更严格的 IoU 0.5 到 0.95 的平均值。裂缝属于细长目标map50高但map低是正常现象不必焦虑。4.4 模型改进方向C2f 和 Head 的选择YOLOv8 的 YAML 配置里核心模块是 C2fCross Stage Partial with 2 convolutions相比 YOLOv5 的 C3 模块增加了更多梯度流分支在小目标检测上有天然优势。如果训练出来的效果不够理想优先改模型结构而不是疯狂调学习率。常见修改方案# yolov8n_custom.yaml backbone: # 原有 C2f 层后增加一层增强对细长裂缝的特征提取 - [-1, 1, C2f, [128, True]] head: # 在检测头前增加注意力机制模块 - [-1, 1, CBAM, [128]]具体实现需要引入额外的注意力机制代码但思路是裂缝是小目标可以在第 4 个 C2f 层后面加一个 CBAMConvolutional Block Attention Module让模型更关注裂缝区域的特征通道。这部分属于进阶优化毕设做到这一步属于加分项不追求极致精度的话原版 YOLOv8 已够用。5. 可视化界面与单张图片推理从命令行到 GUI训练完模型下一步是把模型封装成一个能「点开就用」的应用。这里先做命令行推理再升级成可视化界面两个步骤分开方便排查问题。5.1 单张图片和视频的推理代码最简单的推理方式from ultralytics import YOLO model YOLO(runs/detect/crack_train/weights/best.pt) # 单张图片推理 results model.predict( sourcetest_images/road_crack.jpg, conf0.25, imgsz640, saveTrue, save_txtTrue )参数说明conf0.25是置信度阈值小于这个值的检测框会被过滤。裂缝的纹理不清晰阈值设太高容易漏检0.25 是平衡值。saveTrue会把标注好的图片保存到runs/detect/predict/目录。save_txtTrue会把检测到的裂缝坐标保存为 txt 文件这个在批量处理时很有用。如果想要实时视频检测只需把source替换成视频路径或者摄像头编号results model.predict(source0, showTrue)showTrue会弹出实时画面窗口。这一步先确认推理没问题再去做 GUI 封装。5.2 基于 PyQt5 的可视化界面实现可视化界面是毕设验收的加分项。用 PyQt5 做界面核心就三个组件图片选择按钮、显示画布、检测按钮。完整的最小实现如下import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton, QLabel, QFileDialog from PyQt5.QtGui import QPixmap, QImage from PyQt5.QtCore import Qt import cv2 from ultralytics import YOLO class CrackDetectorApp(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle(道路裂缝识别系统) self.setGeometry(100, 100, 800, 600) self.model YOLO(runs/detect/crack_train/weights/best.pt) # 选图按钮 self.btn_open QPushButton(选择图片, self) self.btn_open.setGeometry(50, 50, 100, 30) self.btn_open.clicked.connect(self.open_image) # 检测按钮 self.btn_detect QPushButton(开始检测, self) self.btn_detect.setGeometry(50, 100, 100, 30) self.btn_detect.clicked.connect(self.detect_crack) # 图片显示区域 self.label_img QLabel(self) self.label_img.setGeometry(200, 50, 550, 500) self.label_img.setAlignment(Qt.AlignCenter) self.image_path None def open_image(self): path, _ QFileDialog.getOpenFileName(self, 选择图片, , Images (*.jpg *.png *.jpeg)) if path: self.image_path path pixmap QPixmap(path) # 缩放图片适应显示区域保持宽高比 pixmap pixmap.scaled(550, 500, Qt.KeepAspectRatio) self.label_img.setPixmap(pixmap) def detect_crack(self): if not self.image_path: return # 读取图片并推理 results self.model.predict(sourceself.image_path, conf0.25) annotated_img results[0].plot() # 返回标注后的 BGR 图像 # 颜色空间转换 BGR - RGB rgb_img cv2.cvtColor(annotated_img, cv2.COLOR_BGR2RGB) h, w, ch rgb_img.shape bytes_per_line ch * w qimg QImage(rgb_img.data, w, h, bytes_per_line, QImage.Format_RGB888) pixmap QPixmap.fromImage(qimg) pixmap pixmap.scaled(550, 500, Qt.KeepAspectRatio) self.label_img.setPixmap(pixmap) if __name__ __main__: app QApplication(sys.argv) window CrackDetectorApp() window.show() sys.exit(app.exec_())这段代码里的关键点是results[0].plot()它会在原图基础上画出检测框和类别标签返回的是 BGR 格式的 numpy 数组。PyQt 的 QImage 只认 RGB不转换的话颜色会偏蓝偏紫。风险提示如果在__init__里就加载模型GUI 启动会比较慢因为模型加载要几百毫秒到 1 秒不等。更稳妥的做法是把模型初始化放在一个初始化函数里或者用 QThread 做异步加载否则启动时界面会卡住几秒没响应。6. 部署打包与常见错误处理让项目在别的电脑上也能跑训练和 GUI 都跑通之后最后一个环节是把整个系统打包成一个可执行文件在没装 Python 的机器上也能双击运行。PyInstaller 是主要工具但它和 ultralytics 的搭配有几个典型的坑。6.1 PyInstaller 打包命令与参数先安装 PyInstallerpip install pyinstaller执行打包pyinstaller -w --onefile \ --add-data runs/detect/crack_train/weights/best.pt;runs/detect/crack_train/weights \ --hidden-import ultralytics \ --hidden-import cv2 \ app.py-w让程序运行时不弹出黑色的控制台窗口--onefile打包成单个 exe 文件。--add-data把模型权重文件打包进去分号分隔源路径和目标路径Windows 下用分号Linux 下用冒号。6.2 打包后模型路径失效的解决方案打包成单文件 exe 后有个经典问题模型权重文件的路径在 PyInstaller 的临时解压目录里程序运行时用sys._MEIPASS获取这个临时目录的路径import sys import os def resource_path(relative_path): 获取打包后资源文件的绝对路径 if hasattr(sys, _MEIPASS): # 存在 _MEIPASS 说明是打包后的状态 base_path sys._MEIPASS else: # 开发环境下直接使用当前目录 base_path os.path.abspath(.) return os.path.join(base_path, relative_path) # 加载模型时使用 model_path resource_path(runs/detect/crack_train/weights/best.pt) self.model YOLO(model_path)这段代码是部署环节最关键的部分。不处理sys._MEIPASS的话打包后的 exe 双击就会在加载模型时报「no such file or directory」因为运行时根本找不到runs/目录。提示PyInstaller 打包体积很大baseline 就有 200MB 以上因为 PyTorch 本身体积庞大。如果要减小体积可以用--exclude-module torchvision前提是你确实没用到 torchvision 的功能。6.3 排查思路训练常见报错与修复对照表报错现象原因修复方法CUDA out of memorybatch 太大或图片尺寸过大调小 batch 到 4 或 2imgsz 调为 512No labels found in ...labels 目录里没有 txt 文件labelimg 切换为 YOLO 格式重新导出并确认图片和 txt 同名FileNotFoundError: yolov8n.pt首次运行需从网上加载预训练权重网络受限手动下载 yolov8n.pt 放到当前目录AttributeError: NoneType object has no attribute shape图片路径里含中文将图片和数据集路径全部改为英文路径路径含中文是 Windows 下最容易踩的坑OpenCV 的imread对中文路径支持不友好PyQt 的QFileDialog选出来的中文路径传到model.predict()后会直接报 NoneType 错误。最保险的做法是数据集和代码放在纯英文路径下这也是为什么建议在 conda 环境目录或者C:/project/crack_detect/这类路径下创建项目。6.4 部署后验证的完整流程打包完成后要做三个层面的验证第一层裸环境测试。找一台没有安装 Python 的电脑拷入 exe 文件运行确认能正常弹出界面、能选图、能检测。这一步过滤环境依赖问题。第二层边界测试。用不同清晰度的图片测试重点看光照很暗的、裂缝很小的、背景很花的图片确认程序不会崩溃。GUI 程序最容易在图片读取上崩最好在detect_crack里加 try-except 包裹。第三层性能测试。在目标机器上记录从点击「开始检测」到结果显示的耗时。CPU 推理一张 640x640 的图片需要 2-5 秒这是正常的如果超过 10 秒说明imgsz设置过大或者模型没有用上 GPU。部署阶段的最后一个技巧是在 exe 的同级目录下放一个说明.txt把模型类别裂缝 crack、置信度阈值、输入图片要求建议 jpg 格式、分辨率 640x640 左右写清楚。这个 txt 既方便自己验收也方便导师或评委快速理解系统边界。本文还有配套的精品资源点击获取