feat: 重构 Docker 配置结构，添加 compute 模块及新增文档
- 将 Dockerfile 和 docker-compose.yml 迁移至 docker/ 目录下统一管理 - 新增 compute 计算模块（API 入口、依赖配置） - 新增 docker/app 和 docker/compute 部署配置 - 新增 demo-development-plan.md 演示开发计划文档 - 更新后端 API 设计、部署计划、架构需求等文档 - 更新 postgres 数据库 schema Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
wuyongtao
545
docs/demo-development-plan.md
Normal file
545
docs/demo-development-plan.md
Normal file
@@ -0,0 +1,545 @@
|
||||
# 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。
|
||||
Reference in New Issue
Block a user