YG_FT/docs/demo-development-plan.md

# Demo 开发计划

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

## 1. Demo 目标

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

```text
登录
 -> 数据集管理
 -> 模型管理
 -> 创建微调任务
 -> 自动/手动选择算力节点
 -> 检查模型/数据集资源副本
 -> 缺失资源则同步到目标节点
 -> 启动训练任务
 -> 查看 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 后端基础模块

目录建议：

```text
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 列表 |

创建任务参数需要支持：

```json
{
  "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

目录建议：

```text
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 应用后端配置

```env
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 算力服务配置

```env
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 本地文件目录

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