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

> 后端建议使用 FastAPI，统一挂载 `/modelTF` 前缀。本文根据当前 Vue 前端路由、API 模块和页面交互契约梳理接口，并补充完整微调平台必须具备的用户中心、权限控制、审计、异步任务、文件版本与监控能力。前端 Mock 仅作为隔离开发辅助，不作为接口设计准则。

菜单、二级路由、规划菜单、接口和数据库的总览映射见 `docs/menu-functional-requirements.md`。后续新增接口时，必须同步标注对应页面/功能模块。

## 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 /modelTF/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`，正式后端必须返回完整用户信息。

### 2.2 当前用户

`GET /modelTF/me`

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

### 2.3 用户管理

| 方法 | 路径 | 说明 | 权限 |
| --- | --- | --- | --- |
| GET | `/modelTF/users` | 用户列表 | `user-settings` |
| POST | `/modelTF/users` | 创建用户 | `user-settings` |
| PUT | `/modelTF/users/{id}` | 更新角色、状态、页面权限 | `user-settings` |
| DELETE | `/modelTF/users/{id}` | 删除用户 | `user-settings` |
| PUT | `/modelTF/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 /modelTF/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": []
}
```

说明：首页需要由后端提供正式聚合接口，避免前端拼多接口导致加载慢。

### 3.2 健康指标

`GET /modelTF/health`

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

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

### 3.3 平台性能

`GET /modelTF/system-info`

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

### 3.4 日志

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

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

## 4. 模型管理

### 4.1 模型登记

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/modelTF/model-manage` | 模型列表 |
| GET | `/modelTF/model-manage/{id}` | 模型详情 |
| GET | `/modelTF/model-manage/name/{name}` | 按名称查询 |
| POST | `/modelTF/model-manage` | 创建模型 |
| PUT | `/modelTF/model-manage/{id}` | 编辑模型 |
| DELETE | `/modelTF/model-manage/{id}` | 删除模型 |
| PUT | `/modelTF/model-manage/{id}/purpose` | 修改用途 |
| GET | `/modelTF/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 | `/modelTF/model-manage/trained-models` | 已训练模型列表 |
| DELETE | `/modelTF/model-manage/trained-models/{id}?type=merged\|lora` | 删除训练产物 |
| POST | `/modelTF/model-manage/merge` | 合并 LoRA 权重 |
| GET | `/modelTF/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 | `/modelTF/dataset-manage` | 数据集列表 |
| GET | `/modelTF/dataset-manage/{id}` | 数据集详情 |
| POST | `/modelTF/dataset-manage` | 创建数据集 |
| PUT | `/modelTF/dataset-manage/{id}` | 更新数据集 |
| DELETE | `/modelTF/dataset-manage/{id}` | 删除数据集 |
| POST | `/modelTF/dataset-manage/upload/{dataset_id}` | 上传文件，字段名 `files`；默认同步到启用的算力节点 `/data/yg-ft/datasets/{dataset_id}/` |
| GET | `/modelTF/dataset-manage/download/{dataset_id}` | 打包下载数据集 |
| GET | `/modelTF/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 | `/modelTF/dataset-manage/preview/{file_id}` | 当前版本内容预览 |
| GET | `/modelTF/dataset-manage/versions/{file_id}` | 文件版本列表 |
| GET | `/modelTF/dataset-manage/versions/{file_id}/{version_id}` | 读取历史版本 |
| POST | `/modelTF/dataset-manage/versions/{file_id}` | 保存为新版本 |
| PUT | `/modelTF/dataset-manage/versions/{file_id}/active` | 切换当前版本 |
| DELETE | `/modelTF/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 | `/modelTF/data-process` | 数据处理任务列表 |
| POST | `/modelTF/data-process` | 创建草稿任务 |
| GET | `/modelTF/data-process/{id}` | 任务详情 |
| PUT | `/modelTF/data-process/{id}` | 更新任务配置 |
| DELETE | `/modelTF/data-process/{id}` | 删除任务 |
| POST | `/modelTF/data-process/{id}/start` | 启动处理 |
| POST | `/modelTF/data-process/{id}/stop` | 停止处理 |
| GET | `/modelTF/data-process/{id}/progress` | 查询进度 |
| GET | `/modelTF/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 | `/modelTF/data-process/{id}/source-files` | 上传源文件，字段名 `files` |
| DELETE | `/modelTF/data-process/{id}/source-files/{file_id}` | 移除源文件 |
| POST | `/modelTF/data-process/{id}/external/test` | 测试外部数据源连接 |
| POST | `/modelTF/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 | `/modelTF/data-process/{id}/preview/build` | 根据源文件和配置生成预览切片 |
| GET | `/modelTF/data-process/{id}/preview` | 查询预览切片 |
| PUT | `/modelTF/data-process/{id}/preview/{preview_id}` | 编辑切片内容 |
| POST | `/modelTF/data-process/{id}/preview` | 手动新增切片 |
| DELETE | `/modelTF/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 | `/modelTF/data-process/{id}/generate` | 启动 LLM 生成 |
| GET | `/modelTF/data-process/{id}/results` | 查询结果明细 |
| PUT | `/modelTF/data-process/{id}/results/{result_id}` | 编辑结果 |
| POST | `/modelTF/data-process/{id}/results/{result_id}/restore` | 恢复原始结果 |
| POST | `/modelTF/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 | `/modelTF/fine-tune` | 训练任务列表 |
| GET | `/modelTF/fine-tune/{id}` | 训练任务详情 |
| GET | `/modelTF/fine-tune/check-name?name=xxx` | 任务名查重 |
| POST | `/modelTF/fine-tune` | 创建训练任务记录 |
| POST | `/modelTF/fine-tune/{id}/command-preview` | 训练创建页/详情页命令预览，返回目标节点、Compute Job payload 和 LLaMA-Factory 命令 |
| POST | `/modelTF/fine-tune/{id}/preflight` | 训练创建页启动前预检，校验节点、模型路径、数据集路径、引擎命令和训练参数 |
| POST | `/modelTF/fine-tune/start` | 启动训练，应用侧选择算力节点并提交 Compute Job |
| PUT | `/modelTF/fine-tune/{id}` | 更新任务 |
| POST | `/modelTF/fine-tune/stop/{id}` | 停止任务 |
| DELETE | `/modelTF/fine-tune/{id}` | 删除任务 |
| GET | `/modelTF/fine-tune/progress/{id}` | 获取训练进度 |
| GET | `/modelTF/fine-tune/{id}/events` | SSE 训练日志/进度 |
| POST | `/modelTF/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": ""
}
```

训练启动前检查和命令预览：

- 页面模块：`/fine-tune/create` 创建训练任务的“参数确认/启动训练”区域；`/training-log/:id` 训练详情页的“任务配置/命令查看”区域。
- `POST /modelTF/fine-tune/{id}/command-preview`：不做远端路径强校验，只返回应用侧调度出的算力节点、标准 Compute Job payload、训练引擎命令和工作目录，供前端展示最终 LLaMA-Factory 启动命令。
- `POST /modelTF/fine-tune/{id}/preflight`：启动前强校验，真实 `llama_factory` 会检查目标节点连通性、模型路径、数据集目录、LLaMA-Factory HOME、训练命令是否可用；`smoke` 引擎用于自动化闭环验收，会跳过模型/数据集路径检查。
- `POST /modelTF/fine-tune/start`：内部先执行 preflight，预检失败返回 `409` 且任务保持 `pending`，预检通过后再写入 `syncing/queued/running` 运行态并提交 Compute Job。

请求体可传启动覆盖参数：

```json
{
  "requested_node_id": "node_xxx",
  "gpus": [0],
  "batch_size": 1,
  "learning_rate": 0.0002,
  "n_epochs": 1
}
```

响应结构：

```json
{
  "valid": true,
  "errors": [],
  "warnings": [],
  "node": {
    "id": "node_xxx",
    "code": "gpu-node-01",
    "scheduler_status": "online",
    "gpu_count": 1
  },
  "job_payload": {},
  "preview": {
    "engine": "llama_factory",
    "command": ["llamafactory-cli", "train", "..."],
    "command_text": "llamafactory-cli train ...",
    "work_dir": "/app/LLaMA-Factory",
    "path_checks": []
  }
}
```

### 7.2 训练日志详情页

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

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

建议新增：

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

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

## 8. 模型评测

### 8.1 评测任务

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/modelTF/model-eval` | 评测任务列表 |
| GET | `/modelTF/model-eval/{id}` | 评测详情 |
| POST | `/modelTF/model-eval/start` | 启动评测 |
| DELETE | `/modelTF/model-eval/{id}` | 删除评测 |
| GET | `/modelTF/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 | `/modelTF/dimension` | 维度列表 |
| GET | `/modelTF/dimension/{id}` | 维度详情 |
| POST | `/modelTF/dimension` | 创建维度 |
| PUT | `/modelTF/dimension/{id}` | 编辑维度 |
| DELETE | `/modelTF/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 | `/modelTF/model-compare` | 推理/对比任务列表 |
| GET | `/modelTF/model-compare/{id}` | 任务详情 |
| POST | `/modelTF/model-compare` | 创建任务 |
| DELETE | `/modelTF/model-compare/{id}` | 删除任务 |
| POST | `/modelTF/model-compare/{id}/load` | 加载任务内模型 |
| POST | `/modelTF/model-compare/{id}/unload` | 卸载任务内模型 |
| GET | `/modelTF/model-compare/{id}/load-status` | 查询加载状态 |
| POST | `/modelTF/model-compare/{id}/load-status` | 更新加载状态 |
| POST | `/modelTF/model-compare/{id}/start-model` | 启动单个模型服务 |
| POST | `/modelTF/model-compare/stop-by-pid` | 按 PID 停止模型 |
| POST | `/modelTF/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 | `/modelTF/model-compare/stream-chat` | 流式对话，建议 SSE/chunked |
| POST | `/modelTF/model-compare/chat-with-port` | 指定端口非流式对话 |
| POST | `/modelTF/model-chat/batch` | API 模型批量对话 |
| POST | `/modelTF/model-chat/local/chat` | 本地模型对话 |
| POST | `/modelTF/model-chat/local/preload` | 预加载本地模型 |
| POST | `/modelTF/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 | `/modelTF/data-convert/jobs` | 创建转换任务，multipart 上传源文件 |
| GET | `/modelTF/data-convert/jobs/{id}` | 转换任务详情 |
| GET | `/modelTF/data-convert/jobs/{id}/download` | 下载转换结果 |
| DELETE | `/modelTF/data-convert/jobs/{id}` | 删除转换任务 |

请求字段：

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

### 10.2 自定义工具

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

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/modelTF/tools` | 工具列表 |
| POST | `/modelTF/tools` | 创建工具 |
| GET | `/modelTF/tools/{id}` | 工具详情 |
| PUT | `/modelTF/tools/{id}` | 编辑工具 |
| DELETE | `/modelTF/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 | `/modelTF/tenants` | 租户列表 | 平台管理员 |
| POST | `/modelTF/tenants` | 创建租户 | 平台管理员 |
| GET | `/modelTF/tenants/{id}` | 租户详情 | 租户管理员 |
| PUT | `/modelTF/tenants/{id}` | 更新租户 | 平台管理员 |
| PUT | `/modelTF/tenants/{id}/quota` | 设置租户配额 | 平台管理员 |
| PUT | `/modelTF/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 | `/modelTF/projects` | 当前用户可访问项目列表 |
| POST | `/modelTF/projects` | 创建项目 |
| GET | `/modelTF/projects/{id}` | 项目详情 |
| PUT | `/modelTF/projects/{id}` | 更新项目 |
| POST | `/modelTF/projects/{id}/archive` | 归档项目 |
| GET | `/modelTF/projects/{id}/members` | 项目成员 |
| POST | `/modelTF/projects/{id}/members` | 添加成员 |
| PUT | `/modelTF/projects/{id}/members/{user_id}` | 修改项目角色 |
| DELETE | `/modelTF/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 | `/modelTF/resources/{resource_type}/{resource_id}/acl` | 查询资源授权 |
| PUT | `/modelTF/resources/{resource_type}/{resource_id}/acl` | 覆盖资源授权 |
| POST | `/modelTF/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 | `/modelTF/approvals` | 审批列表，支持 `type=pending/mine/done` |
| POST | `/modelTF/approvals` | 发起审批 |
| GET | `/modelTF/approvals/{id}` | 审批详情 |
| POST | `/modelTF/approvals/{id}/approve` | 通过 |
| POST | `/modelTF/approvals/{id}/reject` | 驳回 |
| POST | `/modelTF/approvals/{id}/cancel` | 撤回 |
| GET | `/modelTF/approval-templates` | 审批模板列表 |
| PUT | `/modelTF/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 算力资源与队列

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

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

算力节点设计说明：

- 多算力节点仍按“单机多 GPU 节点”管理，每台 GPU 服务器是一条 `compute_nodes` 记录。
- 每个可执行训练的节点都需要部署 `Compute API`、`Compute Agent`、`File Gateway` 和宿主机挂载的 LLaMA-Factory。
- 节点之间默认不互相访问，应用平台主动访问所有节点的 Compute API/File Gateway。
- 调度支持 `auto` 和 `manual`：普通用户默认自动调度，管理员或高级用户可手动指定节点。
- 节点地址、权重、标签、启用状态、最大并发和本地路径都由 `/compute` 算力节点页面维护。
- 连接测试由应用后端发起，依次探测算力侧 `GET /modelTF/v1/compute/health` 和 `GET /modelTF/compute/resources/gpus`；返回包可为裸 JSON，也可为 `{code,message,data}` 包装结构。

新增/编辑节点请求：

```json
{
  "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": "offline",
  "scheduler_weight": 100,
  "tags": ["A800", "80GB", "llama_factory"],
  "max_parallel_jobs": 4,
  "data_root": "/data/yg-ft",
  "model_root": "/data/yg-ft/models",
  "log_root": "/opt/yg-ft/logs/training",
  "description": "北京机房训练节点"
}
```

启动成功后，响应中的训练任务会包含 `compute_node_id`、`compute_job_id`、`process_id`、`status`、`progress`、`output_dir`、`log_file` 等字段。应用侧后台 worker 会按 `COMPUTE_POLL_INTERVAL_SECONDS` 定时调用目标算力节点查询 Compute Job，并回写训练任务状态。

算力任务日志查询参数：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tail_lines` | int | 否 | 默认 `200`，返回最后 N 行，范围 `1-5000` |
| `offset` | int | 否 | 从第 N 行开始读取；当传入 `offset` 或 `limit` 时分页优先，忽略默认 tail 行数 |
| `limit` | int | 否 | 分页读取行数，范围 `1-5000` |

响应字段包括 `content`、`metrics`、`total_lines`、`offset`、`limit`、`has_more`、`next_offset`。前端训练详情页、训练日志页和算力队列页可以用该接口增量读取日志，避免一次性拉取大文件。

任务维度实时日志接口：`GET /modelTF/fine-tune/{task_id}/logs?tail_lines=500`。该接口由应用后端按任务绑定的 `compute_node_id` 和 `compute_job_id` 转发到目标算力节点日志接口；如果训练尚未创建 Compute Job 或远端日志暂时不可达，则返回任务 `failure_reason`，用于页面展示启动失败、预检失败和远端训练失败原因。

算力任务重试：

```json
{
  "force": false,
  "priority": "high",
  "requested_node_id": "node_xxx",
  "gpus": [0]
}
```

默认只允许 `failed`、`stopped` 任务重试；如确需重新执行已完成任务，需要显式传 `force=true`。重试会清空旧的运行时字段，重新调度节点并创建新的 Compute Job。

算力任务优先级：

```json
{
  "priority": "low|normal|high|urgent"
}
```

第一版优先级写入任务 payload，并影响 `/modelTF/compute/queue` 的展示排序；后续如接入独立队列调度器，可保持接口不变，将该字段映射到调度器优先级。

连接测试响应：

```json
{
  "node_id": "node_xxx",
  "success": true,
  "latency_ms": 35,
  "gpu_count": 8,
  "health": {
    "status": "ok",
    "api_version": "v1",
    "execution_mode": "real",
    "capabilities": ["gpu_discovery", "llama_factory", "file_gateway", "job_polling"]
  }
}
```

算力节点响应字段：

```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",
  "api_version": "v1",
  "capabilities": ["gpu_discovery", "llama_factory"],
  "description": "北京机房训练节点",
  "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 | `/modelTF/compute/jobs` | 创建训练/评测/数据处理/推理任务 |
| POST | `/modelTF/compute/jobs/preview` | 算力节点训练命令预览，不启动进程 |
| POST | `/modelTF/compute/jobs/validate` | 算力节点训练启动前预检，校验参数、路径和引擎命令 |
| GET | `/modelTF/compute/jobs/{id}` | 查询任务 |
| POST | `/modelTF/compute/jobs/{id}/stop` | 停止任务 |
| GET | `/modelTF/compute/jobs/{id}/logs` | 拉取日志 |
| POST | `/modelTF/compute/files/check-paths` | 算力节点本地路径可用性检查 |
| GET | `/modelTF/compute/resources/gpus` | 查询 GPU |
| POST | `/modelTF/compute/files/upload` | 上传到算力本地磁盘 |
| POST | `/modelTF/compute/files/import-local` | 从算力服务器本地路径导入到 `YG_FT_DATA_ROOT` |
| GET | `/modelTF/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
}
```

当前 LLaMA-Factory 训练作业最小 payload：

```json
{
  "id": "ft_xxx",
  "name": "finance-sft-001",
  "engine": "llama_factory",
  "base_model": "/data/yg-ft/models/Qwen2.5-7B",
  "model_name_or_path": "/data/yg-ft/models/Qwen2.5-7B",
  "train_dataset_id": "ds_finance_train",
  "dataset": "ygft_ds_finance_train",
  "dataset_key": "ygft_ds_finance_train",
  "dataset_dir": "/data/yg-ft/datasets/ds_finance_train",
  "dataset_info": {
    "ygft_ds_finance_train": {
      "file_name": "train.jsonl",
      "formatting": "alpaca",
      "columns": {
        "prompt": "instruction",
        "query": "input",
        "response": "output"
      }
    }
  },
  "output_dir": "/data/yg-ft/outputs/finance-sft-001",
  "template": "qwen",
  "train_method": "lora",
  "gpus": [0],
  "batch_size": 2,
  "learning_rate": 0.0002,
  "n_epochs": 3,
  "save_steps": 50
}
```

数据集启动规则：
- 页面选择的是平台数据集 ID，后端提交 Compute Job 时会将其转换为 LLaMA-Factory 数据集 key。
- 单文件数据集使用 `--dataset ygft_{dataset_id}`；多文件数据集使用 `--dataset ygft_{dataset_id}_1,ygft_{dataset_id}_2`。
- `dataset_dir` 指向目标算力节点上的独立数据集目录 `/data/yg-ft/datasets/{dataset_id}`。
- Compute API 在 preflight 和启动训练前根据 `dataset_info` 生成 `{dataset_dir}/dataset_info.json`，避免 LLaMA-Factory 读取全局 `/data/yg-ft/datasets/dataset_info.json` 失败。
- `columns` 只声明训练文件实际存在的字段；`system`、`history` 等可选字段不能默认写入，否则样本缺少字段时 LLaMA-Factory 会在格式转换阶段报 `KeyError`。
- 正式启动前，应用侧会把当前数据集文件内容同步到被调度的算力节点，确保在线编辑/版本切换后的训练文件被使用。
- Preflight 会校验 `dataset_info.columns` 对应字段是否能在样本文件中找到，并校验 PyTorch CUDA 可用性、所选 GPU 是否存在、显存是否满足 `MIN_TRAINING_GPU_MEMORY_GB`。
- Compute 健康检查返回 `torch_cuda`，用于区分 `nvidia-smi` 可见但 PyTorch CUDA 初始化失败的环境问题。

应用侧轮询同步响应：

```json
{
  "synced": 1,
  "failed": [],
  "items": [
    {
      "id": "ft_xxx",
      "status": "running",
      "progress": 35,
      "compute_job_id": "ft_xxx",
      "process_id": 52341,
      "output_dir": "/data/yg-ft/outputs/finance-sft-001",
      "log_file": "/opt/yg-ft/logs/training/ft_xxx.log"
    }
  ]
}
```

手动指定节点时：

```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 | `/modelTF/files/upload-session` | 创建分片上传会话 |
| PUT | `/modelTF/files/upload-session/{id}/parts/{part_no}` | 上传分片 |
| POST | `/modelTF/files/upload-session/{id}/complete` | 完成上传 |
| GET | `/modelTF/files/{id}/preview` | 文件预览 |
| GET | `/modelTF/files/{id}/download-url` | 获取短时下载链接 |
| POST | `/modelTF/import/local-model` | 从算力节点本地路径导入模型 |
| POST | `/modelTF/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 | `/modelTF/training-engines` | 训练引擎列表 |
| GET | `/modelTF/training-engines/{id}` | 引擎详情 |
| GET | `/modelTF/training-engines/{id}/schema` | 参数 schema |
| POST | `/modelTF/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 | `/modelTF/fine-tune/{id}/checkpoints` | checkpoint 列表 |
| POST | `/modelTF/fine-tune/{id}/retry` | 失败任务重试 |
| POST | `/modelTF/fine-tune/{id}/resume` | 从 checkpoint 恢复训练 |
| DELETE | `/modelTF/fine-tune/{id}/checkpoints/{checkpoint_id}` | 删除 checkpoint，可能触发审批 |
| PUT | `/modelTF/fine-tune/{id}/checkpoint-retention` | 设置 checkpoint 保留策略 |

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

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

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

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

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

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

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

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

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

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

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

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

### 14.4 模型管理

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

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

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

### 14.6 微调训练

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

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

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

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

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

The current backend/compute implementation has connected the B+D training runtime features below:

| Page module | API | Runtime behavior |
| --- | --- | --- |
| Training detail / logs `/training-log/:id` | `GET /modelTF/fine-tune/{id}/overview` | Returns task progress, parsed training metrics and real checkpoint records. |
| Training detail / loss chart `/training-log/:id` | `GET /modelTF/fine-tune/{id}/metrics` | Reads `fine_tune_metrics`, populated from Compute log polling and log proxy access. |
| Training detail / checkpoint list `/training-log/:id` | `GET /modelTF/fine-tune/{id}/checkpoints` | Reads `fine_tune_checkpoints`, populated from Compute scanning `output_dir/checkpoint-*`. |
| Merge weights `/model-manage/merge` | `POST /modelTF/model-manage/merge` | Submits a real Compute job using `llamafactory-cli export`; records the job in `compute_jobs`; updates `trained_models.merging/merged/merged_path` when queried after completion. |
| Compute ops / job detail | `GET /modelTF/compute/jobs/{job_id}` | Supports both fine-tune jobs and model merge/export jobs recorded in `compute_jobs`. |
| Compute ops / job logs | `GET /modelTF/compute/jobs/{job_id}/logs` | Proxies logs from the assigned Compute node for training and merge/export jobs. |

Operational diagnostic script:

```bash
APP_BASE_URL=http://localhost:17861 \
COMPUTE_BASE_URL=http://localhost:19100 \
COMPUTE_SERVICE_TOKEN=change_me \
DATABASE_URL=postgresql+psycopg://user:password@host:5432/yg_ft \
python scripts/ops_diagnostics.py
```
## P2/P3 runtime extension note

This iteration extends the B+D runtime implementation with production-facing model asset governance and compute operations:

| Page module | API | Description |
| --- | --- | --- |
| Trained model detail / artifacts | `GET /modelTF/model-manage/trained-models/{id}/artifacts` | Returns registered adapter, merged model and quantized/export artifacts from `model_artifacts`. |
| Trained model detail / lineage | `GET /modelTF/model-manage/trained-models/{id}/lineage` | Returns upstream/downstream relations from `model_lineage`, including base model to fine-tuned model and merge/export relations. |
| Merge/export task list | `GET /modelTF/model-manage/export-jobs?trained_model_id=xxx` | Returns model export and merge jobs from `model_export_jobs`. |
| Compute node replicas | `GET /modelTF/compute/nodes/{id}/replicas/drift` | Checks whether model/dataset/output replicas still exist on the compute node local disk and updates replica status. |
| Compute node replicas | `POST /modelTF/compute/nodes/{id}/replicas/repair` | Marks drifted replicas as `repair_pending` and creates a resource sync job for the operator/scheduler to process. |

The scheduler now uses the `scheduler_locks` table while starting training tasks. Node selection, task state update, resource sync job creation and GPU pre-allocation are written in one database transaction to reduce multi-worker GPU contention.
