企业官网建设流程全解析

简介：基于YOLOv8的道路病害检测平台源码包，面向计算机视觉方向学习者、毕业设计及课程设计开发者，提供一套可直接运行的Web端目标检测应用方案。平台利用YOLOv8的多尺度特征提取与实时推理优势，针对道路裂缝、坑洼、积水等常见病害进行识别和定位。资源共48个文件，以Python脚本为主（24个py），涵盖Django项目配置、API接口、模型封装等核心模块，另有预训练权重（.pt）、依赖清单与使用说明（md/txt），压缩包约5.41MB，整体轻量、结构清晰，便于快速部署与学习。已有158人学习下载。源码覆盖数据预处理、模型加载、检测推理到结果展示的完整流程，并配有环境搭建和运行指导；同时提供可修改的配置文件与模块化目录，方便接入自定义数据集进行训练和预测，也可作为理解YOLOv8从算法到系统落地的参考项目。

1. 道路病害检测的 YOLOv8 选型与平台定位

路巡车一天拍回上万张路面照片，人工筛裂缝和坑槽既慢又漏，二值化加形态学只对均匀光照管用，碰上阴影、油污、修补带就全部失效。把 YOLOv8 训练成道路病害检测模型，再包一层 Web 服务，是目前小团队能最快拿到可用结果的做法：标注几百张图就能跑出初版，换相机、换路段只需增量微调。这也是常被压缩成“源码+使用说明”交付的核心组件。下面按选型、环境、数据、训练、服务封装、导出验证的顺序展开，覆盖 GTX 1660Ti 这种 6G 显存机器能完整跑通的参数组合，适合用它做毕业设计，也适合小团队做道路病害检测原型。

2. YOLOv8 在道路病害检测里的选型依据与平台模块拆解

2.1 C2f、anchor-free Head 与多尺度特征对细长病害的意义

道路病害检测不是普通的目标检测换数据集。裂缝是宽度 2~5 像素的长条，可能横跨 1600 像素；坑槽边缘和影子边界几乎同色；修补带则和旧路面之间没有清晰轮廓。YOLOv8 在这类目标上表现稳定，原因要从结构说起。

YOLOv8 的 C2f 模块把输入沿通道维度拆成多支，每支经过一次 Bottleneck 后与前面所有分支 concat，再送入下一层。相比 YOLOv5 的 C3，C2f 让每一层梯度都能同时抵达浅层和深层分支，参数增量不大，但对边缘纹理这类中频信息的传导更充分。裂缝的灰度与沥青路面差距常在 10 个灰度级以内，这种梯度设计比单纯加深网络更有利于保留浅层的边缘响应。代价是推理延迟略升，所以平台初版本人建议用 yolov8n 或 yolov8s 起量，不要一上来就用 l。

更关键的是 anchor-free 解耦头。旧版 anchor-based 需要预设长宽比，而裂缝长宽比可能到 15:1，坑槽又接近 1:1，预设 anchor 很难同时覆盖。YOLOv8 把目标判定改为每个位置回归到中心点的距离，配合 DFL 分布损失输出坐标，对极端长宽比更宽容。实际经验是，裂缝这类长条目标在切换到 anchor-free 后，recall 通常比 YOLOv5 高 3~5 个百分点。

多尺度检测头覆盖 P3/P4/P5。原图上宽度只有 3 像素的裂缝，缩到 640 分辨率后往往只剩 1 像素，直接消失。所以我建议道路病害场景把输入分辨率至少提到 1280，必要时 1536。下表是分辨率选择的趋势判断，具体数值会因数据集和显卡波动：

2.2 平台从数据到服务的四个模块

一个能交付的道路病害检测平台，不会只放一个训练脚本。即使交付物是“源码+使用说明.zip”，内部也应按数据、训练、推理、服务四条线拆开，否则接手的人很难把模型从训练环境迁到生产环境。

pavement_platform/ ├── data/ # 原始图片与标注回传 ├── datasets/ # 切分后的 YOLO 格式数据集 ├── runs/ # 训练产物：weights、results.csv ├── src/ │ ├── train.py │ ├── detect_batch.py │ └── api.py ├── output/ │ ├── json/ # 结构化检测结果 │ └── annotated/ # 画框后的图片 └── requirements.txt

我一般把训练和推理严格分开：训练环境需要 torch 全家桶，线上平台则只装 onnxruntime 或精简后的 ultralytics。混在一起部署，最常见的后果是升级一个依赖把另一个环境搞坏。目录里runs/承担实验记录，output/json/是给下游工单系统消费的，画框图只是给人复核用的副产品。

2.3 依赖组合与先验证 CUDA 再装包

依赖版本不用追新，兼容性比版本号重要。下面这个组合在 Windows 和 Ubuntu 上都能直接跑：

ultralytics>=8.2.0 torch>=2.0.0 torchvision>=0.15.0 opencv-python>=4.8 numpy>=1.24,<2.0 pandas>=2.0

注意 numpy 必须锁在 2.x 以下。Ultralytics 8.2.x 在 numpy 2.0 下偶发np.int属性报错，排查起来很费时间。装完先验证 CUDA 是否真的可用：

python -c "import torch;print(torch.__version__,torch.cuda.is_available(),torch.cuda.get_device_name(0))"

输出里torch.cuda.is_available()必须为 True。这一步不做，后面训练时你以为在用 GPU，实际可能在 CPU 上跑一周。

3. 道路病害数据集准备：YOLOv8 环境配置、标注规范与训练/验证切分

3.1 用 conda 搭出最小 yolov8 环境

环境配置是新手问得最多的环节，问题基本都出在 torch 与 CUDA 版本不匹配。推荐顺序是先装 torch，再装 ultralytics，让 pip 去解析剩余依赖：

conda create -n pavement python=3.10 -y conda activate pavement pip install -U pip pip install torch==2.2.2 torchvision==0.17.2 --index-url https://download.pytorch.org/whl/cu121 pip install ultralytics==8.2.10

这里 cu121 对应 CUDA 12.1 runtime，GTX 1660Ti 只要显卡驱动足够新就能用，不需要额外装完整的 CUDA Toolkit。先装 torch 的原因是 ultralytics 默认会拉最新版 torch，最新版对老显卡的编译优化不一定更好，锁定小版本更可控。装完后执行yolo task=detect mode=check，它会列出当前环境里的 torch、CUDA 和 ultralytics 版本关系。

提示：不要用系统自带 python 直接开干，conda 环境隔离是后面所有实验可复现的前提。

3.2 标注格式与数据集目录约定

YOLO 格式要求图片和标签平行存放，训练集与验证集各自独立目录：

datasets/pavement/ ├── images/ │ ├── train/ │ └── val/ └── labels/ ├── train/ └── val/

每张road_001.jpg对应一个road_001.txt，每行是一个目标：类别序号加归一化坐标class_id cx cy w h。下面是一个四类病害数据集的标签示例：

0 0.4831 0.2204 0.2106 0.0221 1 0.7312 0.5311 0.1023 0.0874 2 0.2204 0.8442 0.3510 0.0566 3 0.8640 0.1271 0.0822 0.0693

第 0 类是裂缝，第 1 类是坑槽，第 2 类是修补带，第 3 类是井盖。类别顺序一旦训练开始就不要再改，否则已标注数据的类别语义全部错位。标注时用任意支持 YOLO 导出的工具都行，关键是导出前确认类别列表和训练 yaml 完全一致。

我每次拿到标注数据都会先跑一遍完整性检查，避免在训练时报出莫名其妙的坐标错误：

from pathlib import Path from PIL import Image img_dir = Path("datasets/pavement/images/val") label_dir = Path("datasets/pavement/labels/val") for lp in label_dir.glob("*.txt"): ip = img_dir / f"{lp.stem}.jpg" if not ip.exists(): print(f"孤儿标签: {lp}") continue with Image.open(ip) as im: W, H = im.size for raw in lp.read_text().splitlines(): parts = raw.split() if len(parts) != 5: print(f"字段数错误 {lp.name}: {raw}") continue cls, cx, cy, bw, bh = map(float, parts) if not (0 <= cx <= 1 and 0 <= cy <= 1 and 0 <= bw <= 1 and 0 <= bh <= 1): print(f"坐标越界 {lp.name}: {parts}")

这段脚本在训练前扫一遍，能拦下三种常见问题：图片被移动但标签没跟上、标注文件里混入空行、坐标写成像素值而不是归一化值。YOLO 默认按归一化坐标理解，如果标注工具误存像素坐标，第一个 epoch 就会出现 loss 飙升或直接 NaN。

3.3 切分训练/验证集与类别不均衡处理

切分时最容易犯的错是随机打乱所有图片。道路巡检数据通常按路段连续拍摄，同一病害可能出现在连续几十帧里，随机切分会让验证集和训练集高度相似，mAP 虚高。正确做法是按拍摄批次或路段分组，同一路段只进一个集合。

import random import shutil from pathlib import Path random.seed(42) src = Path("data/labeled") train_img = Path("datasets/pavement/images/train") val_img = Path("datasets/pavement/images/val") images = sorted(src.glob("*.jpg")) random.shuffle(images) val_count = max(1, int(len(images) * 0.2)) val_set = set(images[:val_count]) for img in images: dst = val_img if img in val_set else train_img dst.mkdir(parents=True, exist_ok=True) shutil.copy2(img, dst / img.name) label = src / f"{img.stem}.txt" if label.exists(): label_dst = Path(str(dst).replace("images", "labels")) label_dst.mkdir(parents=True, exist_ok=True) shutil.copy2(label, label_dst / label.name)

脚本里random.seed(42)保证可复现，val_count取 20% 是常用默认值。如果要做跨路段验证，就别用这个脚本，而是把同一个地点前缀的图片整个划到验证集。

道路病害的类别分布通常极不均匀：裂缝样本可能占 70%，坑槽只有 8%。我有两个建议，按优先级排列：

不建议直接在验证集上做复制增强，那会让验证分数失真。平台里我一般保留原始验证集不动，只用增强后的训练集做训练。

4. 用 YOLOv8 训练自己的道路病害数据集：命令、损失曲线与推理验证

4.1 训练命令与关键超参数组合

数据集就绪后，先写数据描述文件datasets/pavement/pavement.yaml：

path: datasets/pavement train: images/train val: images/val nc: 4 names: 0: crack 1: pothole 2: patching 3: manhole

path是数据集的根目录，train和val都基于它做相对定位。nc必须和标注里的类别数一致，多一个或少一个都会在训练时直接报错。

启动训练用下面这条命令：

yolo detect train \ --model yolov8n.pt \ --data datasets/pavement/pavement.yaml \ --imgsz 1280 \ --batch 8 \ --epochs 200 \ --optimizer SGD \ --lr0 0.01 \ --lrf 0.01 \ --mosaic 1.0 \ --close_mosaic 10 \ --patience 30 \ --project runs/pavement \ --name v8n_1280 \ --device 0

--model yolov8n.pt使用 nano 预训练权重做迁移学习，起点比随机初始化收敛快得多。imgsz=1280是为保住细小裂缝；6G 显存跑不动就降到 960，同时把batch降到 4。--close_mosaic 10表示最后 10 个 epoch 关闭马赛克增强，因为 mosaic 拼接会裁掉部分小目标，最后几个 epoch 用真实分布微调更稳。

训练产物默认落在runs/pavement/v8n_1280/，里面weights/best.pt是验证分数最好的权重，weights/last.pt是最后一个 epoch 的权重。平台交付时认准 best.pt。

4.2 用 results.csv 画损失函数曲线图

训练过程中每个 epoch 都会写一行results.csv，包含 box_loss、cls_loss、dfl_loss、precision、recall、mAP50 等列。直接给它画出来，比盯着终端日志直观得多：

import pandas as pd import matplotlib.pyplot as plt df = pd.read_csv("runs/pavement/v8n_1280/results.csv") df.columns = [c.strip() for c in df.columns] fig, axes = plt.subplots(2, 2, figsize=(12, 8)) axes[0, 0].plot(df["epoch"], df["train/box_loss"], label="train_box") axes[0, 0].plot(df["epoch"], df["val/box_loss"], label="val_box") axes[0, 0].set_title("Box Loss") axes[0, 0].legend() axes[0, 1].plot(df["epoch"], df["train/cls_loss"], label="train_cls") axes[0, 1].plot(df["epoch"], df["val/cls_loss"], label="val_cls") axes[0, 1].set_title("Cls Loss") axes[0, 1].legend() axes[1, 0].plot(df["epoch"], df["metrics/precision(B)"], label="precision") axes[1, 0].plot(df["epoch"], df["metrics/recall(B)"], label="recall") axes[1, 0].set_title("P/R") axes[1, 1].plot(df["epoch"], df["metrics/mAP50(B)"], label="mAP50") axes[1, 1].set_title("mAP50") axes[1, 1].legend() plt.tight_layout() plt.savefig("loss_curve.png", dpi=200)

列名带前导空格是 ultralytics 的老毛病，所以第一步先strip()。判别训练是否正常看两点：train/box_loss 持续下降，val/box_loss 同步下降说明还在学习；val 出现回升而 train 继续跌，就是过拟合。道路病害数据量小时，mAP50 后期在小幅震荡中缓慢爬升是正常现象，不必因为某个 epoch 掉了 2% 就重来。

4.3 单图推理、结果输出与置信度参数

训练完成后，先用 single image 验证模型有没有学偏：

from ultralytics import YOLO model = YOLO("runs/pavement/v8n_1280/weights/best.pt") results = model.predict( source="samples/road_021.jpg", conf=0.25, iou=0.45, imgsz=1280, max_det=500, save_txt=True, save_crop=True, save_conf=True, ) for r in results: for box, cls, c in zip(r.boxes.xyxy.cpu().numpy(), r.boxes.cls.cpu().numpy(), r.boxes.conf.cpu().numpy()): print(f"{r.path} {model.names[int(cls)]} {float(c):.2f} {box.tolist()}")

conf=0.25是默认阈值，巡检场景要求高召回时降到 0.15；做复核界面时提到 0.4 减少无关框。iou=0.45控制 NMS 合并重叠框的力度，病害密集相邻时调低到 0.4，让裂缝框别被合并掉。max_det=500防止极端情况下输出几百个框把平台打崩。save_crop会把每个病害裁剪成小图，方便人工只看局部确认。

输出坐标xyxy是原图分辨率下的像素坐标，可直接存库或换算经纬度。批量检测时逐行追加到 CSV 或 JSON 即可。

5. 把训练好的 YOLOv8 封装成道路病害检测平台

5.1 先写 CLI 批处理脚本，再谈平台

很多人一上来就想写 Web 界面，我建议先做 CLI 批处理。它既能验证模型在真实图片上的表现，又能在后续接 API 时直接复用检测逻辑：

from pathlib import Path import json from ultralytics import YOLO model = YOLO("runs/pavement/v8n_1280/weights/best.pt") def run_on_dir(src: Path, out: Path, conf: float = 0.25): out.mkdir(parents=True, exist_ok=True) for img_path in sorted(src.glob("*.jpg")): result = model.predict(str(img_path), conf=conf, verbose=False)[0] detections = [] for box, cls, c in zip(result.boxes.xyxy.cpu().numpy(), result.boxes.cls.cpu().numpy(), result.boxes.conf.cpu().numpy()): detections.append({ "bbox": [round(float(x), 2) for x in box], "class": model.names[int(cls)], "confidence": float(c), }) (out / f"{img_path.stem}.json").write_text( json.dumps(detections, ensure_ascii=False, indent=2) )

输出 JSON 而不是画框图，是平台能否对接业务系统的关键：工单派发、病害统计、按路段聚合赔付分析都需要结构化数据。ensure_ascii=False保证中文字段名不被转义。单独一张病害图只是给人看的，别把它当成平台的主交付物。

5.2 用 FastAPI 暴露检测服务

CLI 验证通过后，用 FastAPI 把检测封装成 HTTP 接口：

from io import BytesIO import numpy as np from fastapi import FastAPI, UploadFile, File from ultralytics import YOLO from PIL import Image app = FastAPI() model = YOLO("runs/pavement/v8n_1280/weights/best.pt") @app.post("/detect") async def detect(file: UploadFile = File(...), conf: float = 0.25): img = Image.open(BytesIO(await file.read())).convert("RGB") result = model.predict(source=np.array(img), conf=conf, verbose=False)[0] items = [] for box, cls, c in zip(result.boxes.xyxy.cpu().numpy(), result.boxes.cls.cpu().numpy(), result.boxes.conf.cpu().numpy()): items.append({ "bbox": [round(float(x), 2) for x in box], "class": result.names[int(cls)], "confidence": float(c), }) return {"image_size": [int(img.size[0]), int(img.size[1])], "count": len(items), "detections": items}

模型在模块加载时实例化一次，避免每个请求重复读权重。convert("RGB")去掉了拍摄设备可能带的 alpha 通道。image_size返回宽高顺序需要注意，PIL 的size是 (width, height)，与 OpenCV 的shape相反，API 文档里写清楚。

启动服务：

uvicorn src.api:app --host 0.0.0.0 --port 8000 --workers 1

workers=1不是随便写的：每个 worker 都会在显存里复制一份模型，6G 显存最多同时放两个 yolov8n。并发不够时，正确方向是加队列和异步任务，而不是堆 worker。

测试接口：

curl -X POST http://127.0.0.1:8000/detect \ -F "file=@samples/road_021.jpg" \ -F "conf=0.25"

5.3 视频与 RTSP 流接入的抽帧设计

道路巡检视频本质上是一串高度重复的连续帧。病害不会在一帧内凭空消失，逐帧推理既浪费算力，又让下游存储爆炸。我通常按每秒 1 帧抽检：

import cv2 from ultralytics import YOLO model = YOLO("runs/pavement/v8n_1280/weights/best.pt") cap = cv2.VideoCapture("road_video.mp4") fps = cap.get(cv2.CAP_PROP_FPS) sample_interval = int(fps) frame_idx = 0 while True: ok, frame = cap.read() if not ok: break if frame_idx % sample_interval != 0: frame_idx += 1 continue frame_idx += 1 results = model.predict(frame, imgsz=1280, verbose=False) annotated = results[0].plot() cv2.imwrite(f"output/annotated/frame_{frame_idx:06d}.jpg", annotated) cap.release()

从 RTSP 拉流时只要把cv2.VideoCapture("rtsp://...")替换这一行即可。注意设置cv2.CAP_PROP_BUFFERSIZE，拉流端缓冲太大时只积压不解码，延迟会随时间累积到十几秒。抽帧策略要在漏检概率和算力之间折中：

6. 导出 ONNX 并做推理速度与精度的回归验证

6.1 导出 ONNX 与双引擎对比

训练完的平台不能直接用 pt 文件上线。pt 权重里带着训练组件，启动慢，还不适合用 onnxruntime 或 TensorRT 加速。我用下面的命令导出：

yolo export model=runs/pavement/v8n_1280/weights/best.pt \ format=onnx opset=12 dynamic=False simplify=True

dynamic=False固定输入尺寸，导出后的图对 TensorRT 更友好；simplify=True会去掉冗余算子，帮助减少推理耗时。导出后同样能用 ultralytics 的接口验证一致性：

import time import statistics from ultralytics import YOLO pt_model = YOLO("best.pt") onnx_model = YOLO("best.onnx") for m in (pt_model, onnx_model): times = [] for _ in range(50): t0 = time.perf_counter() m.predict("samples/road_021.jpg", imgsz=1280, verbose=False) times.append(time.perf_counter() - t0) times.sort() p50 = statistics.median(times) * 1000 p95 = times[-3] * 1000 print(f"{m.ckpt_path if hasattr(m, 'ckpt_path') else 'onnx'}: p50={p50:.1f}ms p95={p95:.1f}ms")

这里只统计前传时间，不包含预处理和后处理，作为一个横向对比的稳定基线。

6.2 平台接线上线前的四项验证

平台发布前我会过一遍下面的检查表，每一项都有明确通过标准：

最后给一个具体建议：把每周人工复核中发现的误检图单独放进hard_samples/目录，每次改完数据或调完参，用这批样本重跑同一份导出后的 ONNX，对比 bbox 抖动。如果某个原本正确的裂缝框在新版本里偏移超过 1 像素，不要只看 mAP 是否涨了，先回滚到上一版再继续调。这个回归集比验证集上的 0.1% 波动更能反映现场问题。

本文还有配套的精品资源，点击获取