简介面向目标检测学习者和道路养护开发者这份基于YOLOv8的路面坑洼检测系统资源提供了完整Python工程可解决从数据标注、模型训练到推理评估的落地问题。压缩包共10个文件4个Python脚本覆盖数据预处理、训练、验证与预测2个pt权重文件即best.pt和y8best.pt可直接加载推理另有txt依赖清单、md项目说明、mp4演示视频和png效果图大小约170.66MB目录结构清晰便于按需取用。已有424人学习下载。适合课程设计、毕业设计及道路巡检预研等场景。通过阅读README与源码可掌握YOLOv8的道路缺陷识别流程包括标注格式、超参数配置、非极大值抑制及mAP评估方法演示视频和效果图可直观对照模型表现便于复现实验、二次开发或迁移到交通标志识别、路面破损评估等相近视觉任务。1. 路面坑洼检测为什么用YOLOv8一个高分项目的技术底气道路养护单位每年花在人工巡检上的时间惊人漏检一个拳头大的坑洼雨季过后可能变成一条裂缝。传统图像处理靠边缘和灰度阈值遇到路面阴影、水渍、轮胎痕迹就翻车。基于YOLOv8实现的路面坑洼检测系统能直接把摄像头画面里的坑洼框出来输出位置、大小和置信度训练好的模型在普通显卡上跑实时推理。这套方法不只适合做毕设拿高分放在真实巡检场景里也能当第一版工具用。本文从数据准备、模型训练、参数调整到避坑验证完整讲清楚这个系统怎么做出来以及哪些地方容易让效果不如预期。2. 坑洼检测任务拆解与YOLOv8选型逻辑做路面坑洼检测之前先别急着写代码。我见过不少开发者拿公开的车辆检测模型直接去预测坑洼效果差到没法看。原因是坑洼这个目标在成像特征、尺度分布和干扰来源上都和常见物体差得很远必须先把任务拆开再选模型。2.1 坑洼检测的技术难点小目标、阴影与路面纹理干扰坑洼检测第一个难点是目标太小。在1080p的行车记录仪画面里一个宽度15厘米的坑洼可能只占30到60像素属于典型的小目标。小目标在卷积网络深层特征图里几乎只剩几个响应点很容易被忽略。第二是对比度低。坑洼和周围沥青路面的颜色差异通常不大边缘是渐变的没有清晰的边界线。夜间或逆光下这种边界更加模糊人眼都容易漏看模型更难。第三是干扰物多。路面阴影、油渍、水坑、裂缝、修补过的补丁甚至轮胎留下的黑色印迹看起来都像坑洼。如果数据集里这些负样本不够模型就会把阴影当成坑洼产生大量误检。我做过一个测试只给模型看晴天白天的坑洼图拿到阴天场景里测试误检率直接翻了3倍这就是背景干扰没学够的典型翻车现场。所以坑洼检测的真正难点不是模型不够深而是数据能不能覆盖小目标、弱对比和复杂干扰这三件事。后续的标注、增强和推理都需要围绕这三点来设计。2.2 对比Faster R-CNN与YOLO系列为什么YOLOv8更合适坑洼检测需要实时性因为巡检车在移动视频帧率一般要跑到25以上才有实用价值。两阶段检测器Faster R-CNN精度不错但前背景候选框生成阶段非常耗时在低端GPU上很难达到实时。YOLO系列作为单阶段检测器把分类和回归放在同一个网络里一次完成速度优势明显。YOLOv8相对之前的版本有几个关键改进。一是用anchor-free方式预测目标省去了预设anchor尺寸的麻烦。坑洼的尺寸变化很大从拳头小坑到半米大坑都有anchor-free直接回归距离对小坑更友好。二是骨干网络引入了C2f结构丰富了梯度流对小目标的特征提取有一定帮助。三是损失函数用了一系列优化组合在相同训练配置下收敛更平稳。我用一个表格把几个常见方案的差异列出来方案推理速度1080p, GPU小目标表现训练配置复杂度部署便利性Faster R-CNN5~10 FPS中高中YOLOv530~60 FPS中低高YOLOv830~80 FPS中偏上极低高RT-DETR20~40 FPS中中中从表里看YOLOv8在速度、易用性和表现上综合最优。另一个实际原因是Python生态完整。ultralytics库把训练、验证、导出、推理全部封装成几行命令对做项目、快速出结果非常有利。如果后续要落地到边缘设备YOLOv8导出为ONNX或TensorRT也顺不会卡在格式转换上。2.3 系统整体流程数据、训练、推理、报告整个坑洼检测系统的技术流程可以拆成4个模块。数据模块负责采集图片、标注坑洼位置、转换成模型需要的格式训练模块负责加载预训练权重、在自建数据集上微调、输出最佳权重文件推理模块负责读入图片或视频、调用模型预测、把检测框和置信度画到画面上报告模块负责统计检测数量、导出结果图或表格。我习惯把这个流程固定成一个顺序避免来回改文件路径。目录结构这样组织pothole_detection/ ├── data/ │ ├── images/ │ ├── labels/ │ ├── train.txt │ ├── val.txt │ └── data.yaml ├── models/ │ └── yolov8n.pt ├── scripts/ │ ├── convert_annotations.py │ ├── train.py │ ├── detect.py │ └── evaluate.py ├── runs/ │ └── detect/ └── README.md这个结构的核心价值在清晰。数据、代码、输出分开训练完能在runs目录里直接看到结果图、指标曲线和权重文件。项目说明文档只需要按这个目录结构写评分或接手的人能快速找到每一个环节的产物。3. 数据准备坑洼数据集的获取、标注与格式转换模型效果的天花板是数据决定的。一个标注质量差、场景单一的数据集再好的网络结构也救不回来。这一章讲清楚数据集从哪来、标注怎么转、增强怎么做。3.1 数据集来源与自采建议坑洼检测领域有公开的道路病害数据集里面包含坑洼、裂缝、修补等类别。我一般会先去这类公开数据里筛选坑洼类别再结合自采数据一起用。注意公开数据集的图片分辨率、拍摄角度和检测场景可能和你的目标环境不一致最好只作为预训练和补充不能全部依赖。自采数据建议用手机或行车记录仪拍摄覆盖晴天、阴天、雨天、逆光、夜晚路灯等条件。拍摄时保持镜头距离地面1米到1.5米角度略向下倾斜模拟道路巡检的视角。每段视频截取关键帧去掉连续帧里几乎一模一样的图片避免数据集冗余。坑洼类别不要分太细。我见过有人把坑洼分成“小坑”“大坑”“深坑”三类但标注一致性很难保证模型反而学混乱。最省事且稳定的做法是只用一类pothole把形状深浅差异交给模型自己去学。标注工具推荐用LabelImg或LabelMe。LabelImg直接输出Pascal VOC格式的XML文件LabelMe输出JSON格式两者都需要转换成YOLO使用的txt文件。转换逻辑是统一的我直接给出脚本。3.2 用Python把VOC/JSON标注转成YOLO格式YOLO格式的标签是每行一个目标五个数字分别是类别id、归一化中心x、中心y、宽度w、高度h。注意是归一化到图片宽高后的值。下面是VOC XML转YOLO txt的完整脚本。import os import xml.etree.ElementTree as ET def voc_to_yolo(xml_path, txt_path, classes): tree ET.parse(xml_path) root tree.getroot() # 读取图片宽高标注里的坐标都是像素值 width int(root.find(size/width).text) height int(root.find(size/height).text) lines [] for obj in root.iter(object): name obj.find(name).text if name not in classes: continue # 跳过非目标类别 class_id classes.index(name) box obj.find(bndbox) xmin float(box.find(xmin).text) ymin float(box.find(ymin).text) xmax float(box.find(xmax).text) ymax float(box.find(ymax).text) # 转成YOLO的归一化坐标 x_center ((xmin xmax) / 2) / width y_center ((ymin ymax) / 2) / height w (xmax - xmin) / width h (ymax - ymin) / height # 防止边界越界裁剪到0~1之间 x_center min(max(x_center, 0.0), 1.0) y_center min(max(y_center, 0.0), 1.0) w min(max(w, 0.0), 1.0) h min(max(h, 0.0), 1.0) lines.append(f{class_id} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}) with open(txt_path, w) as f: f.write(\n.join(lines)) if __name__ __main__: classes [pothole] # 类别列表按训练顺序 xml_dir annotations/xml txt_dir annotations/yolo os.makedirs(txt_dir, exist_okTrue) for xml_file in os.listdir(xml_dir): if not xml_file.endswith(.xml): continue xml_path os.path.join(xml_dir, xml_file) txt_path os.path.join(txt_dir, xml_file.replace(.xml, .txt)) voc_to_yolo(xml_path, txt_path, classes) print(转换完成txt文件数量:, len(os.listdir(txt_dir)))脚本的核心逻辑是读出每个目标的像素坐标先计算中心点坐标和宽高再分别除以图片宽高完成归一化。这样得到的数值和图片分辨率无关训练时模型就不用关心原始图片尺寸。转换完成之后建议随机抽取几张图片把txt里的坐标画出来验证一下防止坐标错位。常见错误是XML里的xmax、ymax被当成了宽高导致框变形。我一般会写一个短的绘图脚本肉眼检查一遍再进入训练。3.3 数据增强策略亮度扰动、仿射变换与Mosaic坑洼检测的数据增强要优先解决光照和视角变化。路面阴影是最大的误检源所以亮度、对比度、阴影方向的扰动很重要。YOLOv8在训练时已经内置了Mosaic增强、HSV扰动等默认是开启的。Mosaic把4张图拼接成一张相当于扩大了batch size也增加了目标尺度的变化对坑洼这种小目标很有效。我建议默认开Mosaic但要注意在训练最后10个epoch时关闭它因为Mosaic生成的拼接图和真实场景差距较大一直开着会阻碍模型收敛。如果想自己控制增强可以使用albumentations库自定义。import albumentations as A train_transform A.Compose([ A.RandomBrightnessContrast(brightness_limit0.3, contrast_limit0.3, p0.8), A.HueSaturationValue(hue_shift_limit10, sat_shift_limit20, val_shift_limit30, p0.5), A.Affine(scale(0.8, 1.2), translate_percent(0.1, 0.1), rotate(-15, 15), p0.5), A.GaussNoise(var_limit(10.0, 50.0), p0.3), ], bbox_paramsA.BboxParams(formatyolo, min_visibility0.3))这段代码里的每个增强都有明确目的。RandomBrightnessContrast用于模拟晴天、阴天的光照突变这是抗阴影误检的关键。Affine中的随机缩放和旋转模拟了巡检车在不同角度、不同高度拍摄的情况同时让模型适应坑洼的尺度变化。GaussNoise模拟摄像头的传感器噪声增强模型的鲁棒性。min_visibility0.3的意思是如果增强后的标注框被裁剪得只剩不到30%可见就丢弃这个标注避免模型学到残破的框。这个参数在小目标场景特别有用。数据增强不是越多越好要结合验证集效果调整。如果增强过强训练集和验证集的分布差距变得过大会导致验证集mAP一直上不去这是一个需要来回试的玄学问题。4. 用YOLOv8训练坑洼检测模型关键配置与实操命令数据准备好以后训练模型反而相对简单。YOLOv8把训练流程压缩到了极简但参数配置仍旧决定最终效果尤其是输入分辨率、epoch和batch size的配合。4.1 安装ultralytics包与验证环境训练前先安装官方库。建议使用独立的Python环境避免依赖冲突。我一般在项目根目录创建虚拟环境后执行pip install ultralytics python -c import ultralytics; print(ultralytics.__version__)如果能看到版本号说明安装成功。这一行验证代码很关键因为有些老教程会让装单独安装torch但ultralytics会自动拉取匹配版本的torch。注意看torch的CUDA版本。可以用下面命令确认GPU可用python -c import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0) if torch.cuda.is_available() else CPU)如果这里打印False后续训练会全部跑到CPU上时间可能慢几十倍。遇到这种情况优先检查显卡驱动和CUDA版本这一块的具体坑在第5章专门说。4.2 准备data.yaml与模型配置文件ultralytics训练需要data.yaml描述数据集路径和类别。我的习惯是把所有数据放到同一个上级目录data.yaml里写绝对路径避免不同机器上路径不同导致的加载失败。文件内容如下# data.yaml path: /home/user/pothole_detection/data train: images/train val: images/val nc: 1 names: 0: potholepath指向数据集根目录train和val指向相对path的图片目录。注意YOLO会自动寻找与图片同名的txt标签文件目录结构需要保持一一对应。如果报错找不到标签多半是图片和txt文件名不一致或没有放在images对应的labels目录下。nc1表示只有坑洼一个类别names列表顺序要和转换脚本里的classes顺序一致。这个顺序一旦错了模型训练结果和推理输出的类别含义就全乱了。4.3 启动训练命令行参数与核心超参解读训练命令可以直接通过ultralytics的CLI执行。下面是常用的一条yolo train \ modelyolov8n.pt \ datadata.yaml \ epochs50 \ imgsz640 \ batch16 \ lr00.01 \ device0执行后会在runs/detect/train目录下生成权重、日志和验证结果。对坑洼检测这个小目标场景模型文件建议选yolov8n或yolov8s。yolov8n速度最快但特征提取能力弱小坑洼容易漏yolov8s精度更高速度和精度平衡点最好。我一般先跑s模型拿一个baseline时间充足再试n模型的蒸馏看看能不能保留精度同时加速。imgsz参数决定训练时的输入分辨率。默认640对普通目标合适但坑洼小目标多分辨率太低坑洼直接缩成几个像素。我建议在显存允许范围内把imgsz提到768或896。代价是显存占用和训练时间上升需要同步调小batch。batch表示每次迭代送入的图片数量影响梯度估计稳定性和显存占用。batch16是8G显存比较稳妥的起点如果显存不足先降到8而不是改小imgsz。lr0是初始学习率0.01是官方预设一般不用动。真正影响收敛的是epochs。坑洼数据集通常只有几百到几千张50个epoch足够收敛加太多反而过拟合。4.4 训练日志与指标监控看Loss和mAP训练过程中终端会持续打印box_loss、cls_loss、dfl_loss和mAP50、mAP50-95等指标。很多人只关心mAP忽略loss其实loss才是判断有没有在学的核心。如果box_loss持续下降但mAP停滞多半是数据标注噪声大如果loss降到很低但mAP低可能存在过拟合。训练结束后runs/detect/train目录下会有results.csv每行对应一个epoch的结果。我用下面的脚本快速画一张训练曲线能直观看到收敛情况import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(runs/detect/train/results.csv) # 列名里含空格先清理 df.columns [c.strip() for c in df.columns] plt.figure(figsize(10, 4)) plt.subplot(1, 2, 1) plt.plot(df[epoch], df[train/box_loss], labelbox_loss) plt.title(Box Loss) plt.legend() plt.subplot(1, 2, 2) plt.plot(df[epoch], df[metrics/mAP50(B)], labelmAP50, colorgreen) plt.title(mAP50) plt.legend() plt.tight_layout() plt.savefig(training_curves.png)这张图是项目说明文档里最有说服力的图片。评分或汇报时贴出loss收敛曲线和mAP曲线一眼就能看出训练过程健康。我习惯把这张图放在README的前面位置比大段文字说明效果更好。5. 避坑指南路面坑洼检测项目最容易翻车的5个细节这一章写的是我在多个坑洼检测项目里踩过的坑每条都是现象、原因、解决的完整链路。提前避掉这些问题项目进度能快一倍。5.1 标注框不贴合坑洼边缘mAP虚高但实际效果差现象训练时mAP50达到0.85以上看起来效果很好但把模型放到真实视频里框要么偏大要么框住了坑洼的一半边缘。检测框抖动很严重结论无法直接用。原因坑洼的边界是渐变的标注的人凭感觉画框不同图片里框的松紧程度不一致。模型学到的边界本身是模糊的mAP计算时只要预测框和标注框的IoU大于0.5就算命中所以宽松的标注让mAP偏高却没有真实反映定位精度。解决标注时定一个统一规则框要紧贴坑洼最外圈的可见凹陷边缘不要包含周围的裂缝和路面。已经标好的数据可以用脚本统一缩放每个框到原框的0.95倍强制收紧一点。另外在训练时关注mAP50-95这个指标对框的贴合度更敏感如果mAP50与mAP50-95差距过大说明框质量有问题。5.2 小坑洼漏检输入分辨率与anchor尺寸如何调现象图片里大的坑洼都能检测到但小坑洼小于32×32像素几乎全部漏检。把图片放大再推理会好一点但速度下降。原因YOLOv8在640分辨率下下采样倍数使得小目标的特征图分辨率有限原始特征响应太弱。它虽然有anchor-free设计但小目标在backbone下采样后可能只剩一个点难以回归准确定位。解决优先把imgsz从640提高到768或896小目标保留的像素信息更多。也可以在训练时开启多尺度训练ultralytics自带的scale参数默认0.9可以把它设为0.5~1.5让模型看到不同尺度的输入。另外单独统计数据集中目标宽高分布如果大部分小目标集中在画面中央可以裁剪掉无用区域再训练相当于变相提高小目标分辨率。5.3 训练中断与过拟合断点续训与早停参数现象训练到第30个epoch时进程因为显存溢出或手动误关中断。重新从头训练浪费了前面所有时间而且后期mAP曲线开始下降明显过拟合。原因ultralytics默认每10个epoch保存一次权重但没有开断点续训时中断后只能从头开始。过拟合是因为epoch设50但数据量少模型在后期开始记忆训练集噪声。解决训练命令里加resume参数yolo train resume modelruns/detect/train/weights/last.pt这样会从last.pt继续训练保留优化器状态。同时显存溢出时把batch减小而不是重新跑。对于过拟合设置patience10模型会在验证集指标连续10个epoch不提升时自动早停保存best.pt。这个参数很值得用省去手动盯曲线的时间。5.4 torch与CUDA版本不匹配导致训练卡死现象训练命令启动后进程卡在“ Downloading... ”或跑起来几秒后报错出现ABORT或CUDA error。有的人干脆不用GPU训练速度慢到令人崩溃。原因常见是torch的CUDA版本和显卡驱动支持的CUDA版本不一致或者装了CPU版torch。ultralytics安装时会自动装torch但不一定匹配你的显卡驱动版本。解决先看驱动支持的CUDA版本用nvidia-smi查看右上角的CUDA Version。然后重新安装对应的torch。我一般用官方推荐的命令pip uninstall torch torchvision pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118注意具体CUDA版本号要按你的驱动来不要照抄。装好后跑torch.cuda.is_available()确认True再训练。这个坑能卡掉一整天排查顺序是nvidia-smi看驱动→查看torch版本→对不上就重装。5.5 模型部署时预处理不一致推理结果与训练时偏差大现象训练时mAP不错但导出模型后放到另一个脚本里推理同一张图检测结果和训练时的验证结果不一样框偏了好几个像素置信度也低。原因推理脚本没有做相同的数据预处理。训练时YOLOv8会自动做letterbox保持宽高比填充灰边推理时如果直接resize到640×640图片变形目标形状被拉伸检测自然不准。解决使用ultralytics自带的推理方法它会自动执行letterbox不会出错。如果是自己导出的ONNX或自己写的预处理必须手动实现letterboximport cv2 import numpy as np def letterbox(img, new_size(640, 640), color(114, 114, 114)): h, w img.shape[:2] r min(new_size[0] / h, new_size[1] / w) nh, nw int(round(h * r)), int(round(w * r)) img_resized cv2.resize(img, (nw, nh), interpolationcv2.INTER_LINEAR) canvas np.full((new_size[0], new_size[1], 3), color, dtypenp.uint8) dx (new_size[1] - nw) // 2 dy (new_size[0] - nh) // 2 canvas[dy:dynh, dx:dxnw] img_resized return canvas, r, dx, dy推理得到坐标后要减去dx、dy并除以r才能映射回原图坐标。很多部署翻车都是忘了这一步。6. 用混淆矩阵与PR曲线验证坑洼检测模型的真实水平训练好模型后不要只看终端里那个mAP数字。我会用验证集做一次正式评估生成混淆矩阵和PR曲线这能告诉你模型到底错在哪比mAP有用得多。ultralytics自带的val命令可以直接输出评估结果yolo val modelruns/detect/train/weights/best.pt datadata.yaml它在runs/detect/val目录下生成混淆矩阵、PR曲线、F1曲线等。混淆矩阵里最值得看的是背景类被误检成坑洼的比例。坑洼检测最常见的错误是阴影误检混淆矩阵里会表现为background行里有大量预测为pothole的样本。如果这个比例超过一定阈值说明背景干扰还需要用数据增强或负样本来压制。PR曲线展示不同置信度阈值下的精确率和召回率关系。坑洼检测场景里精确率和召回率需要权衡。如果做道路普查宁可多报告一些疑似坑洼让人工复核就选召回率高的阈值如果做自动作业决策则需要高精确率减少误报。我一般会看F1曲线找到最优置信度阈值而不是用默认0.25。如果想在Python脚本里独立验证可以这样跑一次from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) metrics model.val(datadata.yaml, splitval, conf0.25, iou0.5) print(mAP50:, metrics.box.map50) print(mAP50-95:, metrics.box.map)这里conf是置信度阈值iou是评估时的IoU阈值。调低conf会提升召回率但降低精确率。通过多次设置conf对比最终结果你会找到这个特定数据集上的“甜点”。这套验证习惯帮我校准过不止一次模型。有个项目里mAP50看起来很高但混淆矩阵显示大量阴影误检后来我增加了阴影区域的负样本误检率下降了一半。如果没有矩阵可视化我根本不知道问题出在背景而不是坑洼本身。这也成了我以后做目标检测项目的固定动作先看混淆矩阵再调阈值。希望这些从数据到验证的完整路径能帮你少走一段弯路。坑洼检测不难难的是把细节都做对祝你的项目一次跑通。本文还有配套的精品资源点击获取