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 架构分层

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 仓库建议结构

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 /modelTF/users
• POST /modelTF/users
• PUT /modelTF/users/{id}
• DELETE /modelTF/users/{id}
• PUT /modelTF/users/{id}/password

项目空间

路由：

• /projects
• /projects/create
• /projects/:id
• /projects/:id/members
• /projects/:id/permissions

功能：

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

联调接口：

• GET /modelTF/projects
• POST /modelTF/projects
• GET /modelTF/projects/{id}
• PUT /modelTF/projects/{id}
• GET /modelTF/projects/{id}/members
• POST /modelTF/projects/{id}/members

审批中心

路由：

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

功能：

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

联调接口：

• GET /modelTF/approvals
• POST /modelTF/approvals/{id}/approve
• POST /modelTF/approvals/{id}/reject
• POST /modelTF/approvals/{id}/cancel

算力资源中心

路由：

• /compute
• /compute/gpus
• /compute/queue
• /compute/nodes

功能：

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

联调接口：

• GET /modelTF/compute/gpus
• GET /modelTF/compute/queue
• GET /modelTF/compute/nodes
• GET /modelTF/quotas/usage

5.2 现有页面改造

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

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

通用改造：

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

6. 后端开发计划

6.1 P0 模块

Auth 模块

开发内容：

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

交付接口：

• POST /modelTF/login
• POST /modelTF/logout
• GET /modelTF/me

Tenant / Project 模块

开发内容：

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

交付接口：

• /modelTF/tenants
• /modelTF/projects
• /modelTF/projects/{id}/members

Resource ACL 模块

开发内容：

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

交付接口：

• GET /modelTF/resources/{resource_type}/{resource_id}/acl
• PUT /modelTF/resources/{resource_type}/{resource_id}/acl

Compute Gateway 模块

开发内容：

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

交付接口：

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

Fine Tune 模块

开发内容：

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

交付接口：

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

Approval 模块

开发内容：

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

交付接口：

• /modelTF/approvals
• /modelTF/approval-templates

Audit 模块

开发内容：

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

交付接口：

• GET /modelTF/audit-logs
• GET /modelTF/login-logs

6.2 P1 模块

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

6.3 P2 模块

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

7. 算力平台开发计划

7.1 Compute API

接口：

• POST /modelTF/compute/jobs
• GET /modelTF/compute/jobs/{id}
• POST /modelTF/compute/jobs/{id}/stop
• GET /modelTF/compute/jobs/{id}/logs
• GET /modelTF/compute/resources/gpus
• POST /modelTF/compute/files/upload
• GET /modelTF/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。
• 根据平台数据集 ID 生成 LLaMA-Factory dataset key 和 {dataset_dir}/dataset_info.json。
• 单文件数据集使用一个 dataset key，多文件数据集拆分为多个 key 并通过逗号组合传入 --dataset。
• 正式启动前由应用侧同步当前数据集文件到目标算力节点，确保训练使用最新激活版本。
• 设置 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/team-development-plan.md：3-4 人并行开发人员分工、模块边界、接口范围和里程碑。

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

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

16. 页面模块开发工作包

本节用于多人并行开发时认领任务。每个工作包都标明对应页面、前端内容、后端接口、DB 表和部署/算力依赖。当前菜单、二级路由、规划菜单和接口/数据库映射总览见 docs/menu-functional-requirements.md；按 3-4 人落地的具体人员边界和开发节奏见 docs/team-development-plan.md。

16.1 基础入口与用户权限

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

16.2 租户和项目空间

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

16.3 数据集和数据处理

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

16.4 模型管理和训练

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

16.5 评测、推理和发布

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

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

工作包	页面/路由	前端开发	后端开发	DB 关联	依赖
审批中心	/approvals、/approvals/pending、/approvals/mine、/approvals/:id	审批列表、详情、通过/驳回/撤回	/modelTF/approvals 系列	approval_instances、approval_steps	用户、项目
审批模板	/approval-settings	动作策略、审批人规则、超时配置	/modelTF/approval-templates 系列	approval_templates	租户/项目
算力资源中心	/compute、/compute/gpus、/compute/queue、/compute/nodes	GPU 卡片、节点状态、队列、优先级、节点新增/编辑、连接测试、启用/禁用、维护模式、节点权重/标签、本地资源副本	/modelTF/compute/*、/modelTF/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 /modelTF/quotas/usage、GET/PUT /modelTF/retention-policies	storage_nodes、storage_objects、cleanup_jobs、retention_policies	文件网关
审计中心	/audit-logs、/login-logs、/download-logs	筛选、详情、导出	GET /modelTF/audit-logs、GET /modelTF/login-logs、GET /modelTF/download-logs	audit_logs、login_sessions	审计中间件

16.7 页面开发优先级建议

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

P1/P2/P3 Development Status

Priority	Scope	Implemented content	Remaining production hardening
P1	Training runtime assets	Compute scans real checkpoint-* directories; backend persists checkpoints to fine_tune_checkpoints; backend parses log metrics into fine_tune_metrics; completed training auto-registers a trained model with its real output directory.	Add full TensorBoard event parsing and retention/cleanup execution policies.
P2	Model merge/export	/modelTF/model-manage/merge submits llamafactory-cli export through Compute; merge/export jobs are recorded in compute_jobs and model_export_jobs; trained model artifacts are recorded in model_artifacts; base->trained and merge/export relations are recorded in model_lineage; APIs expose artifacts, lineage and export jobs.	Add frontend polling/status panels for export jobs and richer artifact checksum generation during long-running export.
P3	Compute ops	compute_jobs and gpu_allocations are updated from runtime polling; training start uses scheduler_locks to serialize node selection and GPU pre-allocation; terminal task states release GPU allocations; resource replica drift check and repair-pending APIs are available; scripts/ops_diagnostics.py checks backend, PostgreSQL, Compute health, GPU discovery and Compute jobs.	Add dedicated scheduler worker, automatic replica repair execution from authoritative source metadata, and lock timeout alarms.