简介基于YOLOv8的行人检测项目源码包面向计算机视觉方向的学生与开发者尤其适合有课程设计、毕业设计需求的高校学习者。代码均测试运行成功训练与视频检测两类Python脚本齐备配套数据集说明文档可直接复现完整训练与推理流程拿来即可上手。资源共6个文件以pt模型权重、py脚本和txt说明文档为主权重选用YOLOv8n、YOLO11n轻量版本压缩包约15.89MB部署门槛低。训练产出包含核心指标曲线、混淆矩阵、F1分数曲线、PR曲线、验证集预测结果及标签分布图可直观展示模型性能便于答辩与汇报。已有36人学习下载适合作为行人检测方向的入门项目或二次开发基础。1. 基于YOLOv8的行人检测项目一个能直接跑通的课设资源基于YOLOv8的行人检测项目是一个把训练、验证、推理整条链路都打包好的课程设计资源。资源包里有yolov8n.pt预训练权重、best.pt训练好的成果权重、train_mode.py训练脚本、Detection_video.py视频检测脚本外加一份README.dataset.txt数据集说明。适合计科、人工智能、自动化这类专业的在校生做课设或毕设起步也适合刚入门目标检测的新手照着复现。它解决的不是手写一个检测算法而是用最少的配置成本跑通一个能答辩、能演示的行人检测流程。我在实际拆解时发现真正耗时间的不是训练本身而是环境配置、权重版本匹配和数据说明这三件事。这个包把这三件事做了基本兜底下面按我的拆解顺序从项目结构讲到坑再讲到验证和进阶整体走一遍。2. 项目结构与环境配置先看清资源包再动手2.1 资源包文件清单每个文件各自的定位拿到的压缩包解开后核心文件一共六个加上一个数据集说明文件。我把它们整理成一张表方便你对号入座。文件类型作用使用时机yolov8n.pt预训练权重YOLOv8n 官方 COCO 预训练模型训练初始化用训练启动时加载yolo11n.pt预训练权重YOLO11n 官方权重ultralytics 新版本模型备选初始化或对比实验best.pt训练产物训练过程中验证集指标最优的权重推理、答辩演示train_mode.pyPython 脚本训练入口封装数据集配置与超参数训练阶段Detection_video.pyPython 脚本视频/图片推理脚本加载 best.pt 出结果推理阶段README.dataset.txt文本文档数据集说明含类别、目录结构、标注格式动手前必读有些同学拿到压缩包第一件事就是双击 train_mode.py这是最容易翻车的。yolov8n.pt 是 COCO 80 类预训练权重行人检测任务一般只需要 person 一个类直接用预训练权重推理也能出框但精度和边界框质量达不到课设展示标准。正确做法是先读 README.dataset.txt确认数据集里标签是 YOLO 格式的 txt 还是 VOC 的 xml再决定训练脚本怎么改。best.pt 是训练完的产物它是 yolov8n.pt 在你的数据集上微调后的结果。这个文件的来历很关键如果训练 epoch 太少或者数据量只有几十张best.pt 的泛化能力是有限的。我一般会在拿到资源后先做一次快速推理验证确认 best.pt 在真实摄像头画面或短视频里的表现再决定是直接用于答辩还是重训一轮。2.2 环境配置版本匹配是第一道门槛YOLOv8 项目跑不起来八成问题出在环境版本上。这个包依赖 ultralytics 框架、PyTorch 和 OpenCV三者的版本必须互相兼容。我建议用 conda 单独建一个虚拟环境不要跟系统 Python 混在一起否则后面装 torch 时容易把 base 环境搞坏。conda create -n yolov8 python3.9 -y conda activate yolov8 pip install ultralytics8.2.0 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118 pip install opencv-python第一行创建 Python 3.9 的虚拟环境yolov8 对 3.9 的兼容性最稳3.10 以上也能跑但部分旧版 ultralytics 在 3.11 上会有 warnings。第二行装 ultralytics 8.2.0这个版本配 yolo11n.pt 没有问题。第三行装 CUDA 11.8 版 PyTorch如果你的显卡驱动只支持 CUDA 12.x把 cu118 换成 cu121 即可。GTX 1660Ti 用户照这个配置跑 yolov8n 完全没问题显存 6GB 足够支撑 batch 16 的训练。装完后在命令行输入yolo看是否能弹出帮助信息再输入python -c import torch; print(torch.cuda.is_available())确认 GPU 可用。输出 True 才能继续否则你的训练会落到 CPU 上yolov8n 在 CPU 上跑一个 epoch 可能要十几分钟直接劝退。这一步是整个项目最基础的体检体检不过就别急着碰 train_mode.py。2.3 yolov8n 与 yolo11n行人检测场景下的模型选型这个资源包里同时出现了 yolov8n.pt 和 yolo11n.pt很多新手会困惑两个都能加载到底用哪个YOLOv8n 是 YOLOv8 系列里最轻量的版本参数量约 3.2M计算量 8.7 GFLOPs在 GTX 1660Ti 上单张 640x640 图片推理大约 30~50ms。YOLO11n 是 ultralytics 后续推出的新版本nano 体量差不多但 C2f 模块换成了 C3k2推理速度略有提升。我的建议是如果是课程设计、毕业设计这种以稳定为主的场景优先用 yolov8n.pt 做训练初始化。原因很简单YOLOv8 的资料最多答辩时老师问网络结构你讲 C2f 和 anchor-free head一问一个准。yolo11n 更适合做对比实验比如用同一份数据集分别训 v8n 和 11n把两个模型的 mAP 曲线放在一起这种对比本身就是课设的加分项。从网络结构角度看YOLOv8n 的 backbone 是 CSPDarknet 结构核心模块是 C2f它把梯度分流做得更细特征复用效率高。head 部分采用 decoupled head 设计分类和回归分两个分支配合 anchor-free 策略使得行人这类小目标检测稳定性比 YOLOv5 好。理解这一点你就知道为什么训练脚本里默认输入尺寸是 640 而不是 416 了——分辨率太低行人这种小目标在下采样 32 倍后会丢失大量细节。3. train_mode.py 训练实战参数、数据与指标图全拆解3.1 数据集目录规范与 data.yaml 配置训练前必须先确认数据集的目录结构。YOLOv8 的标准目录是 images 和 labels 两个文件夹各自分成 train 和 val 子集。我在拆这个包时发现README.dataset.txt 里通常会写明数据来源和标注格式如果是从 Roboflow 或 Labelimg 导出的大概率是 YOLO 格式目录结构长这样datasets/ ├── images/ │ ├── train/ │ │ ├── img_001.jpg │ │ ├── img_002.jpg │ └── val/ │ ├── val_001.jpg └── labels/ ├── train/ │ ├── img_001.txt │ ├── img_002.txt └── val/ ├── val_001.txt每个 txt 文件里是标注信息格式是class_id x_center y_center width height坐标全部归一化到 0~1 之间。比如0 0.5146 0.4352 0.1562 0.4127表示一个类别 id 为 0 的目标中心点在图片横向 51.46%、纵向 43.52% 的位置。这个格式是 YOLO 系列的通用交换格式如果你的标签是 VOC 的 xml需要先转换成 txt 再训练。data.yaml 是训练脚本读取的核心配置文件train_mode.py 一般会调用它。如果你的项目里没有单独的 yaml那大概率是写在 train_mode.py 里。常见内容如下path: ./datasets # 数据集根目录相对路径或绝对路径 train: images/train val: images/val nc: 1 # 类别数量行人检测只检测人所以是 1 names: 0: person这里最容易出错的是 path 字段。如果训练时提示找不到图片文件先检查 path 是不是相对当前工作目录写的。我习惯把所有数据放在项目根目录下然后 path 写成./datasets这样不管从哪个终端启动都能定位。另一个坑是 nc 必须和 names 长度一致你标了 person 和 car 两类nc 却写 1训练不会报错但 mAP 计算会乱掉。3.2 训练脚本参数拆解epochs、batch 与 imgsz 怎么调train_mode.py 的核心逻辑其实就十几行基于 ultralytics 的封装。我按常规写法拆解一下这个脚本你打开自己的 train_mode.py 对照着改就行。from ultralytics import YOLO if __name__ __main__: model YOLO(yolov8n.pt) # 加载 COCO 预训练权重作为初始化 model.train( data./datasets/data.yaml, # 数据集配置文件路径 epochs100, # 训练轮数课设建议 100 轮起步 batch16, # 每批图片数量6GB 显存跑 n 模型安全值 imgsz640, # 输入分辨率行人小目标建议保持 640 patience20, # 连续 20 轮验证指标不提升就早停 device0, # 0 表示第一块 GPU没有 GPU 改成 cpu workers4, # 数据加载线程数 saveTrue, # 保存训练过程中的权重 project./runs/detect, # 训练结果输出目录 nametrain1 # 本次实验命名避免覆盖上一次结果 )这段代码里最关键的是 batch 和 imgsz 的搭配。GTX 1660Ti 是 6GB 显存yolov8n 在 imgsz640 下每张图大约占用 250~400MB 显存batch16 是安全上界开到 32 直接 OOM。如果你显卡显存只有 4GBbatch 降到 8或者把 imgsz 降到 512但行人检测不推荐降分辨率会造成小目标漏检。patience20 配合 epochs100 是个性价比很高的组合数据好的时候 50 轮就收敛了数据差也不会硬跑完 100 轮浪费时间。workers 参数容易被忽略Windows 系统下 workers 大于 0 偶尔会触发 DataLoader 的 bug报一个 Broken pipe 错误。遇到这个问题把 workers 改成 0 就能解决但代价是数据加载变慢训练每个 epoch 会多花一点时间。如果换不换都行优先保证训练能跑起来再谈效率。训练启动后终端会实时打印进度条包含每个 batch 的 loss、GPU 利用率、当前学习率等信息。这一步相当于给训练过程拍 CT看到 GPU 利用率在 90% 以上说明数据加载没有成为瓶颈如果 GPU 利用率一直在 30% 以下徘徊多半是 workers 太小或者 CPU 性能跟不上加线程数能缓解。3.3 训练产物与六类指标图解读答辩怎么讲训练结束后runs/detect/train1 目录下会生成一堆文件这是整个资源包最值钱的部分也是答辩评审最关注的证据。我按重要性列一张清单标注每张图该怎么说。文件内容答辩讲法results.png损失函数曲线和 mAP 曲线展示 loss 收敛趋势训练稳定无过拟合confusion_matrix.png混淆矩阵说明误检和漏检集中在哪些类别F1_curve.pngF1 分数随置信度变化曲线找到最佳置信度阈值展示综合精度PR_curve.png精确率-召回率曲线mAP 的来源曲线下面积越大越好val_batch*_pred.jpg验证集预测结果直接证明模型能正确框出行人labels.jpg标签分布图展示数据集中目标的位置和大小分布results.png 是最核心的一张图上面有多条曲线损失函数曲线包括 train/box_loss、train/cls_loss、val/box_loss 等。我看这张图有个习惯先看 val 损失是不是在 epoch 中段开始反弹如果 val 损失先降后升而 train 损失持续下降说明过拟合了。此时需要加大数据增强或者降低 epochs。训练结束时 val/box_loss 在 0.02 以下、val/cls_loss 在 0.01 以下基本就是可用状态。confusion_matrix.png 能直接看出你的模型把行人误检成什么了。背景和 person 之间的误检值是重点数值超过 10% 说明大量背景被当成行人这时候需要提高置信度阈值或者检查数据里是否有大量形似行人的负样本。PR_curve.png 和 F1_curve.png 看曲线的拐点F1 曲线的顶点横坐标通常是最佳置信度阈值推理时把这个值填进 conf 参数比默认的 0.25 效果好。4. 避坑实录训练与推理的四个常见问题4.1 训练正常结束但 mAP 为 0先查标签现象训练流程走完终端打印的 mAP50 和 mAP50-95 都是 0但 loss 在下降。打开 val_batch*_pred.jpg 发现图上一个框都没有。原因这是典型的数据集标签错位。最常见的情况是 labels 目录里对应的 txt 文件为空或者标注坐标超出了 0~1 范围。YOLO 格式要求坐标归一化到 0~1 之间如果你从 VOC 转 YOLO 时没有做归一化坐标值还是像素级模型训练时会把这些越界框全部丢弃。解决先随机抽一个训练样本的 txt 打开检查每行的四个数值是否都在 0~1 区间。再用脚本统计目录下所有非空标签文件的数量和图片数量是否对应我在拆这个包时习惯写一段检查脚本把空标签和越界标注一条条过滤出来。4.2 显存溢出 OOM6GB 显卡的 batch 边界现象训练跑到第一个 epoch 中途终端报 CUDA out of memory进程直接杀掉。重启后换了 batch2 才能跑但速度慢到怀疑人生。原因ultralytics 默认开启了 AMP 混合精度训练理论上显存占用会降低但前提是 PyTorch 版本和 GPU 驱动兼容。GTX 1660Ti 的 6GB 显存跑 yolov8nbatch16 是上限如果同时开着 TensorBoard 或者系统桌面占用显存就会在边缘触发 OOM。解决把 batch 降到 8 基本能稳定跑完。还有一个冷门技巧是给 PyTorch 设置显存缓存清理在 train 前加一行torch.cuda.empty_cache()。另外检查一下进程管理器关掉不必要的占用显存的程序再训练。4.3 权重加载报错yolo11n.pt 与 ultralytics 版本不匹配现象YOLO(yolo11n.pt) 加载时报错提示 Unknown model or incompatible weights但加载 yolov8n.pt 一切正常。原因yolo11n 是 YOLO11 系列的权重需要 ultralytics 8.3.0 以上的版本才能识别。如果你的环境装的是 8.0 或 8.1 的旧版加载新权重自然失败。反过来新版 ultralytics 加载 yolov8n.pt 也有兼容层但偶尔会出现警告。解决直接在命令行执行pip install -U ultralytics升级到最新版。升级后要注意新版框架的训练结果输出结构可能略有变化代码里如果硬编码了 runs/detect/train 路径需要同步调整。4.4 视频推理卡顿丢帧Detection_video.py 的性能瓶颈现象用 Detection_video.py 跑一个 1080p 视频画面明显卡顿检测框跳来跳去像是掉帧。原因默认参数下模型每一帧都做完整推理没有做跳帧处理而且视频读取和显示都在主线程里帧率上不去。GTX 1660Ti 跑 yolov8n 单帧推理 30~50ms理论上限 20~30 FPS但加上画面绘制和窗口显示实际能到 15 FPS 就不错了。解决推理脚本里加一个跳帧逻辑每 3 帧处理一次中间两帧直接复用上一次的检测结果。行人移动速度不快跳 2 帧完全不影响体验。另外把视频帧缩放到 640x640 再送进模型不要用 1080p 原图分辨率不对会拖慢预处理。5. Detection_video.py 推理与验收从可视化到可复现5.1 推理脚本参数与命令行用法Detection_video.py 加载的是 best.pt不是训练前的预训练权重。这两个混用是新手最容易犯的错误用 yolov8n.pt 推理出来的框是 COCO 80 类的结果虽然也能框住行人但那是通用模型的能力不能代表你的训练成果。正确姿势如下from ultralytics import YOLO model YOLO(best.pt) # 加载训练后的最优权重 results model.predict( sourcetest_video.mp4, # 视频路径摄像头就填 0 conf0.35, # 置信度阈值F1 曲线顶点附近最佳 iou0.45, # NMS 的 IoU 阈值 saveTrue, # 保存标注后的视频 imgsz640, # 与训练时保持一致 vid_stride3 # 每 3 帧推理一次跳帧加速 )conf 参数决定置信度门槛调太高会漏检远处行人调太低会出一堆误检。我一般先跑一次看 F1_curve.png 的顶点比如顶点在 0.35推理就填 0.35。iou 是 NMS 的抑制阈值行人密集的场景适当调到 0.4减少重叠框。vid_stride3 是跳帧策略一次推理跳过 2 帧画面流畅度明显提升而检测结果几乎无感。5.2 进阶导出 ONNX 与边缘设备部署如果想把 best.pt 用到树莓派或 RK3588 这类边缘设备上需要先转成 ONNX 格式。ultralytics 提供了一个命令行入口一行搞定yolo export modelbest.pt formatonnx imgsz640 opset12导出的 best.onnx 可以直接用 onnxruntime 推理也可以在 RK3588 上通过 RKNN-Toolkit2 转成 rknn 格式部署。这里我踩过一个坑导出时 imgsz 必须和训练时一致否则模型输入尺寸对不上部署端预处理稍不注意就报维度错误。建议导出后先用 onnxruntime 跑单张图片验证输出再往板子上搬。拿到任何 YOLO 项目我都强制自己先看 README.dataset.txt再验 best.pt 推理最后才改代码训练这套顺序走了很多次省掉的都是查环境问题的时间。毕竟课设答辩最尴尬的不是模型不够准而是现场演示时脚本起不来。希望这份拆解能帮你少走一段弯路尽快让项目跑起来、看得见结果。本文还有配套的精品资源点击获取