简介YOLOv8深度学习框架源码与说明文档已整理为一份rar压缩包面向计算机、电子信息工程、数学等专业大学生可作课程设计、期末大作业或毕业设计阶段的参考资料。包内共155个文件主体包含66个Python脚本、41个YAML配置文件、23个Markdown说明文档其中Python脚本覆盖数据加载、模型训练、验证推理等环节YAML文件定义了模型结构、训练超参与数据集路径Markdown文档提供使用说明与二次开发指引另有Dockerfile、Shell脚本、样式表等环境与辅助文件整体仅938KB轻量易获取。目前已有652人学习或下载适合具备一定编程基础、能自行调试并扩展功能的读者。通过这份源码与文档可快速掌握YOLOv8的目录组织方式、模型配置方法及训练推理流程也能在此基础上修改网络模块、调整训练参数或接入自定义数据集用于目标检测相关实验与课程项目。需注意资料定位为“参考资料”而非定制需求作者不提供答疑服务读者需具备独立阅读代码与排错的能力。1. YOLOv8 源码包拿在手里先别急着解压跑训练“YOLOv8深度学习框架源码说明文档.rar”这种压缩包在网盘、项目群和课程资源里很常见。解压后面对一大坨目录和 README很多人第一反应就是照着说明文档敲环境命令但真正决定这份源码包能不能用起来的是你对三个东西有没有概念代码树的入口脚本、说明文档里隐含的环境版本以及数据集应该放成什么结构。YOLOv8 的源码本身是 ultralytics 那一套但打包的人用的 PyTorch 版本、CUDA 版本和权重文件可能完全不同直接开跑经常在环境依赖和数据集格式上翻车。这篇笔记就带着你从解压开始把环境搭建、数据准备、训练、损失曲线验证和部署这条路完整走一遍新手能跟得上老手可以重点看避坑部分。2. 从 rar 到跑通推理先摸清源码包里的三样东西再搭 Ubuntu 20.04 CPU 环境拿到压缩包的第一件事不是解压跑命令而是先确认这个 rar 里装的到底是什么。很多人解压之后看到一堆文件和文件夹文件名从 README 到环境配置不一而足结果装了半天环境才发现说明文档对应的是一套旧版代码白白浪费一晚上。2.1 解压后先核对这三类文件源码树、说明文档和权重文件一个标准的 YOLOv8 源码包解压后一般能分成三类内容。第一类是源码树常见目录名是 ultralytics/、yolov8/也可能打包的人改过名里面有模型的网络定义、train.py、detect.py 这类入口脚本以及 utils、cfg 这些子目录。第二类是说明文档通常叫 README.md、环境安装.txt、依赖说明.md作用不只是给你看流程也是排查环境问题时的依据。第三类是权重文件后缀为 .pt常见名称是 yolov8n.pt、yolov8s.pt、best.pt这些决定你训练是接着别人训好的模型继续还是从零开始。解压后我一般会花五分钟做一次完整性核对。先看说明文档里写的 Python 版本和依赖清单再打开源码里的 requirements.txt 对照一下然后确认权重文件能不能正常读取。.pt 文件本质上是个 zip 归档可以直接用 Python 读取写入的信息# 用 python 快速读取权重文件里的保存信息与模型结构 python -c import torch; ckpttorch.load(yolov8n.pt, map_locationcpu); print(ckpt.get(model).yaml) 2/dev/null || unzip -p yolov8n.pt | head -c 300第一条命令能打出模型结构 yaml说明说明 PyTorch 版本基本对得上如果 torch 版本太旧读不了第二条命令用 unzip 直接把 pt 包里的模型 yaml 文本抽出来。看到输出里的 C2f、Detect 这些模块名说明这份源码是标准 YOLOv8 结构之后的训练命令可以直接按官方参数走。这一步也是后面训练跑不出来时最有力的排查线索别跳过。2.2 Ubuntu 20.04 CPU 版环境搭建用 conda 把依赖一次装齐网上搜 ubuntu20.04搭建yolov8环境cpu版本能找到一堆教程但很多都默认你有 NVIDIA 显卡和 CUDA。实际手里这台机器有没有卡直接决定安装命令完全不同。我一般建议先建一个干净的 conda 虚拟环境把 Python 版本锁在 3.9 或 3.10避免和系统自带的 Python 纠缠。# 1. 创建独立虚拟环境Python 版本优先按说明文档要求 conda create -n yolov8 python3.9 -y conda activate yolov8 # 2. CPU 版安装PyTorch 官方源里的 cpu 版本不装 CUDA 组件 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 3. 安装源码包依赖ultralytics 是 YOLOv8 核心库 pip install ultralytics pip install -r requirements.txt # 如果源码目录下存在这个文件这里最关键的是第二步的--index-url https://download.pytorch.org/whl/cpu参数。很多人在 CPU 机器上直接执行默认的 pip install torch会把带 CUDA 的版本拉下来装完 import torch 倒是正常但跑训练时永远只跑 CPU还占掉几个 GB 磁盘空间。-r requirements.txt用来安装打包人锁定的依赖但 requirements.txt 里的版本可能和 ultralytics 最新版冲突所以我的习惯是先装 ultralytics再补装 requirements.txt遇到冲突时以源码包说明文档为准。装完后跑一句python -c import torch; print(torch.__version__)看到版本号里带 cpu 字样环境才算真正就绪。2.3 最小推理命令先不训练把 detect 跑通再谈其他环境装完别急着训练先用现成权重跑一次推理。这一步验证的是环境、源码、权重三条链路是否打通成功率远高于直接训练而且能很快暴露问题。# 用源码里的 detect.py 跑一张示例图显式指定 cpu python detect.py --weights yolov8n.pt --source data/images/bus.jpg --device cpu # 官方 CLI 风格等价写法适合快速验证 yolo predict modelyolov8n.pt sourcedata/images/bus.jpg devicecpu--device cpu在推理时必须手写。默认参数里 device 可能是 0CPU 机器上不指定会直接报 CUDA 初始化的错这是一道送分题也是很多新手第一次见到的报错。--weights指向你解压出来的权重文件--source可以是一张图片、一个目录也可以是一个视频文件。跑完后源码目录下会生成 runs/detect/ 文件夹里面有标注好检测框的结果图。看到框线画在物体上说明源码包的基础功能是好的可以进入数据准备阶段。2.4 结合网络结构图对照源码确认这是不是你要的 YOLOv8YOLOv8 的网络结构和 YOLOv5 比最明显的区别是 backbone 里用 C2f 模块替换了原来的 C3同时 head 部分把 Anchor-Based 换成了 Anchor-Free。很多源码包拿到手后训练效果不对根源是打包人改过网络结构而你还在按原版 YOLOv8 的参数调。确认结构最直接的办法就是把模型结构图打出来。前面 torch.load 读出的 model.yaml 能看到模块列表更直观的方式是用 Netron 打开 ONNX 或 pt 文件看整个计算图。源码的 models 目录下通常也有 yaml 配置文件比如 yolov8n.yaml、yolov8s.yaml打开后如果 detect 模块的输入通道和 Backbone 特征层对不上结构就是被改过。遇到这种情况优先用源码包自带的说明文档里的默认参数别拿网上教程的参数硬套。结构确认没问题后再进下一步把数据喂进去。3. 把数据装进 YOLOv8labelme 标注转格式、数据 yaml 与训练参数调优推理能跑通接下来才进入这个源码包真正的用处训练自己的数据集。这一步卡住的人最多因为大部分源码包自带的说明文档只写“把数据放到 datasets 目录下”但“放”不是复制粘贴而是要把标注文件转成 YOLO 需要的格式。3.1 labelme 标注转 YOLO 格式从 JSON 到每个图片一个 txtlabelme 是用的非常多的标注工具标注后每个图片对应一个 JSON 文件里面是 polygon 点坐标。YOLO 训练需要的格式不一样它是每个图片对应一个同名 txt 文件每行类别编号 x_center y_center width height坐标全部归一化到 0 到 1。处理数据集用于 yolov8 训练第一步就是写转换脚本。# labelme_convert.py —— 把 labelme 的 json 转成 YOLO 训练用的 txt import json import os import numpy as np # 这个列表的索引就是类别编号顺序必须和后面的 data.yaml 完全一致 class_names [person, car] def convert_one(json_path, txt_path, img_w, img_h): with open(json_path, r, encodingutf-8) as f: data json.load(f) with open(txt_path, w) as out: for shape in data[shapes]: label shape[label] if label not in class_names: continue points np.array(shape[points], dtypenp.float32) # 求多边形外接矩形YOLO 只支持矩形框 x1, y1 points.min(axis0) x2, y2 points.max(axis0) # 转成中心点坐标和宽高再除以图片尺寸归一化 cx (x1 x2) / 2 / img_w cy (y1 y2) / 2 / img_h w (x2 - x1) / img_w h (y2 - y1) / img_h out.write(f{class_names.index(label)} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}\n)这个脚本里有几个默认假设新手最容易不留意。class_names 的排序就是模型输出的类别编号如果你在 labelme 里标注时用的标签和这个列表顺序不一致训练出来的结果会驴唇不对马嘴。另外脚本处理的是外接矩形如果目标本身是细长条或者旋转物体外接矩形会框进大量背景这种情况建议裁剪原图或者换支持旋转框的检测模型。转换完成之后一定要抽查几张图把 txt 里的坐标画回图片上对照这一步能过滤掉绝大多数标注干净度问题。3.2 划分训练集验证集与 data.yaml三个路径别写错YOLOv8 训练时不会去读 labelme 的 JSON它只认图片目录和 txt 标注目录。常见的目录结构是这样的datasets/mydata/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yaml注意 labels 目录里放的是转换出来的 txt 文件文件名和对应图片完全同名只是扩展名从 .jpg 换成 .txt。图片划分一般按 8:2 或者 9:1划分时用脚本随机抽千万别让验证集里混入和训练集一样的图片否则 mAP 会虚高得很离谱。数据集结构就绪之后需要在源码的 datasets 目录下写一个 data.yaml# data.yaml —— YOLOv8 训练数据配置文件 path: datasets/mydata # 数据集根目录相对于你执行训练命令的目录 train: images/train # 训练图片目录path 的相对路径 val: images/val # 验证图片目录 names: 0: person 1: carpath 字段建议写相对路径不要写死成 C:/Users/xxx 或 /home/xxx 这种绝对路径。原因很简单这个源码包可能要在多台机器间拷来拷去路径一变整个配置就要改。我习惯把 data.yaml 放在数据集根目录下执行训练命令时把工作目录切到源码根目录这样 path: datasets/mydata 始终指向正确位置。names 的类别顺序和前面转换脚本里的 class_names 必须严格一致因为 txt 文件里的编号是数字只有这一处映射定义了这个数字对应的语义。3.3 训练命令与关键参数batch、epochs、imgsz、device 一次讲清数据就绪后训练的命令在官方源码包里有两种写法。一种是直接跑训练脚本另一种是 yolo CLI# 在源码根目录下执行用 yolov8s 作为预训练权重 yolo train datadatasets/mydata/data.yaml modelyolov8s.pt epochs100 batch16 imgsz640 device0 # 如果数据量小用 CPU 也要能训把 device 改成 cpu并把批次调小 yolo train datadatasets/mydata/data.yaml modelyolov8s.pt epochs50 batch8 imgsz640 devicecpu批次的设置逻辑讲究的是显存“满载但不满溢”。GTX1660Ti 这类 6GB 显存卡yolov8s 配 imgsz640 时 batch16 比较安全batch32 大概率会报 CUDA out of memory。epochs 不是越大越好源码包会在训练目录下自动生成 best.pt当连续很多轮验证损失不再下降时会触发早停设得过大也只是白等。imgsz 这里尤其注意训练时用的尺寸和推理时最好保持一致如果训练用 640、部署时想用 1280 提速精度会掉一截需要重新评估。device0 是默认用第一张显卡CPU 机器必须显式写 devicecpu。训练启动后终端会打印每一轮的 box_loss、cls_loss、dfl_loss 三个损失值还有 mAP50 和 mAP50-95 两组精度指标这一步跑通说明源码包在你手里真正活过来了。4. 训练产物怎么看损失曲线、混淆矩阵与模型大小取舍训练结束不等于任务结束。很多人训练完直接拿 best.pt 去测却不看训练过程中生成的指标文件结果模型效果不好也不知道是哪一步出了问题。YOLOv8 训练时会自动在 runs/detect/train/ 目录下输出一堆产物学会读这些文件比多训几十轮还有用。4.1 训练目录下到底生成了什么从 results.csv 到混淆矩阵训练结束后runs/detect/ 下会按 train、train2、train3 这样递增生成目录。如果是第一次训练就是 runs/detect/train里面至少有这几个东西weights/ 目录下放着 best.pt 和 last.pt前者是验证集表现最好的权重后者是最后一轮的权重results.csv 记录每一轮的损失和精度指标confusion_matrix.png 是验证集上的混淆矩阵能直观看出类别互相混淆的情况还有 val_batch0_pred.jpg 这类图片是验证集预测结果的贴图。best.pt 和 last.pt 的用途不同。训练中断后想续训用 last.pt 加 resume 参数接着跑做部署和测试默认取 best.pt。判断该取哪个不能只信文件名要打开 results.csv 对着看。4.2 画损失函数曲线把 results.csv 变成能看懂的图网上搜 yolov8画损失函数曲线图能找到不少脚本但很多人不会去看 torch 或者 matplotlib 的版本导致画图脚本跑不起来。其实 results.csv 就是标准表格直接用 pandas 读出来画图就行不用依赖训练框架本身的画图代码。# 画训练损失曲线 —— 从 results.csv 读取并可视化 import pandas as pd import matplotlib.pyplot as plt # 训练过程中自动生成的指标文件 df pd.read_csv(runs/detect/train/results.csv) # 新版本列名形如 train/box_loss旧版本可能叫 train_box_loss loss_col [c for c in df.columns if box_loss in c] if not loss_col: raise ValueError(results.csv 里没找到 box_loss 列先打印 df.columns 确认列名) plt.figure(figsize(10, 6)) plt.plot(df[epoch], df[loss_col[0]], labeltrain box_loss) plt.plot(df[epoch], df[loss_col[1]], labelval box_loss) plt.xlabel(epoch) plt.ylabel(loss) plt.legend() plt.grid(True) plt.savefig(loss_curve.png, dpi150)这段代码最值得注意的地方是列名的兼容处理。不同版本的 ultralytics 输出列名不完全一致有的叫 train/box_loss有的叫 train_box_loss直接写死列名很容易报 KeyError。先打印 df.columns 看一眼再决定用哪一列。怎么看曲线是否正常训练 box_loss 应该持续下降val box_loss 如果下降一段后反弹走高就是过拟合的典型信号这时候应该减小 epochs 或加大数据增强如果两个损失从头到尾都不怎么降优先怀疑学习率和数据标注质量。4.3 从 yolov8s 换成 yolov8n网络结构图告诉你的模型取舍依据源码包里通常会带多个尺寸的模型 yamlyolov8n、yolov8s、yolov8m、yolov8l、yolov8x。n 是 nano速度最快精度最低s 是小模型速度和精度比较均衡。实际项目里训练阶段用 s 起步部署阶段如果设备算力有限再换 n 或者直接蒸馏是常见做法。把模型结构图打出来对比可以发现n 和 s 的网络结构完全相同区别只在于每层的通道数和 C2f 模块里 bottleneck 的重复次数。也就是说n 不是 s 的裁剪版而是通道更窄的独立配置。部署到嵌入式设备时yolov8n 的参数量只有 s 的四分之一左右CPU 推理速度能快一倍以上但 mAP50 可能掉 3 到 5 个点。这个取舍没有标准答案取决于你的目标和设备。我的建议是训练阶段至少用 s不要一上来就用 n因为 n 的容量小在复杂数据集上很难收敛到好效果等到部署前再权衡是否压缩模型。5. YOLOv8 落地避坑5 个环境与数据的高频翻车点源码包这条路走完一轮之后你会发现大部分报错就集中在那么几个地方。这里把最常见的问题按现象、原因、处理的顺序写清楚全是血泪经验照着排查能省不少时间。5.1 装完 torch 一 import 就报错CUDA 版本和环境变量对不上现象conda 环境建好、pip 装完依赖执行import torch时直接报CUDA driver initialization failed或者torch.cuda.is_available()返回 False 但安装时没提示任何错误。原因在 CPU 机器上装了一个带 CUDA 的 torch或者显卡驱动版本低于 PyTorch 要求的 CUDA 最低版本。很多打包人说明文档里写的是 GPU 环境的命令直接照抄就出问题。处理先执行pip list | grep torch看版本号带cu118、cu121这类后缀的就是 CUDA 版。如果是 CPU 机器按 2.2 节用--index-url https://download.pytorch.org/whl/cpu重装 CPU 版。如果是 GPU 机器先执行nvidia-smi看支持的 CUDA 版本再装对应的 torch。装完后再跑一次python -c import torch; print(torch.__version__, torch.cuda.is_available())输出 True 再继续。5.2 标注类别和 data.yaml 对不上训练时 loss 正常验证时全错现象训练过程十分顺利损失一直往下走但拿训练好的模型去测试本该检测出来的人、车全部被标成同一个类别或者类别编号整体错位。原因labelme 转 txt 时写的 class_names 列表和 data.yaml 里的 names 顺序不一致。比如转换脚本里序号 0 是 person但 data.yaml 里 0 写成了 car模型按编号学习推理结果自然对不上。处理转换脚本和 data.yaml 写好后先统计一下训练集 labels 目录里出现过的类别编号用grep -o ^[0-9] labels/train/*.txt | sort | uniq -c看一下每个编号有多少目标再和 data.yaml 的 names 逐行核对。这种问题没有任何训练技巧能弥补只能数据源头解决。5.3 中文路径和空格目录加载失败数据集在 Windows 上跑不通现象在 Windows 上解压源码包数据集放在D:\我的项目\数据集\这类路径下运行训练命令时报FileNotFoundError但很明显文件就在那里。原因ultralytics 内部处理路径时对中文字符和空格支持不完全尤其在读取 label 文件或者调用多进程 DataLoader 时编码问题会直接让文件查找失败。处理整个项目路径只用英文、数字、下划线目录层级不要太深。D:\yolov8_project\datasets\mydata这种结构就不会出问题。另外源码包解压后如果路径带中文先把整个文件夹挪到纯英文路径下再执行任何命令。这一步看着像玄学实际是 PyTorch DataLoader 在 Windows 上和中文编码的兼容性问题无解只能避开。5.4 batch size 过大直接 CUDA out of memory现象训练跑了几个 epoch突然终端报RuntimeError: CUDA out of memory小显存显卡特别常见。原因batch size 设成 32 甚至 64但显卡只有 4GB 或 6GB 显存。YOLOv8 在 imgsz640 下每个样本会占用相当多的显存包括输入图像、特征图、梯度不是只看模型参数大小。处理GPU 先跑一个空模型测试显存上限或者直接按保守值来4GB 显存 batch46GB 显存 batch88GB 显存 batch16先跑起来再说。如果显存刚好卡在边缘可以加上--workers 4调整数据加载线程数或者把 imgsz 降到 480。另外有一种情况是训练中途才爆显存通常是因为验证阶段开启的 NMS 或者缓存占用了临时显存可以调低--conf-thres或者关闭--plots相关选项。5.5 训练集和验证集重叠导致 mAP 虚高后误判模型现象训练结束mAP50 显示 0.95 以上模型看起来神勇但换一批真实图片测试效果立刻泄气检测率远低于训练时的指标。原因数据集划分时直接用shutil.copy把同样的图片复制进了 train 和 val 目录或者从网上爬的公开数据集里本身就存在重复图片。模型在训练时已经“见过”验证集指标自然漂亮。处理按文件名做一次去重比较两张图片的 md5确认 train 和 val 里没有重复文件。更稳妥的做法是写一个划分脚本遍历全部图片按 8:2 比例随机分配而不是手工挑图。验证模型真实水平最好留一部分完全不参与训练的图片做最终测试这个测试集的指标才是你敢报出去的数字。6. 部署验证把 best.pt 导出 ONNX再检查 RK3588 板端可用性训练完的模型放到设备上跑才是源码包的最终价值。常见做法是把 best.pt 导出成 ONNX再交给板端的推理框架做转换。这里以 RK3588 为例因为这块板子现在做边缘检测项目用得确实多rknn-toolkit2 也是开源的步骤可复现。# 导出 ONNXopset 固定为 12兼容 rknn-toolkit2 yolo export modelruns/detect/train/weights/best.pt formatonnx opset12 simplifyTrue导出成功后会生成 best.onnx用 Netron 打开看一眼输入输出。输入一般是 1x3x640x640输出可能是 1x84x8400 或者分解后的多个输出取决于导出时是否带--dynamic参数。rknn-toolkit2 转换时对动态尺寸支持有限导出时不要开 dynamic。转换前先用 onnxruntime 在电脑上跑一张图确认 ONNX 输出和原 PyTorch 模型的检测框一致再走板端转换能避免把问题带到 RK3588 上到时候分工排查效率低得多。# 验证 ONNX 和原模型输出差异检测框中心坐标偏差需要控制在很小范围 import onnxruntime as ort import numpy as np sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) input_name sess.get_inputs()[0].name fake_input np.random.rand(1, 3, 640, 640).astype(np.float32) outputs sess.run(None, {input_name: fake_input}) for i, out in enumerate(outputs): print(foutput {i}: shape{out.shape}, range[{out.min():.3f}, {out.max():.3f}])这一步确认输出形状和数值范围正常后说明 onnx 文件本身没被导坏。真正到 RK3588 上还要用 rknn-toolkit2 把 onnx 转成 rknn 格式板端用 rknn-toolkit-lite 加载推理。我自己的教训是模型从 PyTorch 到 ONNX 到 RKNN每一步都会有一点精度损失所以板端测试指标和电脑上比掉 1 到 2 个点属于正常掉 5 个点以上就要回去查导出参数和量化设置。这条验证链跑通你手上这份 YOLOv8 源码包才算真正被吃透了。希望这些过程能帮你少走几步弯路把时间花在调模型而不是调环境上。本文还有配套的精品资源点击获取 YOLOv8源码包实战：从环境搭建到RK3588部署避坑指南
简介YOLOv8深度学习框架源码与说明文档已整理为一份rar压缩包面向计算机、电子信息工程、数学等专业大学生可作课程设计、期末大作业或毕业设计阶段的参考资料。包内共155个文件主体包含66个Python脚本、41个YAML配置文件、23个Markdown说明文档其中Python脚本覆盖数据加载、模型训练、验证推理等环节YAML文件定义了模型结构、训练超参与数据集路径Markdown文档提供使用说明与二次开发指引另有Dockerfile、Shell脚本、样式表等环境与辅助文件整体仅938KB轻量易获取。目前已有652人学习或下载适合具备一定编程基础、能自行调试并扩展功能的读者。通过这份源码与文档可快速掌握YOLOv8的目录组织方式、模型配置方法及训练推理流程也能在此基础上修改网络模块、调整训练参数或接入自定义数据集用于目标检测相关实验与课程项目。需注意资料定位为“参考资料”而非定制需求作者不提供答疑服务读者需具备独立阅读代码与排错的能力。1. YOLOv8 源码包拿在手里先别急着解压跑训练“YOLOv8深度学习框架源码说明文档.rar”这种压缩包在网盘、项目群和课程资源里很常见。解压后面对一大坨目录和 README很多人第一反应就是照着说明文档敲环境命令但真正决定这份源码包能不能用起来的是你对三个东西有没有概念代码树的入口脚本、说明文档里隐含的环境版本以及数据集应该放成什么结构。YOLOv8 的源码本身是 ultralytics 那一套但打包的人用的 PyTorch 版本、CUDA 版本和权重文件可能完全不同直接开跑经常在环境依赖和数据集格式上翻车。这篇笔记就带着你从解压开始把环境搭建、数据准备、训练、损失曲线验证和部署这条路完整走一遍新手能跟得上老手可以重点看避坑部分。2. 从 rar 到跑通推理先摸清源码包里的三样东西再搭 Ubuntu 20.04 CPU 环境拿到压缩包的第一件事不是解压跑命令而是先确认这个 rar 里装的到底是什么。很多人解压之后看到一堆文件和文件夹文件名从 README 到环境配置不一而足结果装了半天环境才发现说明文档对应的是一套旧版代码白白浪费一晚上。2.1 解压后先核对这三类文件源码树、说明文档和权重文件一个标准的 YOLOv8 源码包解压后一般能分成三类内容。第一类是源码树常见目录名是 ultralytics/、yolov8/也可能打包的人改过名里面有模型的网络定义、train.py、detect.py 这类入口脚本以及 utils、cfg 这些子目录。第二类是说明文档通常叫 README.md、环境安装.txt、依赖说明.md作用不只是给你看流程也是排查环境问题时的依据。第三类是权重文件后缀为 .pt常见名称是 yolov8n.pt、yolov8s.pt、best.pt这些决定你训练是接着别人训好的模型继续还是从零开始。解压后我一般会花五分钟做一次完整性核对。先看说明文档里写的 Python 版本和依赖清单再打开源码里的 requirements.txt 对照一下然后确认权重文件能不能正常读取。.pt 文件本质上是个 zip 归档可以直接用 Python 读取写入的信息# 用 python 快速读取权重文件里的保存信息与模型结构 python -c import torch; ckpttorch.load(yolov8n.pt, map_locationcpu); print(ckpt.get(model).yaml) 2/dev/null || unzip -p yolov8n.pt | head -c 300第一条命令能打出模型结构 yaml说明说明 PyTorch 版本基本对得上如果 torch 版本太旧读不了第二条命令用 unzip 直接把 pt 包里的模型 yaml 文本抽出来。看到输出里的 C2f、Detect 这些模块名说明这份源码是标准 YOLOv8 结构之后的训练命令可以直接按官方参数走。这一步也是后面训练跑不出来时最有力的排查线索别跳过。2.2 Ubuntu 20.04 CPU 版环境搭建用 conda 把依赖一次装齐网上搜 ubuntu20.04搭建yolov8环境cpu版本能找到一堆教程但很多都默认你有 NVIDIA 显卡和 CUDA。实际手里这台机器有没有卡直接决定安装命令完全不同。我一般建议先建一个干净的 conda 虚拟环境把 Python 版本锁在 3.9 或 3.10避免和系统自带的 Python 纠缠。# 1. 创建独立虚拟环境Python 版本优先按说明文档要求 conda create -n yolov8 python3.9 -y conda activate yolov8 # 2. CPU 版安装PyTorch 官方源里的 cpu 版本不装 CUDA 组件 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 3. 安装源码包依赖ultralytics 是 YOLOv8 核心库 pip install ultralytics pip install -r requirements.txt # 如果源码目录下存在这个文件这里最关键的是第二步的--index-url https://download.pytorch.org/whl/cpu参数。很多人在 CPU 机器上直接执行默认的 pip install torch会把带 CUDA 的版本拉下来装完 import torch 倒是正常但跑训练时永远只跑 CPU还占掉几个 GB 磁盘空间。-r requirements.txt用来安装打包人锁定的依赖但 requirements.txt 里的版本可能和 ultralytics 最新版冲突所以我的习惯是先装 ultralytics再补装 requirements.txt遇到冲突时以源码包说明文档为准。装完后跑一句python -c import torch; print(torch.__version__)看到版本号里带 cpu 字样环境才算真正就绪。2.3 最小推理命令先不训练把 detect 跑通再谈其他环境装完别急着训练先用现成权重跑一次推理。这一步验证的是环境、源码、权重三条链路是否打通成功率远高于直接训练而且能很快暴露问题。# 用源码里的 detect.py 跑一张示例图显式指定 cpu python detect.py --weights yolov8n.pt --source data/images/bus.jpg --device cpu # 官方 CLI 风格等价写法适合快速验证 yolo predict modelyolov8n.pt sourcedata/images/bus.jpg devicecpu--device cpu在推理时必须手写。默认参数里 device 可能是 0CPU 机器上不指定会直接报 CUDA 初始化的错这是一道送分题也是很多新手第一次见到的报错。--weights指向你解压出来的权重文件--source可以是一张图片、一个目录也可以是一个视频文件。跑完后源码目录下会生成 runs/detect/ 文件夹里面有标注好检测框的结果图。看到框线画在物体上说明源码包的基础功能是好的可以进入数据准备阶段。2.4 结合网络结构图对照源码确认这是不是你要的 YOLOv8YOLOv8 的网络结构和 YOLOv5 比最明显的区别是 backbone 里用 C2f 模块替换了原来的 C3同时 head 部分把 Anchor-Based 换成了 Anchor-Free。很多源码包拿到手后训练效果不对根源是打包人改过网络结构而你还在按原版 YOLOv8 的参数调。确认结构最直接的办法就是把模型结构图打出来。前面 torch.load 读出的 model.yaml 能看到模块列表更直观的方式是用 Netron 打开 ONNX 或 pt 文件看整个计算图。源码的 models 目录下通常也有 yaml 配置文件比如 yolov8n.yaml、yolov8s.yaml打开后如果 detect 模块的输入通道和 Backbone 特征层对不上结构就是被改过。遇到这种情况优先用源码包自带的说明文档里的默认参数别拿网上教程的参数硬套。结构确认没问题后再进下一步把数据喂进去。3. 把数据装进 YOLOv8labelme 标注转格式、数据 yaml 与训练参数调优推理能跑通接下来才进入这个源码包真正的用处训练自己的数据集。这一步卡住的人最多因为大部分源码包自带的说明文档只写“把数据放到 datasets 目录下”但“放”不是复制粘贴而是要把标注文件转成 YOLO 需要的格式。3.1 labelme 标注转 YOLO 格式从 JSON 到每个图片一个 txtlabelme 是用的非常多的标注工具标注后每个图片对应一个 JSON 文件里面是 polygon 点坐标。YOLO 训练需要的格式不一样它是每个图片对应一个同名 txt 文件每行类别编号 x_center y_center width height坐标全部归一化到 0 到 1。处理数据集用于 yolov8 训练第一步就是写转换脚本。# labelme_convert.py —— 把 labelme 的 json 转成 YOLO 训练用的 txt import json import os import numpy as np # 这个列表的索引就是类别编号顺序必须和后面的 data.yaml 完全一致 class_names [person, car] def convert_one(json_path, txt_path, img_w, img_h): with open(json_path, r, encodingutf-8) as f: data json.load(f) with open(txt_path, w) as out: for shape in data[shapes]: label shape[label] if label not in class_names: continue points np.array(shape[points], dtypenp.float32) # 求多边形外接矩形YOLO 只支持矩形框 x1, y1 points.min(axis0) x2, y2 points.max(axis0) # 转成中心点坐标和宽高再除以图片尺寸归一化 cx (x1 x2) / 2 / img_w cy (y1 y2) / 2 / img_h w (x2 - x1) / img_w h (y2 - y1) / img_h out.write(f{class_names.index(label)} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}\n)这个脚本里有几个默认假设新手最容易不留意。class_names 的排序就是模型输出的类别编号如果你在 labelme 里标注时用的标签和这个列表顺序不一致训练出来的结果会驴唇不对马嘴。另外脚本处理的是外接矩形如果目标本身是细长条或者旋转物体外接矩形会框进大量背景这种情况建议裁剪原图或者换支持旋转框的检测模型。转换完成之后一定要抽查几张图把 txt 里的坐标画回图片上对照这一步能过滤掉绝大多数标注干净度问题。3.2 划分训练集验证集与 data.yaml三个路径别写错YOLOv8 训练时不会去读 labelme 的 JSON它只认图片目录和 txt 标注目录。常见的目录结构是这样的datasets/mydata/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yaml注意 labels 目录里放的是转换出来的 txt 文件文件名和对应图片完全同名只是扩展名从 .jpg 换成 .txt。图片划分一般按 8:2 或者 9:1划分时用脚本随机抽千万别让验证集里混入和训练集一样的图片否则 mAP 会虚高得很离谱。数据集结构就绪之后需要在源码的 datasets 目录下写一个 data.yaml# data.yaml —— YOLOv8 训练数据配置文件 path: datasets/mydata # 数据集根目录相对于你执行训练命令的目录 train: images/train # 训练图片目录path 的相对路径 val: images/val # 验证图片目录 names: 0: person 1: carpath 字段建议写相对路径不要写死成 C:/Users/xxx 或 /home/xxx 这种绝对路径。原因很简单这个源码包可能要在多台机器间拷来拷去路径一变整个配置就要改。我习惯把 data.yaml 放在数据集根目录下执行训练命令时把工作目录切到源码根目录这样 path: datasets/mydata 始终指向正确位置。names 的类别顺序和前面转换脚本里的 class_names 必须严格一致因为 txt 文件里的编号是数字只有这一处映射定义了这个数字对应的语义。3.3 训练命令与关键参数batch、epochs、imgsz、device 一次讲清数据就绪后训练的命令在官方源码包里有两种写法。一种是直接跑训练脚本另一种是 yolo CLI# 在源码根目录下执行用 yolov8s 作为预训练权重 yolo train datadatasets/mydata/data.yaml modelyolov8s.pt epochs100 batch16 imgsz640 device0 # 如果数据量小用 CPU 也要能训把 device 改成 cpu并把批次调小 yolo train datadatasets/mydata/data.yaml modelyolov8s.pt epochs50 batch8 imgsz640 devicecpu批次的设置逻辑讲究的是显存“满载但不满溢”。GTX1660Ti 这类 6GB 显存卡yolov8s 配 imgsz640 时 batch16 比较安全batch32 大概率会报 CUDA out of memory。epochs 不是越大越好源码包会在训练目录下自动生成 best.pt当连续很多轮验证损失不再下降时会触发早停设得过大也只是白等。imgsz 这里尤其注意训练时用的尺寸和推理时最好保持一致如果训练用 640、部署时想用 1280 提速精度会掉一截需要重新评估。device0 是默认用第一张显卡CPU 机器必须显式写 devicecpu。训练启动后终端会打印每一轮的 box_loss、cls_loss、dfl_loss 三个损失值还有 mAP50 和 mAP50-95 两组精度指标这一步跑通说明源码包在你手里真正活过来了。4. 训练产物怎么看损失曲线、混淆矩阵与模型大小取舍训练结束不等于任务结束。很多人训练完直接拿 best.pt 去测却不看训练过程中生成的指标文件结果模型效果不好也不知道是哪一步出了问题。YOLOv8 训练时会自动在 runs/detect/train/ 目录下输出一堆产物学会读这些文件比多训几十轮还有用。4.1 训练目录下到底生成了什么从 results.csv 到混淆矩阵训练结束后runs/detect/ 下会按 train、train2、train3 这样递增生成目录。如果是第一次训练就是 runs/detect/train里面至少有这几个东西weights/ 目录下放着 best.pt 和 last.pt前者是验证集表现最好的权重后者是最后一轮的权重results.csv 记录每一轮的损失和精度指标confusion_matrix.png 是验证集上的混淆矩阵能直观看出类别互相混淆的情况还有 val_batch0_pred.jpg 这类图片是验证集预测结果的贴图。best.pt 和 last.pt 的用途不同。训练中断后想续训用 last.pt 加 resume 参数接着跑做部署和测试默认取 best.pt。判断该取哪个不能只信文件名要打开 results.csv 对着看。4.2 画损失函数曲线把 results.csv 变成能看懂的图网上搜 yolov8画损失函数曲线图能找到不少脚本但很多人不会去看 torch 或者 matplotlib 的版本导致画图脚本跑不起来。其实 results.csv 就是标准表格直接用 pandas 读出来画图就行不用依赖训练框架本身的画图代码。# 画训练损失曲线 —— 从 results.csv 读取并可视化 import pandas as pd import matplotlib.pyplot as plt # 训练过程中自动生成的指标文件 df pd.read_csv(runs/detect/train/results.csv) # 新版本列名形如 train/box_loss旧版本可能叫 train_box_loss loss_col [c for c in df.columns if box_loss in c] if not loss_col: raise ValueError(results.csv 里没找到 box_loss 列先打印 df.columns 确认列名) plt.figure(figsize(10, 6)) plt.plot(df[epoch], df[loss_col[0]], labeltrain box_loss) plt.plot(df[epoch], df[loss_col[1]], labelval box_loss) plt.xlabel(epoch) plt.ylabel(loss) plt.legend() plt.grid(True) plt.savefig(loss_curve.png, dpi150)这段代码最值得注意的地方是列名的兼容处理。不同版本的 ultralytics 输出列名不完全一致有的叫 train/box_loss有的叫 train_box_loss直接写死列名很容易报 KeyError。先打印 df.columns 看一眼再决定用哪一列。怎么看曲线是否正常训练 box_loss 应该持续下降val box_loss 如果下降一段后反弹走高就是过拟合的典型信号这时候应该减小 epochs 或加大数据增强如果两个损失从头到尾都不怎么降优先怀疑学习率和数据标注质量。4.3 从 yolov8s 换成 yolov8n网络结构图告诉你的模型取舍依据源码包里通常会带多个尺寸的模型 yamlyolov8n、yolov8s、yolov8m、yolov8l、yolov8x。n 是 nano速度最快精度最低s 是小模型速度和精度比较均衡。实际项目里训练阶段用 s 起步部署阶段如果设备算力有限再换 n 或者直接蒸馏是常见做法。把模型结构图打出来对比可以发现n 和 s 的网络结构完全相同区别只在于每层的通道数和 C2f 模块里 bottleneck 的重复次数。也就是说n 不是 s 的裁剪版而是通道更窄的独立配置。部署到嵌入式设备时yolov8n 的参数量只有 s 的四分之一左右CPU 推理速度能快一倍以上但 mAP50 可能掉 3 到 5 个点。这个取舍没有标准答案取决于你的目标和设备。我的建议是训练阶段至少用 s不要一上来就用 n因为 n 的容量小在复杂数据集上很难收敛到好效果等到部署前再权衡是否压缩模型。5. YOLOv8 落地避坑5 个环境与数据的高频翻车点源码包这条路走完一轮之后你会发现大部分报错就集中在那么几个地方。这里把最常见的问题按现象、原因、处理的顺序写清楚全是血泪经验照着排查能省不少时间。5.1 装完 torch 一 import 就报错CUDA 版本和环境变量对不上现象conda 环境建好、pip 装完依赖执行import torch时直接报CUDA driver initialization failed或者torch.cuda.is_available()返回 False 但安装时没提示任何错误。原因在 CPU 机器上装了一个带 CUDA 的 torch或者显卡驱动版本低于 PyTorch 要求的 CUDA 最低版本。很多打包人说明文档里写的是 GPU 环境的命令直接照抄就出问题。处理先执行pip list | grep torch看版本号带cu118、cu121这类后缀的就是 CUDA 版。如果是 CPU 机器按 2.2 节用--index-url https://download.pytorch.org/whl/cpu重装 CPU 版。如果是 GPU 机器先执行nvidia-smi看支持的 CUDA 版本再装对应的 torch。装完后再跑一次python -c import torch; print(torch.__version__, torch.cuda.is_available())输出 True 再继续。5.2 标注类别和 data.yaml 对不上训练时 loss 正常验证时全错现象训练过程十分顺利损失一直往下走但拿训练好的模型去测试本该检测出来的人、车全部被标成同一个类别或者类别编号整体错位。原因labelme 转 txt 时写的 class_names 列表和 data.yaml 里的 names 顺序不一致。比如转换脚本里序号 0 是 person但 data.yaml 里 0 写成了 car模型按编号学习推理结果自然对不上。处理转换脚本和 data.yaml 写好后先统计一下训练集 labels 目录里出现过的类别编号用grep -o ^[0-9] labels/train/*.txt | sort | uniq -c看一下每个编号有多少目标再和 data.yaml 的 names 逐行核对。这种问题没有任何训练技巧能弥补只能数据源头解决。5.3 中文路径和空格目录加载失败数据集在 Windows 上跑不通现象在 Windows 上解压源码包数据集放在D:\我的项目\数据集\这类路径下运行训练命令时报FileNotFoundError但很明显文件就在那里。原因ultralytics 内部处理路径时对中文字符和空格支持不完全尤其在读取 label 文件或者调用多进程 DataLoader 时编码问题会直接让文件查找失败。处理整个项目路径只用英文、数字、下划线目录层级不要太深。D:\yolov8_project\datasets\mydata这种结构就不会出问题。另外源码包解压后如果路径带中文先把整个文件夹挪到纯英文路径下再执行任何命令。这一步看着像玄学实际是 PyTorch DataLoader 在 Windows 上和中文编码的兼容性问题无解只能避开。5.4 batch size 过大直接 CUDA out of memory现象训练跑了几个 epoch突然终端报RuntimeError: CUDA out of memory小显存显卡特别常见。原因batch size 设成 32 甚至 64但显卡只有 4GB 或 6GB 显存。YOLOv8 在 imgsz640 下每个样本会占用相当多的显存包括输入图像、特征图、梯度不是只看模型参数大小。处理GPU 先跑一个空模型测试显存上限或者直接按保守值来4GB 显存 batch46GB 显存 batch88GB 显存 batch16先跑起来再说。如果显存刚好卡在边缘可以加上--workers 4调整数据加载线程数或者把 imgsz 降到 480。另外有一种情况是训练中途才爆显存通常是因为验证阶段开启的 NMS 或者缓存占用了临时显存可以调低--conf-thres或者关闭--plots相关选项。5.5 训练集和验证集重叠导致 mAP 虚高后误判模型现象训练结束mAP50 显示 0.95 以上模型看起来神勇但换一批真实图片测试效果立刻泄气检测率远低于训练时的指标。原因数据集划分时直接用shutil.copy把同样的图片复制进了 train 和 val 目录或者从网上爬的公开数据集里本身就存在重复图片。模型在训练时已经“见过”验证集指标自然漂亮。处理按文件名做一次去重比较两张图片的 md5确认 train 和 val 里没有重复文件。更稳妥的做法是写一个划分脚本遍历全部图片按 8:2 比例随机分配而不是手工挑图。验证模型真实水平最好留一部分完全不参与训练的图片做最终测试这个测试集的指标才是你敢报出去的数字。6. 部署验证把 best.pt 导出 ONNX再检查 RK3588 板端可用性训练完的模型放到设备上跑才是源码包的最终价值。常见做法是把 best.pt 导出成 ONNX再交给板端的推理框架做转换。这里以 RK3588 为例因为这块板子现在做边缘检测项目用得确实多rknn-toolkit2 也是开源的步骤可复现。# 导出 ONNXopset 固定为 12兼容 rknn-toolkit2 yolo export modelruns/detect/train/weights/best.pt formatonnx opset12 simplifyTrue导出成功后会生成 best.onnx用 Netron 打开看一眼输入输出。输入一般是 1x3x640x640输出可能是 1x84x8400 或者分解后的多个输出取决于导出时是否带--dynamic参数。rknn-toolkit2 转换时对动态尺寸支持有限导出时不要开 dynamic。转换前先用 onnxruntime 在电脑上跑一张图确认 ONNX 输出和原 PyTorch 模型的检测框一致再走板端转换能避免把问题带到 RK3588 上到时候分工排查效率低得多。# 验证 ONNX 和原模型输出差异检测框中心坐标偏差需要控制在很小范围 import onnxruntime as ort import numpy as np sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) input_name sess.get_inputs()[0].name fake_input np.random.rand(1, 3, 640, 640).astype(np.float32) outputs sess.run(None, {input_name: fake_input}) for i, out in enumerate(outputs): print(foutput {i}: shape{out.shape}, range[{out.min():.3f}, {out.max():.3f}])这一步确认输出形状和数值范围正常后说明 onnx 文件本身没被导坏。真正到 RK3588 上还要用 rknn-toolkit2 把 onnx 转成 rknn 格式板端用 rknn-toolkit-lite 加载推理。我自己的教训是模型从 PyTorch 到 ONNX 到 RKNN每一步都会有一点精度损失所以板端测试指标和电脑上比掉 1 到 2 个点属于正常掉 5 个点以上就要回去查导出参数和量化设置。这条验证链跑通你手上这份 YOLOv8 源码包才算真正被吃透了。希望这些过程能帮你少走几步弯路把时间花在调模型而不是调环境上。本文还有配套的精品资源点击获取