rtsp-video-analysis-system/YOLOV8-SETUP.md

# YOLOv8模型配置指南

本系统使用**YOLOv8**（Ultralytics）进行目标检测推理。

## 快速开始

### 1. 准备模型文件

将YOLOv8训练好的模型放到指定位置：

```bash
# 模型文件路径
python-inference-service/models/best.pt
```

### 2. 准备类别文件（可选）

创建 `classes.txt` 文件，每行一个类别名称：

```bash
# 文件路径
python-inference-service/models/classes.txt

# 内容示例
person
car
truck
bicycle
```

### 3. 启动服务

```bash
# 使用部署脚本
deploy.bat  # Windows
./deploy.sh # Linux/Mac

# 或手动启动
docker-compose up -d
```

## 训练YOLOv8模型

如果还没有训练好的模型，可以按以下步骤训练：

### 1. 安装Ultralytics

```bash
pip install ultralytics
```

### 2. 准备数据集

创建数据集配置文件 `data.yaml`：

```yaml
# 数据集路径
path: /path/to/dataset
train: images/train
val: images/val

# 类别
nc: 4  # 类别数量
names: ['person', 'car', 'truck', 'bicycle']  # 类别名称
```

### 3. 训练模型

```python
from ultralytics import YOLO

# 加载预训练模型
model = YOLO('yolov8n.pt')  # n, s, m, l, x 可选

# 训练模型
results = model.train(
    data='data.yaml',
    epochs=100,
    imgsz=640,
    batch=16,
    device=0  # GPU设备ID，CPU使用'cpu'
)

# 训练完成后，最佳模型保存在 runs/detect/train/weights/best.pt
```

### 4. 导出模型

训练完成后，将最佳模型复制到项目中：

```bash
# 复制模型文件
cp runs/detect/train/weights/best.pt python-inference-service/models/best.pt

# 创建类别文件
echo "person
car
truck
bicycle" > python-inference-service/models/classes.txt
```

## 模型配置

### 修改模型参数

编辑 `python-inference-service/models/yolov8_model.py`：

```python
# 置信度阈值
self.conf_threshold = 0.25  # 默认0.25，降低可检测更多目标

# 输入图像尺寸
self.img_size = 640  # 默认640，可改为320、1280等
```

### 配置文件

`python-inference-service/models/models.json`：

```json
[
  {
    "name": "yolov8_detector",
    "path": "models/yolov8_model.py",
    "size": [640, 640],
    "comment": "YOLOv8检测模型"
  }
]
```

参数说明：
- `name`: 模型名称（API调用时使用）
- `path`: 模型包装类路径
- `size`: 输入图像尺寸 [宽度, 高度]

## 多模型配置

如果有多个模型，可以配置多个：

```json
[
  {
    "name": "person_detector",
    "path": "models/person_model.py",
    "size": [640, 640]
  },
  {
    "name": "vehicle_detector",
    "path": "models/vehicle_model.py",
    "size": [640, 640]
  }
]
```

然后为每个模型创建对应的模型文件，参考 `yolov8_model.py`。

## 测试模型

### 本地测试

```python
from ultralytics import YOLO

# 加载模型
model = YOLO('python-inference-service/models/best.pt')

# 测试图像
results = model('test.jpg')

# 显示结果
results[0].show()

# 打印检测结果
for r in results:
    print(r.boxes)
```

### API测试

启动服务后，使用curl测试：

```bash
# 1. 检查服务健康
curl http://localhost:10080/python-api/health

# 2. 查看可用模型
curl http://localhost:10080/python-api/api/models

# 3. 测试检测（文件上传）
curl -X POST "http://localhost:10080/python-api/api/detect/file" \
  -F "model_name=yolov8_detector" \
  -F "file=@test.jpg"
```

## 性能优化

### 1. 使用GPU

确保Docker配置了GPU支持：

```yaml
# docker-compose.yml
python-service:
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1
            capabilities: [gpu]
```

### 2. 选择合适的模型大小

YOLOv8提供多种尺寸：

| 模型 | 参数量 | 速度 | 精度 |
|------|--------|------|------|
| YOLOv8n | 3.2M | 最快 | 较低 |
| YOLOv8s | 11.2M | 快 | 中等 |
| YOLOv8m | 25.9M | 中等 | 较高 |
| YOLOv8l | 43.7M | 慢 | 高 |
| YOLOv8x | 68.2M | 最慢 | 最高 |

根据需求选择：
- 实时处理 → 使用 `yolov8n.pt` 或 `yolov8s.pt`
- 高精度 → 使用 `yolov8l.pt` 或 `yolov8x.pt`

### 3. 调整图像尺寸

```python
# 在 yolov8_model.py 中
self.img_size = 320  # 更快但精度降低
# 或
self.img_size = 1280  # 更慢但精度提高
```

## 常见问题

### Q1: 模型加载失败

```
错误：FileNotFoundError: best.pt not found
解决：确保模型文件在 python-inference-service/models/best.pt
```

### Q2: GPU不可用

```
错误：CUDA not available
解决：
1. 检查NVIDIA驱动安装
2. 检查Docker GPU支持
3. 使用 docker run --gpus all 测试GPU
```

### Q3: 检测结果为空

```
原因：
1. 置信度阈值太高
2. 模型未正确训练
3. 输入图像与训练数据差异大

解决：
1. 降低 conf_threshold
2. 检查模型训练情况
3. 检查输入图像质量
```

### Q4: 推理速度慢

```
解决：
1. 使用GPU加速
2. 使用更小的模型（如yolov8n）
3. 减小输入图像尺寸
4. 批量处理多张图像
```

## 模型版本差异

### YOLOv5 vs YOLOv8

本系统已从YOLOv5升级到YOLOv8：

| 特性 | YOLOv5 | YOLOv8 |
|------|--------|--------|
| 精度 | 较高 | 更高 |
| 速度 | 快 | 更快 |
| API | yolov5 | ultralytics |
| 训练 | 复杂 | 简单 |

### 迁移说明

如果之前使用YOLOv5模型：

1. 使用YOLOv8重新训练（推荐）
2. 或使用 `garbage_model.py` 作为模板支持YOLOv5

## 参考资料

- [Ultralytics YOLOv8文档](https://docs.ultralytics.com/)
- [YOLOv8 GitHub](https://github.com/ultralytics/ultralytics)
- [模型训练教程](https://docs.ultralytics.com/modes/train/)
- [推理示例](https://docs.ultralytics.com/modes/predict/)

## 技术支持

如遇问题：
1. 查看服务日志：`docker-compose logs python-service`
2. 查看模型加载日志
3. 测试模型是否可以本地加载
4. 检查环境配置是否正确