基于YOLOv8的行人检测系统：从数据集到模型部署全攻略

简介基于YOLOv8的行人检测系统毕业设计项目包面向计算机相关专业正在准备毕设的学生以及需要完整项目实战练习的开发者。资源内含可运行源码、训练好的.pt模型权重及全部训练与测试数据覆盖从模型配置、训练脚本到结果输出的完整流程经导师指导并获得评审99分的高分认可代码结构清晰零基础用户也能按文档快速上手复现。压缩包共15个文件以jpg图片数据、pt模型权重、yaml配置文件、py训练脚本和txt说明文档为主整体大小约155.74MB适合作为课程设计、期末大作业或项目实战参考。目前已有116人学习使用。除核心检测逻辑外还提供多种模型规格与融合配置方便读者对比精度与速度深入理解YOLOv8在行人检测场景中的调优方法。1. 毕业设计拿到“基于YOLOv8的行人检测系统这个资源包能帮你省掉一半以上的前期时间打开某开源平台搜“基于yolov8的行人检测系统 源码训练好的模型全部数据”结果一页一页。很多同学毕设题目就落在这个方向上但真正动手时才发现光有源码没有权重推理是一张全黑的图光有模型没有数据答辩老师一问“你的训练集怎么来的”就卡壳。这个标题把源码、模型、数据三样东西打包在一起意味着你可以跳过从零训练行人检测器最耗时的数据标注和模型调试阶段直接拿到一个能跑的基线系统再按毕设要求做界面、加功能、优化指标。它适合本科毕业设计、课程设计也适合第一次接触目标检测、想快速体验“训练到部署”闭环的读者。但别指望解压就能答辩——你要搞清楚模型是哪个数据集训的、类别索引是不是0、数据格式和你本机环境是否匹配。这些下面一一拆开讲。2. 为什么是YOLOv8做行人检测选型逻辑、环境搭建和代码包结构2.1 YOLOv8的网络结构对行人检测友好在哪里行人检测是目标检测的子问题YOLOv8能做到高帧率和接近两阶段检测器的精度是工程落地的首选。YOLOv8主要有四处改动主干里的C2f模块替代了YOLOv5的C3等价于用更多的跨层连接让梯度流动更充分检测头改成了Anchor-Free直接预测目标中心与宽高少了一组锚框超参数分类与回归分支解耦训练收敛更快Neck部分保留FPNPAN多尺度特征对大小行人都能覆盖。从行人检测的角度看Anchor-Free FPN/PAN的组合在常规场景下漏检率比旧版更低尤其对密集站立的人群。更关键的是Ultralytics把训练、验证、导出、部署封装成一条命令这对毕业设计需要反复改参数调实验非常省时间。2.2 在Ubuntu 20.04上搭建YOLOv8环境CPU版也能跑环境搭建是拿到源码包后的第一道门槛。搜“ubuntu20.04搭建yolov8环境cpu版本”的同学很多其实步骤非常少。通过conda隔离Python版本能避免很多依赖冲突。conda create -n yolov8 python3.10 -y conda activate yolov8 pip install ultralytics pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu先装CPU版PyTorch再装ultralytics是为了避免pip自动拉取CUDA版torch导致磁盘占用过高。如果你的笔记本有NVIDIA显卡比如GTX 1660Ti以上想把训练放在GPU上就不要指定cpu的index-url直接把torch和ultralytics一起装pip install ultralytics python -c import torch; print(torch.cuda.is_available())最后一行输出True说明GPU可用。注意ultralytics当前版本要求Python 3.8以上建议3.10Python 3.12某些旧版本依赖会报编译错误。2.3 验证安装用官方COCO权重跑一张图环境配好后先在源码包外验证ultralytics本身没问题。使用官方YOLOv8n权重对官方示例图推理python - PY from ultralytics import YOLO model YOLO(yolov8n.pt) # 首次运行会自动下载权重 results model(https://ultralytics.com/images/bus.jpg, saveTrue) print(results[0].boxes) PY看到输出里包含person类别说明环境正常。此时你用的模型是COCO 80类预训练权重其中person是第0类。但注意COCO的person和第3章要用的行人检测数据集不能直接画等号COCO里person包含各种姿态和尺度背景简单而行人检测数据集往往有密集遮挡、夜间/雨天场景。所以毕设项目如果提供了专门在行人数据上训练好的权重推理脚本里的类别索引必须改过来否则会用80类的头去预测1类数据集的标签几乎什么都检测不到。2.4 先摸清源码包的目录结构再动手每个毕设打包的目录都不一样但通常会有这几个东西源码train.py/detect.py、训练好的权重best.pt/last.pt、数据集images/labels和说明README。我一般会先执行find . -maxdepth 2 -type d看一眼大目录再重点看三个文件data.yaml数据集配置、best.pt验证集上最优权重、predict.py推理脚本。用Python快速比较best.pt和last.pt的差异import torch a torch.load(weights/best.pt, map_locationcpu)[model] b torch.load(weights/last.pt, map_locationcpu)[model] print(a.__dict__.get(names), b.__dict__.get(names))如果两个权重的names不一致说明训练过程中类别映射出了问题这种情况在网上下载的模型里并不少见。拿到源码包后第一件事不是跑训练而是确认模型输出类别和你将要用的数据类别对得上这一步能避免后面所有推理结果都是空的。3. 行人检测数据集怎么准备从标注格式到训练集划分3.1 标题里的“全部数据”到底是什么格式标题写的“全部数据”通常指已经整理成YOLO格式的行人检测数据集目录大概是images/train、labels/train、images/val、labels/val。但也有很常见的例外数据是COCO JSON标注或者LabelMe导出的*.json。打开一个标注文件看看ls datasets/person/labels/train/ | head -5 sed -n 1p datasets/person/labels/train/000001.txt第二行输出如果是0 0.52 0.31 0.18 0.42这类五个数就是YOLO格式可以直接用。如果看到的是[{image_path:...}]这种JSON结构说明还需要转换。很多网上打包的数据集不会告诉你细节因此我的习惯是先花两分钟统计标签分布awk {count[$1]} END {for (k in count) print k, count[k]} datasets/person/labels/train/*.txt输出里如果只出现0说明是单类行人检测出现0 1 2则要注意是不是包含“行人”、“骑行者”、“背景”等多类。毕设答辩时会问“你的模型能检测哪几类”所以这个分布必须提前搞清楚。3.2 把COCO JSON转换成YOLO格式bbox转换脚本如果你的“全部数据”是COCO格式常见于CrowdHuman、COCO-Person等大型行人数据集需要把JSON里的bbox从[left, top, width, height]转成YOLO需要的[x_center, y_center, width, height]并归一化。下面这段脚本是常见做法可以处理单类或多类并生成一个类别映射文件。import json import os from pathlib import Path def coco_to_yolo(json_path, out_dir): with open(json_path, r, encodingutf-8) as f: coco json.load(f) cat_id_map {c[id]: i for i, c in enumerate(coco[categories])} Path(out_dir).mkdir(parentsTrue, exist_okTrue) for img in coco[images]: w, h img[width], img[height] stem Path(img[file_name]).stem lines [] for ann in coco[annotations]: if ann[image_id] ! img[id]: continue x, y, bw, bh ann[bbox] cx (x bw / 2) / w cy (y bh / 2) / h nw, nh bw / w, bh / h lines.append(f{cat_id_map[ann[category_id]]} {cx:.6f} {cy:.6f} {nw:.6f} {nh:.6f}) if lines: Path(out_dir, f{stem}.txt).write_text(\n.join(lines), encodingutf-8) coco_to_yolo(annotations.json, labels/train)这段脚本把COCO bbox左上角坐标转成归一化中心坐标。注意三个坑一是COCO的类别ID不连续比如person可能是1但YOLO要求类别从0开始连续编号所以必须重建cat_id_map二是有些数据集的文件名带子目录Path(file_name).stem只取文件名可能重名建议先os.path.relpath保留子目录三是ann里可能存在无效框宽高为0或坐标越界转换前最好过滤。3.3 LabelMe标注如何转成YOLO格式如果“全部数据”是LabelMe标注的JSON格式是shapes里的多边形点集没有直接的bbox。都要转成外接矩形然后做同样的归一化。下面是常用的转换片段import json import glob def labelme_to_yolo(json_file, out_dir): with open(json_file, r, encodingutf-8) as f: data json.load(f) w, h data[imageWidth], data[imageHeight] stem Path(json_file).stem lines [] for shape in data[shapes]: if shape[label] ! person: continue xs [p[0] for p in shape[points]] ys [p[1] for p in shape[points]] x1, y1, x2, y2 min(xs), min(ys), max(xs), max(ys) bw, bh x2 - x1, y2 - y1 cx, cy (x1 x2) / 2, (y1 y2) / 2 lines.append(f0 {cx/w:.6f} {cy/h:.6f} {bw/w:.6f} {bh/h:.6f}) Path(out_dir, f{stem}.txt).write_text(\n.join(lines), encodingutf-8)这段代码把LabelMe多边形的最小外接矩形当作目标框。如果标注时用矩形框shape[points]恰好只有两个顶点逻辑同样成立。注意类别名要和后续data.yaml里的names保持一致比如这里用的label是personnames: [person]序号0对应person。如果数据里有多个类别比如person、rider、background得先确认毕设到底要做单类还是多类检测不相关的类先去掉否则会影响mAP计算。3.4 划分训练集与验证集别把同一个场景的照片分到两个集合数据转换完成后需要把图片和标签划分成train和val。用random.shuffle直接分会有个坑连续抓拍的背景高度相似如果同一场景的帧被拆分到训练和验证验证指标会虚高。建议按图片所在目录分组切分至少保证视频帧序列不分家。一个简单粗暴的方式是按文件名前缀分组import os import random from pathlib import Path source_images datasets/person/all_images source_labels datasets/person/all_labels random.seed(42) images sorted(Path(source_images).glob(*.jpg)) random.shuffle(images) split_point int(len(images) * 0.8) train_imgs images[:split_point] val_imgs images[split_point:] for subset, img_list in [(train, train_imgs), (val, val_imgs)]: Path(fdatasets/person/images/{subset}).mkdir(parentsTrue, exist_okTrue) Path(fdatasets/person/labels/{subset}).mkdir(parentsTrue, exist_okTrue) for img in img_list: os.rename(img, fdatasets/person/images/{subset}/{img.name}) lbl Path(source_labels) / (img.stem .txt) if lbl.exists(): os.rename(lbl, fdatasets/person/labels/{subset}/{lbl.name})这个脚本使用随机分割但设置了随机种子。它能跑通的前提是所有图片都在同一个目录如果源码包的数据本身已经按train/val组织好就跳过这一步。切完以后检查一下ls datasets/person/images/train | wc -l ls datasets/person/labels/train | wc -l数目不一致说明有图片没有对应标签训练时YOLO会忽略这些图片但如果缺口太大训练集会缩水最好找回来。3.5 写data.yaml路径、类别数和namesYOLOv8用data.yaml描述训练数据。下面是一个单类行人检测的完整示例path: /home/yourname/datasets/person # 绝对路径不要写相对路径 train: images/train val: images/val nc: 1 names: 0: person建议path写成绝对路径因为训练命令的工作目录不一定是项目根目录相对路径经常会报“dataset not found”。如果你把数据放在项目目录内也可以写成path: datasets/person但必须确认路径从当前目录是可达的。nc: 1对应单类names的索引从0开始。验证配置是否正常from ultralytics.data import YOLODataset ds YOLODataset(data.yaml, imgsz640) print(len(ds))如果能打印出数据集长度说明路径和标签格式都能被YOLO解析。不能解析时会直接报错这时候按第5章里的排查方法检查标签内容即可。4. 用YOLOv8训练行人检测模型命令、参数和损失曲线4.1 从预训练权重微调省一半时间既然毕设项目给了训练好的模型你可以选择直接做二次微调用yolov8n.pt这个在COCO上预训练过的权重作为起点。常见做法是yolo train datadata.yaml modelyolov8n.pt epochs50 imgsz640 batch16 device0 namepedestrian_finetune这里modelyolov8n.pt会自动下载COCO预训练权重建模并将最后的输出类别数自动调整为data.yaml里的nc1。如果不想下载也可以指向本地已有的权重yolo train datadata.yaml modelruns/detect/person_baseline/weights/best.pt epochs30 imgsz640 batch8 device0把之前训出来的best.pt当初始权重继续训练适合你已经有一版模型、想让它在新增数据上再提升的情况。只用单类训练50个epoch在GTX 1660Ti上大约需要40分钟到1小时CPU上则可能要跑一夜。毕设时间紧的话一次训练用epochs30先看收敛趋势即可。4.2 训练命令的必调参数imgsz、batch、device、patience上述命令里几个参数直接影响训练成败。imgsz是输入分辨率行人检测用小目标多建议设为640或更高设成320会加速但漏检明显增加batch受显存限制可以先设16OOM就降到8或4device0指定用第一块GPUCPU训练则写devicecpu。patience是早停耐心值默认50个epoch内验证指标没有提升就停数据量小、指标波动大时可以调大到20。还有一个容易被忽略的cache参数建议设cacheTrue会把图片缓存进内存或磁盘减少磁盘IO等待yolo train datadata.yaml modelyolov8n.pt epochs100 imgsz640 batch16 device0 cacheTrue nameperson_v1缓存会占约两倍图片集大小的内存不够则写cachedisk。这在普通机械硬盘上训练时提速非常明显。4.3 训练过程中的监控从震荡的loss到稳定的mAP50训练开始后终端会每个epoch打印一行train/box_loss、cls_loss、dfl_loss、val/box_loss、metrics/precision(B)、recall(B)、mAP50(B)等。毕设答辩时需要展示“模型如何收敛”最直观的是看训练结束后自动生成的曲线图。训练完的目录里有个runs/detect/person_v1/results.png里面包含所有loss曲线和mAP曲线。如果你想自己画某一次实验的损失函数曲线图也可以读CSV再画import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(runs/detect/person_v1/results.csv) plt.figure(figsize(10, 4)) plt.plot(df[epoch], df[train/box_loss], labeltrain box_loss) plt.plot(df[epoch], df[val/box_loss], labelval box_loss) plt.xlabel(epoch) plt.ylabel(loss) plt.legend() plt.savefig(loss_curve.png)看曲线的时候注意一个现象train loss持续下降但val mAP50不涨大概率是过拟合已经发生此时可以回退到val mAP最高的那个epoch也就是weights/best.pt。ultralytics每次训练完成都会在runs/detect/person_v1/weights/下写出best.pt和last.pt毕设最终要用的永远是best.pt。4.4 训练中断了怎么办断点续训长训练的时候断电或内存崩溃很常见。last.pt就是为断点续训准备的。恢复训练命令yolo train resume modelruns/detect/person_v1/weights/last.pt系统会自动读取之前训练到第几个epoch、优化器状态和数据配置继续往下跑。注意恢复训练时必须使用和之前相同的代码版本和data.yaml路径否则可能出现类别不匹配或数据重新分割的问题。另外如果你想修改学习率或增强参数再继续别用resume建议用modellast.pt但不加resume从头以新的配置继续。5. 避坑指南行人检测项目最常见的5个翻车点5.1 现象训练刚开始就OOM显存爆掉很多人在GTX 1660Ti 6G显存上训练默认batch16直接OOM。原因是yolov8l或yolov8x在640分辨率下显存占用很高。先检查你用的模型是n/s/m/l/x哪一档。解决方法是换小模型或降batchyolo train datadata.yaml modelyolov8s.pt imgsz640 batch8 device0如果还是OOM把batch4、imgsz480或者开启梯度累积。ultralytics的yolo train没有单独的梯度累积参数但通过增大batch并配合device0可以调如果条件有限直接用yolov8n并设imgsz640 batch4在6G显存上能跑。5.2 现象训练到一半val mAP50一直是0最常见的原因是data.yaml的类别和标签文件里的类别ID对不上。比如标签里是0 0.5 0.5 0.1 0.1但data.yaml里names: [person, rider]模型以为有两个类实际上没有类别1的样本训练时criterion报错或者强行忽略。解决办法是用前面统计标签分布的方法查看类别索引然后修改data.yaml保证nc等于实际类别数。还有一种原因是标签坐标是绝对像素值而不是归一化值导致IoU计算失败。可以抽样一帧图片画框验证import cv2 img cv2.imread(datasets/person/images/train/000001.jpg) h, w img.shape[:2] with open(datasets/person/labels/train/000001.txt) as f: for line in f: cls, cx, cy, bw, bh map(float, line.split()) x1 int((cx - bw/2) * w) y1 int((cy - bh/2) * h) x2 int((cx bw/2) * w) y2 int((cy bh/2) * h) cv2.rectangle(img, (x1, y1), (x2, y2), (0,255,0), 2) cv2.imwrite(check.jpg, img)如果框位置明显偏移或超出图像范围就是标签归一化出了问题。5.3 现象小目标和遮挡行人漏检严重行人检测数据集里远处的小目标和互相遮挡的行人是最难的部分。YOLOv8默认输入640小目标只有几个像素特征提取阶段就容易丢。解决方向有三个把imgsz从640提升到960或1280虽然训练变慢但对小目标提升明显在data.yaml里关闭过强的mosaic增强因为mosaic会进一步缩小目标占比使用官方提供的--augment默认配置也可以在推理时用TTA但毕设系统一般不用TTA因为太慢。更实际的做法是调整推理时的conf和iouyolo predict modelbest.pt sourcecrowd.jpg conf0.2 iou0.4conf0.2能召回更多候选框但误检也变多iou0.4比默认0.7的NMS更激进能保留被压制的重叠框。在密集行人场景下IOU调低比调conf更有用。5.4 现象模型推理结果全是0一个框都没有如果你是直接用官方yolov8n.pt对行人照片推理通常能检出但换成自己训练好的best.pt后没人一般在模型类索引和数据类别对不上。自己训练的模型类别索引从0开始但如果data.yaml里names是[person]而推理脚本里names引用了COCO的80类表就会出错。解决方法是直接用模型自带namesmodel YOLO(best.pt) names model.names # {0: person} 这才是模型真实的类别映射不要在推理脚本里硬编码COCO类别名。另一个原因是输入图片通道数不对有些灰度图被读成3通道后模型虽然不报错但预测效果极差。用cv2.imread读图后确认img.shape是(H, W, 3)。5.5 现象CPU推理速度极慢误以为是代码死循环用CPU跑YOLOv8n单张640图片耗时大约在0.5秒到2秒之间这在笔记本上算正常。慢的往往不是推理本身而是视频帧读取、图像缩放和画框后存储阻塞。优化顺序是先确保输入帧尺寸不超过640用letterbox而不是直接resize再用yolo predict带halfTrue试图半精度推理CPU不支持的话会提示错误最后把视频写入从cv2.VideoWriter改成不带质量压缩的avi编码能显著降低写盘时间。如果你是在Ubuntu 20.04上用纯CPU跑还建议编译OpenVINO版本ultralytics里直接指定deviceopenvino就能用Intel核显加速速度能提升一倍多yolo predict modelbest.pt sourcevideo.mp4 deviceopenvino上面这个操作不用改代码适合演示现场快速出效果。注意openvino只支持Intel芯片AMD或Apple Silicon无效。6. 让毕设更好交差推理脚本、模型导出和版本管理的一个小习惯6.1 写一个能对图片、视频、摄像头同时生效的推理入口源码包里通常会有detect.py但很多时候只支持一种输入。我习惯封装成三选一用socket或命令行参数控制import argparse from ultralytics import YOLO parser argparse.ArgumentParser() parser.add_argument(--source, typestr, default0, helpimage_path or video_path or 0 for camera) args parser.parse_args() model YOLO(runs/detect/person_v1/weights/best.pt) results model(args.source, conf0.3, iou0.5, imgsz640, saveTrue, vid_stride2) for i, r in enumerate(results): print(f{i}: {len(r.boxes)} persons detected)vid_stride2表示视频每隔一帧处理一次省掉一半计算量。摄像头输入源写0会自动打开默认摄像头毕设演示时非常方便。6.2 导出ONNX或TensorRT防止答辩现场没有PyTorch环境下载的源码包里最常缺的是部署环境。最好提前把best.pt导出成ONNX就算答辩电脑没有GPU和ultralytics也能用OpenCV的DNN模块跑。导出命令yolo export modelruns/detect/person_v1/weights/best.pt formatonnx dynamicTrue opset12导出后得到best.onnx。验证一下它和PyTorch模型输出是否一致import onnxruntime as ort import numpy as np session ort.InferenceSession(best.onnx) input_name session.get_inputs()[0].name outputs session.run(None, {input_name: np.random.randn(1, 3, 640, 640).astype(np.float32)}) print([o.shape for o in outputs])形状通常是(1, 84, 8400)如果没有输出C2f分支的dlf模块也是正常的。如果你后面要上RK3588等嵌入式板子优先导出成formatrknn的中间格式这个标题的热搜里也提到过RK3588部署YOLOv8假设你和作者都打算往边缘端做那ONNX这步必须验证无误否则转移到瑞芯微的NPU上会踩一堆算子不支持的坑。6.3 把毕设交付变成可复现的工程一个README和一个requirements.txt最后想分享一个我自己的交付习惯不管源码包里原本有什么在提交毕设前花10分钟写一个最小化requirements.txt和README.md。requirements.txt只写ultralytics8.x.x、opencv-python、torch这几行不锁定过多版本README里写清楚“训练好的模型在weights/best.pt测试图片放在demo/images运行python detect.py --source demo/1.jpg即可看到结果”。这个东西能让老师或其他同学在一台新机器上5分钟跑通也能让两周后的你快速捡起代码。我见过太多毕设项目因为没有README作者自己答辩前都忘了模型是从哪个数据集训的。把这个习惯带上你的“基于YOLOv8的行人检测系统”就不只是一个压缩包而是一个可以被复现、被评分的完整工程。希望帮到你。本文还有配套的精品资源点击获取