YG_FT/docs/platform-architecture-requirements.md

# 模型训练平台架构与功能需求设计

> 本文基于当前前端页面、已有接口/数据库设计，以及用户补充的 6 条约束进行补全。目标是把平台从“单前端原型 + 后端接口草案”扩展为企业可落地的模型训练平台方案。

## 1. 补充需求结论

### 1.1 已确认约束

1. 部署形态：单机多 GPU。
2. 文件存储：本地磁盘。
3. 训练框架：当前固定 LLaMA-Factory，但要预留其他训练平台接入标准。
4. 权限粒度：需要到项目、模型、数据集级隔离。
5. 企业治理：需要多租户、审批流、审计留存周期。
6. 部署边界：算力平台与应用平台分开部署。

### 1.2 对整体设计的影响

- 不能只做页面级 RBAC，需要引入“租户 -> 项目 -> 资源 -> 成员/角色/ACL”的资源权限模型。
- 单机多 GPU 不等于简单指定 GPU ID，需要有 GPU 资源池、锁定、排队、抢占策略和异常释放机制。
- 本地磁盘存储与应用/算力分离存在天然冲突：文件不能只存应用服务器本地，也不能让应用直接读算力服务器目录。建议将训练文件、模型文件、日志文件统一落在算力节点本地磁盘，由算力平台提供文件网关 API；应用平台只保存元数据和访问路径。
- LLaMA-Factory 应作为第一个训练引擎插件，而不是写死到业务流程里。后续接入其他平台时只需实现同一套训练引擎协议。
- 审批流、审计和保留策略必须从第一版进入数据模型和接口，否则后期补会牵动大量资源表。

## 2. 总体架构设计

### 2.1 逻辑分层

```mermaid
flowchart LR
  U["用户浏览器"] --> APP["应用平台 Web / FastAPI"]
  APP --> DB["PostgreSQL"]
  APP --> REDIS["Redis / 任务队列"]
  APP --> CPAPI["算力平台 API"]
  CPAPI --> AGENT["算力节点 Agent"]
  AGENT --> GPU["单机多 GPU"]
  AGENT --> DISK["本地磁盘工作区"]
  AGENT --> LF["LLaMA-Factory 引擎"]
```

### 2.2 应用平台职责

应用平台负责业务编排和企业治理，不直接执行训练命令：

- 用户、租户、项目、权限、审批、审计。
- 模型、数据集、任务、评测、推理任务元数据。
- 前端 API、OpenAPI、统一认证、统一响应。
- 训练/评测/数据处理任务创建、状态查询、审批校验。
- 与算力平台通信，下发任务、查询进度、拉取日志、下载产物。

建议部署组件：

- Nginx：静态前端与反向代理。
- FastAPI：业务 API。
- PostgreSQL：业务元数据。
- Redis：缓存、任务队列、SSE 状态缓存、分布式锁。
- Worker：审批通知、审计归档、周期清理、异步导出。

### 2.3 算力平台职责

算力平台负责“实际占用 GPU 和磁盘”的事情：

- GPU 发现、资源上报、锁定、释放。
- 本地磁盘工作区管理。
- 数据集文件接收、校验、解压、版本目录管理。
- LLaMA-Factory 命令生成、执行、停止、日志采集。
- 训练产物、LoRA adapter、merged model、checkpoint 管理。
- 推理服务进程管理、端口分配、健康检查。
- 系统/GPU 监控指标采集。

建议部署组件：

- Compute API：只暴露给应用平台访问。
- Compute Agent：本机服务，具备启动/停止进程权限。
- 本地文件网关：上传、下载、预览、断点续传、文件校验。
- Engine Adapter：LLaMA-Factory 适配器，后续扩展其他训练引擎。

### 2.4 应用与算力平台通信

建议统一使用内部 HTTP/gRPC API，并配置服务间认证：

- 应用平台调用算力平台必须携带 `X-Service-Token` 或 mTLS 证书。
- 算力平台不信任前端用户身份，只信任应用平台下发的租户、项目、任务和资源上下文。
- 第一阶段不默认启用算力侧回调，应用平台通过定时轮询 Compute API 同步任务状态；如未来启用回调，必须带签名，避免伪造状态。

核心通信接口：

| 方向 | 接口 | 说明 |
| --- | --- | --- |
| 应用 -> 算力 | `POST /compute/jobs` | 创建训练/评测/数据处理/推理任务 |
| 应用 -> 算力 | `POST /compute/jobs/{id}/stop` | 停止任务 |
| 应用 -> 算力 | `GET /compute/jobs/{id}` | 查询任务状态 |
| 应用 -> 算力 | `GET /compute/jobs/{id}/logs` | 拉取日志 |
| 应用 -> 算力 | `GET /compute/resources/gpus` | 查询 GPU 状态 |
| 应用 -> 算力 | `POST /compute/files/upload` | 上传文件到算力本地磁盘 |
| 应用 -> 算力 | `GET /compute/files/{object_id}/download` | 下载文件 |
| 应用 -> 算力 | `GET /compute/jobs?status=running` | 定时轮询任务状态、指标、产物索引 |

## 3. 本地磁盘存储设计

### 3.1 存储根目录

由于算力和应用分离，建议文件主存储放在算力节点本地磁盘：

```text
/data/ft-platform/
  tenants/{tenant_id}/
    projects/{project_id}/
      datasets/{dataset_id}/
      models/base/{model_id}/
      models/trained/{trained_model_id}/
      jobs/{job_id}/
        input/
        output/
        logs/
        checkpoints/
        tmp/
```

应用平台数据库保存：

- `storage_type=local`。
- `storage_node_id`。
- `relative_path`。
- `checksum_sha256`。
- `byte_size`。
- `tenant_id/project_id/resource_id`。

### 3.2 文件访问原则

- 前端不直接访问磁盘路径。
- 应用平台生成短时下载凭证，转发或重定向到算力文件网关。
- 预览内容只读取前 N 行或指定区间，避免大文件撑爆 API。
- 大文件上传必须支持分片上传、校验、断点续传。
- 删除操作采用软删除 + 延迟清理，等待审计留存和审批结果。

### 3.3 磁盘配额

配额应分三层：

- 租户配额：总容量、模型容量、数据容量、日志容量。
- 项目配额：可用容量、最大文件大小、最大任务产物保留数。
- 用户配额：可上传文件总量、并发任务产物占用。

超过配额时：

- 禁止新建任务或上传文件。
- 允许下载和清理。
- 提示可清理的 checkpoint、过期日志、失败任务临时目录。

## 4. 单机多 GPU 资源调度

第一版可以先以单个算力节点跑通主链路，但数据模型、接口和页面需要按多算力节点预留。多节点阶段仍然采用“每台 GPU 服务器 = 一个单机多 GPU 节点”的模式，不引入 Kubernetes。

### 4.1 GPU 资源模型

每张 GPU 需要记录：

- `gpu_index`、`uuid`、型号、显存、驱动版本。
- 当前利用率、显存占用、温度、功耗。
- 当前锁定任务、进程 PID、端口。
- 状态：`idle`、`reserved`、`running`、`draining`、`offline`、`error`。

### 4.2 调度策略

第一版建议支持三种模式：

- 手动指定 GPU：兼容当前前端选择 GPU 的模式。
- 自动选择 GPU：按空闲显存、温度、任务队列选择。
- 项目配额调度：项目最多可占用 N 张 GPU，避免单项目占满机器。

训练任务启动流程：

1. 应用平台校验权限、配额、审批状态。
2. 生成任务，状态为 `pending`。
3. 算力平台尝试锁定 GPU。
4. 锁定成功后创建工作区并启动 LLaMA-Factory。
5. Agent 持续上报进度、日志、指标。
6. 任务完成后释放 GPU，登记模型产物。

### 4.3 并发与排队

- 同一 GPU 同时只允许一个训练任务。
- 推理服务可与训练互斥，默认不允许混跑；如后续允许，需要显存保留策略。
- 数据处理如果只调用 API 模型，可以不占 GPU；如果调用本地模型生成，需要占用 GPU。
- 支持任务队列优先级：`low`、`normal`、`high`、`urgent`。
- 高优任务是否可抢占低优任务，需要审批或管理员权限。

### 4.4 多算力节点升级策略

多算力节点阶段的推荐决策：

- 每个可执行训练任务的 GPU 节点都部署 `Compute API`、`Compute Agent`、`File Gateway`、LLaMA-Factory、CUDA/PyTorch 训练环境和本地数据盘。
- 应用服务器可以主动访问所有算力节点的 `Compute API/File Gateway`。
- 算力节点之间默认不互相访问，不做节点间点对点同步；所有调度、状态同步和资源分发由应用平台统一编排。
- 长期坚持每台算力服务器本地磁盘，因此需要 `resource_replicas` 记录数据集、基座模型、checkpoint、adapter、导出模型在哪些节点已有本地副本。
- 调度前必须检查目标节点是否已有模型和数据集副本；缺失时由应用平台通过目标节点 File Gateway 创建同步任务，完成后再启动训练。
- 调度支持自动和手动两种模式：普通用户默认自动调度，管理员/高级用户可手动指定节点、GPU、标签或节点组。

多节点自动调度建议：

1. 过滤 `enabled = true` 且 `scheduler_status = online` 的节点。
2. 按训练引擎、GPU 型号、显存、节点标签、租户/项目配额过滤。
3. 优先选择已存在所需模型/数据集副本的节点，减少跨节点复制。
4. 同等条件下按空闲 GPU、队列长度、节点权重和最近健康检查排序。
5. `draining` 节点不接收新任务，但允许已有任务完成。

## 5. 训练引擎接入标准

### 5.1 引擎抽象

LLaMA-Factory 是第一实现，但业务系统只依赖统一训练引擎接口：

```text
TrainingEngine
  validate_config(config)
  prepare_workspace(job_context)
  build_command(job_context)
  start(job_context)
  stop(job_id)
  parse_progress(log_line)
  collect_artifacts(job_id)
  export_model(job_id, export_config)
```

### 5.2 引擎注册信息

每个训练引擎需要声明：

- 引擎编码：`llama_factory`。
- 支持任务：`SFT`、`DPO`、`CPT`。
- 支持方法：`lora`、`qlora`、`full`。
- 支持模型模板：`qwen`、`llama3` 等。
- 支持数据格式：Alpaca、ShareGPT、DPO pair、pretrain text。
- 支持量化和导出格式。
- 参数 schema。
- 命令模板或启动方式。

### 5.3 LLaMA-Factory 适配要求

LLaMA-Factory 适配器负责：

- 将平台训练参数转换为 YAML/CLI 参数。
- 根据项目工作区生成数据集配置。
- 自动设置 `CUDA_VISIBLE_DEVICES`。
- 解析训练日志中的 loss、epoch、learning_rate、ETA。
- 收集 checkpoint、adapter、merged model、training_args、trainer_state。
- 支持训练停止和失败恢复。

### 5.4 后续接入其他平台的标准

其他训练平台只要实现以下契约即可接入：

- 输入：模型引用、数据集引用、训练配置、资源需求、输出目录。
- 输出：任务状态、进度、日志、指标、产物清单、失败原因。
- 生命周期：`prepare`、`start`、`running`、`stop`、`complete`、`cleanup`。
- 安全：不能越权访问其他租户/项目目录。
- 可观测：必须输出结构化事件和日志。

## 6. 多租户与项目级隔离

### 6.1 租户模型

需要新增租户管理：

- 租户名称、编码、状态。
- 租户管理员。
- 租户资源配额：GPU 并发数、磁盘容量、最大项目数。
- 租户审计策略、保留周期、审批策略。

### 6.2 项目空间

所有业务资源必须归属项目：

- 数据集。
- 模型。
- 训练任务。
- 评测任务。
- 推理任务。
- 数据处理任务。
- 自定义工具。

项目字段：

- 项目名称、描述、所属租户。
- 项目管理员、成员。
- 默认资源权限。
- GPU/磁盘/任务并发配额。
- 项目状态：启用、归档、禁用。

### 6.3 资源级权限

建议采用 RBAC + ACL 混合：

- RBAC 决定用户是否能访问模块，例如能否进入模型管理。
- 项目角色决定用户是否能管理项目内资源。
- 资源 ACL 处理特殊授权，例如某个数据集只给指定成员可读。

项目角色建议：

| 角色 | 权限 |
| --- | --- |
| Project Owner | 项目设置、成员、资源、审批策略全权限 |
| Project Maintainer | 创建/编辑模型、数据集、任务，可发起发布和删除 |
| Developer | 创建训练、评测、推理、数据处理任务 |
| Reviewer | 审批、复核、查看评测结果 |
| Viewer | 只读查看 |

资源权限建议：

- `read`：查看资源。
- `write`：编辑元数据和内容。
- `execute`：用于训练/评测/推理。
- `download`：下载文件和模型。
- `delete`：删除或申请删除。
- `manage_acl`：管理资源授权。

### 6.4 数据隔离要求

- API 查询必须默认带 `tenant_id` 和用户可访问项目范围。
- 数据库所有核心资源表增加 `tenant_id`、`project_id`。
- 本地磁盘路径包含租户和项目 ID，防止路径混用。
- 算力任务上下文必须携带租户/项目，Agent 只允许访问对应工作区。
- 日志、审计、下载链接也必须按租户隔离。

## 7. 企业治理设计

### 7.1 审批流

建议第一版支持可配置审批模板：

| 场景 | 是否建议审批 | 原因 |
| --- | --- | --- |
| 删除数据集 | 是 | 数据不可逆风险高 |
| 删除模型 | 是 | 影响训练/推理依赖 |
| 模型发布为可推理服务 | 是 | 影响生产资源 |
| 停止他人训练任务 | 是或管理员直通 | 影响计算成本和他人工作 |
| 导出模型 | 可配置 | 涉及资产外流 |
| 下载敏感数据集 | 可配置 | 涉及数据安全 |
| 提高 GPU 配额 | 是 | 涉及资源竞争 |

审批流能力：

- 发起审批。
- 指定审批人/审批组。
- 多级审批。
- 通过、驳回、撤回、转交。
- 审批超时提醒。
- 审批结果回写原业务动作。

### 7.2 审计留存周期

建议支持租户级配置：

- 操作审计：默认 180 天，可配置 90/180/365/永久。
- 登录审计：默认 180 天。
- 训练日志：默认 90 天。
- 系统监控：原始采样默认 30 天，聚合指标保留 1 年。
- 模型产物：默认长期保留，删除需审批。
- 临时文件：默认 7 天清理。
- 失败任务工作区：默认 14 天清理。

审计不可被普通管理员物理删除，只能由系统归档任务按策略处理。

### 7.3 安全策略

需要补充：

- API Key 加密存储和脱敏展示。
- 外部数据源密码加密存储或不落库。
- 下载链接短时有效。
- 敏感操作二次确认。
- 审批通过后动作有效期，例如 24 小时内执行。
- IP 白名单和服务间 token。
- 操作审计记录 before/after 数据。

## 8. 需要补全的页面和功能

### 8.1 租户与项目页面

当前前端缺失，建议新增：

1. 租户管理页
   - 租户列表、创建、禁用、配额设置、审计策略。
   - 仅平台管理员可见。

2. 项目空间页
   - 项目列表、创建项目、归档项目。
   - 展示项目资源概览：模型数、数据集数、任务数、磁盘占用、GPU 使用。

3. 项目成员页
   - 添加/移除成员。
   - 设置项目角色。
   - 查看成员最近操作。

4. 项目资源权限页
   - 模型/数据集/任务级授权。
   - 支持按用户、用户组、项目角色授权。

### 8.2 用户中心补全

前端路由已有但页面文件缺失或未完成：

- `PermissionDeniedView.vue`
- `UserSettingsView.vue`
- `UserCreateView.vue`
- `UserPermissionView.vue`

建议功能：

- 用户列表、创建、禁用、重置密码。
- 角色管理。
- 页面权限管理。
- 用户所属租户/项目。
- 用户可用 GPU/磁盘配额查看。
- 登录记录和操作审计入口。

### 8.3 审批中心

新增页面：

- 我的申请。
- 待我审批。
- 已办审批。
- 审批详情。
- 审批模板配置。

审批详情需要展示：

- 申请人、申请时间、动作类型、目标资源。
- 变更前后信息。
- 风险提示。
- 审批记录。
- 通过/驳回意见。

### 8.4 算力资源中心

当前只有硬件监控页，建议扩展为算力资源中心：

- GPU 拓扑和状态。
- GPU 当前任务占用。
- GPU 锁定/释放记录。
- 队列中的任务。
- 资源配额：租户/项目/用户维度。
- 算力节点 Agent 状态。
- 算力节点新增/编辑、连接测试、启用/禁用、维护模式。
- 节点权重、标签、训练引擎版本、LLaMA-Factory 健康状态。
- 节点本地资源副本：数据集、模型、checkpoint、adapter 和导出模型缓存。
- 训练引擎健康状态。

### 8.5 文件与存储管理

新增页面：

- 存储总览。
- 租户/项目磁盘占用。
- 大文件列表。
- 临时文件清理。
- Checkpoint 管理。
- 日志保留策略。
- 文件下载审计。

### 8.6 训练引擎管理

新增页面：

- 引擎列表。
- LLaMA-Factory 版本和路径。
- 引擎能力声明。
- 参数 schema 管理。
- 引擎健康检查。
- 引擎接入文档。

### 8.7 任务队列与运行控制

新增页面：

- 全局任务队列。
- 项目任务队列。
- 任务优先级调整。
- 任务重试。
- 任务停止审批。
- 失败任务诊断。

### 8.8 模型发布与服务治理

当前推理/对比页面已有基础能力，但缺少企业化发布能力：

- 模型发布申请。
- 推理服务实例配置。
- 端口、GPU、并发、超时、最大上下文限制。
- 服务启停记录。
- 调用统计。
- 服务下线审批。

## 9. 后端模块补全

### 9.1 新增核心模块

| 模块 | 职责 |
| --- | --- |
| tenant | 租户管理、租户配额、租户策略 |
| project | 项目空间、成员、项目角色 |
| resource_acl | 模型/数据集/任务级资源授权 |
| approval | 审批模板、审批实例、审批动作 |
| quota | GPU、磁盘、任务并发配额 |
| compute_gateway | 应用平台与算力平台通信 |
| file_gateway | 本地磁盘文件上传、下载、预览 |
| engine_registry | 训练引擎注册与能力发现 |
| retention | 审计、日志、临时文件保留策略 |

### 9.2 数据模型补充

在前一版 SQL 基础上，应新增或调整：

- `tenants`
- `tenant_users`
- `projects`
- `project_members`
- `resource_acl`
- `approval_templates`
- `approval_instances`
- `approval_steps`
- `quotas`
- `quota_usage`
- `compute_nodes`
- `gpu_devices`
- `gpu_allocations`
- `compute_jobs`
- `training_engines`
- `retention_policies`

核心资源表需要补充字段：

- `tenant_id`
- `project_id`
- `visibility`
- `owner_id`
- `approval_status`
- `storage_node_id`

需要调整的已有表：

- `models`
- `trained_models`
- `datasets`
- `dataset_files`
- `data_process_tasks`
- `fine_tune_tasks`
- `eval_tasks`
- `inference_tasks`
- `custom_tools`
- `audit_logs`
- `storage_objects`

### 9.3 接口补充

租户：

- `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`

项目：

- `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}`

资源授权：

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

审批：

- `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`

算力：

- `GET /api/compute/nodes`
- `GET /api/compute/gpus`
- `GET /api/compute/queue`
- `POST /api/compute/jobs/{id}/retry`
- `POST /api/compute/jobs/{id}/priority`

训练引擎：

- `GET /api/training-engines`
- `GET /api/training-engines/{id}`
- `POST /api/training-engines/{id}/health-check`
- `GET /api/training-engines/{id}/schema`

## 10. 端到端业务流程

### 10.1 数据集上传

1. 用户进入项目空间。
2. 用户创建数据集。
3. 应用平台校验项目写权限和磁盘配额。
4. 前端上传文件到应用平台。
5. 应用平台转发到算力文件网关，保存到项目目录。
6. 算力平台返回文件元数据和 checksum。
7. 应用平台登记数据集文件版本。
8. 审计记录上传行为。

### 10.2 微调训练

1. 用户选择项目、模型、数据集、训练参数和 GPU。
2. 应用平台检查模型/数据集 `execute` 权限。
3. 检查项目 GPU 并发配额。
4. 如果策略要求审批，先创建审批单。
5. 审批通过后创建 compute job。
6. 算力平台锁定 GPU，生成 LLaMA-Factory 配置，启动训练。
7. 训练日志和指标实时回传。
8. 完成后登记 trained model。
9. 如启用自动合并，进入合并任务。
10. 审计记录任务全生命周期。

### 10.3 模型发布

1. 用户选择训练产物。
2. 提交发布申请。
3. 审批通过后算力平台启动推理服务。
4. 分配端口和 GPU。
5. 应用平台登记服务实例。
6. 前端推理页面调用服务。
7. 监控调用量、延迟、错误率、GPU 占用。

## 11. 当前功能完整性评估

补充 6 条需求后，平台设计已经覆盖完整模型训练平台的主链路：

- 数据准备。
- 数据处理。
- 模型登记。
- 微调训练。
- 训练日志和指标。
- 模型合并和导出。
- 模型评测。
- 推理服务。
- 模型对比。
- 用户、权限、租户、项目隔离。
- 审批、审计、保留策略。
- 算力资源调度。

但如果目标是企业级生产平台，还建议继续确认以下缺口。

## 12. 仍需确认的问题

1. 本地磁盘是否在算力服务器上，应用服务器是否完全不保存训练文件？如果应用服务器也要保存上传临时文件，需要确认临时文件保留周期和容量。
2. 单机多 GPU 是否需要支持 MIG、GPU 分片或多进程共享，还是一张 GPU 同一时间只给一个任务？
3. 是否允许训练任务抢占？高优先级任务是否能停止低优先级任务？
4. 是否需要离线导入已有模型和已有数据集目录，还是所有文件都必须从平台上传？
5. 模型发布是否区分“测试服务”和“生产服务”？生产发布是否必须审批？
6. 是否需要数据集脱敏、敏感字段识别和数据质量评分作为内置流程？
7. 是否需要人工评测/人工复核结果沉淀为新数据集？
8. 是否需要训练任务失败后的断点续训？
9. 是否需要 checkpoint 自动清理策略，例如只保留最近 N 个或最好 N 个？
10. 是否需要对外提供标准 API 给其他系统调用训练、评测、推理能力？
11. 是否需要接入企业统一身份认证，例如 LDAP、OIDC、企业微信、钉钉？
12. 是否需要成本核算：按租户/项目统计 GPU 小时、磁盘占用、模型调用量？
13. 多算力节点是否需要节点组、租户绑定节点或项目绑定节点策略？
14. 跨节点资源同步是否需要限速、同步窗口和管理员审批？

## 13. 推荐决策补充

`system-development-plan.md` 已对上述问题给出第一版建议，需求设计以以下决策为准。

1. 本地磁盘主存储放在算力服务器，应用服务器只保留上传临时文件。临时文件默认保留 24 小时，成功转发到算力文件网关后可立即进入清理队列。
2. 第一版不支持 MIG、GPU 分片和多任务共享同一张 GPU。一张 GPU 同一时间只分配给一个训练任务或一个推理服务。GPU 数据模型预留 `partition_type`、`parent_gpu_uuid`、`memory_total_mb`，便于后续扩展 MIG。
3. 第一版不做自动抢占。支持任务优先级和排队；停止他人任务需要审批或平台管理员权限。
4. 多算力节点仍按“单机多 GPU 节点”管理，每个节点独立部署算力服务和 LLaMA-Factory；节点之间不互相访问，由应用平台统一调度和资源同步。
5. 多节点调度默认自动选择节点，同时支持管理员/高级用户手动指定节点；调度优先考虑节点健康、标签、权重、空闲 GPU、队列长度和资源副本是否已存在。
6. 第一版必须支持离线导入已有模型和数据集目录。导入由算力 Agent 扫描、校验、登记，并归属指定租户和项目。
7. 模型发布区分测试服务和生产服务。测试服务项目内可启动并默认限流；生产服务必须审批。
8. 数据脱敏和数据质量评分作为数据处理模块的一等能力进入第一期，先实现规则版脱敏、格式校验、重复率、完整性、长度分布等指标。
9. 人工评测/复核作为第二期功能，但第一期需在数据库和页面入口预留人工复核状态与修订字段。
10. 第一版支持从 checkpoint 手动恢复训练，不做自动失败续训。失败任务可选择 checkpoint 重试。
11. 第一版必须支持 checkpoint 自动清理策略：默认保留最近 3 个、最优 2 个；已发布模型关联 checkpoint 不自动删除；失败任务 checkpoint 默认保留 14 天。
12. 第一版提供内部 API，第二期再开放面向其他系统的标准 API、API Key、限流和 Webhook。
13. 第一版使用本地账号，预留 OIDC/LDAP 字段和认证 provider 抽象；第二期接入企业统一身份认证。
14. 第一版做 GPU 小时、磁盘占用、任务时长、推理调用量等用量统计；第二期再做成本单价和账单核算。

以上决策需要同步反映在接口文档、数据库 SQL、前端页面和部署方案中。第一版实现不再阻塞于这些问题的反复确认，除非实际部署环境与假设明显冲突。

## 14. 页面功能模块映射

本节用于帮助前端、后端、DB 和测试人员理解需求对应到哪些页面与功能模块。页面路径以当前 Vue 路由和新增规划路由为准。

### 14.1 平台入口与全局能力

| 页面模块 | 路由/入口 | 对应需求 | 主要功能 |
| --- | --- | --- | --- |
| 登录页 | `/login` | 用户认证、本地账号、后续预留 OIDC/LDAP | 登录、会话创建、权限加载 |
| 主布局 | `/` | 全局项目上下文、权限控制 | 菜单、顶部状态、项目切换器、用户信息 |
| 无权限页 | `/permission-denied` | 页面权限和资源权限兜底 | 展示无权限原因、返回可访问页面 |
| 服务看板 | `/dashboard` | 平台运行总览 | 服务健康、任务概览、训练统计、用户操作分布 |

### 14.2 租户、项目与权限治理

| 页面模块 | 建议路由 | 对应需求 | 主要功能 |
| --- | --- | --- | --- |
| 租户管理 | `/tenants`、`/tenants/:id` | 多租户、租户配额、留存策略 | 租户列表、创建/禁用租户、配额、审计留存策略 |
| 项目空间 | `/projects`、`/projects/:id` | 项目级隔离、项目资源聚合 | 项目列表、项目概览、资源统计、项目归档 |
| 项目成员 | `/projects/:id/members` | 项目角色 | 添加成员、移除成员、设置 owner/maintainer/developer/reviewer/viewer |
| 资源授权 | `/projects/:id/permissions` 或资源详情弹窗 | 模型/数据集/任务级 ACL | 按用户、项目角色授权 read/write/execute/download/delete/manage_acl |
| 用户中心 | `/user-settings`、`/user-settings/create`、`/user-settings/:id/permission` | 用户、角色、页面权限 | 用户列表、创建用户、禁用、重置密码、分配页面权限和项目 |

### 14.3 数据链路

| 页面模块 | 路由/入口 | 对应需求 | 主要功能 |
| --- | --- | --- | --- |
| 数据集列表 | `/dataset` | 数据集管理、项目隔离 | 列表、搜索、下载、删除审批入口 |
| 数据集创建/编辑 | `/dataset/create`、`/dataset/:id/edit` | 上传、本地磁盘、文件网关 | 创建数据集、上传文件、离线导入、元数据编辑 |
| 数据集预览 | `/dataset/:id/preview` | 文件版本、在线编辑、乐观锁 | 文件预览、版本切换、保存新版本、下载 |
| 数据处理列表 | `/data-process` | 数据处理任务管理 | 任务列表、状态、输出数据集跳转、删除审批 |
| 数据处理创建向导 | `/data-process/create` | 清洗、切片、生成、质量评分、脱敏 | 任务配置、模型选择、源文件/外部源、预览切片、生成、结果编辑、发布数据集 |
| 数据处理详情 | `/data-process/:id` | 处理统计和结果追踪 | 运行信息、处理统计、失败原因、结果明细 |
| 数据转换 | `/data-convert` | JSON/JSONL 转换 | 上传 JSON、转换任务、下载结果 |

### 14.4 模型训练链路

| 页面模块 | 路由/入口 | 对应需求 | 主要功能 |
| --- | --- | --- | --- |
| 模型管理 | `/model-manage` | 模型登记、离线导入、资源 ACL | 基座模型/API 模型列表、用途变更、授权、删除审批 |
| 模型创建/编辑 | `/model-manage/create`、`/model-manage/:id/edit` | 本地模型/API 模型登记 | 选择本地路径、填写 API 模型信息、加密 API Key |
| 权重合并 | `/model-manage/merge` | LoRA 合并、产物管理 | 选择训练产物、合并权重、生成 merged model |
| 微调任务列表 | `/fine-tune` | 训练任务管理 | 任务列表、状态、进度、停止/删除审批 |
| 微调创建 | `/fine-tune/create` | LLaMA-Factory 训练配置、GPU 调度 | 选择模型/数据集/GPU、训练参数、量化导出、提交审批或启动 |
| 训练日志详情 | `/training-log/:id` | 日志、指标、checkpoint、恢复训练 | 日志 tail、loss 曲线、GPU 状态、checkpoint 列表、恢复/重试 |
| 训练引擎管理 | `/training-engines` | LLaMA-Factory 插件化和后续引擎接入 | 引擎列表、能力声明、schema、健康检查 |

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

| 页面模块 | 路由/入口 | 对应需求 | 主要功能 |
| --- | --- | --- | --- |
| 评测列表 | `/model-eval` | 模型评测 | 评测任务列表、状态、分数、删除 |
| 评测创建 | `/model-eval/create` | 自动评测、LLM Judge、基础指标 | 选择模型/数据集/维度/GPU、配置指标、启动评测 |
| 评测详情 | `/model-eval/:id` | 样本级结果、人工复核预留 | 综合评价、维度汇总、样本评分、错误类型 |
| 评测维度 | `/model-eval/dimension/:id/edit` | 维度和评测 Prompt 管理 | 创建/编辑维度、评分范围、Prompt、启用状态 |
| 推理列表 | `/model-inference` | 测试推理服务 | 推理任务列表、加载/卸载、服务状态 |
| 推理创建 | `/model-inference/create` | 模型服务资源申请 | 选择模型、GPU、端口策略、并发参数 |
| 推理对话 | `/model-inference/chat/:id` | 模型对话 | 单模型流式对话、会话记录 |
| 模型对比 | `/model-compare/chat/:id`、`/model-compare/result` | 多模型对比 | 多模型加载、并行对话、对比结果 |
| 模型发布治理 | `/model-services`、`/model-services/:id` | 测试/生产服务、发布审批 | 测试服务启动、生产发布申请、调用统计、下线审批 |

### 14.6 算力、审批、审计和运维

| 页面模块 | 建议路由 | 对应需求 | 主要功能 |
| --- | --- | --- | --- |
| 算力资源中心 | `/compute`、`/compute/gpus` | 单机多 GPU、资源锁定、队列 | GPU 卡片、任务占用、节点状态、队列、优先级 |
| 存储管理 | `/storage` | 本地磁盘、配额、清理 | 租户/项目占用、大文件、临时文件、checkpoint 清理 |
| 审批中心 | `/approvals`、`/approvals/pending`、`/approvals/mine`、`/approvals/:id` | 审批流 | 我的申请、待我审批、审批详情、通过/驳回/撤回 |
| 审批模板 | `/approval-settings` | 审批策略配置 | 按动作配置审批人、超时、风险级别 |
| 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | 操作审计和留存 | 操作审计、登录审计、下载审计、筛选导出 |
| 平台性能 | `/hardware` | 系统监控 | CPU、内存、磁盘、GPU、进程 |
| 系统日志 | `/logs` | 日志查看 | 系统日志、训练日志、tail/offset 查询 |