YOLOv8目标检测模型本地部署与训练完整教程

本教程系统讲解如何在 Windows 本地环境部署 YOLOv8 目标检测模型，并完成从快速体验、数据集标注、模型训练到结果测试的完整闭环。YOLOv8 是 Ultralytics 开源的目标检测框架，一条命令即可用预训练模型检测图片中的目标，配合标注工具与自己收集的图像数据，还能训练出识别自定义类别的专属模型。本教程的示例项目已内置演示数据集与预训练权重，全部流程在 RTX 2080 Ti 显卡上实测跑通，无显卡的电脑也可以按文中说明改用 CPU 模式体验。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• PyTorch安装与版本选择问题详解，理解 CUDA 版 PyTorch 与显卡驱动的对应关系，本教程第 2 章的 GPU 环境安装依赖它。
• WSL2、Ubuntu与Conda安装教程，本教程使用其中的 conda 创建独立的 Python 虚拟环境。

资源下载

• yolo-demo 示例项目网盘地址，本教程配套示例项目，含示例代码、COCO8 迷你数据集与预训练模型 yolov8n.pt，解压即可离线运行全部示例。
• Ultralytics 官方仓库源码网盘地址，官方仓库 v8.4.162 的源码快照（与本教程实测版本一致），GitHub 访问慢时使用；文档与更新以 Ultralytics 官方仓库 为准。
• labelImg 标注工具网盘地址，本教程第 3 章使用的图像标注工具，内含官方 v1.8.6 完整源码与 Windows 免安装版（双击 labelImg.exe 即可运行，无需安装 Python）；源码与更新以 labelImg 官方仓库 为准。

1. YOLOv8 与目标检测

1.1 目标检测是什么

给计算机看一张图片，按任务深度可分为三个层次：

目标检测处于中间层：对图中每个感兴趣的目标画一个矩形框，并给出类别与置信度。自动驾驶识别行人、厂区监控识别安全帽、文档识别二维码位置，都属于这类任务。

1.2 YOLOv8 与 Ultralytics 框架

YOLO（You Only Look Once）系列是目标检测领域最有影响力的单阶段检测算法，思路是把检测当作一次前向推理直接输出框与类别，兼顾速度与精度。YOLOv8 由 Ultralytics 公司于 2023 年发布，是目前工程化程度最高的版本：安装即用、支持多任务、训练与推理接口统一。

YOLOv8 官方支持五类视觉任务，均使用同一套训练与预测接口：

Ultralytics 框架采用 AGPL-3.0 开源协议：学习、研究与个人项目可以自由使用；将训练成果集成到闭源商业产品时，需要遵守 AGPL 义务或向 Ultralytics 购买商业许可。此外，官方后来发布的 YOLO11 与 YOLOv8 使用完全相同的接口，本教程全部命令把权重文件换成 yolo11n.pt 即可平滑升级。

1.3 模型规格选择

每个任务都提供 n / s / m / l / x 五种规格，从左到右模型越大、精度越高、速度越慢：

表中 COCO mAP50-95 一列是业界统一标尺下的成绩，拆开是三部分：COCO 指评测用的 COCO 数据集（80 个常见类别、约 12 万张标注图，目标检测领域的标准考试卷）；mAP（mean Average Precision，平均精度均值）衡量「找得全不全、找得准不准」，对每个类别计算平均精度后取 80 类平均；50-95 指判定「检测正确」的 IoU 门槛（预测框与真实框的重叠比例）从 0.5 到 0.95 取 10 档分别算分再平均，门槛越高要求框画得越贴。以 yolov8n 的约 37 为例，含义是在 COCO 全部 80 类上、十档严格程度下的综合得分约 37%。自定义项目的类别数与难度都不同于 COCO，你的模型指标与这一列不具直接可比性。

入门与自定义训练建议从 n 或 s 开始：小模型迭代快，先验证数据与流程，再考虑加大模型换精度。

一次检测的前向过程如下，模型最终输出的原始框经非极大值抑制（NMS）去掉重叠冗余，得到图中每个目标的边界框、类别与置信度：

2. 环境准备与快速体验

2.1 硬件与软件清单

无独立显卡的电脑可以完成本教程全部演示（CPU 模式），真实项目训练建议使用 NVIDIA 显卡。

2.2 创建虚拟环境并安装依赖

打开命令提示符，创建并激活独立虚拟环境：

conda create -n yolo python=3.10
conda activate yolo

有 NVIDIA 显卡时，先安装 CUDA 版 PyTorch（版本与显卡的对应关系见前置教程）：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

无 NVIDIA 显卡时跳过上一步，直接安装 CPU 版即可：

pip install torch torchvision

然后安装 YOLOv8 框架与依赖。requirements.txt 在示例项目压缩包内，包含 ultralytics 与 tqdm 两个包：

pip install -r requirements.txt

注意安装顺序：先装 CUDA 版 PyTorch，再装 ultralytics。反过来执行时，依赖解析可能把 CPU 版 PyTorch 覆盖进去，导致训练只能跑 CPU。

2.3 部署示例项目

从资源下载区获取 yolo-demo.zip，解压到任意目录（下文以 D:\yolo-demo 为例）。解压后的结构如下：

yolo-demo
├── main.py            命令行入口，含 detect / train / test 三个子命令
├── config.py          路径与超参数集中配置
├── requirements.txt   依赖清单
├── README.md          使用说明
├── assets
│   └── bus.jpg        快速体验图片
└── datasets
    └── coco8          内置 COCO8 迷你数据集（8 张图，训练演示用）

首次运行会自动下载预训练模型 yolov8n.pt（约 6MB）到项目根目录；压缩包内已附带该文件时则直接使用，无需联网。

2.4 验证 GPU 环境

在项目目录下执行：

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

本教程实测输出如下，三项分别代表 torch 版本、CUDA 是否可用、显卡型号：

2.11.0+cu128 True NVIDIA GeForce RTX 2080 Ti

中间项为 False 时训练会退回 CPU，通常是显卡驱动过旧或误装了 CPU 版 PyTorch，可先更新驱动，再按 2.2 节的顺序重装。

2.5 预训练模型快速体验

执行 detect 子命令，用预训练模型检测示例图片：

python main.py detect

实测输出：

image 1/1 D:\yolo-demo\assets\bus.jpg: 640x480 4 persons, 1 bus, 1 stop sign, 10.2ms
Speed: 39.7ms preprocess, 10.2ms inference, 18.3ms postprocess per image at shape (1, 3, 640, 480)
Results saved to D:\yolo-demo\runs\detect\predict

输出显示检测到 4 个行人、1 辆公交车与 1 个停止标志，结果图片保存在 runs/detect/predict 目录：

detect 子命令的核心逻辑只有三步：加载模型、调用预测、保存结果。完整代码请查看 yolo-demo/main.py：

def cmd_detect(args):
    # 加载模型：默认预训练模型，--weights 可换成自己训练的 best.pt
    model = YOLO(args.weights or config.PRETRAINED_MODEL, task="detect")
    model.predict(
        source=args.source or config.DEMO_IMAGE,
        save=True,
        name=args.name,
        exist_ok=True,
    )

熟悉命令行的话，也可以直接使用 ultralytics 自带的 yolo 命令完成同样的事：

yolo detect predict model=yolov8n.pt source=assets/bus.jpg

3. 数据集准备与标注

3.1 数据集从哪里来

训练自定义检测模型，数据集有三种常见来源：

为让示例不依赖任何外部数据，本教程示例项目内置了官方迷你数据集 COCO8（COCO 2017 的 8 张图采样，含人、狗、马、大象、雨伞、盆栽等目标），用于走通训练全流程；训练自己的模型时，把数据集换成你的即可，方法见 4.5 节。

3.2 用 labelImg 标注图片

标注工具推荐 labelImg，Windows 下直接安装即可运行，无需任何图形界面转发配置：

pip install labelImg

若 pip 安装异常，可改用 conda 安装：conda install -c conda-forge labelimg。安装完成后，在项目目录启动：

labelImg datasets/mydata/images/train

启动后先做三项配置，之后标注效率会高很多：

1. 点击左侧工具栏的格式按钮（默认显示 PascalVOC），每点击一次切换一种格式，把它切换为 YOLO。
2. 点击左侧 Change Save Dir，把标注结果保存目录设为数据集的 labels 目录。
3. 点击上方菜单 View，勾选 Auto Save mode 开启自动保存。

标注单个目标的操作：按快捷键 W 创建矩形框，拖动调整框住目标，在弹出的对话框输入类别名（如 smoker），回车保存。常用快捷键如下：

3.3 YOLO 格式标签文件

labelImg 切换到 YOLO 格式后，每张图片对应生成一个同名 .txt 标签文件，每个目标占一行，五个数值全部按图像宽高归一化到 0 到 1：

<class_id> <x_center> <y_center> <width> <height>

示例：

0 0.5 0.5 0.3 0.4    类别0，框中心在(0.5, 0.5)，宽0.3，高0.4
1 0.2 0.8 0.15 0.2   类别1，框中心在(0.2, 0.8)，宽0.15，高0.2

同时需要一个 classes.txt 文件按行声明类别，行号就是类别编号：

smoker
face

3.4 数据集目录结构与 data.yaml

训练前把数据按「图像 + 标签、训练 + 验证」组织成固定目录结构，常见两种布局：

样式一（按内容分）        样式二（按用途分）
your_dataset/            your_dataset/
├── images/              ├── train/
│   ├── train/           │   ├── images/
│   ├── valid/           │   └── labels/
│   └── test/            ├── valid/
└── labels/              │   ├── images/
    ├── train/           │   └── labels/
    ├── valid/           └── test/
    └── test/                ├── images/
                            └── labels/

本教程示例项目内置的 COCO8 采用样式二（train 与 val 两个用途目录，各自包含 images 与 labels）。目录就绪后，编写数据集配置文件 mydata.yaml 告诉框架数据在哪里、有哪些类别：

path: D:\yolo-demo\datasets\mydata   # 数据集根目录，建议写绝对路径
train: images/train                  # 训练图像相对 path 的路径
val: images/val                      # 验证图像相对 path 的路径

# 类别名称，顺序必须与 classes.txt 一致，编号从 0 开始
names:
  0: smoker
  1: face

3.5 数据量建议

自定义类别的数据量直接决定模型上限。得益于预训练权重的迁移学习，如今的数据门槛比从零训练低得多，但「能跑通」与「真可用」之间仍差着数倍的数据量，建议按两档规划：

最低门槛（跑通流程与原型验证）

推荐规模（面向实际交付）

比总数更重要的是场景覆盖度：同样 1000 张图，全部来自单一光照与角度，效果远不如均匀覆盖暗光、逆光、远距离、遮挡与多背景的 500 张。补数据的正确姿势是盯住模型的失败样本——哪里误检、漏检，就补哪里的数据。

数据质量决定数量是否有效：框要贴紧目标、类别要标全、困难样本（遮挡、小目标、暗光）要覆盖。几百张随手框带来的提升，往往不如数量减半的精心标注。

4. 模型训练

4.1 训练流程总览

模型训练是一个「训练、观察、调整」的循环过程，直到验证指标达到预期：

4.2 首次训练：用 COCO8 走通全流程

示例项目的默认配置已指向内置 COCO8 数据集，直接执行 train 子命令：

python main.py train --name demo

实测输出（节选）：

Ultralytics 8.4.162  Python-3.10.21 torch-2.11.0+cu128 CUDA:0 (NVIDIA GeForce RTX 2080 Ti, 22528MiB)
Model summary: 129 layers, 3,157,200 parameters, 3,157,184 gradients, 8.9 GFLOPs

      Epoch    GPU_mem   box_loss   cls_loss   dfl_loss  Instances       Size
      10/10     0.629G     0.9593      1.828      1.213         13        640
                 Class     Images  Instances      Box(P          R      mAP50  mAP50-95)
                   all          4         17      0.613      0.882      0.888      0.616
10 epochs completed in 0.002 hours.
Optimizer stripped from D:\yolo-demo\runs\detect\demo\weights\best.pt, 6.6MB

COCO8 只有 8 张图，RTX 2080 Ti 上 10 轮训练约 7 秒完成，价值在于快速验证「数据加载、显卡训练、权重保存」整条链路通畅。训练结束后，runs/detect/demo 目录下生成全部产物：

runs/detect/demo
├── weights
│   ├── best.pt             验证指标最优的模型（最终交付物）
│   └── last.pt             最后一轮的模型（断点续训用）
├── args.yaml               本次训练的完整参数存档
├── results.csv             逐轮指标数据
├── results.png             损失与指标曲线总览
├── confusion_matrix.png    混淆矩阵
├── BoxF1_curve.png 等      P-R-F1 关系曲线
├── train_batch*.jpg        训练批次可视化（含数据增强效果）
└── val_batch*_pred.jpg     验证集预测可视化

results.png 是判断训练质量的第一手材料，共十张小图：左列三张训练损失应整体下降，右列四张验证指标应整体上升；验证损失（val 开头）持续上升而训练损失下降时，说明模型开始过拟合，应停止训练或补充数据：

4.3 训练指标解读

训练过程中每轮打印两组指标。训练指标反映模型正在如何学习：

每轮结束后在验证集上计算验证指标，这才是判断模型好坏的依据：

自定义检测项目可参照下表粗略判断指标水平。指标的「含金量」与任务难度强相关，按自己的场景选表：少类别简单场景（1-3 类、目标大而明显、数据充足）的指标容易做高，应当用更严的标准要求模型；多类别复杂场景（类别多、目标小、遮挡严重）的指标天然难做高，同样的分数更有含金量。

少类别简单场景（安全帽、火焰、吸烟等典型自定义项目多属此类）

多类别复杂场景（类别多、目标小、遮挡重）

两个锚点帮助校准预期：一是难度上限，80 类的 YOLOv8x 在 COCO 考卷上 mAP50 约 70 出头、mAP50-95 约 54，多类别复杂场景的优秀线正是按这一难度标定的；二是日常可达性，社区的安全帽等单类检测项目普遍把 mAP50 达到 0.9 视为合格线，数百张高质量标注配合 50 轮以上训练，达到少类别场景的优秀线是常规目标，并非高不可攀。另外注意 Precision 与 Recall 此消彼长，两项同时达标才代表模型真正可用；一项高一项低时，优先回查数据质量与数据量，其次考虑调参。

4.4 继续训练与参数调优

首次训练的指标不达标时，从 best.pt 出发继续训练，同时降低学习率并开启数据增强，是性价比最高的第二轮操作。示例项目通过 --tune 参数启用微调配置：

python main.py train --weights runs/detect/demo/weights/best.pt --tune --name demo-next

--tune 启用的参数及作用如下，均已写入 yolo-demo/main.py，可按需修改：

上例的产物保存在 runs/detect/demo-next，训练项目名换了新目录，之前的 demo 结果不会被覆盖。

4.5 训练自己的数据集

把第 3 章准备的 mydata.yaml 交给 --data 参数，就是一次真实项目的训练：

python main.py train --data D:\yolo-demo\datasets\mydata\mydata.yaml --epochs 100 --name mymodel

真实项目的三点经验：epochs 建议 50 轮起步，配合 --tune 的早停机制让框架自动决定何时停止；数据集较大时把 config.py 中的 BATCH 与 WORKERS 调大可加快训练；训练中途指标停滞属于正常现象，优先补数据，其次调参数。

5. 测试与应用训练结果

5.1 批量测试

正式使用前，用一批没有参与过训练的图片检验模型，test 子命令会遍历整个目录并保存每张图的结果：

python main.py test --weights runs/detect/demo-next/weights/best.pt

实测输出：

找到 4 张待测试图片
测试进度: 100%|██████████| 4/4 [00:02<00:00,  1.34it/s]
测试完成，结果保存在 test/demo

不带 --source 时默认测试内置 COCO8 的验证集图片；测试自己的模型时用 --source 指向你的测试集目录。翻看 test/demo 下的结果图片，重点检查两类错误：目标漏检与背景误检，两者的比例决定是否需要回到第 4 章继续补数据训练。

5.2 用训练好的模型做预测

best.pt 就是一个普通的 YOLO 权重文件，detect 子命令换上 --weights 即可投入使用：

python main.py detect --weights runs/detect/demo-next/weights/best.pt --source datasets/coco8/images/val/000000000036.jpg

实测输出，用内置数据集训练出来的模型已经能稳定检出图中目标：

image 1/1 D:\yolo-demo\datasets\coco8\images\val\000000000036.jpg: 640x512 1 person, 1 umbrella, 9.4ms
Speed: 27.9ms preprocess, 9.4ms inference, 11.9ms postprocess per image at shape (1, 3, 640, 512)
Results saved to D:\yolo-demo\runs\detect\predict

--source 支持多种输入形式：单张图片、整个目录、视频文件，甚至摄像头编号（--source 0），足够覆盖原型验证阶段的全部场景。

5.3 下一步方向

模型达到预期后，常见的三个进阶方向：

• 服务化：用 FastAPI 包一层 HTTP 接口，让网页或其他程序远程调用 best.pt，方法可参考 Python+FastAPI在Windows环境下创建一个基础后端服务教程。
• 导出部署：yolo export model=best.pt format=onnx 导出 ONNX 格式，可在无 Python 环境的设备上推理。
• 持续迭代：收集线上误检、漏检的样本，标注后加入训练集，按第 4 章流程继续训练。

6. 总结

6.1 核心内容回顾

• YOLOv8 是 Ultralytics 开源的目标检测框架，detect 任务提供 n 到 x 五种规格，入门与自定义训练从 yolov8n 开始；框架为 AGPL-3.0 协议，闭源商用需要商业授权。
• 环境三步：conda 建独立环境、先装 CUDA 版 PyTorch 再装 ultralytics、python -c 验证 cuda 项为 True。
• 数据集按「images + labels、train + val」组织，YOLO 标签为归一化坐标文本，data.yaml 声明路径与类别；数据量最低门槛为每类 200 张起步，面向交付每类 1000 张以上。
• 训练是「训练、观察、调整」的循环：results.png 看曲线趋势，少类别简单项目 mAP50 应以 0.9 为目标，不达标时从 best.pt 降学习率继续训练并开启数据增强。
• 交付物是 weights/best.pt，用未参与训练的图片批量测试后再投入使用，后续可走服务化、ONNX 导出与持续迭代三条路线。

6.2 常见问题与解答

问：训练时报显存不足（CUDA out of memory）怎么办？

答：把 config.py 中的 BATCH 调小（16 改 8 甚至 4），WORKERS 调小到 1；关闭占用显存的其他程序（浏览器硬件加速、游戏、其他本地模型）。显卡整体偏弱时换 yolov8n 模型并把输入尺寸调小也是有效手段。

问：torch.cuda.is_available() 返回 False 怎么排查？

答：先执行 nvidia-smi 确认驱动正常；再确认安装顺序，先装 CUDA 版 PyTorch、后装 ultralytics；如果 ultralytics 安装时覆盖了 PyTorch，重新执行一次 CUDA 版安装命令即可修复。无 NVIDIA 显卡的机器直接在 config.py 中把 DEVICE 改为 "cpu"。

问：预训练模型或数据集下载很慢怎么办？

答：本教程的示例项目压缩包已内置 yolov8n.pt 与 COCO8 数据集，解压后全部示例可离线运行。使用其他模型或数据集时，可以手动下载权重文件放到项目目录，数据集也可以用 yolo settings datasets_dir=你的数据集目录 指定存放位置。

问：mAP 指标为 0 或异常低是什么原因？

答：按顺序排查三点：data.yaml 中的 names 与标注时的 classes.txt 顺序是否一致；train/val 路径是否真实指向了图像目录；标注文件与图像是否一一同名对应。三者都正常时，通常是数据量不足或训练轮数太少，补数据并提高 epochs。

问：best.pt 和 last.pt 应该用哪一个？

答：日常使用选 best.pt，它是整个训练过程中验证指标最高的一轮权重；last.pt 是最后一轮的权重，主要用于训练中断后恢复现场。两者都会随训练自动更新，不存在手工挑选的问题。

问：CPU 能完成训练吗？

答：能。把 config.py 中的 DEVICE 改为 "cpu" 即可，本教程的 COCO8 演示在 CPU 上只需数分钟。真实项目的 CPU 训练速度通常慢一个数量级以上，建议至少使用 6GB 显存的 NVIDIA 显卡。

问：训练出的模型可以商用吗？

答：权重文件继承 Ultralytics 框架的 AGPL-3.0 协议。产品开源并遵守 AGPL 义务时可以免费商用；闭源商业使用需要向 Ultralytics 购买商业许可。模型质量与数据合规（自己拍摄或已获授权的图片）需另行自行保障。

问：官方新出的 YOLO11 能用本教程的方法训练吗？

答：可以。YOLO11 与 YOLOv8 共用同一套 ultralytics 框架与接口，把教程中所有 yolov8n.pt 换成 yolo11n.pt 即可，data.yaml、标注格式与训练命令完全不变。