YG_FT/docs/system-development-plan.md

# 模型训练平台整体架构与开发计划

> 本文衔接 `docs/backend-api-design.md`、`docs/postgres-schema.sql`、`docs/platform-architecture-requirements.md`，用于多人并行开发。文档给出关键未决问题建议、整体架构、模块边界、开发拆分、交付计划和联调顺序。

## 1. 关键问题建议

### 1.1 文件存储位置

建议：训练相关文件主存储放在算力服务器本地磁盘，应用服务器只保留上传临时文件。

原因：

- 算力服务器需要高频读取数据集、模型、checkpoint，本地磁盘性能和路径稳定性更好。
- 应用平台与算力平台分离后，应用服务器不应直接持有长期训练资产。
- 应用服务器临时文件建议保留 24 小时，上传成功转发到算力文件网关后立即标记可清理。

落地要求：

- 算力平台提供文件网关 API。
- 数据库保存 `storage_node_id`、`relative_path`、`checksum_sha256`、`byte_size`。
- 前端下载通过应用平台申请短时链接，不暴露真实磁盘路径。

### 1.2 GPU 共享/MIG

建议：第一版不支持 MIG 和 GPU 分片，一张 GPU 同一时间只分配给一个训练/推理服务。

原因：

- 当前目标是单机多 GPU，先保证调度稳定、日志可追踪、资源不冲突。
- 训练任务显存波动较大，共享会增加失败和排障成本。

预留：

- GPU 表中保留 `partition_type`、`parent_gpu_uuid`、`memory_total_mb` 字段。
- 后续如需要 MIG，可扩展为 GPU slice 资源。

### 1.3 任务抢占

建议：第一版不做自动抢占，仅支持管理员手动停止或审批后停止。

原因：

- 自动抢占需要 checkpoint 恢复、优先级策略、资源补偿，复杂度较高。
- 训练任务被抢占可能导致用户产物损坏或成本浪费。

落地：

- 支持任务优先级和排队。
- 高优先级任务可排在队列前。
- 停止他人任务需要审批或平台管理员权限。

### 1.4 离线导入已有模型和数据集

建议：必须支持离线导入。

原因：

- 训练平台通常会接入已有 `/data/models`、`/data/datasets`。
- 只允许网页上传会影响大模型和大数据集迁移效率。

功能：

- 管理员填写算力节点上的路径。
- 算力 Agent 扫描目录、校验大小、格式、checksum。
- 应用平台登记为模型或数据集。
- 导入资源默认归属指定租户和项目。

### 1.5 测试服务与生产服务

建议：模型发布区分测试服务和生产服务。

规则：

- 测试服务：项目内成员可创建，默认限流，允许短期运行。
- 生产服务：必须审批，记录发布版本，支持下线审批。

页面：

- 模型服务列表。
- 测试服务启动。
- 生产发布申请。
- 服务调用统计。

### 1.6 数据脱敏与质量评分

建议：作为数据处理模块的一等能力纳入第一期，但可以先实现规则版。

第一期：

- 手机号、身份证、邮箱、银行卡、地址等规则脱敏。
- 空值、重复、过短、JSON 格式错误、字段缺失检测。
- 数据质量分：完整性、重复率、格式正确率、长度分布。

后续：

- LLM 敏感内容识别。
- 行业词表。
- 人工复核闭环。

### 1.7 人工评测/复核沉淀

建议：第二期实现，但第一期数据库和页面入口预留。

原因：

- 人工评测会引入标注任务、分配、复核、一致性统计。
- 第一版可以先完成自动评测和样本级结果展示。

预留：

- `eval_sample_results` 支持人工修订字段。
- 新增人工复核状态：`unreviewed`、`reviewed`、`disputed`。

### 1.8 断点续训

建议：第一版支持“从 checkpoint 手动恢复”，暂不做自动失败续训。

功能：

- 训练详情展示 checkpoint 列表。
- 新建训练任务可选择 checkpoint 作为恢复点。
- 失败任务允许一键重试，重试时选择最近 checkpoint。

后续：

- 自动失败检测。
- 按错误类型决定是否自动恢复。

### 1.9 Checkpoint 清理

建议：必须支持自动清理策略。

默认策略：

- 保留最近 3 个 checkpoint。
- 保留指标最优 2 个 checkpoint。
- 已发布模型对应 checkpoint 不自动删除。
- 失败任务 checkpoint 保留 14 天。

页面：

- 任务详情 checkpoint 管理。
- 存储管理页查看可清理空间。

### 1.10 对外标准 API

建议：第一版提供内部 API，第二期开放外部 API。

第一版：

- 使用 JWT + 服务 token。
- 面向前端和算力平台。

第二期：

- API Key 管理。
- OpenAPI 文档。
- 请求限流。
- Webhook 回调作为外部系统集成的可选能力，不作为算力状态同步默认方案。
- 外部系统发起训练、评测、推理。

### 1.11 企业统一身份认证

建议：第一版使用本地账号，预留 OIDC/LDAP；第二期接入企业统一认证。

落地：

- 用户表增加 `auth_provider`、`external_id`。
- 登录模块抽象 provider。
- 支持本地用户和外部用户共存。

### 1.12 成本核算

建议：第一版做资源用量统计，第二期做成本核算。

第一版统计：

- GPU 小时。
- 磁盘占用。
- 任务运行时长。
- 推理调用次数、token 量。

第二期核算：

- 租户/项目账单。
- GPU 小时单价。
- 存储单价。
- 模型服务调用成本。

## 2. 总体目标范围

### 2.1 第一版目标

交付一个可在企业内使用的单机多 GPU 模型训练平台：

- 支持多租户、多项目。
- 支持项目级资源隔离和模型/数据集级授权。
- 支持本地磁盘文件管理。
- 支持 LLaMA-Factory 微调训练。
- 支持数据集上传、预览、版本、处理和发布。
- 支持训练任务、日志、指标、产物登记。
- 支持模型评测、推理服务和模型对比。
- 支持审批、审计、基础保留策略。
- 支持应用平台和算力平台分离部署。

### 2.2 第一版不做或仅预留

- 自动任务抢占。
- MIG/GPU 分片。
- 自动断点续训。
- 完整人工评测生产线。
- 外部开放 API 市场化管理。
- 精细成本计费。

## 3. 系统整体架构

### 3.1 架构分层

```mermaid
flowchart TB
  FE["前端 Vue 应用"]
  API["应用平台 FastAPI"]
  DB["PostgreSQL 元数据"]
  REDIS["Redis 队列/缓存/锁"]
  WORKER["应用平台 Worker"]
  COMPUTE["算力平台 Compute API"]
  AGENT["Compute Agent"]
  FILE["本地文件网关"]
  ENGINE["LLaMA-Factory Adapter"]
  GPU["单机多 GPU"]
  DISK["算力节点本地磁盘"]

  FE --> API
  API --> DB
  API --> REDIS
  WORKER --> DB
  WORKER --> REDIS
  API --> COMPUTE
  COMPUTE --> AGENT
  AGENT --> FILE
  AGENT --> ENGINE
  ENGINE --> GPU
  FILE --> DISK
  ENGINE --> DISK
```

### 3.2 仓库建议结构

```text
YG_FT/
  frontend/
  backend/
    app/
      api/
      core/
      modules/
        auth/
        tenant/
        project/
        model/
        dataset/
        data_process/
        fine_tune/
        eval/
        inference/
        approval/
        audit/
        compute_gateway/
      db/
      schemas/
      services/
      workers/
    migrations/
    tests/
  compute/
    api/
    agent/
    engines/
      llama_factory/
    file_gateway/
    tests/
  docs/
  deploy/
    app/
    compute/
    nginx/
    systemd/
```

## 4. 开发内容总览

### 4.1 前端开发

现有前端已有基础页面：

- 服务看板。
- 模型训练列表/创建。
- 评测列表/创建/详情。
- 推理列表/创建/对话。
- 模型对比。
- 模型管理。
- 数据处理列表/创建/详情。
- 数据集管理/上传/预览。
- 工具和数据转换原型。
- 硬件和日志。

需要补全：

| 模块 | 页面 | 优先级 |
| --- | --- | --- |
| 用户中心 | 用户列表、创建用户、权限设置、无权限页 | P0 |
| 租户项目 | 租户管理、项目列表、项目详情、成员管理 | P0 |
| 项目上下文 | 顶部项目切换器、项目权限提示 | P0 |
| 审批中心 | 我的申请、待我审批、审批详情、模板配置 | P0 |
| 算力资源 | GPU 状态、任务队列、节点 Agent 状态、资源配额 | P0 |
| 存储管理 | 磁盘占用、大文件、checkpoint、清理策略 | P1 |
| 训练增强 | checkpoint、恢复训练、产物管理、训练引擎选择 | P1 |
| 模型服务 | 测试服务、生产发布、服务实例、调用统计 | P1 |
| 数据治理 | 脱敏规则、质量评分、数据处理结果发布 | P1 |
| 审计中心 | 操作审计、登录审计、下载审计 | P1 |
| 引擎管理 | LLaMA-Factory 健康、参数 schema、接入标准 | P2 |

### 4.2 后端接口开发

第一批必须完成：

- Auth / RBAC / 项目 ACL。
- Tenant / Project。
- Model / Dataset。
- Data Process。
- Fine Tune。
- Compute Gateway。
- Approval / Audit。
- System Monitor / Logs。

第二批完成：

- Eval。
- Inference / Compare。
- File cleanup / retention。
- Checkpoint management。
- Model service governance。

第三批完成：

- External API。
- OIDC/LDAP。
- Cost accounting。
- Human review。

### 4.3 DB 开发

在 `postgres-schema.sql` 基础上新增企业治理和隔离模型：

- 租户、项目、成员。
- 资源 ACL。
- 审批。
- 配额和用量。
- 算力节点、GPU、分配记录。
- 训练引擎。
- 保留策略。

同时调整已有资源表：

- 增加 `tenant_id`、`project_id`、`owner_id`。
- 增加 `approval_status`。
- 增加 `storage_node_id`。
- 增加资源可见性字段。

### 4.4 系统部署开发

需要拆成应用平台部署包和算力平台部署包：

应用平台：

- Nginx。
- Frontend 静态资源。
- FastAPI。
- PostgreSQL。
- Redis。
- App Worker。

算力平台：

- Compute API。
- Compute Agent。
- File Gateway。
- LLaMA-Factory 环境。
- GPU 监控采集。
- 本地磁盘目录初始化。

## 5. 前端开发计划

### 5.1 P0 页面

#### 用户中心

路由：

- `/user-settings`
- `/user-settings/create`
- `/user-settings/:id/permission`
- `/permission-denied`

功能：

- 用户列表、搜索、角色筛选、状态筛选。
- 创建用户、禁用用户、重置密码。
- 页面权限分配。
- 租户和项目关联展示。
- 无权限页友好提示。

联调接口：

- `GET /api/users`
- `POST /api/users`
- `PUT /api/users/{id}`
- `DELETE /api/users/{id}`
- `PUT /api/users/{id}/password`

#### 项目空间

路由：

- `/projects`
- `/projects/create`
- `/projects/:id`
- `/projects/:id/members`
- `/projects/:id/permissions`

功能：

- 项目列表。
- 创建项目。
- 项目概览。
- 成员管理。
- 项目配额查看。
- 项目切换器。

联调接口：

- `GET /api/projects`
- `POST /api/projects`
- `GET /api/projects/{id}`
- `PUT /api/projects/{id}`
- `GET /api/projects/{id}/members`
- `POST /api/projects/{id}/members`

#### 审批中心

路由：

- `/approvals`
- `/approvals/pending`
- `/approvals/mine`
- `/approvals/:id`
- `/approval-settings`

功能：

- 待审批。
- 我的申请。
- 审批详情。
- 通过、驳回、撤回。
- 审批模板配置。

联调接口：

- `GET /api/approvals`
- `POST /api/approvals/{id}/approve`
- `POST /api/approvals/{id}/reject`
- `POST /api/approvals/{id}/cancel`

#### 算力资源中心

路由：

- `/compute`
- `/compute/gpus`
- `/compute/queue`
- `/compute/nodes`

功能：

- GPU 卡片状态。
- GPU 进程和任务占用。
- 任务队列。
- Agent 健康状态。
- 租户/项目配额。
- 算力节点新增、编辑、连接测试、启用、禁用、维护模式。
- 节点权重、标签、训练引擎版本和本地资源副本。
- 自动调度和手动指定节点入口。

联调接口：

- `GET /api/compute/gpus`
- `GET /api/compute/queue`
- `GET /api/compute/nodes`
- `GET /api/quotas/usage`

### 5.2 现有页面改造

所有资源列表页需要增加项目上下文：

- 数据集列表按项目过滤。
- 模型列表按项目过滤。
- 训练任务按项目过滤。
- 评测任务按项目过滤。
- 推理任务按项目过滤。

通用改造：

- 请求自动带 `project_id`。
- 顶部项目切换后刷新数据。
- 无项目权限时进入无权限页。
- 删除、导出、发布等危险动作走审批。

## 6. 后端开发计划

### 6.1 P0 模块

#### Auth 模块

开发内容：

- 登录、登出、当前用户。
- JWT 生成和校验。
- 密码 hash。
- 页面权限。
- 项目权限。
- 服务间 token。

交付接口：

- `POST /api/login`
- `POST /api/logout`
- `GET /api/me`

#### Tenant / Project 模块

开发内容：

- 租户 CRUD。
- 项目 CRUD。
- 项目成员。
- 项目角色。
- 项目配额读取。

交付接口：

- `/api/tenants`
- `/api/projects`
- `/api/projects/{id}/members`

#### Resource ACL 模块

开发内容：

- 资源授权。
- 权限校验依赖。
- 数据查询作用域过滤。

交付接口：

- `GET /api/resources/{resource_type}/{resource_id}/acl`
- `PUT /api/resources/{resource_type}/{resource_id}/acl`

#### Compute Gateway 模块

开发内容：

- 算力平台客户端。
- 算力节点管理：地址、File Gateway、权重、标签、启用状态、维护状态。
- 自动/手动调度策略。
- 调度前检查模型/数据集在目标节点的资源副本。
- 缺失资源时创建同步任务，通过目标节点 File Gateway 写入本地磁盘。
- 创建 compute job。
- 查询状态和日志。
- 应用侧定时轮询 Compute API，同步任务状态、日志摘要和产物索引。
- 任务状态映射。

交付接口：

- `GET /api/compute/gpus`
- `GET /api/compute/queue`
- `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/nodes/{id}/replicas`
- `POST /api/internal/compute-sync/jobs/poll`
- `POST /api/internal/compute-sync/resources`

#### Fine Tune 模块

开发内容：

- 训练任务创建。
- 参数校验。
- 审批校验。
- GPU 配额校验。
- 下发算力任务。
- 进度和日志。
- 产物登记。

交付接口：

- 沿用 `docs/backend-api-design.md` 的 `/api/fine-tune` 系列。

#### Approval 模块

开发内容：

- 审批模板。
- 审批实例。
- 审批动作。
- 审批通过后触发原业务。

交付接口：

- `/api/approvals`
- `/api/approval-templates`

#### Audit 模块

开发内容：

- 请求审计中间件。
- 操作前后数据记录。
- 登录审计。
- 下载审计。
- 审计查询。

交付接口：

- `GET /api/audit-logs`
- `GET /api/login-logs`

### 6.2 P1 模块

- 数据处理后端化。
- 数据脱敏和质量评分。
- Checkpoint 管理。
- 模型服务治理。
- 存储清理策略。
- 评测详情增强。

### 6.3 P2 模块

- 外部 API Key。
- OIDC/LDAP。
- 成本核算。
- 人工评测。
- 多训练引擎接入。

## 7. 算力平台开发计划

### 7.1 Compute API

接口：

- `POST /compute/jobs`
- `GET /compute/jobs/{id}`
- `POST /compute/jobs/{id}/stop`
- `GET /compute/jobs/{id}/logs`
- `GET /compute/resources/gpus`
- `POST /compute/files/upload`
- `GET /compute/files/{id}/download`

职责：

- 接收应用平台任务。
- 校验服务 token。
- 调用 Agent。
- 聚合状态。
- 提供任务状态查询接口，供应用平台定时轮询。
- 每个单机多 GPU 算力节点都部署一套 Compute API，不依赖其他算力节点。
- 暴露节点健康、GPU、训练引擎、资源副本和文件网关状态。

### 7.2 Compute Agent

职责：

- 发现 GPU。
- 采集 GPU 指标。
- 锁定/释放 GPU。
- 管理任务进程。
- 管理端口。
- 管理工作区。
- 上传日志和任务事件。

关键要求：

- Agent 重启后能恢复正在运行的任务状态。
- 任务异常退出要释放 GPU 锁。
- 停止任务要先 graceful stop，再强制 kill。

### 7.3 LLaMA-Factory Adapter

职责：

- 生成训练 YAML 或 CLI。
- 生成 dataset_info。
- 设置 `CUDA_VISIBLE_DEVICES`。
- 启动训练。
- 解析日志。
- 收集产物。
- 合并 LoRA。
- 导出量化模型。

### 7.4 File Gateway

职责：

- 分片上传。
- 文件校验。
- 文件预览。
- 文件下载。
- 目录扫描导入。
- 短时下载令牌。

## 8. 数据库开发计划

### 8.1 迁移顺序

1. 基础扩展和枚举。
2. 用户、角色、权限。
3. 租户、项目、成员。
4. 资源 ACL。
5. 文件对象和存储节点。
6. 模型、数据集。
7. 数据处理、训练、评测、推理。
8. 审批、审计。
9. 算力节点、GPU、队列、配额。
10. 保留策略和清理记录。

### 8.2 新增表清单

| 表 | 说明 |
| --- | --- |
| `tenants` | 租户 |
| `tenant_users` | 租户用户 |
| `projects` | 项目 |
| `project_members` | 项目成员 |
| `resource_acl` | 资源级授权 |
| `approval_templates` | 审批模板 |
| `approval_instances` | 审批单 |
| `approval_steps` | 审批步骤 |
| `quotas` | 配额 |
| `quota_usage` | 配额使用 |
| `storage_nodes` | 存储节点 |
| `compute_nodes` | 算力节点 |
| `compute_node_engines` | 算力节点训练引擎能力 |
| `gpu_devices` | GPU 设备 |
| `gpu_allocations` | GPU 分配记录 |
| `compute_jobs` | 算力任务 |
| `resource_replicas` | 数据集/模型/产物在算力节点的本地副本 |
| `resource_sync_jobs` | 应用平台编排的资源同步任务 |
| `training_engines` | 训练引擎 |
| `retention_policies` | 保留策略 |
| `cleanup_jobs` | 清理任务 |

### 8.3 索引原则

- 所有租户资源表建立 `(tenant_id, project_id, created_at desc)` 索引。
- 列表页常用状态字段建立 `(tenant_id, project_id, status, created_at desc)` 索引。
- 审计日志按时间分区。
- 指标数据按时间分区。
- 数据集样本大表按 `dataset_id` 和 `version_id` 建索引。
- JSONB 配置只对高频查询字段做表达式索引。

## 9. 部署计划

### 9.1 应用平台部署

组件：

- `frontend-nginx`
- `backend-api`
- `backend-worker`
- `postgres`
- `redis`

配置：

- `DATABASE_URL`
- `REDIS_URL`
- `JWT_SECRET`
- `SERVICE_TOKEN`
- `COMPUTE_API_BASE_URL`
- `FILE_UPLOAD_TEMP_DIR`
- `AUDIT_RETENTION_DAYS`

### 9.2 算力平台部署

组件：

- `compute-api`
- `compute-agent`
- `file-gateway`
- `llama-factory-env`

多算力节点阶段，每台单机多 GPU 服务器都部署以上组件和宿主机挂载的 LLaMA-Factory。算力节点之间默认不互相访问，由应用平台统一调度和同步资源。

配置：

- `COMPUTE_NODE_ID`
- `SERVICE_TOKEN`
- `ENABLE_APP_CALLBACK=false`
- `DATA_ROOT=/data/yg-ft`
- `LLAMA_FACTORY_PATH`
- `PYTHON_ENV_PATH`
- `GPU_VISIBLE_DEVICES`
- `PORT_RANGE_START`
- `PORT_RANGE_END`

### 9.3 网络要求

- 前端只访问应用平台。
- 应用平台可访问算力平台内部 API。
- 第一阶段只开通应用平台主动访问算力平台内部 API，状态同步采用应用侧轮询。
- 算力平台不直接暴露给公网。
- 文件下载通过应用平台签发令牌。

### 9.4 运维脚本

需要提供：

- 应用平台启动/停止。
- 算力平台启动/停止。
- 数据库初始化。
- 默认管理员初始化。
- 本地磁盘目录初始化。
- LLaMA-Factory 健康检查。
- GPU 诊断脚本。
- 日志清理脚本。

## 10. 联调顺序

### 阶段 1：基础框架

目标：前后端登录、项目上下文、权限校验跑通。

交付：

- 登录。
- 用户列表。
- 项目列表。
- 页面权限。
- 当前项目切换。

参与：

- 前端 1 人。
- 后端 1 人。
- DB 1 人。

### 阶段 2：资源管理

目标：模型、数据集、文件上传、离线导入跑通。

交付：

- 模型管理。
- 数据集管理。
- 文件版本。
- 算力文件网关。

参与：

- 前端 1 人。
- 后端 2 人。
- 算力 1 人。

### 阶段 3：训练链路

目标：创建训练任务并在单机多 GPU 上执行 LLaMA-Factory。

交付：

- GPU 状态。
- 训练创建。
- 训练启动。
- 训练日志。
- 指标曲线。
- 产物登记。

参与：

- 前端 1 人。
- 后端 2 人。
- 算力 2 人。

### 阶段 4：数据处理与评测

目标：训练前数据处理、训练后评测闭环。

交付：

- 数据处理任务。
- 脱敏和质量评分。
- 发布数据集。
- 自动评测。
- 评测详情。

参与：

- 前端 1 人。
- 后端 2 人。

### 阶段 5：推理服务与发布治理

目标：训练产物可发布为测试/生产服务。

交付：

- 推理服务启动。
- 对话和对比。
- 发布审批。
- 服务监控。

参与：

- 前端 1 人。
- 后端 1 人。
- 算力 1 人。

### 阶段 6：企业治理

目标：审批、审计、保留、清理、配额完善。

交付：

- 审批中心。
- 审计中心。
- 配额管理。
- 存储清理。
- 保留策略。

参与：

- 前端 1 人。
- 后端 2 人。
- DB 1 人。

## 11. 人员分工建议

### 前端组

- FE-A：基础布局、用户中心、项目空间。
- FE-B：模型、数据集、数据处理。
- FE-C：训练、评测、推理、算力监控。

### 后端应用组

- BE-A：认证、租户、项目、权限、审计。
- BE-B：模型、数据集、数据处理、文件元数据。
- BE-C：训练、评测、推理、审批、任务编排。

### 算力组

- CE-A：Compute API、Agent、GPU 调度、多节点健康检查。
- CE-B：LLaMA-Factory Adapter、日志解析、产物管理。
- CE-C：File Gateway、本地磁盘、离线导入、资源副本同步。

### 数据库/部署组

- DB-A：迁移脚本、索引、分区、种子数据。
- OPS-A：Docker/systemd、Nginx、环境变量、健康检查。

## 12. 里程碑计划

| 里程碑 | 时间建议 | 目标 |
| --- | --- | --- |
| M1 基础治理 | 第 1-2 周 | 登录、用户、租户、项目、权限 |
| M2 资源管理 | 第 3-4 周 | 模型、数据集、文件网关、离线导入 |
| M3 训练主链路 | 第 5-7 周 | GPU 调度、LLaMA-Factory 训练、日志指标、产物、资源副本检查 |
| M3.5 多节点预留 | 第 7-8 周 | compute_nodes 管理、节点权重/标签、自动/手动调度、资源同步任务 |
| M4 数据处理和评测 | 第 8-9 周 | 数据处理、质量评分、自动评测 |
| M5 推理发布 | 第 10-11 周 | 推理服务、模型对比、生产发布审批 |
| M6 企业治理收口 | 第 12 周 | 审批、审计、配额、清理、部署文档 |

## 13. 验收标准

### 13.1 功能验收

- 不同租户用户不能看到彼此资源。
- 项目成员只能访问授权项目资源。
- 模型和数据集支持资源级授权。
- 上传数据集后可预览、编辑版本、用于训练。
- 训练任务可自动调度节点/GPU，也可由管理员手动指定节点/GPU 并成功运行。
- 调度前可识别目标节点是否已有数据集和模型副本，缺失时能创建同步任务。
- 训练日志和指标实时可见。
- 训练产物可登记、合并、发布测试服务。
- 评测任务可生成样本级结果。
- 删除数据集、模型发布等动作可触发审批。
- 审计日志能追踪关键操作。

### 13.2 性能验收

- 常规列表接口 P95 小于 500ms。
- GPU 状态刷新周期 5-10 秒。
- 训练日志拉取支持 tail，不一次加载全文件。
- 大文件上传支持分片。
- 数据集样本超过百万行时列表和预览仍可用。

### 13.3 安全验收

- API Key 和外部数据源密码不明文存储。
- 文件下载链接短时有效。
- 服务间接口不能被前端直接调用。
- 用户越权访问返回 403。
- 审计日志不可由普通用户删除。

## 14. 开发风险和应对

| 风险 | 影响 | 应对 |
| --- | --- | --- |
| 应用/算力分离导致文件路径复杂 | 上传、下载、训练失败 | 统一文件网关，不暴露真实路径 |
| GPU 锁释放异常 | 资源被占用 | Agent 心跳和任务恢复扫描 |
| LLaMA-Factory 参数变化 | 训练失败 | 训练引擎 schema 和版本管理 |
| 权限模型过复杂 | 开发慢、容易越权 | RBAC + 项目角色 + ACL 三层固定规则 |
| 审批流影响体验 | 用户觉得操作慢 | 只对高风险动作审批，低风险动作直通 |
| 本地磁盘爆满 | 训练失败 | 配额、清理策略、checkpoint 保留策略 |

## 15. 文档交付关系

- `docs/backend-api-design.md`：接口定义基础版本。
- `docs/postgres-schema.sql`：初始数据库模型。
- `docs/platform-architecture-requirements.md`：架构与功能需求补充。
- `docs/system-development-plan.md`：多人开发拆分和实施计划。

后续建议再补两份执行文档：

- `docs/compute-platform-api.md`：算力平台内部 API 细节。
- `docs/db-migration-v2.sql`：多租户、项目、审批、算力调度的数据库增量脚本。

## 16. 页面模块开发工作包

本节用于多人并行开发时认领任务。每个工作包都标明对应页面、前端内容、后端接口、DB 表和部署/算力依赖。

### 16.1 基础入口与用户权限

| 工作包 | 页面/路由 | 前端开发 | 后端开发 | DB 关联 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| 登录和会话 | `/login` | 登录表单、错误提示、登录后跳转、会话过期处理 | `POST /api/login`、`GET /api/me`、JWT 中间件 | `users`、`login_sessions`、`v_user_effective_permissions` | 无 |
| 主布局和权限菜单 | `/` | 菜单按权限过滤、用户信息、项目切换器 | 当前用户权限、当前项目上下文 | `permissions`、`role_permissions`、`project_members` | 登录 |
| 用户中心 | `/user-settings`、`/user-settings/create`、`/user-settings/:id/permission` | 用户列表、创建、禁用、重置密码、页面权限 | `/api/users` 系列 | `users`、`user_permissions`、`tenant_users` | 租户/项目 |
| 无权限页 | `/permission-denied` | 无权限说明、返回入口 | 权限异常返回统一错误码 | 无新增 | 主布局 |

### 16.2 租户和项目空间

| 工作包 | 页面/路由 | 前端开发 | 后端开发 | DB 关联 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| 租户管理 | `/tenants`、`/tenants/:id` | 租户列表、创建/禁用、配额、留存策略 | `/api/tenants` 系列 | `tenants`、`tenant_users`、`quotas`、`retention_policies` | 用户中心 |
| 项目列表和详情 | `/projects`、`/projects/:id` | 项目列表、创建、归档、资源概览 | `/api/projects` 系列 | `projects`、`quota_usage` | 租户 |
| 项目成员 | `/projects/:id/members` | 成员列表、添加成员、角色选择 | `/api/projects/{id}/members` 系列 | `project_members` | 项目 |
| 资源授权 | `/projects/:id/permissions`、资源详情弹窗 | ACL 表格、用户/角色授权 | `/api/resources/{type}/{id}/acl` | `resource_acl` | 项目、资源表 |

### 16.3 数据集和数据处理

| 工作包 | 页面/路由 | 前端开发 | 后端开发 | DB 关联 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| 数据集列表 | `/dataset` | 列表、搜索、项目过滤、下载、删除审批入口 | `GET/DELETE /api/dataset-manage` | `datasets`、`resource_acl`、`approval_instances` | 项目上下文 |
| 数据集创建/上传 | `/dataset/create`、`/dataset/:id/edit` | 表单、分片上传、离线导入弹窗 | `POST /api/dataset-manage`、`POST /api/files/upload-session`、`POST /api/import/local-dataset` | `datasets`、`dataset_files`、`storage_objects`、`file_upload_sessions`、`local_import_jobs` | 文件网关 |
| 数据集预览/版本 | `/dataset/:id/preview` | 文件列表、内容预览、版本栏、在线编辑 | `/api/dataset-manage/preview`、`/versions` 系列 | `dataset_file_versions`、`dataset_records` | 数据集上传 |
| 数据处理列表 | `/data-process` | 任务列表、状态、输出数据集跳转 | `/api/data-process` 系列 | `data_process_tasks` | 数据集 |
| 数据处理创建向导 | `/data-process/create` | 任务配置、模型选择、源文件、预览切片、生成、结果编辑、发布 | `/api/data-process/{id}/source-files`、`preview/build`、`generate`、`publish` | `data_process_source_files`、`data_process_preview_items`、`data_process_results` | 数据集、模型、文件网关 |
| 数据处理详情 | `/data-process/:id` | 运行统计、失败原因、结果表格 | `GET /api/data-process/{id}`、`results`、`events` | `data_process_tasks`、`data_process_results` | 数据处理任务 |
| 数据转换 | `/data-convert` | 文件上传、转换状态、下载 | `/api/data-convert/jobs` 系列 | `data_convert_jobs`、`storage_objects` | 文件网关 |

### 16.4 模型管理和训练

| 工作包 | 页面/路由 | 前端开发 | 后端开发 | DB 关联 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| 模型列表 | `/model-manage` | 列表、用途标签、授权、导出、删除审批 | `/api/model-manage` 系列 | `models`、`trained_models`、`resource_acl` | 项目上下文 |
| 模型创建/离线导入 | `/model-manage/create`、`/model-manage/:id/edit` | 本地/API 模型表单、离线导入 | `POST/PUT /api/model-manage`、`POST /api/import/local-model` | `models`、`storage_objects`、`local_import_jobs` | 文件网关 |
| 权重合并 | `/model-manage/merge` | 选择训练产物、合并状态 | `POST /api/model-manage/merge`、`GET /api/compute/jobs/{id}` | `trained_models`、`compute_jobs` | 算力平台 |
| 微调列表 | `/fine-tune` | 任务列表、停止、删除、日志入口 | `/api/fine-tune` 系列 | `fine_tune_tasks` | 模型、数据集 |
| 微调创建 | `/fine-tune/create` | 训练参数、GPU 选择、命令预览、审批提示 | `POST /api/fine-tune`、`POST /api/fine-tune/start`、`GET /api/compute/gpus` | `fine_tune_tasks`、`compute_jobs`、`gpu_allocations` | 算力平台、审批 |
| 训练日志和 checkpoint | `/training-log/:id` | 日志 tail、指标曲线、checkpoint、恢复/重试 | `GET /api/fine-tune/{id}/overview`、`checkpoints`、`resume`、`retry` | `fine_tune_metrics`、`fine_tune_checkpoints` | 训练任务 |
| 训练引擎管理 | `/training-engines` | 引擎列表、schema、健康检查 | `/api/training-engines` 系列 | `training_engines` | 算力 Agent |

### 16.5 评测、推理和发布

| 工作包 | 页面/路由 | 前端开发 | 后端开发 | DB 关联 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| 评测列表 | `/model-eval` | 列表、分数、状态、删除 | `/api/model-eval` 系列 | `eval_tasks` | 模型、数据集 |
| 评测创建 | `/model-eval/create` | 模型/数据集/维度/GPU 选择、指标配置 | `POST /api/model-eval/start`、`GET /api/dimension` | `eval_tasks`、`eval_dimensions`、`compute_jobs` | 算力平台 |
| 评测详情 | `/model-eval/:id` | 综合评价、维度汇总、样本结果、人工复核预留 | `GET /api/model-eval/{id}`、`events` | `eval_sample_results`、`eval_dimension_summaries` | 评测任务 |
| 评测维度 | `/model-eval/dimension/:id/edit` | 维度表单、Prompt 编辑 | `/api/dimension` 系列 | `eval_dimensions` | 模型管理 |
| 推理列表/创建 | `/model-inference`、`/model-inference/create` | 任务列表、模型选择、GPU 选择、加载状态 | `/api/model-compare`、`load/unload` | `inference_tasks`、`inference_task_models` | 算力平台 |
| 推理对话 | `/model-inference/chat/:id` | 单模型流式对话、历史消息 | `stream-chat`、`chat-with-port` | `chat_sessions`、`chat_messages` | 推理服务 |
| 模型对比 | `/model-compare/chat/:id`、`/model-compare/result` | 多模型对话、结果对比 | `/api/model-chat/*` | `chat_sessions`、`chat_messages` | 推理任务 |
| 模型服务治理 | `/model-services`、`/model-services/:id` | 测试/生产服务、发布申请、下线、调用统计 | `POST /api/approvals`、`GET /api/usage/summary` | `model_services`、`approval_instances` | 审批、算力平台 |

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

| 工作包 | 页面/路由 | 前端开发 | 后端开发 | DB 关联 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| 审批中心 | `/approvals`、`/approvals/pending`、`/approvals/mine`、`/approvals/:id` | 审批列表、详情、通过/驳回/撤回 | `/api/approvals` 系列 | `approval_instances`、`approval_steps` | 用户、项目 |
| 审批模板 | `/approval-settings` | 动作策略、审批人规则、超时配置 | `/api/approval-templates` 系列 | `approval_templates` | 租户/项目 |
| 算力资源中心 | `/compute`、`/compute/gpus`、`/compute/queue`、`/compute/nodes` | GPU 卡片、节点状态、队列、优先级、节点新增/编辑、连接测试、启用/禁用、维护模式、节点权重/标签、本地资源副本 | `/api/compute/*`、`/compute/*` 内部接口 | `compute_nodes`、`compute_node_engines`、`gpu_devices`、`compute_jobs`、`gpu_allocations`、`resource_replicas`、`resource_sync_jobs` | Compute API/Agent/File Gateway |
| 存储管理 | `/storage` | 磁盘占用、大文件、临时文件、checkpoint 清理 | `GET /api/quotas/usage`、`GET/PUT /api/retention-policies` | `storage_nodes`、`storage_objects`、`cleanup_jobs`、`retention_policies` | 文件网关 |
| 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | 筛选、详情、导出 | `GET /api/audit-logs`、`GET /api/login-logs`、`GET /api/download-logs` | `audit_logs`、`login_sessions` | 审计中间件 |

### 16.7 页面开发优先级建议

| 优先级 | 页面模块 | 原因 |
| --- | --- | --- |
| P0 | 登录、主布局、用户中心、租户、项目、项目成员、资源授权 | 所有资源隔离和接口过滤依赖这些基础能力 |
| P0 | 模型、数据集、文件上传、算力资源、微调创建、训练日志 | 训练主链路必须先跑通 |
| P0 | 审批中心基础能力 | 删除、发布、导出、停止任务等高风险动作依赖审批 |
| P1 | 数据处理、评测、推理、模型服务治理 | 形成训练前后闭环 |
| P1 | 存储管理、checkpoint、审计中心 | 企业治理和运维收口 |
| P2 | 训练引擎管理、外部 API、OIDC/LDAP、成本核算、人工评测 | 扩展能力，第一版可预留 |