YG_FT/docs/backend-api-design.md

# 模型微调平台后端接口设计

> 后端建议使用 FastAPI，统一挂载 `/api` 前缀。本文根据当前 Vue 前端路由、API 模块、mock 数据和页面交互反推接口，并补充完整微调平台必须具备的用户中心、权限控制、审计、异步任务、文件版本与监控能力。

## 1. 通用约定

### 1.1 统一响应

```json
{
  "code": 0,
  "message": "ok",
  "data": {}
}
```

- `code=0` 成功；非 0 为业务错误。
- HTTP 状态码仍用于认证失败、权限不足、参数错误、系统异常。
- 前端当前 axios 已按 `{ code, data, message }` 解包。

### 1.2 认证与权限

- 登录成功返回 JWT access token，前端后续请求增加 `Authorization: Bearer <token>`。
- 当前前端权限码：`dashboard`、`fine-tune`、`model-eval`、`model-inference`、`model-manage`、`dataset`、`data-process`、`data-convert`、`hardware`、`logs`、`user-settings`。
- 后端 RBAC 建议按 `permission.code + role_permission + user_permission_override` 实现。
- 所有写操作记录审计日志。

### 1.3 分页、排序、筛选

当前前端大多直接取数组，后端建议同时支持分页，便于数据量增长：

```text
page=1&page_size=20&keyword=xxx&sort=-created_at
```

分页响应：

```json
{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 20
}
```

### 1.4 异步任务

训练、评测、模型加载、数据处理、文件转换都应落为异步任务：

- 创建任务：返回 `task_id`。
- 查询详情：返回状态、进度、错误信息、运行统计。
- 实时进度：优先 SSE，必要时 WebSocket。

通用状态建议：`pending`、`running`、`completed`、`failed`、`stopped`。

## 2. 用户中心与系统权限

### 2.1 登录

`POST /api/login`

请求：

```json
{
  "username": "admin",
  "password": "password"
}
```

响应：

```json
{
  "token": "jwt-token",
  "user": {
    "id": "uuid",
    "username": "admin",
    "display_name": "系统管理员",
    "role": "admin",
    "status": "active",
    "permissions": ["dashboard", "fine-tune"],
    "create_time": "2026-07-16T10:00:00+08:00",
    "last_login": "2026-07-16T10:00:00+08:00",
    "protected": true
  }
}
```

说明：前端当前登录接口已经要求返回 `user`，mock 里只返回 token，正式后端必须返回完整用户信息。

### 2.2 当前用户

`GET /api/me`

用于刷新页面后恢复用户信息和权限，避免完全依赖 localStorage。

### 2.3 用户管理

| 方法 | 路径 | 说明 | 权限 |
| --- | --- | --- | --- |
| GET | `/api/users` | 用户列表 | `user-settings` |
| POST | `/api/users` | 创建用户 | `user-settings` |
| PUT | `/api/users/{id}` | 更新角色、状态、页面权限 | `user-settings` |
| DELETE | `/api/users/{id}` | 删除用户 | `user-settings` |
| PUT | `/api/users/{id}/password` | 重置密码 | `user-settings` |

创建用户请求：

```json
{
  "username": "zhangsan",
  "display_name": "张三",
  "password": "InitialPass123",
  "role": "operator",
  "status": "active",
  "permissions": ["dashboard", "fine-tune", "dataset"]
}
```

更新权限请求：

```json
{
  "role": "viewer",
  "status": "active",
  "permissions": ["dashboard", "logs"]
}
```

## 3. 服务看板与系统监控

### 3.1 首页看板

`GET /api/dashboard/overview?period=7d`

返回：

```json
{
  "health": {
    "state": "normal",
    "online_services": 12,
    "running_tasks": 5,
    "pending_alerts": 2
  },
  "service_statuses": [
    { "name": "模型推理", "state": "normal", "instances_online": 6, "instances_total": 6 }
  ],
  "training_stats": [
    { "date": "2026-07-16", "train_count": 11, "gpu_count": 5, "avg_score": 89.0 }
  ],
  "recent_tasks": [],
  "operation_distribution": [],
  "login_duration_rank": [],
  "recent_login_users": []
}
```

说明：首页当前完全使用前端 mock，后端应提供聚合接口，避免前端拼多接口导致加载慢。

### 3.2 健康指标

`GET /api/health`

响应字段兼容前端 `HealthMetrics`：

```json
{
  "cpu_percent": 32,
  "memory_percent": 58,
  "disk_percent": 45
}
```

### 3.3 平台性能

`GET /api/system-info`

返回 CPU、内存、磁盘、GPU、网络、系统运行时间。GPU 进程字段建议包含 `pid`、`name`、`memory_used_gb`、`task_name`、`user`。

### 3.4 日志

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/log-files?date=2026-07-16` | 系统日志文件列表 |
| GET | `/api/log-content?file=system.log` | 系统日志内容 |
| GET | `/api/training-log-files` | 训练日志文件列表 |
| GET | `/api/training-log-content?file=xxx.log` | 训练日志内容 |
| POST | `/api/web-log` | 前端错误/行为日志 |

日志内容应支持 `tail`、`offset`、`limit` 参数，避免一次返回超大文件。

## 4. 模型管理

### 4.1 模型登记

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/model-manage` | 模型列表 |
| GET | `/api/model-manage/{id}` | 模型详情 |
| GET | `/api/model-manage/name/{name}` | 按名称查询 |
| POST | `/api/model-manage` | 创建模型 |
| PUT | `/api/model-manage/{id}` | 编辑模型 |
| DELETE | `/api/model-manage/{id}` | 删除模型 |
| PUT | `/api/model-manage/{id}/purpose` | 修改用途 |
| GET | `/api/model-manage/local-models` | 扫描本地模型目录 |

创建/编辑请求：

```json
{
  "name": "Qwen2.5-7B-Instruct",
  "type": "LLM",
  "purpose": "training",
  "model_source": "local",
  "description": "训练基座",
  "path": "/data/models/qwen2.5-7b",
  "api_url": null,
  "api_key": null,
  "online_model_name": null
}
```

字段说明：

- `type`: `LLM`、`CV`、`NLP`、`Embedding`、`Other`。
- `purpose`: `training`、`inference`、`evaluation`。
- `model_source`: `local`、`api`。
- `api_key` 后端加密存储，列表接口只返回脱敏值。

### 4.2 已训练模型与权重合并

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/model-manage/trained-models` | 已训练模型列表 |
| DELETE | `/api/model-manage/trained-models/{id}?type=merged\|lora` | 删除训练产物 |
| POST | `/api/model-manage/merge` | 合并 LoRA 权重 |
| GET | `/api/model-manage/trained-models/{model_name}/export` | 导出模型文件 |

合并请求：

```json
{
  "model_name": "qwen-ft-finance-001",
  "train_method": "lora",
  "base_model_path": "/data/models/qwen2.5-7b"
}
```

响应：

```json
{
  "merge_task_id": "uuid",
  "status": "pending"
}
```

## 5. 数据集管理

### 5.1 数据集

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/dataset-manage` | 数据集列表 |
| GET | `/api/dataset-manage/{id}` | 数据集详情 |
| POST | `/api/dataset-manage` | 创建数据集 |
| PUT | `/api/dataset-manage/{id}` | 更新数据集 |
| DELETE | `/api/dataset-manage/{id}` | 删除数据集 |
| POST | `/api/dataset-manage/upload/{dataset_id}` | 上传文件，字段名 `files` |
| GET | `/api/dataset-manage/download/{dataset_id}` | 打包下载数据集 |
| GET | `/api/dataset-manage/download/{dataset_id}/{file_id}` | 下载单文件 |

创建数据集：

```json
{
  "name": "金融问答-训练集",
  "type": "train",
  "storage_type": "local",
  "source": "upload",
  "description": "金融领域问答",
  "task_id": null
}
```

数据集类型：

- `type`: `train`、`test`、`eval`、`val`、`other`。
- `storage_type`: `local`、`minio`、`cloud`。
- `source`: `upload`、`task`。

### 5.2 文件预览与版本

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/dataset-manage/preview/{file_id}` | 当前版本内容预览 |
| GET | `/api/dataset-manage/versions/{file_id}` | 文件版本列表 |
| GET | `/api/dataset-manage/versions/{file_id}/{version_id}` | 读取历史版本 |
| POST | `/api/dataset-manage/versions/{file_id}` | 保存为新版本 |
| PUT | `/api/dataset-manage/versions/{file_id}/active` | 切换当前版本 |
| DELETE | `/api/dataset-manage/versions/{file_id}/{version_id}` | 删除非当前、非初始版本 |

创建新版本：

```json
{
  "content": "{\"instruction\":\"...\"}\n",
  "description": "在线编辑",
  "base_version_id": "uuid",
  "expected_current_version_id": "uuid"
}
```

说明：`expected_current_version_id` 用于乐观锁，防止多人编辑覆盖。

## 6. 数据处理

当前数据处理页面为本地模拟，正式后端建议实现以下接口。

### 6.1 任务列表与详情

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/data-process` | 数据处理任务列表 |
| POST | `/api/data-process` | 创建草稿任务 |
| GET | `/api/data-process/{id}` | 任务详情 |
| PUT | `/api/data-process/{id}` | 更新任务配置 |
| DELETE | `/api/data-process/{id}` | 删除任务 |
| POST | `/api/data-process/{id}/start` | 启动处理 |
| POST | `/api/data-process/{id}/stop` | 停止处理 |
| GET | `/api/data-process/{id}/progress` | 查询进度 |
| GET | `/api/data-process/{id}/events` | SSE 实时进度 |

创建任务：

```json
{
  "name": "客服问答数据清洗",
  "description": "清洗并生成 SFT 数据",
  "process_type": "structured",
  "config": {
    "preprocess_options": ["clean_invalid", "detect_structure", "deduplicate"],
    "dataset_split": { "train": 80, "validation": 10, "test": 10 },
    "generation_model_id": "uuid",
    "generation_prompt": "请生成训练数据",
    "temperature": 0.7,
    "max_tokens": 1024,
    "json_mode": false,
    "quality_filter_enabled": true
  }
}
```

### 6.2 源文件与外部数据源

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/data-process/{id}/source-files` | 上传源文件，字段名 `files` |
| DELETE | `/api/data-process/{id}/source-files/{file_id}` | 移除源文件 |
| POST | `/api/data-process/{id}/external/test` | 测试外部数据源连接 |
| POST | `/api/data-process/{id}/external/pull` | 拉取外部数据并生成源文件 |

外部数据源请求：

```json
{
  "type": "mysql",
  "url": "mysql://host:3306/db",
  "auth_mode": "password",
  "username": "user",
  "password": "secret",
  "token": null,
  "limit": 1000
}
```

安全要求：连接密码/token 不落明文，任务详情只回显脱敏配置。

### 6.3 预览切片

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/data-process/{id}/preview/build` | 根据源文件和配置生成预览切片 |
| GET | `/api/data-process/{id}/preview` | 查询预览切片 |
| PUT | `/api/data-process/{id}/preview/{preview_id}` | 编辑切片内容 |
| POST | `/api/data-process/{id}/preview` | 手动新增切片 |
| DELETE | `/api/data-process/{id}/preview/{preview_id}` | 删除切片 |

预览切片字段：

```json
{
  "id": "uuid",
  "source_file_id": "uuid",
  "original_content": "...",
  "edited_content": "...",
  "source_start": 0,
  "source_end": 100,
  "source_start_line": 1,
  "source_end_line": 5,
  "token_count": 50,
  "status": "original"
}
```

### 6.4 生成结果与发布数据集

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/data-process/{id}/generate` | 启动 LLM 生成 |
| GET | `/api/data-process/{id}/results` | 查询结果明细 |
| PUT | `/api/data-process/{id}/results/{result_id}` | 编辑结果 |
| POST | `/api/data-process/{id}/results/{result_id}/restore` | 恢复原始结果 |
| POST | `/api/data-process/{id}/publish` | 发布为数据集 |

结果字段：

```json
{
  "instruction": "生成简洁客服回复",
  "input": "用户反馈页面加载慢",
  "output": "已收到反馈，我们正在排查。",
  "status": "valid"
}
```

发布请求：

```json
{
  "dataset_name": "客服问答清洗集",
  "dataset_type": "train",
  "storage_type": "local",
  "split": { "train": 80, "validation": 10, "test": 10 },
  "format": "alpaca_jsonl"
}
```

## 7. 模型微调

### 7.1 训练任务

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/fine-tune` | 训练任务列表 |
| GET | `/api/fine-tune/{id}` | 训练任务详情 |
| GET | `/api/fine-tune/check-name?name=xxx` | 任务名查重 |
| POST | `/api/fine-tune` | 创建训练任务记录 |
| POST | `/api/fine-tune/start` | 启动训练 |
| PUT | `/api/fine-tune/{id}` | 更新任务 |
| POST | `/api/fine-tune/stop/{id}` | 停止任务 |
| DELETE | `/api/fine-tune/{id}` | 删除任务 |
| GET | `/api/fine-tune/progress/{id}` | 获取训练进度 |
| GET | `/api/fine-tune/{id}/events` | SSE 训练日志/进度 |
| POST | `/api/fine-tune/tensorboard/start` | 启动 TensorBoard |

启动训练请求兼容前端 `FineTuneStartPayload`：

```json
{
  "task_id": "uuid",
  "name": "finance-sft-001",
  "description": "金融 SFT",
  "train_type": "SFT",
  "train_method": "lora",
  "template": "qwen",
  "base_model": "uuid",
  "train_dataset_id": "uuid",
  "auto_merge": true,
  "output_model_name": "qwen-finance-sft-v1",
  "gpus": [0, 1],
  "batch_size": 1,
  "learning_rate": 0.0001,
  "n_epochs": 1,
  "save_steps": 100,
  "lr_scheduler_type": "cosine",
  "max_length": 512,
  "warmup_ratio": 0.05,
  "weight_decay": 0.01,
  "lora_alpha": 16,
  "lora_dropout": 0.1,
  "lora_rank": 8,
  "quantization_bit": 4,
  "export_quantized": false,
  "quant_method": "",
  "quant_bits": 0,
  "quant_group_size": 0,
  "export_format": ""
}
```

### 7.2 训练日志详情页

训练日志页还会联合调用：

- `GET /api/fine-tune/{id}` 获取任务参数。
- `GET /api/dataset-manage/{id}` 获取训练集信息。
- `GET /api/system-info` 获取 GPU 状态。
- `GET /api/training-log-files`、`GET /api/training-log-content` 获取日志。

建议新增：

`GET /api/fine-tune/{id}/overview`

一次返回任务、数据集、GPU、日志摘要、指标曲线，减少页面聚合复杂度。

## 8. 模型评测

### 8.1 评测任务

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/model-eval` | 评测任务列表 |
| GET | `/api/model-eval/{id}` | 评测详情 |
| POST | `/api/model-eval/start` | 启动评测 |
| DELETE | `/api/model-eval/{id}` | 删除评测 |
| GET | `/api/model-eval/{id}/events` | SSE 评测进度 |

启动评测：

```json
{
  "eval_task_name": "金融模型评测-v1",
  "eval_type": "custom",
  "model_id": "uuid",
  "gpu_id": 0,
  "dataset_id": "uuid",
  "dimension_id": "uuid",
  "data_source": "dataset",
  "leaderboard": true,
  "basic_metrics": {
    "bleu": { "enabled": true, "ngram": 4 },
    "rouge": { "enabled": true, "methods": ["rouge-1", "rouge-l"] },
    "cosine": { "enabled": false },
    "output_precision": 3
  }
}
```

详情响应应包含：

- 综合分数、最大分、总体评价、改进建议。
- 维度汇总。
- 样本级输入、参考答案、模型输出、评分、原因、错误类型。

### 8.2 评测维度

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/dimension` | 维度列表 |
| GET | `/api/dimension/{id}` | 维度详情 |
| POST | `/api/dimension` | 创建维度 |
| PUT | `/api/dimension/{id}` | 编辑维度 |
| DELETE | `/api/dimension/{id}` | 删除维度 |

维度请求：

```json
{
  "name": "回答准确性",
  "type": "classification",
  "description": "评估回答是否准确",
  "eval_model": "uuid",
  "eval_method": "standard",
  "eval_prompt": "你是专业评测专家...",
  "is_active": true,
  "bleu_n": null,
  "output_precision": 3,
  "score_min": 0,
  "score_max": 100,
  "pass_threshold": 70
}
```

## 9. 模型推理与对比

前端将“推理”和“模型对比”共用 `model-compare` 接口。

### 9.1 推理/对比任务

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/model-compare` | 推理/对比任务列表 |
| GET | `/api/model-compare/{id}` | 任务详情 |
| POST | `/api/model-compare` | 创建任务 |
| DELETE | `/api/model-compare/{id}` | 删除任务 |
| POST | `/api/model-compare/{id}/load` | 加载任务内模型 |
| POST | `/api/model-compare/{id}/unload` | 卸载任务内模型 |
| GET | `/api/model-compare/{id}/load-status` | 查询加载状态 |
| POST | `/api/model-compare/{id}/load-status` | 更新加载状态 |
| POST | `/api/model-compare/{id}/start-model` | 启动单个模型服务 |
| POST | `/api/model-compare/stop-by-pid` | 按 PID 停止模型 |
| POST | `/api/model-compare/all/stop-all` | 停止全部旧模型服务 |

创建任务：

```json
{
  "name": "金融模型对比",
  "description": "对比基座与微调模型",
  "models": [
    {
      "model_id": "uuid",
      "model_name": "Qwen2.5-7B-Instruct",
      "model_path": "/data/models/qwen2.5-7b",
      "gpu_id": 0,
      "source": "database"
    }
  ]
}
```

### 9.2 对话接口

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/model-compare/stream-chat` | 流式对话，建议 SSE/chunked |
| POST | `/api/model-compare/chat-with-port` | 指定端口非流式对话 |
| POST | `/api/model-chat/batch` | API 模型批量对话 |
| POST | `/api/model-chat/local/chat` | 本地模型对话 |
| POST | `/api/model-chat/local/preload` | 预加载本地模型 |
| POST | `/api/model-chat/trained/preload` | 预加载已训练模型 |

流式请求：

```json
{
  "task_id": "uuid",
  "model_id": "uuid",
  "messages": [
    { "role": "user", "content": "解释什么是 ROE" }
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": true
}
```

建议落库会话与消息，便于对比结果页查看历史。

## 10. 数据转换与工具中心

### 10.1 数据转换

当前 JSON 转 JSONL 页面是 UI 原型，建议接口：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/data-convert/jobs` | 创建转换任务，multipart 上传源文件 |
| GET | `/api/data-convert/jobs/{id}` | 转换任务详情 |
| GET | `/api/data-convert/jobs/{id}/download` | 下载转换结果 |
| DELETE | `/api/data-convert/jobs/{id}` | 删除转换任务 |

请求字段：

- `source_file`: `.json` 文件。
- `output_name`: 输出文件名。
- `encoding`: 默认 `UTF-8`。
- `convert_type`: `json_to_jsonl`。

### 10.2 自定义工具

当前自定义工具仅 localStorage，若要多用户共享，建议接口：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/tools` | 工具列表 |
| POST | `/api/tools` | 创建工具 |
| GET | `/api/tools/{id}` | 工具详情 |
| PUT | `/api/tools/{id}` | 编辑工具 |
| DELETE | `/api/tools/{id}` | 删除工具 |

字段：`name`、`description`、`url`、`icon`、`visibility`、`owner_id`。

## 11. 后端开发需要补齐的关键点

1. 前端路由已有 `user-settings`、`user-create`、`user-permission`、`permission-denied`，但当前仓库缺少对应 Vue 文件；后端仍应先实现用户中心和权限接口。
2. 数据处理主流程目前全在浏览器本地模拟，后端需要正式实现上传、切片、LLM 生成、结果编辑、发布数据集。
3. 训练、评测、数据处理、模型加载都不应同步阻塞 HTTP；建议接 Celery/RQ/Arq 或 FastAPI BackgroundTasks + 独立 worker。
4. 文件内容不要全部入库；数据库保存元数据、版本、校验和、对象存储路径，内容放本地 NAS/MinIO。
5. API Key、外部数据源密码必须加密存储，接口只回显脱敏。
6. 日志和监控数据增长快，需要分区或保留策略。
7. 建议实现 OpenAPI schema，并用 Pydantic enum 与数据库 enum 对齐。

## 12. 仍需确认的问题

1. 部署形态已确认：多算力节点仍按“单机多 GPU 节点”管理，不引入 K8s；每台 GPU 服务器独立部署 Compute API/Agent/File Gateway/LLaMA-Factory。
2. 文件存储：使用本地磁盘、NAS、MinIO，还是对象存储？是否需要断点续传？
3. 训练框架：是否固定使用 LLaMA-Factory？是否还要支持 Transformers 原生、DeepSpeed、Accelerate？
4. 权限粒度：页面级权限是否足够，还是需要到数据集/模型/任务的所有者与项目空间级权限？
5. 多租户/项目空间：是否需要组织、项目、团队隔离？
6. 审批流程：模型发布、数据集删除、停止训练等危险操作是否需要审批？
7. 评测方式：只支持规则指标 + LLM Judge，还是需要人工标注/复核闭环？
8. 推理服务：是否需要长驻服务、自动端口管理、并发限流、会话历史长期保存？
9. 合规安全：数据脱敏、敏感词检测、审计留存周期、模型 API Key 管理是否有公司规范？
10. 数据库规模预期：数据集样本量、日志保留周期、监控采样频率，会影响分区和索引策略。

## 13. 企业治理与算力平台补充接口

根据 `system-development-plan.md`，以下能力已从待确认项升级为第一版设计范围：单机多 GPU、本地磁盘、应用平台/算力平台分离、多租户、项目级资源隔离、审批流、审计留存、LLaMA-Factory 引擎插件化。原有业务接口需要统一增加 `tenant_id`、`project_id` 上下文，列表接口默认只返回当前用户可访问项目内资源。

### 13.1 租户管理

| 方法 | 路径 | 说明 | 权限 |
| --- | --- | --- | --- |
| GET | `/api/tenants` | 租户列表 | 平台管理员 |
| POST | `/api/tenants` | 创建租户 | 平台管理员 |
| GET | `/api/tenants/{id}` | 租户详情 | 租户管理员 |
| PUT | `/api/tenants/{id}` | 更新租户 | 平台管理员 |
| PUT | `/api/tenants/{id}/quota` | 设置租户配额 | 平台管理员 |
| PUT | `/api/tenants/{id}/retention-policy` | 设置租户留存策略 | 平台管理员 |

创建租户：

```json
{
  "name": "研发一部",
  "code": "rd-1",
  "status": "active",
  "quota": {
    "gpu_concurrency": 4,
    "storage_bytes": 10995116277760,
    "max_projects": 20
  },
  "retention_policy": {
    "audit_days": 180,
    "training_log_days": 90,
    "metric_days": 30,
    "temp_file_days": 1
  }
}
```

### 13.2 项目空间

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/projects` | 当前用户可访问项目列表 |
| POST | `/api/projects` | 创建项目 |
| GET | `/api/projects/{id}` | 项目详情 |
| PUT | `/api/projects/{id}` | 更新项目 |
| POST | `/api/projects/{id}/archive` | 归档项目 |
| GET | `/api/projects/{id}/members` | 项目成员 |
| POST | `/api/projects/{id}/members` | 添加成员 |
| PUT | `/api/projects/{id}/members/{user_id}` | 修改项目角色 |
| DELETE | `/api/projects/{id}/members/{user_id}` | 移除成员 |

创建项目：

```json
{
  "tenant_id": "uuid",
  "name": "金融模型微调",
  "code": "finance-ft",
  "description": "金融问答模型训练与评测",
  "quota": {
    "gpu_concurrency": 2,
    "storage_bytes": 2199023255552,
    "max_running_jobs": 3
  }
}
```

项目角色建议：`owner`、`maintainer`、`developer`、`reviewer`、`viewer`。

### 13.3 资源级授权

模型、数据集、训练任务、评测任务、推理任务、数据处理任务都必须支持资源级 ACL。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/resources/{resource_type}/{resource_id}/acl` | 查询资源授权 |
| PUT | `/api/resources/{resource_type}/{resource_id}/acl` | 覆盖资源授权 |
| POST | `/api/resources/{resource_type}/{resource_id}/share` | 快速分享给用户/项目角色 |

授权请求：

```json
{
  "entries": [
    {
      "subject_type": "user",
      "subject_id": "uuid",
      "permissions": ["read", "execute", "download"]
    },
    {
      "subject_type": "project_role",
      "subject_id": "developer",
      "permissions": ["read", "write", "execute"]
    }
  ]
}
```

权限码：`read`、`write`、`execute`、`download`、`delete`、`manage_acl`。

### 13.4 审批中心

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/approvals` | 审批列表，支持 `type=pending/mine/done` |
| POST | `/api/approvals` | 发起审批 |
| GET | `/api/approvals/{id}` | 审批详情 |
| POST | `/api/approvals/{id}/approve` | 通过 |
| POST | `/api/approvals/{id}/reject` | 驳回 |
| POST | `/api/approvals/{id}/cancel` | 撤回 |
| GET | `/api/approval-templates` | 审批模板列表 |
| PUT | `/api/approval-templates/{id}` | 更新审批模板 |

发起审批：

```json
{
  "action": "model_publish",
  "resource_type": "trained_model",
  "resource_id": "uuid",
  "project_id": "uuid",
  "reason": "发布金融问答模型测试服务",
  "payload": {
    "service_level": "production",
    "gpu_id": 0,
    "max_concurrency": 8
  }
}
```

第一版建议触发审批的动作：删除数据集、删除模型、生产服务发布、导出模型、下载敏感数据集、提高 GPU 配额、停止他人任务。

### 13.5 算力资源与队列

应用平台对前端暴露 `/api/compute/*`，实际由 Compute Gateway 调用算力平台内部接口。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/compute/nodes` | 算力节点列表 |
| POST | `/api/compute/nodes` | 新增算力节点 |
| GET | `/api/compute/nodes/{id}` | 算力节点详情 |
| PUT | `/api/compute/nodes/{id}` | 编辑节点地址、权重、标签、路径和启用状态 |
| POST | `/api/compute/nodes/{id}/test-connection` | 测试 Compute API/File Gateway 连通性 |
| POST | `/api/compute/nodes/{id}/enable` | 启用节点 |
| POST | `/api/compute/nodes/{id}/disable` | 禁用节点，不接收新任务 |
| POST | `/api/compute/nodes/{id}/drain` | 进入维护模式，已有任务跑完后下线 |
| POST | `/api/compute/nodes/{id}/health-check` | 主动触发节点健康检查 |
| GET | `/api/compute/nodes/{id}/engines` | 节点训练引擎和版本 |
| GET | `/api/compute/nodes/{id}/replicas` | 节点本地资源副本 |
| GET | `/api/compute/gpus` | GPU 状态 |
| GET | `/api/compute/queue` | 任务队列 |
| GET | `/api/compute/jobs/{id}` | 算力任务详情 |
| POST | `/api/compute/jobs/{id}/retry` | 重试任务 |
| POST | `/api/compute/jobs/{id}/priority` | 调整优先级 |
| POST | `/api/internal/compute-sync/jobs/poll` | 应用平台主动轮询并同步算力任务状态 |
| POST | `/api/internal/compute-sync/resources` | 调度前同步数据集/模型到目标节点 |

算力节点设计说明：

- 多算力节点仍按“单机多 GPU 节点”管理，每台 GPU 服务器是一条 `compute_nodes` 记录。
- 每个可执行训练的节点都需要部署 `Compute API`、`Compute Agent`、`File Gateway` 和宿主机挂载的 LLaMA-Factory。
- 节点之间默认不互相访问，应用平台主动访问所有节点的 Compute API/File Gateway。
- 调度支持 `auto` 和 `manual`：普通用户默认自动调度，管理员或高级用户可手动指定节点。

算力节点响应字段：

```json
{
  "id": "uuid",
  "code": "gpu-node-01",
  "name": "A800 Node 01",
  "api_base_url": "http://10.10.20.31:19100",
  "file_gateway_url": "http://10.10.20.31:19101",
  "enabled": true,
  "scheduler_status": "online",
  "scheduler_weight": 100,
  "tags": ["A800", "80GB", "llama_factory"],
  "gpu_count": 8,
  "current_running_jobs": 2,
  "max_parallel_jobs": 8,
  "data_root": "/data/yg-ft",
  "model_root": "/data/yg-ft/models",
  "log_root": "/opt/yg-ft/logs/compute",
  "last_health_check_at": "2026-07-20T12:00:00+08:00",
  "health_detail": {
    "compute_api": "ok",
    "file_gateway": "ok",
    "llama_factory": "ok"
  }
}
```

GPU 响应字段：

```json
{
  "node_id": "uuid",
  "gpu_index": 0,
  "uuid": "GPU-xxx",
  "name": "NVIDIA A800",
  "status": "running",
  "memory_total_mb": 81920,
  "memory_used_mb": 40960,
  "utilization_percent": 72,
  "temperature": 61,
  "current_job_id": "uuid",
  "current_project_id": "uuid"
}
```

### 13.6 算力平台内部接口

以下接口只允许应用平台调用，不直接暴露给浏览器。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/compute/jobs` | 创建训练/评测/数据处理/推理任务 |
| GET | `/compute/jobs/{id}` | 查询任务 |
| POST | `/compute/jobs/{id}/stop` | 停止任务 |
| GET | `/compute/jobs/{id}/logs` | 拉取日志 |
| GET | `/compute/resources/gpus` | 查询 GPU |
| POST | `/compute/files/upload` | 上传到算力本地磁盘 |
| GET | `/compute/files/{id}/download` | 下载文件 |

创建算力任务：

```json
{
  "tenant_id": "uuid",
  "project_id": "uuid",
  "job_type": "fine_tune",
  "engine": "llama_factory",
  "priority": "normal",
  "scheduler": {
    "mode": "auto",
    "requested_node_id": null,
    "required_tags": ["A800"],
    "preferred_tags": ["llama_factory"],
    "min_gpu_memory_mb": 40960
  },
  "resource_request": {
    "gpu_count": 1,
    "gpu_ids": [0],
    "memory_gb": 64
  },
  "workspace": {
    "root": "/data/ft-platform/tenants/{tenant_id}/projects/{project_id}/jobs/{job_id}"
  },
  "payload": {
    "model_path": "/data/ft-platform/.../models/base/qwen",
    "dataset_path": "/data/ft-platform/.../datasets/train.jsonl",
    "training_args": {}
  },
  "status_sync_mode": "polling",
  "poll_interval_seconds": 10
}
```

手动指定节点时：

```json
{
  "scheduler": {
    "mode": "manual",
    "requested_node_id": "uuid",
    "gpu_ids": [0, 1]
  }
}
```

调度前资源副本检查：

```json
{
  "target_compute_node_id": "uuid",
  "resources": [
    {
      "resource_type": "model",
      "resource_id": "uuid",
      "required": true
    },
    {
      "resource_type": "dataset",
      "resource_id": "uuid",
      "required": true
    }
  ],
  "sync_if_missing": true
}
```

如果目标节点缺少数据集或模型副本，应用平台通过 File Gateway 创建 `resource_sync_jobs`，同步完成后再提交训练任务。

### 13.7 文件网关与离线导入

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/files/upload-session` | 创建分片上传会话 |
| PUT | `/api/files/upload-session/{id}/parts/{part_no}` | 上传分片 |
| POST | `/api/files/upload-session/{id}/complete` | 完成上传 |
| GET | `/api/files/{id}/preview` | 文件预览 |
| GET | `/api/files/{id}/download-url` | 获取短时下载链接 |
| POST | `/api/import/local-model` | 从算力节点本地路径导入模型 |
| POST | `/api/import/local-dataset` | 从算力节点本地路径导入数据集 |

离线导入模型：

```json
{
  "tenant_id": "uuid",
  "project_id": "uuid",
  "compute_node_id": "uuid",
  "path": "/data/models/qwen2.5-7b",
  "name": "Qwen2.5-7B-Instruct",
  "purpose": "training"
}
```

### 13.8 训练引擎管理

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/training-engines` | 训练引擎列表 |
| GET | `/api/training-engines/{id}` | 引擎详情 |
| GET | `/api/training-engines/{id}/schema` | 参数 schema |
| POST | `/api/training-engines/{id}/health-check` | 健康检查 |

LLaMA-Factory 引擎声明：

```json
{
  "code": "llama_factory",
  "name": "LLaMA-Factory",
  "version": "0.9.x",
  "supported_task_types": ["SFT", "DPO", "CPT"],
  "supported_methods": ["lora", "qlora", "full"],
  "supported_formats": ["alpaca", "sharegpt", "dpo_pair", "pretrain_text"],
  "schema": {}
}
```

### 13.9 Checkpoint 与恢复训练

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/fine-tune/{id}/checkpoints` | checkpoint 列表 |
| POST | `/api/fine-tune/{id}/retry` | 失败任务重试 |
| POST | `/api/fine-tune/{id}/resume` | 从 checkpoint 恢复训练 |
| DELETE | `/api/fine-tune/{id}/checkpoints/{checkpoint_id}` | 删除 checkpoint，可能触发审批 |
| PUT | `/api/fine-tune/{id}/checkpoint-retention` | 设置 checkpoint 保留策略 |

默认保留策略：最近 3 个、最优 2 个、已发布模型关联 checkpoint 不自动删除、失败任务保留 14 天。

### 13.10 审计、留存、配额和成本统计

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/audit-logs` | 操作审计 |
| GET | `/api/login-logs` | 登录审计 |
| GET | `/api/download-logs` | 下载审计 |
| GET | `/api/retention-policies` | 留存策略 |
| PUT | `/api/retention-policies/{id}` | 更新留存策略 |
| GET | `/api/quotas/usage` | 配额使用 |
| GET | `/api/usage/summary` | GPU 小时、磁盘、推理调用统计 |

第一版只做用量统计，不做账单计费；第二期可扩展成本核算。

## 14. 接口与页面功能模块映射

本节用于接口开发和前后端联调。后端开发人员可按页面模块确认接口覆盖范围；前端开发人员可按页面查找需要调用的 API。

### 14.1 认证、用户和权限

| 页面模块 | 路由/入口 | 接口 | 说明 |
| --- | --- | --- | --- |
| 登录页 | `/login` | `POST /api/login`、`GET /api/me`、`POST /api/logout` | 登录、恢复用户、退出 |
| 用户中心 | `/user-settings` | `GET /api/users` | 用户列表、搜索、状态筛选 |
| 创建用户 | `/user-settings/create` | `POST /api/users` | 创建本地用户 |
| 用户权限 | `/user-settings/:id/permission` | `PUT /api/users/{id}`、`PUT /api/users/{id}/password` | 用户角色、状态、页面权限、重置密码 |
| 无权限页 | `/permission-denied` | 无专属接口，可调用 `GET /api/me` | 展示当前用户权限和返回入口 |

### 14.2 租户、项目和资源授权

| 页面模块 | 路由/入口 | 接口 | 说明 |
| --- | --- | --- | --- |
| 租户管理 | `/tenants` | `GET /api/tenants`、`POST /api/tenants` | 租户列表、创建租户 |
| 租户详情 | `/tenants/:id` | `GET /api/tenants/{id}`、`PUT /api/tenants/{id}`、`PUT /api/tenants/{id}/quota`、`PUT /api/tenants/{id}/retention-policy` | 租户配置、配额、留存 |
| 项目列表 | `/projects` | `GET /api/projects`、`POST /api/projects` | 项目列表、创建项目 |
| 项目详情 | `/projects/:id` | `GET /api/projects/{id}`、`PUT /api/projects/{id}`、`POST /api/projects/{id}/archive` | 项目概览、归档 |
| 项目成员 | `/projects/:id/members` | `GET /api/projects/{id}/members`、`POST /api/projects/{id}/members`、`PUT /api/projects/{id}/members/{user_id}`、`DELETE /api/projects/{id}/members/{user_id}` | 成员和项目角色 |
| 资源授权 | 资源详情弹窗或 `/projects/:id/permissions` | `GET /api/resources/{resource_type}/{resource_id}/acl`、`PUT /api/resources/{resource_type}/{resource_id}/acl`、`POST /api/resources/{resource_type}/{resource_id}/share` | 模型/数据集/任务级 ACL |

### 14.3 看板、监控和日志

| 页面模块 | 路由/入口 | 接口 | 说明 |
| --- | --- | --- | --- |
| 服务看板 | `/dashboard` | `GET /api/dashboard/overview`、`GET /api/health` | 首页聚合、轻量健康指标 |
| 平台性能 | `/hardware` | `GET /api/system-info`、`GET /api/compute/gpus` | CPU、内存、磁盘、GPU、任务占用 |
| 系统日志 | `/logs` | `GET /api/log-files`、`GET /api/log-content` | 系统日志列表和内容 |
| 训练日志页 | `/training-log/:id` | `GET /api/fine-tune/{id}/overview`、`GET /api/training-log-files`、`GET /api/training-log-content` | 训练日志、指标、GPU 状态 |

### 14.4 模型管理

| 页面模块 | 路由/入口 | 接口 | 说明 |
| --- | --- | --- | --- |
| 模型列表 | `/model-manage` | `GET /api/model-manage`、`DELETE /api/model-manage/{id}`、`PUT /api/model-manage/{id}/purpose` | 模型列表、删除审批入口、用途变更 |
| 模型创建/编辑 | `/model-manage/create`、`/model-manage/:id/edit` | `GET /api/model-manage/{id}`、`POST /api/model-manage`、`PUT /api/model-manage/{id}`、`GET /api/model-manage/local-models` | 本地/API 模型登记 |
| 离线导入模型 | 模型创建页或导入弹窗 | `POST /api/import/local-model` | 从算力节点本地路径导入 |
| 已训练模型 | 模型列表/选择弹窗 | `GET /api/model-manage/trained-models`、`DELETE /api/model-manage/trained-models/{id}` | 训练产物列表和删除 |
| 权重合并 | `/model-manage/merge` | `POST /api/model-manage/merge` | LoRA 合并任务 |
| 模型导出 | 模型列表/详情 | `GET /api/model-manage/trained-models/{model_name}/export` | 导出下载，必要时触发审批 |

### 14.5 数据集与数据处理

| 页面模块 | 路由/入口 | 接口 | 说明 |
| --- | --- | --- | --- |
| 数据集列表 | `/dataset` | `GET /api/dataset-manage`、`DELETE /api/dataset-manage/{id}`、`GET /api/dataset-manage/download/{id}` | 数据集列表、删除、打包下载 |
| 数据集创建/编辑 | `/dataset/create`、`/dataset/:id/edit` | `POST /api/dataset-manage`、`PUT /api/dataset-manage/{id}`、`POST /api/dataset-manage/upload/{dataset_id}` | 数据集元数据和文件上传 |
| 离线导入数据集 | 数据集创建页或导入弹窗 | `POST /api/import/local-dataset` | 从算力节点目录导入 |
| 数据集预览 | `/dataset/:id/preview` | `GET /api/dataset-manage/preview/{file_id}`、`GET /api/dataset-manage/versions/{file_id}`、`POST /api/dataset-manage/versions/{file_id}`、`PUT /api/dataset-manage/versions/{file_id}/active`、`DELETE /api/dataset-manage/versions/{file_id}/{version_id}` | 文件预览、版本、在线编辑 |
| 数据处理列表 | `/data-process` | `GET /api/data-process`、`DELETE /api/data-process/{id}` | 处理任务列表 |
| 数据处理创建向导 | `/data-process/create` | `POST /api/data-process`、`POST /api/data-process/{id}/source-files`、`POST /api/data-process/{id}/preview/build`、`POST /api/data-process/{id}/generate`、`POST /api/data-process/{id}/publish` | 创建、上传、预览、生成、发布 |
| 数据处理详情 | `/data-process/:id` | `GET /api/data-process/{id}`、`GET /api/data-process/{id}/results`、`GET /api/data-process/{id}/progress`、`GET /api/data-process/{id}/events` | 详情、结果、进度 |
| 数据转换 | `/data-convert` | `POST /api/data-convert/jobs`、`GET /api/data-convert/jobs/{id}`、`GET /api/data-convert/jobs/{id}/download` | JSON/JSONL 转换 |

### 14.6 微调训练

| 页面模块 | 路由/入口 | 接口 | 说明 |
| --- | --- | --- | --- |
| 微调列表 | `/fine-tune` | `GET /api/fine-tune`、`POST /api/fine-tune/stop/{id}`、`DELETE /api/fine-tune/{id}` | 训练任务列表、停止、删除 |
| 微调创建 | `/fine-tune/create` | `GET /api/fine-tune/check-name`、`POST /api/fine-tune`、`POST /api/fine-tune/start`、`GET /api/model-manage`、`GET /api/dataset-manage`、`GET /api/compute/gpus` | 参数配置、GPU 选择、启动训练 |
| 训练详情/日志 | `/training-log/:id` | `GET /api/fine-tune/{id}`、`GET /api/fine-tune/progress/{id}`、`GET /api/fine-tune/{id}/events`、`GET /api/fine-tune/{id}/checkpoints` | 日志、进度、checkpoint |
| 恢复/重试训练 | 训练详情页 | `POST /api/fine-tune/{id}/retry`、`POST /api/fine-tune/{id}/resume` | 从 checkpoint 重试或恢复 |
| Checkpoint 管理 | 训练详情页、存储管理页 | `DELETE /api/fine-tune/{id}/checkpoints/{checkpoint_id}`、`PUT /api/fine-tune/{id}/checkpoint-retention` | 清理策略和删除 |
| TensorBoard | 训练详情页 | `POST /api/fine-tune/tensorboard/start` | 启动 TensorBoard |

### 14.7 评测、推理、对比和服务发布

| 页面模块 | 路由/入口 | 接口 | 说明 |
| --- | --- | --- | --- |
| 评测列表 | `/model-eval` | `GET /api/model-eval`、`DELETE /api/model-eval/{id}` | 评测任务列表 |
| 评测创建 | `/model-eval/create` | `POST /api/model-eval/start`、`GET /api/dimension`、`GET /api/model-manage/trained-models`、`GET /api/dataset-manage`、`GET /api/compute/gpus` | 选择模型、数据集、维度、GPU |
| 评测详情 | `/model-eval/:id` | `GET /api/model-eval/{id}`、`GET /api/model-eval/{id}/events` | 综合结果、样本评分 |
| 评测维度 | `/model-eval/dimension/:id/edit` | `GET /api/dimension/{id}`、`POST /api/dimension`、`PUT /api/dimension/{id}`、`DELETE /api/dimension/{id}` | 维度和 Prompt 管理 |
| 推理列表 | `/model-inference` | `GET /api/model-compare`、`POST /api/model-compare/{id}/load`、`POST /api/model-compare/{id}/unload` | 推理任务和加载状态 |
| 推理创建 | `/model-inference/create` | `POST /api/model-compare`、`GET /api/model-manage`、`GET /api/model-manage/trained-models`、`GET /api/compute/gpus` | 选择模型和 GPU |
| 推理对话 | `/model-inference/chat/:id` | `GET /api/model-compare/{id}`、`POST /api/model-compare/stream-chat`、`POST /api/model-compare/chat-with-port` | 单模型对话 |
| 模型对比 | `/model-compare/chat/:id`、`/model-compare/result` | `POST /api/model-chat/batch`、`POST /api/model-chat/local/chat`、`POST /api/model-chat/local/preload`、`POST /api/model-chat/trained/preload` | 多模型对比和预加载 |
| 模型服务治理 | `/model-services`、`/model-services/:id` | `POST /api/approvals`、`GET /api/compute/jobs/{id}`、`GET /api/usage/summary` | 测试/生产服务发布、调用统计、下线审批 |

### 14.8 审批、审计、算力和存储运维

| 页面模块 | 路由/入口 | 接口 | 说明 |
| --- | --- | --- | --- |
| 审批中心 | `/approvals`、`/approvals/pending`、`/approvals/mine`、`/approvals/:id` | `GET /api/approvals`、`POST /api/approvals`、`GET /api/approvals/{id}`、`POST /api/approvals/{id}/approve`、`POST /api/approvals/{id}/reject`、`POST /api/approvals/{id}/cancel` | 审批列表和审批动作 |
| 审批设置 | `/approval-settings` | `GET /api/approval-templates`、`PUT /api/approval-templates/{id}` | 审批模板 |
| 算力资源 | `/compute`、`/compute/gpus`、`/compute/queue`、`/compute/nodes` | `GET/POST/PUT /api/compute/nodes`、`POST /api/compute/nodes/{id}/test-connection`、`POST /api/compute/nodes/{id}/enable`、`POST /api/compute/nodes/{id}/disable`、`POST /api/compute/nodes/{id}/drain`、`GET /api/compute/gpus`、`GET /api/compute/queue`、`POST /api/compute/jobs/{id}/retry`、`POST /api/compute/jobs/{id}/priority` | GPU、节点、队列、节点权重、标签、维护状态、资源副本 |
| 存储管理 | `/storage` | `GET /api/quotas/usage`、`GET /api/files/{id}/download-url`、`GET /api/retention-policies`、`PUT /api/retention-policies/{id}` | 磁盘占用、下载、留存 |
| 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | `GET /api/audit-logs`、`GET /api/login-logs`、`GET /api/download-logs` | 操作、登录、下载审计 |
| 训练引擎管理 | `/training-engines` | `GET /api/training-engines`、`GET /api/training-engines/{id}`、`GET /api/training-engines/{id}/schema`、`POST /api/training-engines/{id}/health-check` | 引擎能力和健康 |