# yolo-practice

**Repository Path**: Glacier_J/yolo-practice

## Basic Information

- **Project Name**: yolo-practice
- **Description**: yolo模型训练实践
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-01-27
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YOLO11 训练模板

基于 Ultralytics YOLO11 的通用训练模板，支持灵活的参数配置和多种任务类型。

## 特性

- ✅ 支持 YOLO11 全系列模型（n/s/m/l/x）
- ✅ 灵活的配置文件系统（模型/训练/数据集分离）
- ✅ 100+ 可调训练参数
- ✅ Windows 环境优化
- ✅ 完善的错误处理和日志输出
- ✅ 支持训练、验证、推理全流程
- ✅ 中文注释，易于理解

## 项目结构

```
yolo-train/
├── config/                    # 配置文件目录
│   ├── model_config.yaml      # 模型配置
│   └── train_config.yaml      # 训练超参数配置
├── data/                      # 数据集目录
│   ├── datasets/              # 数据集存放位置
│   └── example.yaml           # 数据集配置示例
├── models/                    # 预训练权重目录
├── src/                       # 源代码目录
│   ├── train.py               # 训练脚本
│   ├── validate.py            # 验证脚本
│   ├── predict.py             # 推理脚本
│   └── utils.py               # 工具函数
├── runs/                      # 训练输出目录（自动生成）
├── requirements.txt           # Python 依赖
└── README.md                  # 本文件
```

## 环境安装

### 1. Python 环境

推荐使用 Python 3.8 或更高版本。

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. GPU 支持（可选但推荐）

如果有 NVIDIA GPU，确保安装了 CUDA 和 cuDNN：

- CUDA 11.8+ 或 12.x
- PyTorch 2.0+（自动安装 CUDA 版本）

验证 GPU 可用性：

```bash
python -c "import torch; print(torch.cuda.is_available())"
```

## 快速开始

### 1. 准备数据集

数据集需要符合 YOLO 格式，详见 [data/datasets/README.md](data/datasets/README.md)。

目录结构示例：

```
data/datasets/your_dataset/
├── images/
│   ├── train/
│   └── val/
└── labels/
    ├── train/
    └── val/
```

创建数据集配置文件（参考 `data/example.yaml`）：

```yaml
path: ./data/datasets/your_dataset
train: images/train
val: images/val

nc: 2  # 类别数
names:
  0: class1
  1: class2
```

### 2. 配置训练参数

编辑 `config/train_config.yaml` 调整训练参数：

```yaml
train:
  epochs: 100
  batch: 16
  imgsz: 640
  device: 0  # GPU ID，cpu 或 0,1,2,3
  workers: 0  # Windows 建议设为 0
```

### 3. 开始训练

```bash
python src/train.py --data data/your_dataset.yaml
```

训练结果将保存在 `runs/train/exp/` 目录下。

### 4. 验证模型

```bash
python src/validate.py \
    --weights runs/train/exp/weights/best.pt \
    --data data/your_dataset.yaml
```

### 5. 推理预测

```bash
# 单张图片
pn src/predict.py \
    --weights runs/train/exp/weights/best.pt \
    --source path/to/image.jpg

# 文件夹
python src/predict.py \
    --weights runs/train/exp/weights/best.pt \
    --source path/to/images/

# 视频
python src/predict.py \
    --weights runs/train/exp/weights/best.pt \
    --source path/to/video.mp4

# 摄像头
python src/predict.py \
    --weights runs/train/exp/weights/best.pt \
    --source 0
```

## 详细使用说明

### 训练脚本参数

```bash
python src/train.py \
    --model-config config/model_config.yaml \  # 模型配置文件
    --train-config config/train_config.yaml \  # 训练配置文件
    --data data/your_dataset.yaml \            # 数据集配置文件（必需）
    --epochs 100 \                             # 训练轮数（覆盖配置文件）
    --batch 16 \                               # 批次大小
    --imgsz 640 \                              # 图像尺寸
    --device 0 \                               # 设备
    --workers 0 \                              # 数据加载线程数
    --project runs/train \                     # 项目保存路径
    --name exp \                               # 实验名称
    --resume \                                 # 恢复训练
    --verbose                                  # 详细输出
```

### 验证脚本参数

```bash
python src/validate.py \
    --weights runs/train/exp/weights/best.pt \  # 模型权重（必需）
    --data data/your_dataset.yaml \             # 数据集配置（必需）
    --batch 16 \                                # 批次大小
    --imgsz 640 \                               # 图像尺寸
    --device 0 \                                # 设备
    --conf 0.001 \                              # 置信度阈值
    --iou 0.7 \                                 # NMS IoU 阈值
    --save-json \                               # 保存 COCO JSON 结果
    --verbose                         # 详细输出
```

### 推理脚本参数

```bash
python src/predict.py \
    --weights runs/train/exp/weights/best.pt \  # 模型权重（必需）
    --source path/to/source \                   # 输入源（必需）
    --imgsz 640 \                               # 图像尺寸
    --conf 0.25 \                               # 置信度阈值
    --iou 0.7 \                                 # NMS IoU 阈值
    --device 0 \                                # 设备
    --save \                                    # 保存结果
    --save-txt \                                # 保存 TXT 标注
    --save-crop \                               # 保存裁剪框
    --show \                                    # 显示结果
    --verbose                                   # 详细输出
```

## 配置文件说明

### 模型配置 (config/model_config.yaml)

```yaml
model:
  type: 'yolo11n.pt'  # 模型类型：yolo11n/s/m/l/x
  pretrained: true     # 是否使用预训练权重

task: 'detect'  # 任务类型：detect/segment/classify/pose
```

### 训练配置 (config/train_config.yaml)

配置文件包含以下部分：

- **基础训练参数**：epochs、batch、imgsz、device、workers
- **优化器参数**：optimizer、lr0、momentum、weight_decay
- **数据增强参数**：hsv、rotate、translate、mosaic、mixup
- **训练控制参数**：patience、save、resume、amp
- **验证参数**：conf、iou、max_det
- **损失函数权重**：box、cls、dfl

详细参数说明见配置文件中的注释。

## 模型选择指南

| 模型 | 参数量 | 速度 | 精度 | 适用场景 |
|------|--------|------|------|----------|
| yolo11n | 最小 | 最快 | 较低 | 边缘设备、实时应用 |
| yolo11s | 小 | 快 | 中等 | 移动端、嵌入式 |
| yolo11m | 中等 | 平衡 | 良好 | 通用场景 |
| yolo11l | 大 | 较慢 | 高 | 高精度需求 |
| yolo11x | 最大 | 最慢 | 最高 | 精度优先、离线处理 |

## 常见问题

### 1. 显存不足 (CUDA out of memory)

**解决方案**：
- 减小 `batch` 大小（如 16 → 8 → 4）
- 减小 `imgsz` 尺寸（如 640 → 512）
- 使用更小的模型（如 yolo11l → yolo11m）
- 关闭图像缓存（`cache: false`）

### 2. Windows 多进程错误

**解决方案**：
- 设置 `workers: 0`（已在默认配置中）

### 3. 训练速度慢

**检查项**：
- 确认使用 GPU（`device: 0`）
- 启用混合精度训练（`amp: true`）
- 增大 `batch` 大小（在显存允许范围内）
- 启用图像缓存（`cache: true`，需要足够内存）

### 4. 模型不收敛

**调整建议**：
- 检查数据集标注是否正确
- 降低学习率（`lr0: 0.001`）
- 增加训练轮数（`epochs: 200`）
- 调整数据增强强度
- 使用预训练权重（`pretrained: true`）

### 5. 路径错误

**注意事项**：
- 配置文件中使用正斜杠 `/`（不要用反斜杠 `\`）
- 使用绝对路径或相对于配置文件的路径
- Windows 路径示例：`C:/Users/Admin/datasets`

## 进阶功能

### 1. 多 GPU 训练

```bash
python src/train.py \
    --data data/your_dataset.yaml \
    --device 0,1,2,3  # 使用 4 块 GPU
```

### 2. 恢复训练

```bash
python src/train.py \
    --data data/your_dataset.yaml \
    --resume  # 从上次中断处继续
```

### 3. 自定义数据增强

编辑 `config/train_config.yaml` 中的 `augmentation` 部分：

```yaml
augmentation:
  mosaic: 1.0      # Mosaic 增强
  mixup: 0.1       # Mixup 增强
  degrees: 10.0    # 旋转角度
  translate: 0.2   # 平移范围
  scale: 0.9       # 缩放范围
  fliplr: 0.5      # 左右翻转
```

### 4. 导出模型

训练完成后，可以导出为其他格式：

```python
from ultralytics import YOLO

model = YOLO('runs/train/exp/weights/best.pt')

# 导出为 ONNX
model.export(format='onnx')

# 导出为 TensorRT
model.export(format='engine')

# 导出为 CoreML
model.export(format='coreml')
```

## 参考资料

- [Ultralytics YOLO11 官方文档](https://docs.ultralytics.com/)
- [YOLO11 论文](https://arxiv.org/abs/2304.00501)
- [数据集格式说明](data/datasets/README.md)

## 许可证

本项目基于 AGPL-3.0 许可证（继承自 Ultralytics YOLO）。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.0.0 (2026-01-26)
- 初始版本
- 支持 YOLO11 全系列模型训练
- 完整的配置文件系统
- 训练、验证、推理脚本