# trainman

**Repository Path**: bestaone/trainman

## Basic Information

- **Project Name**: trainman
- **Description**: 模型训练、物体检测
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TrainMan - YOLO模型训练平台

## 📋 项目概述

TrainMan是一个基于YOLO系列模型的企业级AI训练平台,提供从数据管理、模型训练、推理测试到生产部署的全流程解决方案。

### 核心特性
- 🎯 支持多版本YOLO模型(YOLOv5/v8/v9/v10, YOLO-NAS等)
- 🚀 分布式训练与任务队列管理
- 📊 实时训练监控与实验对比
- 🔧 完整的模型生命周期管理
- 🌐 RESTful API + 实时推流服务
- 🐳 容器化部署,开箱即用
- 📦 支持CPU开发调试环境、GPU生产环境

---

## 🏗️ 技术架构

### 技术栈

**后端服务**
- **Web框架**: FastAPI (异步高性能)
- **任务队列**: Celery + Redis
- **数据库**: PostgreSQL (元数据)
- **对象存储**: MinIO (自建)
- **深度学习**: PyTorch + Ultralytics
- **模型加速**: ONNX Runtime, TensorRT (可选)

**前端界面**
- **框架**: Vue 3 + TypeScript
- **UI组件**: Element Plus
- **图表**: ECharts
- **实时通信**: WebSocket

**基础设施**
- **容器化**: Docker + Docker Compose
- **反向代理**: Nginx

### 系统架构图

```
┌──────────────────────────────────────────────────────────┐
│                        用户层                              │
│  Web浏览器 │ 移动端 │ API客户端 │ 命令行工具                │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                    接入层 (Nginx)                          │
│  负载均衡 │ SSL终止 │ 静态资源 │ 反向代理                  │
└────────────────────────┬─────────────────────────────────┘
                         │
       ┌─────────────────┼─────────────────┐
       │                 │                 │
┌──────▼────────┐ ┌─────▼──────┐ ┌────────▼────────┐
│  前端应用      │ │  API服务    │ │  WebSocket服务  │
│  (Vue)        │ │  (FastAPI) │ │  (实时推流)      │
└───────────────┘ └─────┬──────┘ └─────────────────┘
                        │
         ┌──────────────┼──────────────┐
         │              │              │
┌────────▼──────┐ ┌────▼────┐ ┌──────▼────────┐
│  PostgreSQL   │ │  Redis  │ │ Celery Worker │
│  (元数据存储)  │ │(队列/缓存)│ │  (训练/推理)   │
└───────────────┘ └─────────┘ └───────┬───────┘
                                      │
                              ┌───────▼───────┐
                              │   GPU资源池    │
                              │ (模型训练/推理) │
                              └───────┬───────┘
                                      │
                              ┌───────▼───────┐
                              │  MinIO/OSS    │
                              │(数据集/模型)   │
                              └───────────────┘
```

---

## 🎯 功能需求

### 1. 用户与权限管理

#### 1.1 用户系统
- [ ] 用户注册、登录、登出
- [ ] JWT Token认证
- [ ] 角色权限管理(管理员/普通用户/访客)
- [ ] 个人信息管理
- [ ] API Key管理(用于程序化访问)

#### 1.2 单租户模式

---

### 2. 数据管理

#### 2.1 数据集管理
- [ ] **上传功能**
  - 支持ZIP压缩包上传（存到minio）

- [ ] **格式支持**
  - YOLO格式 (txt标注)

- [ ] **数据集操作**
  - 数据集列表与详情查看、删除（需要删除minio中的文件）

#### 2.2 标注工具(可选)
- [ ] 集成第三方标注工具(LabelMe)
- [ ] 标注质量检查

#### 2.3 数据预览
- [ ] 图片预览与标注框可视化
- [ ] 按类别筛选
- [ ] 搜索功能

---

### 3. 模型训练

#### 3.1 模型选择
- [ ] 支持YOLOv8 (n/s/m/l/x)
- [ ] 支持YOLOv9
- [ ] 支持YOLOv10
- [ ] 支持YOLOv11
- [ ] 支持YOLOv26

#### 3.2 训练配置
- [ ] **基础参数**
  - 选择预训练模型
  - 选择训练数据集
  - 训练轮数(epochs)
  - 批次大小(batch size)
  - 图像尺寸(imgsz)
  - 设备选择(cpu/gpu/multi-gpu)

- [ ] **高级参数**
  - 优化器选择(SGD/Adam/AdamW)
  - 学习率策略
  - 权重衰减
  - 数据增强参数
  - Early Stopping
  - 模型保存策略(best/last/每N轮)

- [ ] **配置模板**
  - 保存训练配置为模板
  - 快速复用历史配置

#### 3.3 训练执行
- [ ] 提交训练任务到队列
- [ ] 单卡训练
- [ ] 断点续训
- [ ] 任务优先级控制
- [ ] 训练任务取消与暂停

#### 3.4 训练监控
- [ ] **实时指标**
  - Loss曲线(train/val)
  - mAP, Precision, Recall曲线
  - 学习率变化
  - GPU利用率、显存占用

- [ ] **可视化**
  - 训练样本可视化
  - 验证预测结果可视化
  - 混淆矩阵
  - PR曲线

- [ ] **日志系统**
  - 实时训练日志
  - TensorBoard集成

#### 3.5 实验管理
- [ ] 实验列表与搜索
- [ ] 实验对比(多实验指标对比)
- [ ] 实验标签与备注
- [ ] 超参数记录
- [ ] 实验复现(保存完整环境)

---

### 4. 模型推理

#### 4.1 推理模式
- [ ] **单图推理**
  - 上传单张图片
  - 实时返回检测结果
  - 结果可视化(绘制框和标签)

- [ ] **批量推理**
  - 上传多张图片或ZIP
  - 异步任务处理
  - 批量结果导出

- [ ] **视频推理**
  - 上传视频文件
  - 帧提取与推理
  - 结果视频生成
  - webRTC实时推流

- [ ] **摄像头推理**
  - RTSP流接入
  - WebSocket实时推流
  - 延迟优化

#### 4.2 推理配置
- [ ] 置信度阈值(confidence)
- [ ] IoU阈值(NMS)
- [ ] 最大检测数量
- [ ] 类别筛选(只检测特定类别)
- [ ] 推理设备选择

#### 4.3 结果处理
- [ ] JSON格式结果返回
- [ ] 可视化图片下载
- [ ] 结果统计(各类别数量)
- [ ] 结果导出(JSON格式)

---

### 5. 模型服务

#### 5.1 模型部署
- [ ] 一键部署训练好的模型
- [ ] 模型版本切换
- [ ] 灰度发布(A/B测试)
- [ ] 模型热更新(无需重启)
- [ ] 多模型并行部署
- [ ] 模型服务状态监控

#### 5.2 API Key管理
- [ ] **API Key生成与管理**
  - 用户创建多个API Key
  - 自定义Key名称和描述
  - 设置Key过期时间
  - 一键撤销/禁用Key
  - 查看Key使用统计

- [ ] **使用监控**
  - API调用次数统计
  - 最后使用时间记录

#### 5.3 推理服务API

##### 5.3.1 认证方式
所有API请求需在Header中携带API Key:
```bash
Authorization: Bearer <your_api_key>
```

##### 5.3.2 核心接口

**1. 获取可用模型列表**
```http
GET /api/v1/models
```

**请求示例:**
```bash
curl -X GET "https://api.trainman.com/api/v1/models" \
  -H "Authorization: Bearer sk_1234567890abcdef"
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "models": [
      {
        "model_id": "yolov8n_coco_v1",
        "model_name": "YOLOv8n COCO检测器",
        "model_type": "yolov8n",
        "version": "v1.0.0",
        "description": "基于COCO数据集训练的通用目标检测模型",
        "classes": ["person", "car", "dog", ...],
        "num_classes": 80,
        "input_size": [640, 640],
        "status": "active",
        "metrics": {
          "mAP50": 0.52,
          "mAP50_95": 0.37,
          "fps": 120
        },
        "created_at": "2026-02-20T10:00:00Z",
        "updated_at": "2026-02-28T08:30:00Z"
      },
      {
        "model_id": "yolov11m_custom_v2",
        "model_name": "自定义车辆检测器",
        "model_type": "yolov11m",
        "version": "v2.1.0",
        "description": "专门用于车辆检测的定制模型",
        "classes": ["car", "truck", "bus", "motorcycle"],
        "num_classes": 4,
        "input_size": [1280, 1280],
        "status": "active",
        "metrics": {
          "mAP50": 0.89,
          "mAP50_95": 0.76,
          "fps": 45
        },
        "created_at": "2026-02-25T14:20:00Z",
        "updated_at": "2026-02-27T16:45:00Z"
      }
    ],
    "total": 2
  }
}
```

---

**2. 单张图片推理**
```http
POST /api/v1/inference/image
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model_id | string | 是 | 模型ID |
| image | file | 是 | 图片文件(支持jpg/png/bmp) |
| confidence | float | 否 | 置信度阈值(默认0.25) |
| iou_threshold | float | 否 | NMS的IoU阈值(默认0.45) |
| max_det | int | 否 | 最大检测数量(默认300) |
| classes | array | 否 | 指定检测类别ID列表 |
| return_image | bool | 否 | 是否返回可视化图片(默认false) |

**请求示例:**
```bash
curl -X POST "https://api.trainman.com/api/v1/inference/image" \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  -F "model_id=yolov8n_coco_v1" \
  -F "image=@/path/to/image.jpg" \
  -F "confidence=0.3" \
  -F "iou_threshold=0.5" \
  -F "classes=[0,2,7]"
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "inference_id": "inf_20260228_abc123",
    "model_id": "yolov8n_coco_v1",
    "detections": [
      {
        "class_id": 0,
        "class_name": "person",
        "confidence": 0.92,
        "bbox": {
          "x1": 120.5,
          "y1": 80.3,
          "x2": 280.7,
          "y2": 450.2
        },
        "bbox_normalized": {
          "x1": 0.188,
          "y1": 0.125,
          "x2": 0.438,
          "y2": 0.703
        }
      },
      {
        "class_id": 2,
        "class_name": "car",
        "confidence": 0.87,
        "bbox": {
          "x1": 300.0,
          "y1": 200.5,
          "x2": 500.8,
          "y2": 350.3
        },
        "bbox_normalized": {
          "x1": 0.469,
          "y1": 0.313,
          "x2": 0.782,
          "y2": 0.547
        }
      }
    ],
    "num_detections": 2,
    "image_size": {
      "width": 640,
      "height": 640
    },
    "inference_time_ms": 45.6,
    "visualized_image_url": "https://cdn.trainman.com/results/inf_20260228_abc123.jpg"
  }
}
```

---

**3. 批量图片推理**
```http
POST /api/v1/inference/batch
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model_id | string | 是 | 模型ID |
| images | file[] | 是 | 多个图片文件或ZIP压缩包 |
| confidence | float | 否 | 置信度阈值(默认0.25) |
| iou_threshold | float | 否 | NMS的IoU阈值(默认0.45) |
| async | bool | 否 | 是否异步处理(默认true) |
| callback_url | string | 否 | 异步任务完成后的回调URL |

**请求示例:**
```bash
curl -X POST "https://api.trainman.com/api/v1/inference/batch" \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  -F "model_id=yolov8n_coco_v1" \
  -F "images=@/path/to/images.zip" \
  -F "async=true" \
  -F "callback_url=https://your-server.com/callback"
```

**响应示例(异步):**
```json
{
  "code": 200,
  "message": "Batch inference task created",
  "data": {
    "task_id": "batch_20260228_xyz789",
    "status": "pending",
    "total_images": 50,
    "estimated_time_seconds": 120,
    "status_url": "/api/v1/inference/batch/batch_20260228_xyz789/status"
  }
}
```

**查询批量任务状态:**
```http
GET /api/v1/inference/batch/{task_id}/status
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "batch_20260228_xyz789",
    "status": "completed",
    "progress": {
      "total": 50,
      "completed": 50,
      "failed": 0
    },
    "results_url": "https://cdn.trainman.com/batch_results/batch_20260228_xyz789.zip",
    "summary": {
      "total_detections": 324,
      "avg_inference_time_ms": 48.2
    },
    "created_at": "2026-02-28T10:00:00Z",
    "completed_at": "2026-02-28T10:02:15Z"
  }
}
```

---

**4. 视频推理**
```http
POST /api/v1/inference/video
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| model_id | string | 是 | 模型ID |
| video | file | 是 | 视频文件(支持mp4/avi/mov) |
| video_url | string | 是* | 视频URL(*与video二选一) |
| confidence | float | 否 | 置信度阈值(默认0.25) |
| frame_interval | int | 否 | 帧间隔(每N帧推理一次,默认1) |
| output_format | string | 否 | 输出格式(video/json,默认video) |
| save_frames | bool | 否 | 是否保存推理帧(默认false) |
| track_objects | bool | 否 | 是否启用目标跟踪(默认false) |

**请求示例:**
```bash
curl -X POST "https://api.trainman.com/api/v1/inference/video" \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  -F "model_id=yolov11m_custom_v2" \
  -F "video=@/path/to/video.mp4" \
  -F "confidence=0.4" \
  -F "frame_interval=2" \
  -F "output_format=video" \
  -F "track_objects=true"
```

**响应示例:**
```json
{
  "code": 200,
  "message": "Video inference task created",
  "data": {
    "task_id": "video_20260228_def456",
    "status": "processing",
    "video_info": {
      "duration_seconds": 120,
      "fps": 30,
      "total_frames": 3600,
      "resolution": "1920x1080"
    },
    "estimated_time_seconds": 300,
    "status_url": "/api/v1/inference/video/video_20260228_def456/status"
  }
}
```

**查询视频推理状态:**
```http
GET /api/v1/inference/video/{task_id}/status
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "video_20260228_def456",
    "status": "completed",
    "progress": {
      "current_frame": 3600,
      "total_frames": 3600,
      "percentage": 100
    },
    "result_video_url": "https://cdn.trainman.com/video_results/video_20260228_def456.mp4",
    "result_json_url": "https://cdn.trainman.com/video_results/video_20260228_def456.json",
    "statistics": {
      "total_detections": 15680,
      "unique_objects_tracked": 87,
      "avg_fps": 25.3,
      "processing_time_seconds": 285
    },
    "created_at": "2026-02-28T11:00:00Z",
    "completed_at": "2026-02-28T11:04:45Z"
  }
}
```

---

**5. 实时视频流推理 (WebSocket)**
```
ws://api.trainman.com/api/v1/inference/stream
```

**连接参数:**
```javascript
const ws = new WebSocket('ws://api.trainman.com/api/v1/inference/stream');

// 连接建立后发送认证和配置
ws.onopen = () => {
  ws.send(JSON.stringify({
    "action": "authenticate",
    "api_key": "sk_1234567890abcdef",
    "model_id": "yolov8n_coco_v1",
    "config": {
      "confidence": 0.3,
      "iou_threshold": 0.5,
      "return_image": true
    }
  }));
};

// 发送视频帧(Base64编码)
ws.send(JSON.stringify({
  "action": "inference",
  "frame": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}));

// 接收推理结果
ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  console.log(result);
};
```

**WebSocket响应示例:**
```json
{
  "type": "inference_result",
  "frame_id": 12345,
  "timestamp": 1709107200000,
  "detections": [
    {
      "class_id": 0,
      "class_name": "person",
      "confidence": 0.92,
      "bbox": {
        "x1": 120.5,
        "y1": 80.3,
        "x2": 280.7,
        "y2": 450.2
      }
    }
  ],
  "num_detections": 1,
  "inference_time_ms": 32.5,
  "visualized_frame": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}
```

---

**6. RTSP流推理**
```http
POST /api/v1/inference/rtsp
```

**请求参数:**
```json
{
  "model_id": "yolov8n_coco_v1",
  "rtsp_url": "rtsp://camera.example.com:554/stream",
  "rtsp_username": "admin",
  "rtsp_password": "password123",
  "confidence": 0.3,
  "frame_rate": 10,
  "output_stream_url": "rtmp://push.example.com/live/stream1",
  "enable_tracking": true,
  "callback_url": "https://your-server.com/rtsp-events"
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "RTSP stream inference started",
  "data": {
    "stream_id": "rtsp_20260228_ghi789",
    "status": "running",
    "input_url": "rtsp://camera.example.com:554/stream",
    "output_url": "rtmp://push.example.com/live/stream1",
    "preview_url": "ws://api.trainman.com/stream/rtsp_20260228_ghi789",
    "control_url": "/api/v1/inference/rtsp/rtsp_20260228_ghi789/control"
  }
}
```

---

##### 5.3.3 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | API Key无效或已过期 |
| 403 | 权限不足,无法访问该模型 |
| 404 | 模型不存在 |
| 413 | 文件过大 |
| 429 | 请求过于频繁,超过限流 |
| 500 | 服务器内部错误 |
| 503 | 服务暂不可用(GPU资源不足) |

**错误响应示例:**
```json
{
  "code": 429,
  "message": "Rate limit exceeded",
  "data": {
    "limit": 100,
    "remaining": 0,
    "reset_at": "2026-02-28T12:00:00Z"
  }
}
```

---

#### 5.4 性能优化
- [ ] 模型加速
  - ONNX导出
  - TensorRT加速
  - OpenVINO加速(Intel CPU)

- [ ] 缓存策略
  - 结果缓存(相同图片hash)
  - 模型预加载
  - Redis缓存热点数据

---

### 6. 模型管理

#### 6.1 模型仓库
- [ ] 模型列表(名称、版本、创建时间)
- [ ] 模型详情(配置、指标、文件大小)
- [ ] 模型上传
- [ ] 模型下载
- [ ] 模型删除
- [ ] 模型分享(生成下载链接)

#### 6.2 模型评估
- [ ] 在测试集上评估
- [ ] 生成评估报告
  - mAP@0.5, mAP@0.5:0.95
  - 各类别AP
  - 推理速度(FPS)
  - 模型大小
  - 参数量和计算量(FLOPs)

#### 6.3 模型转换
- [ ] PyTorch (.pt) → ONNX
- [ ] ONNX → TensorRT

---

## 📁 项目结构(建议)

```
trainman/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── api/               # API路由
│   │   │   ├── v1/
│   │   │   │   ├── auth.py           # 用户认证接口
│   │   │   │   ├── api_keys.py       # API Key管理接口
│   │   │   │   ├── datasets.py       # 数据集管理
│   │   │   │   ├── training.py       # 训练任务
│   │   │   │   ├── inference.py      # 推理接口
│   │   │   │   ├── models.py         # 模型管理
│   │   │   │   ├── websocket.py      # WebSocket
│   │   │   │   └── stream.py         # 流式推理
│   │   ├── core/              # 核心配置
│   │   │   ├── config.py             # 配置管理
│   │   │   ├── security.py           # 安全认证
│   │   │   ├── api_key_auth.py       # API Key认证
│   │   │   ├── rate_limiter.py       # 限流器
│   │   │   └── database.py           # 数据库连接
│   │   ├── models/            # 数据库模型(ORM)
│   │   │   ├── user.py
│   │   │   ├── api_key.py
│   │   │   ├── api_usage_log.py
│   │   │   ├── dataset.py
│   │   │   ├── training_job.py
│   │   │   ├── model.py
│   │   │   └── inference_job.py
│   │   ├── schemas/           # Pydantic模型(请求/响应)
│   │   │   ├── api_key_schema.py
│   │   │   ├── inference_schema.py
│   │   │   └── model_schema.py
│   │   ├── services/          # 业务逻辑
│   │   │   ├── dataset_service.py
│   │   │   ├── training_service.py
│   │   │   ├── inference_service.py
│   │   │   ├── model_service.py
│   │   │   └── api_key_service.py
│   │   ├── tasks/             # Celery异步任务
│   │   │   ├── training_tasks.py
│   │   │   ├── inference_tasks.py
│   │   │   └── video_tasks.py
│   │   └── utils/             # 工具函数
│   │       ├── image_utils.py
│   │       ├── video_utils.py
│   │       └── hash_utils.py
│   ├── tests/                 # 测试
│   │   ├── test_api/
│   │   │   ├── test_inference.py
│   │   │   └── test_api_keys.py
│   │   └── test_services/
│   ├── alembic/               # 数据库迁移
│   ├── requirements.txt
│   ├── Dockerfile
│   └── main.py                # 应用入口
│
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── views/             # 页面组件
│   │   │   ├── Dashboard.vue
│   │   │   ├── Datasets.vue
│   │   │   ├── Training.vue
│   │   │   ├── Inference.vue
│   │   │   └── Models.vue
│   │   ├── components/        # 通用组件
│   │   ├── api/               # API调用封装
│   │   ├── store/             # 状态管理
│   │   └── router/            # 路由配置
│   ├── package.json
│   ├── Dockerfile
│   └── nginx.conf
│
├── workers/                    # Celery Worker容器
│   ├── Dockerfile
│   └── requirements.txt
│
├── scripts/               # 脚本工具
│   ├── init_db.py             # 初始化数据库
│   ├── create_user.py         # 创建用户
│   └── export_model.py        # 模型导出工具
│
├── docker-compose.yml          # Docker编排
├── docker-compose.dev.yml      # 开发环境
├── .env.example                # 环境变量示例
├── README.md                   # 本文档
└── LICENSE
```

---

## 🚀 实施路线图

### Phase 1: MVP (最小可行产品) - 4-6周
- [ ] 用户认证与基础权限
- [ ] 数据集上传与管理(仅支持YOLO格式)
- [ ] YOLOv8训练功能(单卡)
- [ ] 基础训练监控(loss/mAP曲线)
- [ ] 单图推理与可视化
- [ ] **API Key管理功能**
- [ ] **基础推理API(单图/批量)**
- [ ] 简单的前端界面
- [ ] Docker化部署

### Phase 2: 核心功能增强 - 4-6周
- [ ] 支持多种YOLO版本(v5/v8/v9/V11/v26)
- [ ] 多格式数据集支持(COCO/VOC)
- [ ] 实验管理与对比
- [ ] **视频推理API**
- [ ] **WebSocket实时推流**
- [ ] 模型仓库与版本管理
- [ ] 完整的RESTful API服务
- [ ] API使用监控与统计
- [ ] 完善的前端交互

### Phase 3: 企业级功能
- [ ] AutoML自动调参
- [ ] Docker部署
- [ ] 数据标注集成

---

## 🔧 快速开始(待实现)

### 环境要求
- Docker 20.10+
- Docker Compose 2.0+
- Docker NVIDIA 驱动(GPU支持)
- CPU 或 GPU 支持

### 安装部署

```bash
# 1. 克隆项目
git clone https://github.com/yourusername/trainman.git
cd trainman

# 2. 配置环境变量
cp .env.example .env
vim .env  # 修改数据库密码、存储路径等

# 3. 启动服务
docker-compose up -d

# 4. 初始化数据库
docker-compose exec backend python scripts/init_db.py

# 5. 创建管理员用户
docker-compose exec backend python scripts/create_user.py \
  --username admin \
  --password your_password \
  --role admin

# 6. 访问服务
# 前端: http://localhost:80
# API文档: http://localhost:8000/docs
```

---

## 🔌 API使用示例

### cURL示例

**1. 获取模型列表**
```bash
curl -X GET "https://api.trainman.com/api/v1/models" \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  | jq .
```

**2. 单图推理**
```bash
curl -X POST "https://api.trainman.com/api/v1/inference/image" \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  -F "model_id=yolov8n_coco_v1" \
  -F "image=@./test_image.jpg" \
  -F "confidence=0.3" \
  | jq .
```

**3. 批量推理**
```bash
# 提交任务
TASK_ID=$(curl -X POST "https://api.trainman.com/api/v1/inference/batch" \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  -F "model_id=yolov8n_coco_v1" \
  -F "images=@./images.zip" \
  | jq -r '.data.task_id')

echo "任务ID: $TASK_ID"

# 查询状态
curl -X GET "https://api.trainman.com/api/v1/inference/batch/$TASK_ID/status" \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  | jq .
```

**4. 视频推理**
```bash
# 提交视频推理任务
curl -X POST "https://api.trainman.com/api/v1/inference/video" \
  -H "Authorization: Bearer sk_1234567890abcdef" \
  -F "model_id=yolov11m_custom_v2" \
  -F "video=@./test_video.mp4" \
  -F "confidence=0.4" \
  -F "track_objects=true" \
  | jq .
```

---

## 🎨 核心页面设计(UI草图)

### 1. 仪表盘(Dashboard)
- 系统资源监控(GPU/CPU/内存)
- 正在运行的任务
- 最近训练记录
- 模型性能排行榜

### 2. 数据集管理
- 数据集卡片列表
- 上传按钮(支持拖拽)
- 数据集详情(类别分布饼图、样本预览)

### 3. 训练中心
- 左侧: 训练配置表单
- 右侧: 实时监控图表(loss/mAP曲线)
- 底部: 训练日志滚动显示

### 4. 推理测试
- 上传区域
- 实时预览
- 参数调节(置信度、IoU滑块)
- 结果展示(图片+JSON)

### 5. 模型仓库
- 表格展示(名称、版本、mAP、大小、创建时间)
- 操作按钮(上传、下载、部署、删除、评估)

### 6. API Key管理
- 密钥列表(名称、前缀、权限、创建时间、最后使用时间)
- 创建新密钥按钮
- 密钥详情(调用次数、流量统计、QPS图表)
- 操作按钮(查看权限、编辑、禁用、删除)
- 使用文档与代码示例展示

### 7. API使用监控
- 实时调用统计
- API调用曲线图
- 热门模型排行
- 最近调用日志

---

## 📊 数据库设计(核心表)

### users (用户表)
```sql
id, username, email, hashed_password, role, created_at, updated_at
```

### api_keys (API密钥表)
```sql
CREATE TABLE api_keys (
  id SERIAL PRIMARY KEY,
  key_hash VARCHAR(256) NOT NULL UNIQUE,        -- API Key的哈希值
  key_prefix VARCHAR(20) NOT NULL,              -- 密钥前缀(用于显示,如sk_1234...)
  name VARCHAR(100),                             -- 密钥名称
  description TEXT,                              -- 描述
  user_id INTEGER NOT NULL REFERENCES users(id),
  permissions JSONB,                             -- 权限配置{"models": ["model_id1"], "read_only": false}
  rate_limit INTEGER DEFAULT 100,                -- QPS限制
  expires_at TIMESTAMP,                          -- 过期时间
  is_active BOOLEAN DEFAULT true,
  last_used_at TIMESTAMP,                        -- 最后使用时间
  usage_count BIGINT DEFAULT 0,                  -- 总调用次数
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_api_keys_user_id ON api_keys(user_id);
CREATE INDEX idx_api_keys_key_hash ON api_keys(key_hash);
```

### api_usage_logs (API使用日志表)
```sql
CREATE TABLE api_usage_logs (
  id BIGSERIAL PRIMARY KEY,
  api_key_id INTEGER REFERENCES api_keys(id),
  endpoint VARCHAR(200),                         -- 请求的API端点
  model_id VARCHAR(100),                         -- 使用的模型ID
  request_method VARCHAR(10),                    -- GET/POST等
  response_code INTEGER,                         -- 响应状态码
  inference_time_ms FLOAT,                       -- 推理耗时
  input_size_bytes BIGINT,                       -- 输入大小
  ip_address VARCHAR(50),                        -- 请求IP
  user_agent TEXT,                               -- User Agent
  error_message TEXT,                            -- 错误信息(如果有)
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_api_usage_logs_api_key_id ON api_usage_logs(api_key_id);
CREATE INDEX idx_api_usage_logs_created_at ON api_usage_logs(created_at);
```

### datasets (数据集表)
```sql
id, name, format, path, num_images, num_classes, class_names,
split_ratio, created_by, created_at
```

### training_jobs (训练任务表)
```sql
id, name, model_type, dataset_id, config(JSON), status,
metrics(JSON), logs_path, created_by, started_at, finished_at
```

### models (模型表)
```sql
CREATE TABLE models (
  id SERIAL PRIMARY KEY,
  model_id VARCHAR(100) NOT NULL UNIQUE,         -- 模型唯一标识
  name VARCHAR(200) NOT NULL,
  version VARCHAR(50),
  model_type VARCHAR(50),                        -- yolov8n, yolov11m等
  description TEXT,
  training_job_id INTEGER REFERENCES training_jobs(id),
  model_path VARCHAR(500),                       -- 模型文件路径
  classes JSONB,                                 -- 类别列表
  num_classes INTEGER,
  input_size JSONB,                              -- [640, 640]
  metrics JSONB,                                 -- {mAP50: 0.52, fps: 120}
  framework VARCHAR(50),                         -- pytorch, onnx, tensorrt
  file_size_bytes BIGINT,
  is_deployed BOOLEAN DEFAULT false,
  status VARCHAR(50),                            -- active, inactive, archived
  created_by INTEGER REFERENCES users(id),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_models_model_id ON models(model_id);
CREATE INDEX idx_models_status ON models(status);
```

### inference_jobs (推理任务表)
```sql
CREATE TABLE inference_jobs (
  id BIGSERIAL PRIMARY KEY,
  task_id VARCHAR(100) NOT NULL UNIQUE,
  job_type VARCHAR(50),                          -- image, batch, video, stream
  model_id VARCHAR(100) REFERENCES models(model_id),
  api_key_id INTEGER REFERENCES api_keys(id),
  input_path VARCHAR(500),
  output_path VARCHAR(500),
  status VARCHAR(50),                            -- pending, processing, completed, failed
  config JSONB,                                  -- 推理配置参数
  results JSONB,                                 -- 推理结果摘要
  progress JSONB,                                -- 进度信息
  error_message TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  started_at TIMESTAMP,
  completed_at TIMESTAMP
);

CREATE INDEX idx_inference_jobs_task_id ON inference_jobs(task_id);
CREATE INDEX idx_inference_jobs_status ON inference_jobs(status);
CREATE INDEX idx_inference_jobs_api_key_id ON inference_jobs(api_key_id);
```

---

## 🔒 安全考虑

- [ ] JWT Token有效期管理
- [ ] API接口鉴权
- [ ] 文件上传安全检查(大小、格式、病毒扫描)
- [ ] SQL注入防护(ORM参数化查询)
- [ ] XSS防护(前端输入验证)
- [ ] HTTPS加密传输
- [ ] 敏感信息脱敏(日志中不显示密码)
- [ ] Rate Limiting防止滥用

---

## 📈 性能指标

### 目标性能
- 单图推理: < 50ms (TensorRT优化后)
- API响应: < 100ms (P95)
- 并发请求: > 100 QPS
- 训练任务提交: < 3s
- 前端首屏加载: < 2s

---

## 🤝 贡献指南(待补充)

---

## 📝 License

MIT License

---

## 📧 联系方式

- 项目负责人: [Your Name]
- Email: [your.email@example.com]
- 项目地址: https://github.com/yourusername/trainman

---

**最后更新**: 2026-02-28

---

## 附录: 参考资源

### YOLO相关
- [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics)
- [YOLOv5](https://github.com/ultralytics/yolov5)
- [YOLO-NAS](https://github.com/Deci-AI/super-gradients)

### 框架文档
- [FastAPI](https://fastapi.tiangolo.com/)
- [Celery](https://docs.celeryq.dev/)
- [Vue 3](https://vuejs.org/)

### 部署参考
- [Docker 最佳实践](https://docs.docker.com/develop/dev-best-practices/)
- [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-docker)

  下一步选择:

  1. Subagent-Driven (当前会话) - 我在当前会话中逐个任务派发子代理执行,每个任务完成后进行代码审查
  2. Parallel Session (新会话) - 你打开新会话使用executing-plans技能,批量执行任务并设置检查点

  你希望采用哪种方式开始实施?