YG_FT/docs/demo-development-plan.md

Demo 开发计划

本文档用于指导后续开发一个可演示的模型微调平台 Demo。Demo 不是纯前端展示，而是包含前端、FastAPI 后端、PostgreSQL、算力服务、GPU 状态、LLaMA-Factory 适配器和训练任务主链路的工程化演示版本。

1. Demo 目标

Demo 目标是在没有完整生产环境的条件下，跑通一条可信的模型微调平台主链路：

登录
 -> 数据集管理
 -> 模型管理
 -> 创建微调任务
 -> 自动/手动选择算力节点
 -> 检查模型/数据集资源副本
 -> 缺失资源则同步到目标节点
 -> 启动训练任务
 -> 查看 GPU 占用、训练日志、loss 曲线、checkpoint
 -> 训练完成后登记训练产物
 -> 可进入评测/推理演示

Demo 支持两种算力运行模式：

模式	说明	适用场景
simulator	模拟 GPU、训练进程、训练日志、loss、checkpoint	无 GPU、无 LLaMA-Factory 环境
real	调用 nvidia-smi 和 LLaMA-Factory 启动真实训练	有 GPU 和训练环境

第一版优先实现 simulator，同时保留 real 模式接口和适配器边界。

2. 技术范围

2.1 前端

基于现有 frontend/ 页面开发，逐步从 Mock 切换到 Demo 后端接口。

优先联调页面：

• /login
• /dashboard
• /dataset
• /dataset/create
• /dataset/:id/preview
• /model-manage
• /model-manage/create
• /fine-tune
• /fine-tune/create
• /training-log/:id
• /compute
• /compute/gpus
• /compute/queue
• /compute/nodes

2.2 后端

基于 backend/ FastAPI 工程实现 Demo API：

• 用户登录和当前用户。
• 数据集、模型、训练任务。
• 算力节点、GPU、队列。
• 资源副本和同步任务。
• 训练日志、指标、checkpoint。
• 审计日志最小记录。

2.3 数据库

开发阶段使用项目自带 PostgreSQL。Demo 使用 docs/postgres-schema.sql 的核心子集，并通过 seed 数据初始化演示数据。

2.4 算力服务

基于 compute/ 开发内部 Compute API：

• simulator 模式：模拟 GPU 与训练生命周期。
• real 模式：预留真实 GPU 和 LLaMA-Factory 调用。

每个算力节点仍按“单机多 GPU 节点”设计。多节点 Demo 可以通过多条 compute_nodes 记录模拟，也可以在多台机器上分别部署 docker/compute。

3. 模块开发清单

3.1 后端基础模块

目录建议：

backend/app/modules/
  auth/
  dataset/
  model/
  fine_tune/
  compute_gateway/
  audit/

接口：

方法	路径	说明
POST	/api/login	登录，Demo 可使用固定账号
GET	/api/me	当前用户
GET	/api/dashboard/overview	Demo 看板
GET	/api/health	应用健康检查

验收：

• 能通过前端登录。
• 能返回菜单权限。
• 前端退出后可重新登录。

3.2 数据集 Demo

接口：

方法	路径	说明
GET	/api/dataset-manage	数据集列表
POST	/api/dataset-manage	创建数据集
GET	/api/dataset-manage/{id}	数据集详情
POST	/api/dataset-manage/upload/{dataset_id}	上传或模拟上传文件
GET	/api/dataset-manage/preview/{file_id}	文件预览
GET	/api/dataset-manage/versions/{file_id}	文件版本

Demo 行为：

• 创建数据集后写入 PostgreSQL。
• 文件内容可以存本地 demo 目录或数据库小样本字段。
• 预览支持 JSONL 和文本。
• 数据集创建后生成一条 storage_objects 记录。

3.3 模型 Demo

接口：

方法	路径	说明
GET	/api/model-manage	模型列表
POST	/api/model-manage	新增模型
GET	/api/model-manage/{id}	模型详情
GET	/api/model-manage/local-models	本地模型路径列表
GET	/api/model-manage/trained-models	训练产物列表
POST	/api/model-manage/merge	模拟权重合并任务

Demo 行为：

• 新增本地模型时登记路径，不要求真实权重存在。
• 训练完成后自动生成 trained_models 记录。
• 权重合并可创建一个 compute_jobs 模拟任务。

3.4 算力节点与 GPU Demo

接口：

方法	路径	说明
GET	/api/compute/nodes	算力节点列表
POST	/api/compute/nodes	新增节点
PUT	/api/compute/nodes/{id}	编辑节点
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/gpus	GPU 状态
GET	/api/compute/queue	队列

Demo 行为：

• 默认 seed 两个算力节点：
  • gpu-node-01，4 张模拟 GPU。
  • gpu-node-02，4 张模拟 GPU。
• 支持节点标签：A800、4090、80GB、llama_factory。
• 支持节点状态：online、offline、draining、maintenance。
• GPU 状态随训练任务变化：idle -> reserved -> running -> idle。

3.5 资源副本与同步 Demo

接口：

方法	路径	说明
GET	/api/compute/nodes/{id}/replicas	节点资源副本
POST	/api/internal/compute-sync/resources	创建资源同步任务
GET	/api/internal/compute-sync/resources/{id}	同步任务详情

Demo 行为：

• 训练任务启动前检查目标节点是否已有模型和数据集副本。
• 如果缺失，创建 resource_sync_jobs。
• 同步任务状态模拟：pending -> running -> completed。
• 同步完成后写入 resource_replicas。
• Demo 不需要真实复制大文件，可以创建本地占位文件或只写元数据。

3.6 微调任务 Demo

接口：

方法	路径	说明
GET	/api/fine-tune	训练任务列表
POST	/api/fine-tune	创建训练任务
POST	/api/fine-tune/start	启动训练任务
GET	/api/fine-tune/{id}	任务详情
GET	/api/fine-tune/{id}/overview	训练概览
GET	/api/fine-tune/{id}/events	训练事件
POST	/api/fine-tune/{id}/stop	停止任务
POST	/api/fine-tune/{id}/retry	重试任务
GET	/api/fine-tune/{id}/checkpoints	checkpoint 列表

创建任务参数需要支持：

{
  "name": "demo-sft-task",
  "project_id": "uuid",
  "base_model_id": "uuid",
  "train_dataset_id": "uuid",
  "engine": "llama_factory",
  "scheduler": {
    "mode": "auto",
    "requested_node_id": null,
    "required_tags": ["llama_factory"],
    "min_gpu_memory_mb": 24000
  },
  "training_args": {
    "stage": "sft",
    "finetuning_type": "lora",
    "epochs": 3,
    "learning_rate": 0.0002
  }
}

Demo 行为：

• 自动调度：选择 enabled + online 节点，优先资源副本命中，按空闲 GPU、队列长度、权重排序。
• 手动调度：使用用户指定的 requested_node_id。
• 任务状态模拟：pending -> syncing -> queued -> running -> completed。
• 训练期间每 2-5 秒追加日志和指标。
• 完成后生成 checkpoint 和 trained model。

3.7 Compute API Demo

算力服务内部接口：

方法	路径	说明
GET	/health	节点健康
GET	/api/v1/compute/health	节点详细健康
GET	/compute/resources/gpus	GPU 状态
POST	/compute/jobs	创建任务
GET	/compute/jobs/{id}	查询任务
POST	/compute/jobs/{id}/stop	停止任务
GET	/compute/jobs/{id}/logs	拉取日志
POST	/compute/files/upload	文件网关上传
GET	/compute/files/{id}/download	文件网关下载

simulator 模式行为：

• 在内存或 SQLite/PostgreSQL 中维护任务状态。
• 使用后台线程/async task 模拟训练进度。
• 生成结构化日志、loss 曲线和 checkpoint。

real 模式预留：

• nvidia-smi 采集 GPU。
• subprocess.Popen 启动 LLaMA-Factory。
• 解析真实训练日志。
• 扫描真实 checkpoint 和 adapter。

3.8 LLaMA-Factory Adapter Demo

目录建议：

compute/engines/llama_factory/
  adapter.py
  schemas.py
  command_builder.py
  log_parser.py
  simulator.py

能力：

• validate_config(config)：校验训练参数。
• prepare_workspace(job)：准备工作目录。
• build_command(job)：生成 LLaMA-Factory 命令。
• start(job)：启动真实或模拟训练。
• stop(job_id)：停止任务。
• status(job_id)：查询状态。
• parse_log(line)：解析 loss、epoch、step、learning rate。
• collect_artifacts(job_id)：收集 checkpoint、adapter、merged model。

Demo 阶段必须完成：

• dry_run 命令生成。
• simulator 训练。
• 日志解析器单元测试。

真实训练阶段再完成：

• real 进程启动。
• 真实停止。
• 真实产物扫描。

4. 数据库 Demo 子集

第一版 Demo 最小使用表：

• users
• tenants
• projects
• models
• trained_models
• datasets
• dataset_files
• storage_objects
• fine_tune_tasks
• fine_tune_metrics
• fine_tune_checkpoints
• compute_nodes
• compute_node_engines
• gpu_devices
• compute_jobs
• gpu_allocations
• resource_replicas
• resource_sync_jobs
• audit_logs

Seed 数据：

• 管理员用户：admin / admin123。
• 租户：demo-tenant。
• 项目：demo-project。
• 模型：
  • Qwen2.5-7B-Instruct
  • Llama-3.1-8B-Instruct
• 数据集：
  • finance-sft-demo
  • customer-service-demo
• 算力节点：
  • gpu-node-01
  • gpu-node-02
• GPU：每个节点 4 张模拟 GPU。
• 训练任务：至少 3 条，分别处于 pending、running、completed。

5. 目录和配置建议

5.1 应用后端配置

APP_ENV=demo
DATABASE_URL=postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft
REDIS_URL=redis://redis:6379/0
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=3
DEMO_MODE=true

5.2 算力服务配置

COMPUTE_MODE=simulator
COMPUTE_HOST_ID=gpu-node-01
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
YG_FT_DATA_ROOT=/data/yg-ft
ENABLE_APP_CALLBACK=false

5.3 本地文件目录

runtime/
  app/
    data/
    logs/backend/
  compute/
    logs/
    training-logs/
    data/
      tenants/

6. 开发阶段计划

阶段 1：后端和 DB 最小闭环

目标：

• FastAPI 能启动。
• PostgreSQL 能初始化。
• Seed 数据可导入。
• 前端能登录并读取真实接口。

任务：

• 实现 DB session。
• 建立 Alembic 或 SQL 初始化流程。
• 实现 auth、dashboard、dataset、model 基础接口。
• 完成 Docker app 启动说明。

验收：

• GET /api/health 正常。
• POST /api/login 成功。
• 前端模型/数据集列表来自后端 DB。

阶段 2：Compute Simulator

目标：

• 算力节点、GPU、队列可演示。
• 训练任务可以模拟运行。

任务：

• 实现 compute/api/main.py 内部接口。
• 实现模拟 GPU 状态。
• 实现模拟任务生命周期。
• 实现训练日志和 loss 生成。
• 实现应用后端轮询同步。

验收：

• 前端 /compute/gpus 可看到 GPU 动态状态。
• 创建训练任务后 GPU 状态变化。
• /training-log/:id 能看到日志和曲线。

阶段 3：微调主链路

目标：

• 训练任务从创建到完成可完整演示。

任务：

• 实现调度器。
• 实现资源副本检查。
• 实现资源同步任务模拟。
• 实现 checkpoint 和 trained model 登记。
• 前端微调创建页接入真实后端。

验收：

• 自动调度能选择节点。
• 手动指定节点能生效。
• 缺资源时先同步再训练。
• 训练完成后模型产物出现在模型管理页。

阶段 4：LLaMA-Factory Adapter Dry Run

目标：

• 即使没有真实 GPU，也能展示平台如何生成 LLaMA-Factory 命令和配置。

任务：

• 实现参数校验。
• 实现 YAML/命令生成。
• 实现日志解析器。
• 在训练详情页展示命令预览。

验收：

• 创建训练任务后能查看 LLaMA-Factory 命令。
• 参数错误能返回可读错误。
• 日志解析器能从样例日志提取 loss。

阶段 5：真实 GPU/LLaMA-Factory 可选接入

目标：

• 在有 GPU 环境时可切换为真实训练。

任务：

• 接入 nvidia-smi。
• 检查 CUDA/Driver/PyTorch。
• 启动 LLaMA-Factory 训练进程。
• 停止训练进程。
• 扫描真实 checkpoint。

验收：

• COMPUTE_MODE=real 时能读取真实 GPU。
• 能启动一个最小 LLaMA-Factory 样例任务。
• 真实日志能显示在训练日志页。

7. 前后端联调顺序

1. 登录。
2. 看板。
3. 模型列表。
4. 数据集列表。
5. 算力节点和 GPU。
6. 微调创建。
7. 训练任务列表。
8. 训练日志详情。
9. 模型产物列表。
10. 推理对话 Mock/后端接口。

8. Demo 验收标准

必须满足：

• 不依赖真实 GPU 时，Demo 仍可完整跑通。
• 前端核心页面不再只依赖静态 Mock。
• 数据写入 PostgreSQL，刷新页面后仍存在。
• 训练任务状态会自动流转。
• GPU 状态会随任务变化。
• 训练日志会持续追加。
• loss 曲线会随训练推进变化。
• 训练完成后生成 checkpoint 和训练产物。
• 多算力节点页面能展示节点权重、标签、启用状态和维护状态。
• 资源副本页面能展示模型/数据集在哪些节点已有缓存。

可选满足：

• 接入真实 nvidia-smi。
• 接入真实 LLaMA-Factory。
• 支持真实文件上传到算力节点本地磁盘。

9. 风险和约束

风险	影响	Demo 处理
无 GPU 环境	不能真实训练	使用 COMPUTE_MODE=simulator
无 LLaMA-Factory	不能启动训练框架	使用 adapter dry_run 和 simulator
文件太大	本地 Demo 慢或失败	Demo 只使用小样本和占位文件
前端页面仍有 Mock 依赖	联调不完整	逐页替换 API，不一次性重写
多节点真实网络不可用	无法多机演示	用多条 compute_nodes 模拟多节点

10. 建议第一批开发任务

第一批建议只做 8 个任务：

1. 后端 DB session 和配置。
2. Seed 数据脚本。
3. 登录、模型、数据集基础接口。
4. Compute simulator 基础接口。
5. GPU 动态状态模拟。
6. 微调任务创建和状态机。
7. 训练日志/指标模拟。
8. 前端微调主链路接入后端。

完成这 8 个任务后，就可以形成第一版可演示 Demo。