# YOLO 模型测试流程指南

本文档基于知乎文章整理，帮助你从零开始完成一个 YOLO 目标检测项目的完整流程。

***

## 目录

1. [环境准备](#1-环境准备)
2. [数据收集与准备](#2-数据收集与准备)
3. [数据标注](#3-数据标注)
4. [配置数据集](#4-配置数据集)
5. [模型训练](#5-模型训练)
6. [模型评估与测试](#6-模型评估与测试)

***

## 1. 环境准备

### 1.1 安装 Python 环境

确保 Python 版本 >= 3.8

```bash
python --version
```

### 1.2 创建虚拟环境

为了避免影响全局 Python 环境，建议为项目创建独立的虚拟环境。

**方式一：使用 conda

**首先安装 Anaconda 或 Miniconda：**
1. 下载 Miniconda（推荐，更轻量）：<https://docs.conda.io/en/latest/miniconda.html>
2. 运行安装程序，勾选 "Add Miniconda to PATH"（或安装后手动配置）
3. 验证安装：

```bash
conda --version
```

**创建并激活虚拟环境：**

```bash
# 首次使用需要接受服务条款
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/msys2

# 切换用清华的源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main

# 创建虚拟环境
conda create -n yolo_demo python=3.10 -y

# 激活虚拟环境
conda activate yolo_demo
conda env list

# 安装 pytorch（GPU 支持，需要 CUDA）
# 首先卸载 CPU 版本（如果已安装）
conda uninstall pytorch torchvision torchaudio -y

# 安装 PyTorch CUDA 版本（推荐 CUDA 12.1）
conda install -v pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia -y
# pip 来安装 PyTorch 更稳定
conda activate yolo_demo ; pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 验证安装是否成功
python -c "import torch; print(f'PyTorch版本: {torch.__version__}'); print(f'CUDA可用: {torch.cuda.is_available()}')"
```

**查看已创建的环境：**

```bash
conda env list
```

**常见问题：**
如果遇到 `CondaToSNonInteractiveError` 错误，需要先运行上面的 `conda tos accept` 命令接受服务条款。

**验证虚拟环境已激活：**
激活后，终端提示符前会显示虚拟环境名称：

```bash
(yolo_demo) D:\Codes\AI\Yolo\YoloDemo>
```

**退出虚拟环境：**

```bash
# conda:
conda deactivate
```

### 1.3 安装 YOLOv8（推荐）

```bash
conda activate yolo_demo ; pip install ultralytics
```

### 1.4 验证安装

```bash
python -c "from ultralytics import YOLO; print('YOLOv8 安装成功')"
```

### 1.5 检查 GPU 支持（可选但推荐）

```bash
python -c "import torch; print(f'CUDA可用: {torch.cuda.is_available()}')"
```

***

## 2. 数据收集与准备

### 2.1 确定检测目标

首先明确你要检测的类别，例如：
- car（汽车）
- person（行人）
- bicycle（自行车）

### 2.2 数据量建议

| 项目类型 | 每类最少图片 | 推荐图片数 |
| ---- | ------- | ------ |
| 快速原型 | 100-200 张 | 500 张 |
| 生产应用 | 1000 张    | 3000 张 |

### 2.3 数据来源

**方式一：使用公开数据集**
- COCO 数据集：<https://cocodataset.org>
- Open Images：<https://storage.googleapis.com/openimages>

**方式二：自己拍摄/收集图片**
- 确保图片清晰，目标可见
- 覆盖不同场景、光照、角度
- 统一格式为 JPG 或 PNG

***

## 3. 数据标注

### 3.1 选择标注工具

推荐使用以下工具之一：

- **VisioFirm**（推荐标注工具）⭐
- **TjMakeBot**（在线工具，支持 AI 辅助标注）：<https://www.tjmakebot.com>
- **LabelImg**（本地工具）
- **Roboflow**（在线工具）

**快速启动 VisioFirm：**

```powershell
# 在项目根目录运行
.\start_visiofirm.ps1
```

详细的 VisioFirm 使用说明请查看：[VisioFirm 标注工具使用指南](./2.VisioFirm标注工具使用指南.md)

### 3.2 YOLO 标注格式说明

每张图片对应一个 `.txt` 文件，格式如下：

```
class_id center_x center_y width height
```

示例：

```
0 0.5 0.5 0.3 0.4
1 0.2 0.3 0.1 0.2
```

**说明：**
- `class_id`：类别 ID（从 0 开始）
- `center_x, center_y`：边界框中心点坐标（归一化 0-1）
- `width, height`：边界框宽高（归一化 0-1）

***

## 4. 配置数据集

### 4.1 数据集目录结构

支持多种数据集组织方式：

**方式一：VisioFirm 导出（推荐）**
```
dataset/tags/visiofirm/20260505_01/
├── data.yaml
├── train/images/
├── train/labels/
├── val/images/
├── val/labels/
└── test/images/
    └── test/labels/
```

**方式二：LabelImg 标注**
```
dataset/tags/LabelImg/20260505_01/
├── data.yaml
├── train/images/
├── train/labels/
├── val/images/
├── val/labels/
└── test/images/
    └── test/labels/
```

### 4.2 配置 dataset.yaml

在项目根目录创建 `dataset.yaml` 文件，配置示例见：[configs/dataset-traditional.yaml](../configs/dataset-traditional.yaml)

**关键配置项：**
- `path`: 数据集根目录（支持相对路径）
- `train`: 训练集图片目录（相对于 path）
- `val`: 验证集图片目录（相对于 path）
- `test`: 测试集图片目录（相对于 path）
- `nc`: 类别数量
- `names`: 类别名称列表

**示例配置：**
```yaml
path: ./dataset/tags/visiofirm/20260505_01
train: train/images
val: val/images
test: test/images

nc: 2
names:
  - person
  - bicycle
```

### 4.3 验证数据集

使用 [src/validate_dataset.py](../src/validate_dataset.py) 脚本验证数据集：

```bash
python src/validate_dataset.py
```

***

## 5. 模型训练

### 5.1 开始训练

使用 [src/train.py](../src/train.py) 脚本训练模型：

```bash
python src/train.py
```

常用参数：
- `--config`: dataset.yaml 配置文件路径（默认使用项目根目录）
- `--model`: 预训练模型（默认: yolov8n.pt）
- `--epochs`: 训练轮数（默认: 100）
- `--batch`: 批次大小（默认: 16）
- `--imgsz`: 输入图片尺寸（默认: 640）
- `--lr`: 初始学习率（默认: 0.01）
- `--device`: 设备（cuda/cpu，默认自动检测）

### 5.2 模型选择建议

| 模型 | 参数量 | 速度 | 精度 | 适用场景 |
| ---- | ----- | -- | -- | ---- |
| yolov8n | 3.2M | 最快 | 较低 | 实时检测 |
| yolov8s | 11.2M | 快 | 中等 | 平衡 |
| yolov8m | 25.9M | 中等 | 较高 | 生产环境 |
| yolov8l | 43.7M | 较慢 | 高 | 高精度 |

***

## 6. 模型评估与测试

### 6.1 评估模型

使用 [src/evaluate.py](../src/evaluate.py) 脚本评估模型：

```bash
python src/evaluate.py
```

**特点：**
- 自动查找最新训练的模型（无需手动指定路径）
- 支持从多个可能的位置查找已保存模型

参数：
- `--model`: 模型路径（默认：自动查找最新模型）
- `--config`: dataset.yaml 配置文件路径（默认使用项目根目录）
- `--split`: 评估集（train/val/test，默认: val）

### 6.2 预测

使用 [src/predict.py](../src/predict.py) 脚本进行预测：

```bash
python src/predict.py
```

**特点：**
- 自动查找最新训练的模型（无需手动指定路径）
- 自动从 dataset.yaml 读取测试集路径

参数：
- `--model`: 模型路径（默认：自动查找最新模型）
- `--source`: 预测源（图片/目录，默认：读取 dataset.yaml）
- `--conf`: 置信度阈值（默认: 0.25）
- `--nosave`: 不保存结果（默认保存）

### 6.3 模型导出为 ONNX 格式

使用 [src/export_onnx.py](../src/export_onnx.py) 脚本将 PyTorch (.pt) 模型导出为 ONNX 格式：

```bash
python src/export_onnx.py
```

**特点：**
- 自动查找最新训练的模型（无需手动指定路径）
- 支持模型简化，减小文件体积
- 可自定义输入尺寸和 ONNX opset 版本

参数：
- `--model`: 模型路径（默认：自动查找最新模型）
- `--imgsz`: 输入图片尺寸（默认: 640）
- `--simplify`: 简化模型（默认: True）
- `--no-simplify`: 不简化模型
- `--opset`: ONNX opset 版本（默认: 12）

**使用示例：**
```bash
# 导出最新训练的模型（自动查找）
python src/export_onnx.py

# 导出指定模型
python src/export_onnx.py --model runs/detect/my_model/weights/best.pt

# 自定义输入尺寸
python src/export_onnx.py --imgsz 1280

# 不简化模型
python src/export_onnx.py --no-simplify

# 自定义 opset 版本
python src/export_onnx.py --opset 17
```

***

## 快速开始命令汇总

**注意：请在项目根目录（YoloDemo）下运行以下命令**

```bash
# 1. 配置 dataset.yaml（首次使用）
# 复制 configs/dataset-traditional.yaml 到项目根目录，修改 path 指向你的数据集

# 2. 验证数据集
python src/validate_dataset.py

# 3. 训练模型
python src/train.py

# 4. 评估模型（自动查找最新训练好的模型）
python src/evaluate.py

# 5. 预测（自动查找最新模型）
python src/predict.py

# 6. 导出为 ONNX 格式（自动查找最新模型）
python src/export_onnx.py
```

***

祝训练顺利！