Skip to content

T
test_model
Commit 9449ad59 authored by 闻有阳's avatar 闻有阳
Browse files
Options

上传新文件

parent 4a470238
Hide whitespace changes
Inline Side-by-side
Showing with 542 additions and 0 deletions
train.md 0 → 100644
View file @ 9449ad59
# 训推平台 API 接口文档
## 接口概述
本文档详细描述 YOLOv8 训练任务管理 API 的所有接口，包括请求参数、返回结果及使用示例。该 API 提供训练任务的全生命周期管理，支持任务启动、进度查询、暂停/继续和日志查看等功能。
## 基础信息
- **服务地址**：`http://103.85.179.118:38085`
- **接口前缀**：`/api/yolo/train`
- **数据格式**：请求和返回均为 JSON 格式
- **内容类型**：`Content-Type: application/json`
## 接口详情
### 1. 启动训练任务
#### 接口信息
- **URL**：`/start`
- **方法**：`POST`
- **描述**：创建并启动新的 YOLOv8 训练任务，返回唯一任务 ID 用于后续操作
#### 请求参数
| 参数名 | 类型 | 是否必需 | 示例值 | 描述 |
|--------|------|----------|--------|------|
| dataset_path | string | 是 | `/root/ai/datasets/drink` | 数据集根路径（需包含 data.yaml 配置文件） |
| model_path | string | 是 | `/root/ai/weights/yolov8s.pt` | 预训练模型文件路径 |
| epochs | integer | 否 | 20 | 训练轮次，默认值为 10 |
| batch | integer | 否 | 16 | 批次大小，默认值为 8 |
| imgsz | integer | 否 | 640 | 输入图片尺寸，默认值为 640 |
| use_gpu | boolean | 否 | true | 是否使用 GPU 训练，默认值为 true |
#### 请求示例
```bash
curl -X POST "http://103.85.179.118:38085/api/yolo/train/start" \
-H "Content-Type: application/json" \
-d '{
"dataset_path": "/root/ai/datasets/Drink_284_Detection_YOLO/Drink_284_Detection_Labelme",
"model_path": "/root/ai/weights/yolov8-weights/yolov8s.pt",
"epochs": 20,
"batch": 16,
"imgsz": 640,
"use_gpu": true
}'
```
#### 返回结果
```json
{
"status": "训练任务已启动",
"task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"message": "使用返回的task_id可执行进度查询、停止/继续训练、查看日志",
"train_config": {
"dataset_path": "/root/ai/datasets/Drink_284_Detection_YOLO/Drink_284_Detection_Labelme",
"model_path": "/root/ai/weights/yolov8-weights/yolov8s.pt",
"epochs": 20,
"batch": 16,
"imgsz": 640,
"use_gpu": true
},
"created_at": "2025-10-11T15:30:00.123Z"
}
```
#### 状态码说明
- `200`：请求成功，任务已创建并启动
- `400`：请求参数错误（如缺少必填参数）
### 2. 查询训练进度
#### 接口信息
- **URL**：`/progress`
- **方法**：`GET`
- **描述**：根据任务 ID 查询训练任务的实时进度和状态
#### 请求参数（查询字符串）
| 参数名 | 类型 | 是否必需 | 示例值 | 描述 |
|--------|------|----------|--------|------|
| task_id | string | 是 | `f47ac10b-58cc-4372-a567-0e02b2c3d479` | 启动训练时返回的唯一任务 ID |
#### 请求示例
```bash
curl "http://103.85.179.118:38085/api/yolo/train/progress?task_id=346f39a7-95cb-45f1-bca3-0bea42407b62"
```
#### 返回结果
```json
{
"task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "running",
"progress": "45%",
"current_epoch": 9,
"total_epochs": 20,
"start_time": "2025-10-11T15:30:00.123Z",
"end_time": null,
"resumed_at": null,
"train_dir": "/root/ai/train_output/drink_train_20251011_153000_f47ac10b",
"error": null
}
```
#### 状态说明
- `pending`：任务已创建但未开始
- `running`：任务正在运行
- `stopped`：任务已被手动停止
- `completed`：任务已正常完成
- `failed`：任务执行失败
#### 状态码说明
- `200`：请求成功
- `404`：任务 ID 不存在
### 3. 停止训练任务
#### 接口信息
- **URL**：`/stop`
- **方法**：`POST`
- **描述**：根据任务 ID 停止正在运行的训练任务
#### 请求参数（查询字符串）
| 参数名 | 类型 | 是否必需 | 示例值 | 描述 |
|--------|------|----------|--------|------|
| task_id | string | 是 | `f47ac10b-58cc-4372-a567-0e02b2c3d479` | 训练任务的唯一 ID |
#### 请求示例
```bash
curl -X POST "http://103.85.179.118:38085/api/yolo/train/stop?task_id=346f39a7-95cb-45f1-bca3-0bea42407b62"
```
#### 返回结果
```json
{
"task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "任务已停止",
"stopped_at": "2025-10-11T15:40:00.456Z",
"current_progress": "45%",
"message": "可调用/resume接口继续训练"
}
```
#### 状态码说明
- `200`：请求成功，任务已停止
- `400`：任务状态不允许停止（如已完成或已失败）
- `404`：任务 ID 不存在
### 4. 继续训练任务
#### 接口信息
- **URL**：`/resume`
- **方法**：`POST`
- **描述**：根据任务 ID 继续已停止的训练任务
#### 请求参数（查询字符串）
| 参数名 | 类型 | 是否必需 | 示例值 | 描述 |
|--------|------|----------|--------|------|
| task_id | string | 是 | `f47ac10b-58cc-4372-a567-0e02b2c3d479` | 训练任务的唯一 ID |
#### 请求示例
```bash
curl -X POST "http://103.85.179.118:38085/api/yolo/train/resume?task_id=346f39a7-95cb-45f1-bca3-0bea42407b62"
```
#### 返回结果
```json
{
"task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "任务已恢复训练",
"resumed_at": "2025-10-11T15:45:00.789Z",
"resume_progress": "45%",
"message": "可调用/progress接口查询最新进度"
}
```
#### 状态码说明
- `200`：请求成功，任务已恢复
- `400`：任务状态不允许继续（如正在运行或已完成）
- `404`：任务 ID 不存在
### 5. 查看训练日志
#### 接口信息
- **URL**：`/log`
- **方法**：`GET`
- **描述**：根据任务 ID 查看训练日志，支持指定返回行数
#### 请求参数（查询字符串）
| 参数名 | 类型 | 是否必需 | 示例值 | 描述 |
|--------|------|----------|--------|------|
| task_id | string | 是 | `f47ac10b-58cc-4372-a567-0e02b2c3d479` | 训练任务的唯一 ID |
| log_lines | integer | 否 | 200 | 需要返回的日志行数，默认值为 100 |
#### 请求示例
```bash
# 查看默认的最后100行日志
curl "http://103.85.179.118:38085/api/yolo/train/log?task_id=346f39a7-95cb-45f1-bca3-0bea42407b62"
# 查看最后200行日志
curl "http://103.85.179.118:38085/api/yolo/train/log?task_id=f47ac10b-58cc-4372-a567-0e02b2c3d479&log_lines=200"
```
#### 返回结果
```json
{
"task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"log_file": "/root/ai/train_logs/train_f47ac10b-58cc-4372-a567-0e02b2c3d479.log",
"return_lines": 100,
"total_lines": 1250,
"log_content": "2025-10-11 15:30:00 - INFO - 任务启动：task_id=f47ac10b-58cc-4372-a567-0e02b2c3d479...\n..."
}
```
#### 状态码说明
- `200`：请求成功，返回日志内容
- `404`：任务 ID 不存在或日志文件未生成
- `500`：读取日志文件失败
## 错误码说明
| 状态码 | 描述 | 常见原因 |
|--------|------|----------|
| 200 | 请求成功 | 接口调用成功 |
| 400 | 无效请求 | 参数错误、任务状态不允许当前操作 |
| 404 | 资源不存在 | 任务 ID 错误或不存在 |
| 500 | 服务器错误 | 服务内部错误，查看服务日志获取详情 |
### 6. 上传训练数据集
#### 接口信息
- **URL**：`/api/dataset/upload`
- **方法**：`POST`
- **请求格式**：`multipart/form-data`（文件上传专用格式）
- **描述**：上传 ZIP 格式的数据集压缩包，自动解压至指定目录并校验完整性（需包含`data.yaml`配置文件）
#### 请求参数
| 参数名 | 类型 | 是否必需 | 示例值 | 描述 | 约束说明 |
|--------|------|----------|--------|------|----------|
| dataset_name | string | 是 | `drink_det_v1` | 数据集名称（用于创建唯一目录） | 仅支持字母、数字、下划线，长度 1-50 字符 |
| file | file | 是 | - | 数据集压缩包 | 仅支持 ZIP 格式，单个文件最大限制 10GB |
#### 请求示例
```bash
curl -X POST "http://103.85.179.118:38085/api/dataset/upload" \
-H "Content-Type: multipart/form-data" \
-F "dataset_name=drink_det_v1" \
-F "file=@drink_dataset.zip"
```
#### 成功响应（200 OK）
```json
{
"status": "上传成功",
"dataset_name": "drink_det_v1",
"dataset_path": "/root/ai/datasets/drink_det_v1",
"message": "可使用该路径进行训练",
"created_at": "2023-10-21T09:15:30.123456"
}
```
#### 错误响应
- `400 Bad Request`：`{"detail": "仅支持zip格式的压缩包"}` 或 `{"detail": "数据集缺少必要的data.yaml配置文件"}`
- `500 Internal Server Error`：`{"detail": "解压失败：[错误信息，如压缩包损坏]"}`
---
### 7. 获取可用数据集列表
#### 接口信息
- **URL**：`/api/dataset/list`
- **方法**：`GET`
- **描述**：查询所有已上传且结构合法的数据集（含`data.yaml`的目录），返回基础信息供训练选择
#### 请求参数
无（无需额外参数）
#### 请求示例
```bash
curl "http://103.85.179.118:38085/api/dataset/list"
```
#### 成功响应（200 OK）
{
"total": 2,
"datasets": [
{
"name": "drink_det_v1",
"path": "/root/ai/datasets/drink_det_v1",
"created_at": "2023-10-21T09:15:30.123456",
"sample_count": 1200
},
{
"name": "fruit_det_v2",
"path": "/root/ai/datasets/fruit_det_v2",
"created_at": "2023-10-20T14:20:15.123456",
"sample_count": 850
}
]
}
---
### 8. 模型验证（评估性能）
#### 接口信息
- **URL**：`/api/model/validate`
- **方法**：`POST`
- **描述**：使用指定数据集评估模型性能，返回 mAP、精度、召回率等核心指标，用于判断模型效果
#### 请求参数（JSON 格式）
| 参数名 | 类型 | 是否必需 | 默认值 | 示例值 | 描述 |
|--------|------|----------|--------|--------|------|
| model_path | string | 是 | - | `/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt` | 待验证模型路径（如训练输出的 best.pt） |
| dataset_path | string | 是 | - | `/root/ai/datasets/drink_det_v1` | 验证数据集路径（需含 data.yaml） |
| use_gpu | boolean | 否 | true | true | 是否使用 GPU 加速验证（false 为 CPU） |
| imgsz | integer | 否 | 640 | 640 | 验证时输入图片尺寸 |
#### 请求示例
```bash
curl -X POST "http://103.85.179.118:38085/api/model/validate" \
-H "Content-Type: application/json" \
-d '{
"model_path": "/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt",
"dataset_path": "/root/ai/datasets/drink_det_v1",
"use_gpu": true,
"imgsz": 640
}'
```
#### 成功响应（200 OK）
{
"status": "验证成功",
"model_path": "/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt",
"dataset_path": "/root/ai/datasets/drink_det_v1",
"metrics": {
"mAP50": 0.925,
"mAP50-95": 0.783,
"precision": 0.896,
"recall": 0.872,
"class_metrics": [
{
"class_id": 0,
"class_name": "cola",
"mAP50": 0.951,
"precision": 0.923,
"recall": 0.901
},
{
"class_id": 1,
"class_name": "juice",
"mAP50": 0.902,
"precision": 0.875,
"recall": 0.843
}
],
"metrics": {
"box_loss": 0.023,
"cls_loss": 0.011,
"obj_loss": 0.008
}
},
"validate_time": "2023-10-21T10:30:15.123456"
}
#### 错误响应
- `404 Not Found`：`{"detail": "模型文件不存在：/root/ai/weights/best.pt"}` 或 `{"detail": "数据集配置文件不存在：/root/ai/datasets/drink_det_v1/data.yaml"}`
- `500 Internal Server Error`：`{"detail": "验证失败：[错误信息，如GPU内存不足]"}`
---
### 9. 模型预测（单图检测）
#### 接口信息
- **URL**：`/api/model/predict`
- **方法**：`POST`
- **描述**：使用训练好的模型对单张图片进行目标检测，返回检测结果（类别、置信度、边界框）及结果保存路径
#### 请求参数（JSON 格式）
| 参数名 | 类型 | 是否必需 | 默认值 | 示例值 | 描述 |
|--------|------|----------|--------|--------|------|
| model_path | string | 是 | - | `/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt` | 检测模型路径（如 best.pt） |
| image_path | string | 是 | - | `/root/ai/test_imgs/drink_001.jpg` | 待检测图片路径（支持 jpg/png 格式） |
| use_gpu | boolean | 否 | true | true | 是否使用 GPU 加速预测 |
| conf_threshold | number | 否 | 0.25 | 0.25 | 检测置信度阈值（低于此值的结果不返回） |
| iou_threshold | number | 否 | 0.45 | 0.45 | 非极大值抑制（NMS）的 IoU 阈值 |
| save_result | boolean | 否 | true | true | 是否保存检测结果图片（含边界框标注） |
#### 请求示例
```bash
curl -X POST "http://103.85.179.118:38085/api/model/predict" \
-H "Content-Type: application/json" \
-d '{
"model_path": "/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt",
"image_path": "/root/ai/test_imgs/drink_001.jpg",
"use_gpu": true,
"conf_threshold": 0.25,
"iou_threshold": 0.45,
"save_result": true
}'
```
#### 成功响应（200 OK）
{
"status": "预测成功",
"model_path": "/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt",
"image_path": "/root/ai/test_imgs/drink_001.jpg",
"predictions": [
{
"class_id": 0,
"class_name": "cola",
"confidence": 0.968,
"bbox": [125.3, 89.2, 342.1, 456.7],
"bbox_format": "xyxy"
},
{
"class_id": 1,
"class_name": "juice",
"confidence": 0.893,
"bbox": [412.5, 105.3, 620.8, 430.2]
}
],
"result_save_path": "/root/ai/train_output/predictions/8f4d2c1e/drink_001.jpg",
"predict_time": "0.08s"
}
#### 错误响应
- `404 Not Found`：`{"detail": "图片文件不存在：/root/ai/test_imgs/drink_001.jpg"}`
- `400 Bad Request`：`{"detail": "不支持的图片格式：仅支持jpg/png"}`
---
### 10. 模型导出（格式转换）
#### 接口信息
- **URL**：`/api/model/export`
- **方法**：`POST`
- **描述**：将 YOLO 模型（.pt 格式）导出为部署常用格式（如 ONNX、TensorRT），适配不同推理框架
#### 请求参数（JSON 格式）
| 参数名 | 类型 | 是否必需 | 默认值 | 示例值 | 描述 | 支持格式列表 |
|--------|------|----------|--------|--------|------|--------------|
| model_path | string | 是 | - | `/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt` | 待导出的.pt 模型路径 | - |
| export_format | string | 否 | "onnx" | "onnx" | 目标导出格式 | onnx、torchscript、openvino、engine（TensorRT）、coreml、tflite |
| use_gpu | boolean | 否 | true | true | 导出时是否使用 GPU（仅对 engine 格式生效） | - |
| imgsz | integer | 否 | 640 | 640 | 导出模型的输入尺寸（需与训练一致） | - |
| simplify | boolean | 否 | true | true | 是否简化模型（仅 onnx 格式支持，减小文件体积） | - |
#### 请求示例
```bash
curl -X POST "http://103.85.179.118:38085/api/model/export" \
-H "Content-Type: application/json" \
-d '{
"model_path": "/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt",
"export_format": "onnx",
"use_gpu": true,
"imgsz": 640,
"simplify": true
}'
```
#### 成功响应（200 OK）
{
"status": "导出成功",
"model_path": "/root/ai/train_output/drink_train_20231020_153045_f47ac10b/weights/best.pt",
"export_format": "onnx",
"export_path": "/root/ai/train_output/exports/7a3b5d9c/exported_model.onnx",
"model_size": "12.5MB",
"export_time": "2023-10-21T11:45:20.123456",
"message": "可通过/api/model/download接口下载导出的模型"
}
#### 错误响应
- `400 Bad Request`：`{"detail": "不支持的导出格式：tensorflow，支持的格式：onnx,torchscript,openvino,engine,coreml,tflite"}`
- `500 Internal Server Error`：`{"detail": "模型导出失败：[错误信息，如TensorRT环境未配置]"}`
---
### 11. 模型下载（获取导出文件）
#### 接口信息
- **URL**：`/api/model/download`
- **方法**：`GET`
- **描述**：下载通过`/api/model/export`接口导出的模型文件，支持断点续传
#### 请求参数（查询字符串）
| 参数名 | 类型 | 是否必需 | 示例值 | 描述 | 安全约束 |
|--------|------|----------|--------|------|----------|
| file_path | string | 是 | `/root/ai/train_output/exports/7a3b5d9c/exported_model.onnx` | 导出模型的完整路径（从`/api/model/export`响应中获取） | 仅允许下载`/root/ai/train_output`目录下的文件，防止越权访问 |
#### 请求示例
```bash
curl "http://103.85.179.118:38085/api/model/download?file_path=/root/ai/train_output/exports/7a3b5d9c/exported_model.onnx" -o exported_model.onnx
```
#### 成功响应（200 OK）
- **响应类型**：`application/octet-stream`（二进制文件流）
- **响应头**：包含`Content-Disposition: attachment; filename="exported_model.onnx"`（指定下载文件名）
- **响应体**：模型文件二进制数据
#### 错误响应
- `404 Not Found`：`{"detail": "文件不存在：/root/ai/train_output/exports/7a3b5d9c/exported_model.onnx"}`
- `403 Forbidden`：`{"detail": "无权访问该文件：/root/other_files/model.onnx"}`（访问非允许目录）
## 四、系统配置与附录
### 1. 系统资源限制
| 资源类型 | 限制说明 | 配置修改方式 |
|----------|----------|--------------|
| 并发训练任务 | 默认最大 2 个 | 修改代码中`ThreadPoolExecutor(max_workers=2)`的`max_workers`参数 |
| 数据集上传大小 | 单个文件最大 10GB | 修改`upload_dataset`接口中`shutil.copyfileobj`的缓冲区配置 |
| 模型导出耗时 | ONNX 格式约 10-30 秒，TensorRT 格式约 1-5 分钟 | 取决于 GPU 性能（建议使用 RTX 3090 及以上） |
### 2. 目录结构说明
/root/ai/
├─ datasets/ # 数据集根目录（上传的数据集存放于此）
│ ├─ drink_det_v1/ # 单个数据集目录（含images、labels、data.yaml）
│ └─ fruit_det_v2/
├─ train_logs/ # 训练任务日志目录（每个任务一个日志文件）
├─ train_output/ # 训练输出根目录
│ ├─ drink_train_20231020_153045_f47ac10b/ # 单个训练任务目录
│ │ ├─ weights/ # 模型权重（best.pt、last.pt）
│ │ └─ train.log # YOLO原生日志
│ ├─ predictions/ # 预测结果保存目录
│ └─ exports/ # 模型导出目录
### 3. 常见问题（FAQ）
1. **Q：训练任务启动后立即失败，提示 “数据集路径不存在”？**
A：检查`dataset_path`是否为`/root/ai/datasets/`下的合法目录（可通过`/api/dataset/list`确认路径），且目录内包含`data.yaml`。
2. **Q：模型导出为 ONNX 后，推理时提示 “输入尺寸不匹配”？**
A：确保导出时`imgsz`参数与训练时一致（默认 640），推理时输入图片需先缩放到对应尺寸。
3. **Q：下载模型时提示 “无权访问”？**
A：仅允许下载`/root/ai/train_output`目录下的文件，需使用`/api/model/export`返回的`export_path`作为`file_path`参数。
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment