# 模型训练平台整体架构与开发计划 > 本文衔接 `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 /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。 - 生成 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 /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、成本核算、人工评测 | 扩展能力，第一版可预留 |