YG-Soft/YG_FT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 重构 Docker 配置结构，添加 compute 模块及新增文档

Browse Source 
- 将 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
2026-07-20 14:59:31 +08:00
parent ba4059fe3b
commit 2c1e08a271
20 changed files with 1517 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
Dockerfile
View File

@@ -1,19 +0,0 @@
# syntax=docker/dockerfile:1
FROM node:20-alpine AS build
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ ./
RUN npm run build
FROM nginx:1.27-alpine
COPY docker/nginx.conf.template /etc/nginx/templates/default.conf.template
COPY --from=build /app/frontend/dist /usr/share/nginx/html
EXPOSE 80
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD wget -qO- http://127.0.0.1/ >/dev/null || exit 1

32
README.md
View File

@@ -86,6 +86,8 @@ logs/error-YYYY-MM-DD.log
- `docs/system-development-plan.md`：多人协作开发计划，按前端、后端、DB、部署拆分。 - `docs/system-development-plan.md`：多人协作开发计划，按前端、后端、DB、部署拆分。
- `docs/backend-logging.md`：后端日志模块使用说明。 - `docs/backend-logging.md`：后端日志模块使用说明。
- `docs/deployment-plan.md`：后期部署方案，覆盖单机算力服务器部署与应用/算力分离部署。 - `docs/deployment-plan.md`：后期部署方案，覆盖单机算力服务器部署与应用/算力分离部署。
- `docs/demo-development-plan.md`：可演示 Demo 开发计划，覆盖前端、后端、DB、Compute Simulator、GPU 和 LLaMA-Factory 适配。
- `docker/README.md`：Docker 部署入口，包含应用服务器和算力服务器两套 Compose 使用方式。
## 部署模式 ## 部署模式
@@ -98,6 +100,36 @@ logs/error-YYYY-MM-DD.log
详细方案见 `docs/deployment-plan.md`。 详细方案见 `docs/deployment-plan.md`。
## Docker 部署入口
应用服务器：
```bash
cd docker/app
cp .env.example .env
docker compose --profile build run --rm frontend-builder
docker compose up -d --build
```
算力服务器：
```bash
cd docker/compute
cp .env.example .env
docker compose up -d --build
```
两套 Compose 均采用代码外挂方式运行，镜像只包含运行时环境和第三方依赖。详细说明见 `docker/README.md`。
项目根目录不再保留 `Dockerfile` 和 `docker-compose.yml`，部署时统一进入 `docker/app` 或 `docker/compute` 目录执行。
当前 Docker 约定：
- PostgreSQL/Redis 开发阶段使用项目自带 Compose 服务，生产阶段保留切换企业统一基础设施的配置入口。
- 算力服务器上的 LLaMA-Factory 使用宿主机目录挂载，默认 `/opt/LLaMA-Factory`。
- 应用平台通过定时轮询 Compute API 同步训练状态，默认不要求算力服务器回调应用服务器。
- 多算力节点阶段，每台单机多 GPU 服务器都独立部署 `docker/compute`、Compute API、Agent、File Gateway 和 LLaMA-Factory；节点之间默认不互访，由应用平台通过 `compute_nodes`、`resource_replicas` 和 `resource_sync_jobs` 统一调度与同步。
## 后续开发原则 ## 后续开发原则
- 接口实现优先遵循 `docs/backend-api-design.md`。 - 接口实现优先遵循 `docs/backend-api-design.md`。

1
compute/__init__.py Normal file
View File

@@ -0,0 +1 @@
"""Compute platform package."""

40
compute/api/main.py Normal file
View File

@@ -0,0 +1,40 @@
from __future__ import annotations
import os
from pathlib import Path
from fastapi import FastAPI
def create_app() -> FastAPI:
app = FastAPI(title="YG Fine-Tune Compute API")
@app.get("/health")
async def health_check() -> dict[str, str]:
return {
"status": "ok",
"compute_host_id": os.getenv("COMPUTE_HOST_ID", "unknown"),
}
@app.get("/api/v1/compute/health")
async def compute_health_check() -> dict[str, str | bool]:
data_root = Path(os.getenv("YG_FT_DATA_ROOT", "/data/yg-ft"))
llama_factory_home = Path(os.getenv("LLAMA_FACTORY_HOME", "/opt/LLaMA-Factory"))
return {
"status": "ok",
"compute_host_id": os.getenv("COMPUTE_HOST_ID", "unknown"),
"app_callback_enabled": os.getenv("ENABLE_APP_CALLBACK", "false").lower() == "true",
"data_root": str(data_root),
"data_root_exists": data_root.exists(),
"llama_factory_home": str(llama_factory_home),
"llama_factory_home_exists": llama_factory_home.exists(),
}
@app.get("/api/v1/compute/jobs")
async def list_jobs() -> dict[str, list[dict[str, str]]]:
return {"items": []}
return app
app = create_app()

5
compute/requirements.txt Normal file
View File

@@ -0,0 +1,5 @@
fastapi>=0.111.0
uvicorn[standard]>=0.30.0
pydantic>=2.7.0
python-dotenv>=1.0.1
httpx>=0.27.0

15
docker-compose.yml
View File

@@ -1,15 +0,0 @@
services:
yg-ft-frontend:
build:
context: .
dockerfile: Dockerfile
image: yg-ft-frontend:latest
container_name: yg-ft-frontend
ports:
- "6801:80"
environment:
# Change this if the backend is deployed somewhere else.
API_PROXY_PASS: "http://host.docker.internal:7861"
extra_hosts:
- "host.docker.internal:host-gateway"
restart: unless-stopped

219
docker/README.md Normal file
View File

@@ -0,0 +1,219 @@
# Docker 部署说明
本文档对应 `docs/deployment-plan.md`，按应用服务器和算力服务器拆分 Dockerfile 与 Docker Compose 文件。所有业务代码均通过 volume 外挂到容器内，镜像只包含运行时环境和第三方依赖。
## 目录
```text
docker/
app/
Dockerfile.backend
Dockerfile.frontend
docker-compose.yml
.env.example
compute/
Dockerfile.compute
docker-compose.yml
.env.example
```
项目根目录不再保留 `Dockerfile` 和 `docker-compose.yml`，避免与应用服务器、算力服务器拆分部署入口混淆。
## 应用服务器部署
应用服务器包含前端 Nginx、Backend API、PostgreSQL、Redis。
开发阶段默认由项目自带 PostgreSQL/Redis：
```env
USE_BUILTIN_POSTGRES=true
USE_BUILTIN_REDIS=true
DATABASE_URL=postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft
REDIS_URL=redis://redis:6379/0
```
后续切换企业统一基础设施时，保留应用配置方式，只需要：
- 修改 `DATABASE_URL` 指向企业 PostgreSQL。
- 修改 `REDIS_URL` 指向企业 Redis。
- 从 Compose 中移除或禁用 `postgres`、`redis` 服务。
- 保留 `docs/postgres-schema.sql` 作为数据库初始化或迁移参考。
首次部署前先构建前端产物：
```bash
cd docker/app
cp .env.example .env
docker compose --profile build run --rm frontend-builder
docker compose up -d --build
```
默认访问地址：
```text
http://<app-server-ip>:6801
```
应用侧代码外挂：
```text
../../backend -> /app
../../frontend/dist -> /usr/share/nginx/html
../../runtime/app/logs/backend -> /opt/yg-ft/logs/backend
../../runtime/app/data -> /data/yg-ft
```
如果算力服务独立部署，需要在 `docker/app/.env` 中修改：
```env
COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
COMPUTE_SERVICE_TOKEN=change_me
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=10
COMPUTE_POLL_BATCH_SIZE=100
```
状态同步采用应用侧定时轮询 Compute API 为主，避免算力服务器需要访问应用服务器，从而减少双向网络策略开通。
## 应用服务与算力服务交互
应用服务与算力服务之间只要求应用服务器主动访问算力服务器：
```text
Frontend
-> Backend API
-> Compute API
-> Compute Agent / LLaMA-Factory
-> 本地数据盘 / 模型目录 / 训练产物
<- Backend Worker 定时轮询 Compute API
```
默认交互流程：
- `Backend API` 读取 `COMPUTE_API_BASE_URL`，向 `Compute API` 提交训练、评测、合并、导出等任务。
- `Compute API` 在算力服务器上调度 `Compute Agent`。
- `Compute Agent` 通过宿主机挂载目录调用 LLaMA-Factory，并读写 `/data/yg-ft` 下的数据集、模型和训练产物。
- `Backend Worker` 按 `COMPUTE_POLL_INTERVAL_SECONDS` 定时轮询 Compute API，同步任务状态、训练指标、日志摘要和产物索引。
- 前端只访问应用服务；文件下载和产物访问由应用服务完成权限校验后，再通过 `FILE_GATEWAY_BASE_URL` 获取受控资源。
当前支持通过环境变量动态配置算力服务地址：
```env
COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
COMPUTE_SERVICE_TOKEN=change_me
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=10
COMPUTE_POLL_BATCH_SIZE=100
```
后续多算力节点阶段建议升级为数据库配置：在 `compute_nodes` 表中维护节点地址、服务 token、启用状态、权重、标签和健康状态，并通过“算力节点管理”页面动态启停节点，避免每次调整地址都重启应用服务。
## 算力服务器部署
算力服务器包含 Compute API、后续 Compute Agent、后续 File Gateway、GPU runtime、本地训练数据目录和宿主机挂载的 LLaMA-Factory。
部署前需要安装：
- NVIDIA Driver。
- NVIDIA Container Toolkit。
- Docker Engine 和 Docker Compose Plugin。
- LLaMA-Factory 宿主机目录，默认 `/opt/LLaMA-Factory`。
- 本地训练数据盘，默认 `/data/yg-ft`。
算力服务器上的 LLaMA-Factory 使用宿主机挂载方式，不在当前 Compose 中重新构建 LLaMA-Factory 镜像：
```env
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
```
启动：
```bash
cd docker/compute
cp .env.example .env
docker compose up -d --build
```
健康检查：
```text
GET http://<compute-server-ip>:9100/health
GET http://<compute-server-ip>:9100/api/v1/compute/health
```
算力侧代码和数据外挂：
```text
../../compute -> /app/compute
${LLAMA_FACTORY_HOST_PATH} -> /opt/LLaMA-Factory
${YG_FT_DATA_ROOT_HOST} -> /data/yg-ft
../../runtime/compute/logs -> /opt/yg-ft/logs/compute
../../runtime/compute/training-logs -> /opt/yg-ft/logs/training
```
算力侧只需要允许应用服务器访问 Compute API/File Gateway，不要求访问应用服务器：
```env
ENABLE_APP_CALLBACK=false
COMPUTE_SERVICE_TOKEN=change_me
```
## 多算力节点部署
多算力节点仍按“单机多 GPU 节点”部署。每台 GPU 服务器都需要独立部署一套算力服务和宿主机挂载的 LLaMA-Factory：
```text
gpu-node-01: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
gpu-node-02: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
gpu-node-03: docker/compute + /opt/LLaMA-Factory + /data/yg-ft
```
节点之间默认不互相访问。应用服务器主动访问每个节点的 Compute API/File Gateway，并通过 `compute_nodes` 表或算力节点管理页面维护：
- `api_base_url`
- `file_gateway_url`
- `enabled`
- `scheduler_status`
- `scheduler_weight`
- `tags`
- `data_root`
- `model_root`
- `log_root`
长期使用每台算力服务器本地磁盘时，需要由应用平台维护资源副本关系。调度前先检查目标节点是否已有数据集和模型副本；如果没有，应用平台通过目标节点 File Gateway 创建资源同步任务，同步完成后再提交训练任务。
## 单机所有服务部署在算力服务器
在同一台 GPU 服务器上分别启动两套 Compose：
```bash
cd docker/app
docker compose --profile build run --rm frontend-builder
docker compose up -d --build
cd ../compute
docker compose up -d --build
```
应用侧 `.env` 中可使用：
```env
COMPUTE_API_BASE_URL=http://host.docker.internal:9100
FILE_GATEWAY_BASE_URL=http://host.docker.internal:9101
COMPUTE_STATUS_SYNC_MODE=polling
```
Linux 环境如需容器访问宿主机地址，可在应用侧 Compose 中按需增加 `extra_hosts: ["host.docker.internal:host-gateway"]`，或直接配置算力服务器内网 IP。
## 生产注意事项
- 当前 Compose 是工程部署骨架，后续 Backend Worker、Compute Agent、File Gateway 有可运行入口后，再拆分为独立服务。
- PostgreSQL 和 Redis 开发阶段采用项目自带部署，生产阶段保留切换企业统一基础设施的配置入口。
- 生产环境请把 `change_me` 替换为强密码或密钥管理系统注入。
- 当前镜像默认优先保证宿主机外挂日志和数据目录可写；生产环境如需非 root 运行，需要统一宿主机目录 UID/GID 后在 Compose 中增加 `user` 配置。
- Compute API 不应暴露公网，建议通过防火墙限制只允许应用服务器访问。
- GPU 容器需要 NVIDIA Container Toolkit，否则 `gpus: all` 无法生效。
- 前端 Nginx 默认挂载 `frontend/dist`，发布前需要先运行 `frontend-builder` 或由 CI 构建产物。

34
docker/app/.env.example Normal file
View File

@@ -0,0 +1,34 @@
APP_ENV=prod
APP_NAME=YG Fine-Tune Platform API
API_PREFIX=/api
POSTGRES_DB=yg_ft
POSTGRES_USER=yg_ft
POSTGRES_PASSWORD=change_me
DATABASE_URL=postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft
REDIS_URL=redis://redis:6379/0
# Development uses the built-in PostgreSQL/Redis services in docker-compose.yml.
# For enterprise infrastructure, replace DATABASE_URL/REDIS_URL and remove or disable those services.
USE_BUILTIN_POSTGRES=true
USE_BUILTIN_REDIS=true
LOG_LEVEL=INFO
LOG_DIR=/opt/yg-ft/logs/backend
LOG_FILE_PREFIX=backend
LOG_ERROR_FILE_PREFIX=error
LOG_MAX_BYTES=20971520
LOG_RETENTION_DAYS=10
API_PROXY_PASS=http://backend-api:8000
# Split deployment: set these to the compute server address, for example http://10.10.20.31:9100.
COMPUTE_API_BASE_URL=http://compute-api:9100
COMPUTE_SERVICE_TOKEN=change_me
FILE_GATEWAY_BASE_URL=http://compute-api:9101
# The application side polls Compute API for job state to avoid opening reverse network access.
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=10
COMPUTE_POLL_BATCH_SIZE=100

21
docker/app/Dockerfile.backend Normal file
View File

@@ -0,0 +1,21 @@
# syntax=docker/dockerfile:1
FROM python:3.11-slim
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1
WORKDIR /app
COPY backend/requirements.txt /tmp/requirements.txt
RUN pip install --upgrade pip \
&& pip install -r /tmp/requirements.txt \
&& rm -f /tmp/requirements.txt
RUN mkdir -p /opt/yg-ft/logs/backend /data/yg-ft \
&& chmod -R 0775 /opt/yg-ft /data/yg-ft
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

10
docker/app/Dockerfile.frontend Normal file
View File

@@ -0,0 +1,10 @@
# syntax=docker/dockerfile:1
FROM nginx:1.27-alpine
RUN mkdir -p /usr/share/nginx/html
EXPOSE 80
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD wget -qO- http://127.0.0.1/ >/dev/null || exit 1

122
docker/app/docker-compose.yml Normal file
View File

@@ -0,0 +1,122 @@
services:
frontend-builder:
image: node:20-alpine
profiles:
- build
working_dir: /workspace
volumes:
- ../../frontend:/workspace
- frontend_node_modules:/workspace/node_modules
command: sh -c "npm ci && npm run build"
frontend:
build:
context: ../..
dockerfile: docker/app/Dockerfile.frontend
image: yg-ft-frontend-runtime:latest
container_name: yg-ft-frontend
depends_on:
backend-api:
condition: service_started
ports:
- "6801:80"
environment:
API_PROXY_PASS: ${API_PROXY_PASS:-http://backend-api:8000}
volumes:
- ../../frontend/dist:/usr/share/nginx/html:ro
- ../nginx.conf.template:/etc/nginx/templates/default.conf.template:ro
networks:
- yg-ft-app
restart: unless-stopped
backend-api:
build:
context: ../..
dockerfile: docker/app/Dockerfile.backend
image: yg-ft-backend-api:latest
container_name: yg-ft-backend-api
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
expose:
- "8000"
environment:
APP_ENV: ${APP_ENV:-prod}
APP_NAME: ${APP_NAME:-YG Fine-Tune Platform API}
API_PREFIX: ${API_PREFIX:-/api}
DATABASE_URL: ${DATABASE_URL:-postgresql+asyncpg://yg_ft:change_me@postgres:5432/yg_ft}
REDIS_URL: ${REDIS_URL:-redis://redis:6379/0}
USE_BUILTIN_POSTGRES: ${USE_BUILTIN_POSTGRES:-true}
USE_BUILTIN_REDIS: ${USE_BUILTIN_REDIS:-true}
LOG_LEVEL: ${LOG_LEVEL:-INFO}
LOG_DIR: ${LOG_DIR:-/opt/yg-ft/logs/backend}
LOG_FILE_PREFIX: ${LOG_FILE_PREFIX:-backend}
LOG_ERROR_FILE_PREFIX: ${LOG_ERROR_FILE_PREFIX:-error}
LOG_MAX_BYTES: ${LOG_MAX_BYTES:-20971520}
LOG_RETENTION_DAYS: ${LOG_RETENTION_DAYS:-10}
COMPUTE_API_BASE_URL: ${COMPUTE_API_BASE_URL:-http://compute-api:9100}
COMPUTE_SERVICE_TOKEN: ${COMPUTE_SERVICE_TOKEN:-change_me}
FILE_GATEWAY_BASE_URL: ${FILE_GATEWAY_BASE_URL:-http://compute-api:9101}
COMPUTE_STATUS_SYNC_MODE: ${COMPUTE_STATUS_SYNC_MODE:-polling}
COMPUTE_POLL_INTERVAL_SECONDS: ${COMPUTE_POLL_INTERVAL_SECONDS:-10}
COMPUTE_POLL_BATCH_SIZE: ${COMPUTE_POLL_BATCH_SIZE:-100}
PYTHONPATH: /app
volumes:
- ../../backend:/app:ro
- ../../runtime/app/logs/backend:/opt/yg-ft/logs/backend
- ../../runtime/app/data:/data/yg-ft
networks:
- yg-ft-app
healthcheck:
test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/v1/health', timeout=3).read()\""]
interval: 30s
timeout: 5s
retries: 3
start_period: 20s
restart: unless-stopped
postgres:
image: postgres:16-alpine
container_name: yg-ft-postgres
environment:
POSTGRES_DB: ${POSTGRES_DB:-yg_ft}
POSTGRES_USER: ${POSTGRES_USER:-yg_ft}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-change_me}
PGDATA: /var/lib/postgresql/data/pgdata
volumes:
- postgres_data:/var/lib/postgresql/data
- ../../docs/postgres-schema.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
networks:
- yg-ft-app
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
redis:
image: redis:7-alpine
container_name: yg-ft-redis
command: ["redis-server", "--appendonly", "yes"]
volumes:
- redis_data:/data
networks:
- yg-ft-app
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 3s
retries: 5
restart: unless-stopped
networks:
yg-ft-app:
name: yg-ft-app
volumes:
frontend_node_modules:
postgres_data:
redis_data:

19
docker/compute/.env.example Normal file
View File

@@ -0,0 +1,19 @@
COMPUTE_ENV=prod
COMPUTE_HOST_ID=gpu-node-01
COMPUTE_API_PORT=9100
FILE_GATEWAY_PORT=9101
# The application server actively polls Compute API; compute server does not need reverse access.
COMPUTE_SERVICE_TOKEN=change_me
ENABLE_APP_CALLBACK=false
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
YG_FT_DATA_ROOT=/data/yg-ft
YG_FT_DATA_ROOT_HOST=/data/yg-ft
LOG_DIR=/opt/yg-ft/logs/compute
CUDA_VISIBLE_DEVICES=all
NVIDIA_VISIBLE_DEVICES=all
NVIDIA_DRIVER_CAPABILITIES=compute,utility

37
docker/compute/Dockerfile.compute Normal file
View File

@@ -0,0 +1,37 @@
# syntax=docker/dockerfile:1
FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
ENV DEBIAN_FRONTEND=noninteractive \
PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1
WORKDIR /app
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
python3 \
python3-pip \
python3-venv \
git \
curl \
ca-certificates \
tini \
&& ln -sf /usr/bin/python3 /usr/local/bin/python \
&& ln -sf /usr/bin/pip3 /usr/local/bin/pip \
&& rm -rf /var/lib/apt/lists/*
COPY compute/requirements.txt /tmp/requirements.txt
RUN pip install --upgrade pip \
&& pip install -r /tmp/requirements.txt \
&& rm -f /tmp/requirements.txt
RUN mkdir -p /opt/yg-ft/logs/compute /opt/yg-ft/logs/training /data/yg-ft /opt/LLaMA-Factory \
&& chmod -R 0775 /opt/yg-ft /data/yg-ft /opt/LLaMA-Factory
ENTRYPOINT ["/usr/bin/tini", "--"]
EXPOSE 9100
CMD ["uvicorn", "compute.api.main:app", "--host", "0.0.0.0", "--port", "9100"]

41
docker/compute/docker-compose.yml Normal file
View File

@@ -0,0 +1,41 @@
services:
compute-api:
build:
context: ../..
dockerfile: docker/compute/Dockerfile.compute
image: yg-ft-compute-api:latest
container_name: yg-ft-compute-api
gpus: all
ports:
- "${COMPUTE_API_PORT:-9100}:9100"
environment:
COMPUTE_ENV: ${COMPUTE_ENV:-prod}
COMPUTE_HOST_ID: ${COMPUTE_HOST_ID:-gpu-node-01}
COMPUTE_SERVICE_TOKEN: ${COMPUTE_SERVICE_TOKEN:-change_me}
ENABLE_APP_CALLBACK: ${ENABLE_APP_CALLBACK:-false}
LLAMA_FACTORY_HOME: ${LLAMA_FACTORY_HOME:-/opt/LLaMA-Factory}
YG_FT_DATA_ROOT: ${YG_FT_DATA_ROOT:-/data/yg-ft}
LOG_DIR: ${LOG_DIR:-/opt/yg-ft/logs/compute}
CUDA_VISIBLE_DEVICES: ${CUDA_VISIBLE_DEVICES:-all}
NVIDIA_VISIBLE_DEVICES: ${NVIDIA_VISIBLE_DEVICES:-all}
NVIDIA_DRIVER_CAPABILITIES: ${NVIDIA_DRIVER_CAPABILITIES:-compute,utility}
PYTHONPATH: /app
volumes:
- ../../compute:/app/compute:ro
- ${LLAMA_FACTORY_HOST_PATH:-/opt/LLaMA-Factory}:${LLAMA_FACTORY_HOME:-/opt/LLaMA-Factory}
- ${YG_FT_DATA_ROOT_HOST:-/data/yg-ft}:${YG_FT_DATA_ROOT:-/data/yg-ft}
- ../../runtime/compute/logs:/opt/yg-ft/logs/compute
- ../../runtime/compute/training-logs:/opt/yg-ft/logs/training
networks:
- yg-ft-compute
healthcheck:
test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:9100/health', timeout=3).read()\""]
interval: 30s
timeout: 5s
retries: 3
start_period: 20s
restart: unless-stopped
networks:
yg-ft-compute:
name: yg-ft-compute

97
docs/backend-api-design.md
View File

@@ -687,7 +687,7 @@ page=1&page_size=20&keyword=xxx&sort=-created_at
## 12. 仍需确认的问题 ## 12. 仍需确认的问题
1. 部署形态：单机多 GPU、K8s、多训练节点，还是只在一台服务器上调度？ 1. 部署形态已确认：多算力节点仍按“单机多 GPU 节点”管理，不引入 K8s；每台 GPU 服务器独立部署 Compute API/Agent/File Gateway/LLaMA-Factory。
2. 文件存储：使用本地磁盘、NAS、MinIO，还是对象存储？是否需要断点续传？ 2. 文件存储：使用本地磁盘、NAS、MinIO，还是对象存储？是否需要断点续传？
3. 训练框架：是否固定使用 LLaMA-Factory？是否还要支持 Transformers 原生、DeepSpeed、Accelerate？ 3. 训练框架：是否固定使用 LLaMA-Factory？是否还要支持 Transformers 原生、DeepSpeed、Accelerate？
4. 权限粒度：页面级权限是否足够，还是需要到数据集/模型/任务的所有者与项目空间级权限？ 4. 权限粒度：页面级权限是否足够，还是需要到数据集/模型/任务的所有者与项目空间级权限？
@@ -836,12 +836,58 @@ page=1&page_size=20&keyword=xxx&sort=-created_at
| 方法 | 路径 | 说明 | | 方法 | 路径 | 说明 |
| --- | --- | --- | | --- | --- | --- |
| GET | `/api/compute/nodes` | 算力节点列表 | | GET | `/api/compute/nodes` | 算力节点列表 |
| POST | `/api/compute/nodes` | 新增算力节点 |
| GET | `/api/compute/nodes/{id}` | 算力节点详情 |
| PUT | `/api/compute/nodes/{id}` | 编辑节点地址、权重、标签、路径和启用状态 |
| POST | `/api/compute/nodes/{id}/test-connection` | 测试 Compute API/File Gateway 连通性 |
| POST | `/api/compute/nodes/{id}/enable` | 启用节点 |
| POST | `/api/compute/nodes/{id}/disable` | 禁用节点，不接收新任务 |
| POST | `/api/compute/nodes/{id}/drain` | 进入维护模式，已有任务跑完后下线 |
| POST | `/api/compute/nodes/{id}/health-check` | 主动触发节点健康检查 |
| GET | `/api/compute/nodes/{id}/engines` | 节点训练引擎和版本 |
| GET | `/api/compute/nodes/{id}/replicas` | 节点本地资源副本 |
| GET | `/api/compute/gpus` | GPU 状态 | | GET | `/api/compute/gpus` | GPU 状态 |
| GET | `/api/compute/queue` | 任务队列 | | GET | `/api/compute/queue` | 任务队列 |
| GET | `/api/compute/jobs/{id}` | 算力任务详情 | | GET | `/api/compute/jobs/{id}` | 算力任务详情 |
| POST | `/api/compute/jobs/{id}/retry` | 重试任务 | | POST | `/api/compute/jobs/{id}/retry` | 重试任务 |
| POST | `/api/compute/jobs/{id}/priority` | 调整优先级 | | POST | `/api/compute/jobs/{id}/priority` | 调整优先级 |
| POST | `/api/internal/compute-callbacks/jobs` | 算力平台任务回调 | | POST | `/api/internal/compute-sync/jobs/poll` | 应用平台主动轮询并同步算力任务状态 |
| POST | `/api/internal/compute-sync/resources` | 调度前同步数据集/模型到目标节点 |
算力节点设计说明：
- 多算力节点仍按“单机多 GPU 节点”管理，每台 GPU 服务器是一条 `compute_nodes` 记录。
- 每个可执行训练的节点都需要部署 `Compute API`、`Compute Agent`、`File Gateway` 和宿主机挂载的 LLaMA-Factory。
- 节点之间默认不互相访问，应用平台主动访问所有节点的 Compute API/File Gateway。
- 调度支持 `auto` 和 `manual`：普通用户默认自动调度，管理员或高级用户可手动指定节点。
算力节点响应字段：
```json
{
"id": "uuid",
"code": "gpu-node-01",
"name": "A800 Node 01",
"api_base_url": "http://10.10.20.31:9100",
"file_gateway_url": "http://10.10.20.31:9101",
"enabled": true,
"scheduler_status": "online",
"scheduler_weight": 100,
"tags": ["A800", "80GB", "llama_factory"],
"gpu_count": 8,
"current_running_jobs": 2,
"max_parallel_jobs": 8,
"data_root": "/data/yg-ft",
"model_root": "/data/yg-ft/models",
"log_root": "/opt/yg-ft/logs/compute",
"last_health_check_at": "2026-07-20T12:00:00+08:00",
"health_detail": {
"compute_api": "ok",
"file_gateway": "ok",
"llama_factory": "ok"
}
}
```
GPU 响应字段： GPU 响应字段：
@@ -884,6 +930,13 @@ GPU 响应字段：
"job_type": "fine_tune", "job_type": "fine_tune",
"engine": "llama_factory", "engine": "llama_factory",
"priority": "normal", "priority": "normal",
"scheduler": {
"mode": "auto",
"requested_node_id": null,
"required_tags": ["A800"],
"preferred_tags": ["llama_factory"],
"min_gpu_memory_mb": 40960
},
"resource_request": { "resource_request": {
"gpu_count": 1, "gpu_count": 1,
"gpu_ids": [0], "gpu_ids": [0],
@@ -897,10 +950,46 @@ GPU 响应字段：
"dataset_path": "/data/ft-platform/.../datasets/train.jsonl", "dataset_path": "/data/ft-platform/.../datasets/train.jsonl",
"training_args": {} "training_args": {}
}, },
"callback_url": "http://app/api/internal/compute-callbacks/jobs" "status_sync_mode": "polling",
"poll_interval_seconds": 10
} }
``` ```
手动指定节点时：
```json
{
"scheduler": {
"mode": "manual",
"requested_node_id": "uuid",
"gpu_ids": [0, 1]
}
}
```
调度前资源副本检查：
```json
{
"target_compute_node_id": "uuid",
"resources": [
{
"resource_type": "model",
"resource_id": "uuid",
"required": true
},
{
"resource_type": "dataset",
"resource_id": "uuid",
"required": true
}
],
"sync_if_missing": true
}
```
如果目标节点缺少数据集或模型副本，应用平台通过 File Gateway 创建 `resource_sync_jobs`，同步完成后再提交训练任务。
### 13.7 文件网关与离线导入 ### 13.7 文件网关与离线导入
| 方法 | 路径 | 说明 | | 方法 | 路径 | 说明 |
@@ -1064,7 +1153,7 @@ LLaMA-Factory 引擎声明：
| --- | --- | --- | --- | | --- | --- | --- | --- |
| 审批中心 | `/approvals`、`/approvals/pending`、`/approvals/mine`、`/approvals/:id` | `GET /api/approvals`、`POST /api/approvals`、`GET /api/approvals/{id}`、`POST /api/approvals/{id}/approve`、`POST /api/approvals/{id}/reject`、`POST /api/approvals/{id}/cancel` | 审批列表和审批动作 | | 审批中心 | `/approvals`、`/approvals/pending`、`/approvals/mine`、`/approvals/:id` | `GET /api/approvals`、`POST /api/approvals`、`GET /api/approvals/{id}`、`POST /api/approvals/{id}/approve`、`POST /api/approvals/{id}/reject`、`POST /api/approvals/{id}/cancel` | 审批列表和审批动作 |
| 审批设置 | `/approval-settings` | `GET /api/approval-templates`、`PUT /api/approval-templates/{id}` | 审批模板 | | 审批设置 | `/approval-settings` | `GET /api/approval-templates`、`PUT /api/approval-templates/{id}` | 审批模板 |
| 算力资源 | `/compute`、`/compute/gpus`、`/compute/queue`、`/compute/nodes` | `GET /api/compute/nodes`、`GET /api/compute/gpus`、`GET /api/compute/queue`、`POST /api/compute/jobs/{id}/retry`、`POST /api/compute/jobs/{id}/priority` | GPU、节点、队列 | | 算力资源 | `/compute`、`/compute/gpus`、`/compute/queue`、`/compute/nodes` | `GET/POST/PUT /api/compute/nodes`、`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`、`GET /api/compute/queue`、`POST /api/compute/jobs/{id}/retry`、`POST /api/compute/jobs/{id}/priority` | GPU、节点、队列、节点权重、标签、维护状态、资源副本 |
| 存储管理 | `/storage` | `GET /api/quotas/usage`、`GET /api/files/{id}/download-url`、`GET /api/retention-policies`、`PUT /api/retention-policies/{id}` | 磁盘占用、下载、留存 | | 存储管理 | `/storage` | `GET /api/quotas/usage`、`GET /api/files/{id}/download-url`、`GET /api/retention-policies`、`PUT /api/retention-policies/{id}` | 磁盘占用、下载、留存 |
| 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | `GET /api/audit-logs`、`GET /api/login-logs`、`GET /api/download-logs` | 操作、登录、下载审计 | | 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | `GET /api/audit-logs`、`GET /api/login-logs`、`GET /api/download-logs` | 操作、登录、下载审计 |
| 训练引擎管理 | `/training-engines` | `GET /api/training-engines`、`GET /api/training-engines/{id}`、`GET /api/training-engines/{id}/schema`、`POST /api/training-engines/{id}/health-check` | 引擎能力和健康 | | 训练引擎管理 | `/training-engines` | `GET /api/training-engines`、`GET /api/training-engines/{id}`、`GET /api/training-engines/{id}/schema`、`POST /api/training-engines/{id}/health-check` | 引擎能力和健康 |

545
docs/demo-development-plan.md Normal file
View 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。

124
docs/deployment-plan.md
View File

@@ -139,7 +139,7 @@ flowchart LR
A --> L["LLaMA-Factory"] A --> L["LLaMA-Factory"]
A --> G["GPU/CUDA"] A --> G["GPU/CUDA"]
A --> FS["算力服务器本地磁盘"] A --> FS["算力服务器本地磁盘"]
A -- "状态回调/日志摘要" --> B B -- "定时轮询任务状态/指标/产物索引" --> C
``` ```
### 5.3 部署边界 ### 5.3 部署边界
@@ -170,8 +170,8 @@ GPU 算力服务器部署：
- 协议：内部 HTTPS REST，后续可扩展 gRPC。 - 协议：内部 HTTPS REST，后续可扩展 gRPC。
- 鉴权：服务间 Token，生产建议 mTLS + IP 白名单。 - 鉴权：服务间 Token，生产建议 mTLS + IP 白名单。
- 幂等：训练任务提交使用 `Idempotency-Key` 或 `job_id`。 - 幂等：训练任务提交使用 `Idempotency-Key` 或 `job_id`。
- 回调：算力平台向应用平台回调任务状态、指标摘要、产物索引。 - 状态同步：默认由应用平台定时轮询 Compute API，拉取任务状态、指标摘要和产物索引。
- 拉取：应用平台也可以定时轮询 Compute API，避免回调失败导致状态丢失。 - 回调策略：第一阶段关闭算力侧回调，避免算力服务器访问应用服务器，减少双向网络策略开通。
文件互通： 文件互通：
@@ -196,9 +196,46 @@ GPU 算力服务器部署：
### 5.6 风险 ### 5.6 风险
- 文件传输链路比单机部署复杂。 - 文件传输链路比单机部署复杂。
- 需要处理跨服务器网络失败、回调失败、任务状态对账。 - 需要处理跨服务器网络失败、轮询延迟、任务状态对账。
- 需要明确模型、数据集、产物在应用侧和算力侧的索引关系。 - 需要明确模型、数据集、产物在应用侧和算力侧的索引关系。
### 5.7 多算力节点部署约定
多算力节点阶段仍然按“单机多 GPU 节点”部署，每台 GPU 服务器都是一个独立算力节点。每个参与调度的节点都必须部署：
- Compute API。
- Compute Agent。
- File Gateway。
- LLaMA-Factory 宿主机目录和训练依赖。
- CUDA、NVIDIA Driver、NCCL、PyTorch。
- 本地数据盘 `/data/yg-ft`。
- 本地日志和训练产物目录。
网络策略保持单向：
```text
应用服务器 -> 算力节点 A Compute API/File Gateway
应用服务器 -> 算力节点 B Compute API/File Gateway
应用服务器 -> 算力节点 C Compute API/File Gateway
```
默认不要求：
```text
算力节点 -> 应用服务器
算力节点 A -> 算力节点 B
```
多节点任务调度由应用平台统一完成。应用平台从 `compute_nodes` 读取节点地址、权重、标签、启用状态、维护状态和健康检查结果；从 `resource_replicas` 判断目标节点是否已有所需数据集/模型副本；缺失时创建 `resource_sync_jobs`，通过目标节点 File Gateway 同步资源。
调度策略：
- 默认自动调度，按节点健康、标签、GPU 空闲、队列长度、节点权重和资源副本命中率排序。
- 支持管理员/高级用户手动指定节点或 GPU。
- `disabled` 节点不参与调度。
- `draining` 节点不接收新任务，但允许已有任务跑完。
- `maintenance/offline` 节点只允许查看和清理，不允许提交训练任务。
## 6. Compute API 接入标准 ## 6. Compute API 接入标准
为预留其他训练平台，应用平台只依赖统一算力接口，不直接依赖 LLaMA-Factory 命令。 为预留其他训练平台，应用平台只依赖统一算力接口，不直接依赖 LLaMA-Factory 命令。
@@ -241,6 +278,9 @@ LOG_DIR=/opt/yg-ft/logs/backend
COMPUTE_API_BASE_URL=https://compute.internal:9100 COMPUTE_API_BASE_URL=https://compute.internal:9100
COMPUTE_SERVICE_TOKEN=*** COMPUTE_SERVICE_TOKEN=***
FILE_GATEWAY_BASE_URL=https://compute.internal:9101 FILE_GATEWAY_BASE_URL=https://compute.internal:9101
COMPUTE_STATUS_SYNC_MODE=polling
COMPUTE_POLL_INTERVAL_SECONDS=10
COMPUTE_POLL_BATCH_SIZE=100
``` ```
算力平台： 算力平台：
@@ -250,9 +290,10 @@ COMPUTE_ENV=prod
COMPUTE_HOST_ID=gpu-node-01 COMPUTE_HOST_ID=gpu-node-01
COMPUTE_API_PORT=9100 COMPUTE_API_PORT=9100
FILE_GATEWAY_PORT=9101 FILE_GATEWAY_PORT=9101
APP_CALLBACK_BASE_URL=https://app.internal/api/v1/compute/callbacks COMPUTE_SERVICE_TOKEN=***
APP_SERVICE_TOKEN=*** ENABLE_APP_CALLBACK=false
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
YG_FT_DATA_ROOT=/data/yg-ft YG_FT_DATA_ROOT=/data/yg-ft
LOG_DIR=/opt/yg-ft/logs/compute LOG_DIR=/opt/yg-ft/logs/compute
CUDA_VISIBLE_DEVICES=0,1,2,3 CUDA_VISIBLE_DEVICES=0,1,2,3
@@ -295,11 +336,74 @@ CUDA_VISIBLE_DEVICES=0,1,2,3
- ERROR 日志能触发告警。 - ERROR 日志能触发告警。
- 日志、数据集、模型、产物所在磁盘容量有监控和告警。 - 日志、数据集、模型、产物所在磁盘容量有监控和告警。
## 11. 仍需确认的问题 ## 11. Docker Compose 文件规划
当前项目按应用服务器和算力服务器拆分了两套 Docker 部署文件，均采用代码外挂方式运行：
```text
docker/
app/
Dockerfile.backend # Backend API 运行时镜像，代码通过 volume 挂载到 /app
Dockerfile.frontend # Nginx 前端运行时镜像，frontend/dist 通过 volume 挂载
docker-compose.yml # 应用服务器：frontend、backend-api、postgres、redis
.env.example
compute/
Dockerfile.compute # CUDA + Python + Compute API 运行时镜像
docker-compose.yml # 算力服务器：compute-api，预留 agent/file gateway 拆分
.env.example
```
项目根目录不再保留 `Dockerfile` 和 `docker-compose.yml`，避免与拆分部署入口混淆。
应用服务器启动：
```bash
cd docker/app
cp .env.example .env
docker compose --profile build run --rm frontend-builder
docker compose up -d --build
```
算力服务器启动：
```bash
cd docker/compute
cp .env.example .env
docker compose up -d --build
```
应用服务器与算力服务器独立部署时，需要在 `docker/app/.env` 中配置：
```env
COMPUTE_API_BASE_URL=http://<compute-server-ip>:9100
FILE_GATEWAY_BASE_URL=http://<compute-server-ip>:9101
COMPUTE_SERVICE_TOKEN=change_me
```
这些地址在当前 Docker 阶段通过环境变量动态配置。后续多算力节点阶段建议升级为数据库配置，由应用平台从 `compute_nodes` 表读取节点地址、权重、标签、健康状态和启用状态，并在“算力节点管理”页面维护。
多节点后，每台算力服务器各自进入 `docker/compute` 启动一套算力服务，并在应用平台中登记为一条 `compute_nodes` 记录：
```text
gpu-node-01 -> http://10.10.20.31:9100 / http://10.10.20.31:9101
gpu-node-02 -> http://10.10.20.32:9100 / http://10.10.20.32:9101
gpu-node-03 -> http://10.10.20.33:9100 / http://10.10.20.33:9101
```
算力服务器需要在 `docker/compute/.env` 中配置：
```env
ENABLE_APP_CALLBACK=false
COMPUTE_SERVICE_TOKEN=change_me
LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory
YG_FT_DATA_ROOT_HOST=/data/yg-ft
```
## 12. 仍需确认的问题
- 生产环境是否已有统一 ELK/OpenSearch、Filebeat/Vector 标准配置。 - 生产环境是否已有统一 ELK/OpenSearch、Filebeat/Vector 标准配置。
- 数据库和 Redis 是否由企业基础设施统一提供，还是由项目自行部署。 - PostgreSQL/Redis 开发阶段采用项目自带部署；生产阶段是否切换企业统一基础设施，以及对应 SLA 仍需确认。
- 是否需要 PostgreSQL 主备、备份恢复、审计日志长期归档的明确 SLA。 - 是否需要 PostgreSQL 主备、备份恢复、审计日志长期归档的明确 SLA。
- 大文件上传是否需要断点续传、限速、病毒扫描或 DLP 检测。 - 大文件上传是否需要断点续传、限速、病毒扫描或 DLP 检测。
- 应用服务器与算力服务器之间是否允许双向访问，还是只能应用侧主动访问算力侧。 - 应用服务器与算力服务器默认只开通应用侧主动访问算力侧；如后续需要实时回调，再单独评估双向网络策略。
- 是否需要未来支持多台 GPU 节点调度；如果需要，Compute API 需要提前设计节点注册和调度策略。 - 多算力节点已按单机多 GPU 节点扩展设计；仍需确认是否需要节点组、租户绑定节点、同步限速和资源副本清理审批。

50
docs/platform-architecture-requirements.md
View File

@@ -80,7 +80,7 @@ flowchart LR
- 应用平台调用算力平台必须携带 `X-Service-Token` 或 mTLS 证书。 - 应用平台调用算力平台必须携带 `X-Service-Token` 或 mTLS 证书。
- 算力平台不信任前端用户身份，只信任应用平台下发的租户、项目、任务和资源上下文。 - 算力平台不信任前端用户身份，只信任应用平台下发的租户、项目、任务和资源上下文。
- 所有任务回调必须带签名，避免伪造状态。 - 第一阶段不默认启用算力侧回调，应用平台通过定时轮询 Compute API 同步任务状态；如未来启用回调，必须带签名，避免伪造状态。
核心通信接口： 核心通信接口：
@@ -93,7 +93,7 @@ flowchart LR
| 应用 -> 算力 | `GET /compute/resources/gpus` | 查询 GPU 状态 | | 应用 -> 算力 | `GET /compute/resources/gpus` | 查询 GPU 状态 |
| 应用 -> 算力 | `POST /compute/files/upload` | 上传文件到算力本地磁盘 | | 应用 -> 算力 | `POST /compute/files/upload` | 上传文件到算力本地磁盘 |
| 应用 -> 算力 | `GET /compute/files/{object_id}/download` | 下载文件 | | 应用 -> 算力 | `GET /compute/files/{object_id}/download` | 下载文件 |
| 算力 -> 应用 | `POST /api/internal/compute-callbacks/jobs` | 回调任务状态、指标、产物 | | 应用 -> 算力 | `GET /compute/jobs?status=running` | 定时轮询任务状态、指标、产物索引 |
## 3. 本地磁盘存储设计 ## 3. 本地磁盘存储设计
@@ -149,6 +149,8 @@ flowchart LR
## 4. 单机多 GPU 资源调度 ## 4. 单机多 GPU 资源调度
第一版可以先以单个算力节点跑通主链路，但数据模型、接口和页面需要按多算力节点预留。多节点阶段仍然采用“每台 GPU 服务器 = 一个单机多 GPU 节点”的模式，不引入 Kubernetes。
### 4.1 GPU 资源模型 ### 4.1 GPU 资源模型
每张 GPU 需要记录： 每张 GPU 需要记录：
@@ -183,6 +185,25 @@ flowchart LR
- 支持任务队列优先级：`low`、`normal`、`high`、`urgent`。 - 支持任务队列优先级：`low`、`normal`、`high`、`urgent`。
- 高优任务是否可抢占低优任务，需要审批或管理员权限。 - 高优任务是否可抢占低优任务，需要审批或管理员权限。
### 4.4 多算力节点升级策略
多算力节点阶段的推荐决策：
- 每个可执行训练任务的 GPU 节点都部署 `Compute API`、`Compute Agent`、`File Gateway`、LLaMA-Factory、CUDA/PyTorch 训练环境和本地数据盘。
- 应用服务器可以主动访问所有算力节点的 `Compute API/File Gateway`。
- 算力节点之间默认不互相访问，不做节点间点对点同步；所有调度、状态同步和资源分发由应用平台统一编排。
- 长期坚持每台算力服务器本地磁盘，因此需要 `resource_replicas` 记录数据集、基座模型、checkpoint、adapter、导出模型在哪些节点已有本地副本。
- 调度前必须检查目标节点是否已有模型和数据集副本；缺失时由应用平台通过目标节点 File Gateway 创建同步任务，完成后再启动训练。
- 调度支持自动和手动两种模式：普通用户默认自动调度，管理员/高级用户可手动指定节点、GPU、标签或节点组。
多节点自动调度建议：
1. 过滤 `enabled = true` 且 `scheduler_status = online` 的节点。
2. 按训练引擎、GPU 型号、显存、节点标签、租户/项目配额过滤。
3. 优先选择已存在所需模型/数据集副本的节点，减少跨节点复制。
4. 同等条件下按空闲 GPU、队列长度、节点权重和最近健康检查排序。
5. `draining` 节点不接收新任务，但允许已有任务完成。
## 5. 训练引擎接入标准 ## 5. 训练引擎接入标准
### 5.1 引擎抽象 ### 5.1 引擎抽象
@@ -421,6 +442,9 @@ LLaMA-Factory 适配器负责：
- 队列中的任务。 - 队列中的任务。
- 资源配额：租户/项目/用户维度。 - 资源配额：租户/项目/用户维度。
- 算力节点 Agent 状态。 - 算力节点 Agent 状态。
- 算力节点新增/编辑、连接测试、启用/禁用、维护模式。
- 节点权重、标签、训练引擎版本、LLaMA-Factory 健康状态。
- 节点本地资源副本：数据集、模型、checkpoint、adapter 和导出模型缓存。
- 训练引擎健康状态。 - 训练引擎健康状态。
### 8.5 文件与存储管理 ### 8.5 文件与存储管理
@@ -650,6 +674,8 @@ LLaMA-Factory 适配器负责：
10. 是否需要对外提供标准 API 给其他系统调用训练、评测、推理能力？ 10. 是否需要对外提供标准 API 给其他系统调用训练、评测、推理能力？
11. 是否需要接入企业统一身份认证，例如 LDAP、OIDC、企业微信、钉钉？ 11. 是否需要接入企业统一身份认证，例如 LDAP、OIDC、企业微信、钉钉？
12. 是否需要成本核算：按租户/项目统计 GPU 小时、磁盘占用、模型调用量？ 12. 是否需要成本核算：按租户/项目统计 GPU 小时、磁盘占用、模型调用量？
13. 多算力节点是否需要节点组、租户绑定节点或项目绑定节点策略？
14. 跨节点资源同步是否需要限速、同步窗口和管理员审批？
## 13. 推荐决策补充 ## 13. 推荐决策补充
@@ -658,15 +684,17 @@ LLaMA-Factory 适配器负责：
1. 本地磁盘主存储放在算力服务器，应用服务器只保留上传临时文件。临时文件默认保留 24 小时，成功转发到算力文件网关后可立即进入清理队列。 1. 本地磁盘主存储放在算力服务器，应用服务器只保留上传临时文件。临时文件默认保留 24 小时，成功转发到算力文件网关后可立即进入清理队列。
2. 第一版不支持 MIG、GPU 分片和多任务共享同一张 GPU。一张 GPU 同一时间只分配给一个训练任务或一个推理服务。GPU 数据模型预留 `partition_type`、`parent_gpu_uuid`、`memory_total_mb`，便于后续扩展 MIG。 2. 第一版不支持 MIG、GPU 分片和多任务共享同一张 GPU。一张 GPU 同一时间只分配给一个训练任务或一个推理服务。GPU 数据模型预留 `partition_type`、`parent_gpu_uuid`、`memory_total_mb`，便于后续扩展 MIG。
3. 第一版不做自动抢占。支持任务优先级和排队；停止他人任务需要审批或平台管理员权限。 3. 第一版不做自动抢占。支持任务优先级和排队；停止他人任务需要审批或平台管理员权限。
4. 第一版必须支持离线导入已有模型和数据集目录。导入由算力 Agent 扫描、校验、登记，并归属指定租户和项目。 4. 多算力节点仍按“单机多 GPU 节点”管理，每个节点独立部署算力服务和 LLaMA-Factory；节点之间不互相访问，由应用平台统一调度和资源同步。
5. 模型发布区分测试服务和生产服务。测试服务项目内可启动并默认限流；生产服务必须审批。 5. 多节点调度默认自动选择节点，同时支持管理员/高级用户手动指定节点；调度优先考虑节点健康、标签、权重、空闲 GPU、队列长度和资源副本是否已存在。
6. 数据脱敏和数据质量评分作为数据处理模块的一等能力进入第一期，先实现规则版脱敏、格式校验、重复率、完整性、长度分布等指标。 6. 第一版必须支持离线导入已有模型和数据集目录。导入由算力 Agent 扫描、校验、登记，并归属指定租户和项目。
7. 人工评测/复核作为第二期功能，但第一期需在数据库和页面入口预留人工复核状态与修订字段。 7. 模型发布区分测试服务和生产服务。测试服务项目内可启动并默认限流；生产服务必须审批。
8. 第一版支持从 checkpoint 手动恢复训练，不做自动失败续训。失败任务可选择 checkpoint 重试。 8. 数据脱敏和数据质量评分作为数据处理模块的一等能力进入第一期，先实现规则版脱敏、格式校验、重复率、完整性、长度分布等指标。
9. 第一版必须支持 checkpoint 自动清理策略：默认保留最近 3 个、最优 2 个；已发布模型关联 checkpoint 不自动删除；失败任务 checkpoint 默认保留 14 天。 9. 人工评测/复核作为第二期功能，但第一期需在数据库和页面入口预留人工复核状态与修订字段。
10. 第一版提供内部 API，第二期再开放面向其他系统的标准 API、API Key、限流和 Webhook。 10. 第一版支持从 checkpoint 手动恢复训练，不做自动失败续训。失败任务可选择 checkpoint 重试。
11. 第一版使用本地账号，预留 OIDC/LDAP 字段和认证 provider 抽象；第二期接入企业统一身份认证。 11. 第一版必须支持 checkpoint 自动清理策略：默认保留最近 3 个、最优 2 个；已发布模型关联 checkpoint 不自动删除；失败任务 checkpoint 默认保留 14 天。
12. 第一版做 GPU 小时、磁盘占用、任务时长、推理调用量等用量统计；第二期再做成本单价和账单核算。 12. 第一版提供内部 API，第二期再开放面向其他系统的标准 API、API Key、限流和 Webhook。
13. 第一版使用本地账号，预留 OIDC/LDAP 字段和认证 provider 抽象；第二期接入企业统一身份认证。
14. 第一版做 GPU 小时、磁盘占用、任务时长、推理调用量等用量统计；第二期再做成本单价和账单核算。
以上决策需要同步反映在接口文档、数据库 SQL、前端页面和部署方案中。第一版实现不再阻塞于这些问题的反复确认，除非实际部署环境与假设明显冲突。 以上决策需要同步反映在接口文档、数据库 SQL、前端页面和部署方案中。第一版实现不再阻塞于这些问题的反复确认，除非实际部署环境与假设明显冲突。

110
docs/postgres-schema.sql
View File

@@ -1147,6 +1147,116 @@ CREATE INDEX IF NOT EXISTS idx_gpu_allocations_scope ON gpu_allocations(tenant_i
CREATE UNIQUE INDEX IF NOT EXISTS uq_gpu_allocations_active_gpu CREATE UNIQUE INDEX IF NOT EXISTS uq_gpu_allocations_active_gpu
ON gpu_allocations(gpu_device_id) WHERE released_at IS NULL; ON gpu_allocations(gpu_device_id) WHERE released_at IS NULL;
-- Multi compute-node scheduling and local-cache metadata.
-- Each GPU server is modeled as one compute node. Nodes do not call each other;
-- the application platform schedules jobs and syncs resources through each node's File Gateway.
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS file_gateway_url text;
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS enabled boolean NOT NULL DEFAULT true;
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS scheduler_status varchar(40) NOT NULL DEFAULT 'online';
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS scheduler_weight integer NOT NULL DEFAULT 100 CHECK (scheduler_weight >= 0);
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS tags text[] NOT NULL DEFAULT '{}';
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS service_token_encrypted text;
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS data_root text NOT NULL DEFAULT '/data/yg-ft';
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS model_root text NOT NULL DEFAULT '/data/yg-ft/models';
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS log_root text NOT NULL DEFAULT '/opt/yg-ft/logs/compute';
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS max_parallel_jobs integer NOT NULL DEFAULT 1 CHECK (max_parallel_jobs >= 0);
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS current_running_jobs integer NOT NULL DEFAULT 0 CHECK (current_running_jobs >= 0);
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS last_health_check_at timestamptz;
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS health_detail jsonb NOT NULL DEFAULT '{}'::jsonb;
ALTER TABLE compute_nodes ADD COLUMN IF NOT EXISTS drain_reason text;
CREATE INDEX IF NOT EXISTS idx_compute_nodes_scheduler
ON compute_nodes(enabled, scheduler_status, scheduler_weight DESC, last_health_check_at DESC);
CREATE INDEX IF NOT EXISTS idx_compute_nodes_tags_gin
ON compute_nodes USING gin(tags);
ALTER TABLE compute_jobs ADD COLUMN IF NOT EXISTS scheduler_mode varchar(40) NOT NULL DEFAULT 'auto';
ALTER TABLE compute_jobs ADD COLUMN IF NOT EXISTS requested_node_id uuid REFERENCES compute_nodes(id) ON DELETE SET NULL;
ALTER TABLE compute_jobs ADD COLUMN IF NOT EXISTS assigned_at timestamptz;
ALTER TABLE compute_jobs ADD COLUMN IF NOT EXISTS scheduler_reason text;
CREATE INDEX IF NOT EXISTS idx_compute_jobs_requested_node
ON compute_jobs(requested_node_id, status, created_at DESC);
CREATE TABLE IF NOT EXISTS compute_node_engines (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
compute_node_id uuid NOT NULL REFERENCES compute_nodes(id) ON DELETE CASCADE,
engine_id uuid REFERENCES training_engines(id) ON DELETE SET NULL,
engine_code varchar(80) NOT NULL,
engine_version varchar(80),
home_path text,
status varchar(40) NOT NULL DEFAULT 'available',
capability jsonb NOT NULL DEFAULT '{}'::jsonb,
last_health_check_at timestamptz,
health_detail jsonb NOT NULL DEFAULT '{}'::jsonb,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (compute_node_id, engine_code)
);
SELECT touch_updated_at('compute_node_engines');
CREATE INDEX IF NOT EXISTS idx_compute_node_engines_node_status
ON compute_node_engines(compute_node_id, status, engine_code);
CREATE TABLE IF NOT EXISTS resource_replicas (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id uuid REFERENCES tenants(id) ON DELETE SET NULL,
project_id uuid REFERENCES projects(id) ON DELETE SET NULL,
resource_type varchar(80) NOT NULL,
resource_id uuid NOT NULL,
storage_object_id uuid REFERENCES storage_objects(id) ON DELETE SET NULL,
compute_node_id uuid NOT NULL REFERENCES compute_nodes(id) ON DELETE CASCADE,
local_path text NOT NULL,
status varchar(40) NOT NULL DEFAULT 'available',
sync_status varchar(40) NOT NULL DEFAULT 'synced',
checksum_sha256 char(64),
byte_size bigint NOT NULL DEFAULT 0 CHECK (byte_size >= 0),
version varchar(120),
pinned boolean NOT NULL DEFAULT false,
last_verified_at timestamptz,
expires_at timestamptz,
failure_reason text,
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (resource_type, resource_id, compute_node_id)
);
SELECT touch_updated_at('resource_replicas');
CREATE INDEX IF NOT EXISTS idx_resource_replicas_resource
ON resource_replicas(resource_type, resource_id, status);
CREATE INDEX IF NOT EXISTS idx_resource_replicas_node_status
ON resource_replicas(compute_node_id, status, sync_status, updated_at DESC);
CREATE INDEX IF NOT EXISTS idx_resource_replicas_scope
ON resource_replicas(tenant_id, project_id, resource_type, updated_at DESC);
CREATE TABLE IF NOT EXISTS resource_sync_jobs (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id uuid REFERENCES tenants(id) ON DELETE SET NULL,
project_id uuid REFERENCES projects(id) ON DELETE SET NULL,
target_compute_node_id uuid NOT NULL REFERENCES compute_nodes(id) ON DELETE CASCADE,
source_compute_node_id uuid REFERENCES compute_nodes(id) ON DELETE SET NULL,
resource_type varchar(80) NOT NULL,
resource_id uuid NOT NULL,
storage_object_id uuid REFERENCES storage_objects(id) ON DELETE SET NULL,
status task_status NOT NULL DEFAULT 'pending',
transfer_mode varchar(40) NOT NULL DEFAULT 'app_proxy',
source_uri text,
target_path text NOT NULL,
byte_size bigint NOT NULL DEFAULT 0 CHECK (byte_size >= 0),
checksum_sha256 char(64),
progress numeric(5,2) NOT NULL DEFAULT 0 CHECK (progress >= 0 AND progress <= 100),
failure_reason text,
requested_by uuid REFERENCES users(id) ON DELETE SET NULL,
started_at timestamptz,
completed_at timestamptz,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now()
);
SELECT touch_updated_at('resource_sync_jobs');
CREATE INDEX IF NOT EXISTS idx_resource_sync_jobs_status
ON resource_sync_jobs(status, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_resource_sync_jobs_target
ON resource_sync_jobs(target_compute_node_id, status, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_resource_sync_jobs_resource
ON resource_sync_jobs(resource_type, resource_id, status);
CREATE TABLE IF NOT EXISTS resource_acl ( CREATE TABLE IF NOT EXISTS resource_acl (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(), id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id uuid REFERENCES tenants(id) ON DELETE CASCADE, tenant_id uuid REFERENCES tenants(id) ON DELETE CASCADE,

47
docs/system-development-plan.md
View File

@@ -156,7 +156,7 @@
- API Key 管理。 - API Key 管理。
- OpenAPI 文档。 - OpenAPI 文档。
- 请求限流。 - 请求限流。
- Webhook 回调。 - Webhook 回调作为外部系统集成的可选能力，不作为算力状态同步默认方案。
- 外部系统发起训练、评测、推理。 - 外部系统发起训练、评测、推理。
### 1.11 企业统一身份认证 ### 1.11 企业统一身份认证
@@ -487,6 +487,9 @@ YG_FT/
- 任务队列。 - 任务队列。
- Agent 健康状态。 - Agent 健康状态。
- 租户/项目配额。 - 租户/项目配额。
- 算力节点新增、编辑、连接测试、启用、禁用、维护模式。
- 节点权重、标签、训练引擎版本和本地资源副本。
- 自动调度和手动指定节点入口。
联调接口： 联调接口：
@@ -567,16 +570,27 @@ YG_FT/
开发内容： 开发内容：
- 算力平台客户端。 - 算力平台客户端。
- 算力节点管理：地址、File Gateway、权重、标签、启用状态、维护状态。
- 自动/手动调度策略。
- 调度前检查模型/数据集在目标节点的资源副本。
- 缺失资源时创建同步任务，通过目标节点 File Gateway 写入本地磁盘。
- 创建 compute job。 - 创建 compute job。
- 查询状态和日志。 - 查询状态和日志。
- 状态回调验签。 - 应用侧定时轮询 Compute API，同步任务状态、日志摘要和产物索引。
- 任务状态映射。 - 任务状态映射。
交付接口： 交付接口：
- `GET /api/compute/gpus` - `GET /api/compute/gpus`
- `GET /api/compute/queue` - `GET /api/compute/queue`
- `POST /api/internal/compute-callbacks/jobs` - `GET/POST/PUT /api/compute/nodes`
- `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/nodes/{id}/replicas`
- `POST /api/internal/compute-sync/jobs/poll`
- `POST /api/internal/compute-sync/resources`
#### Fine Tune 模块 #### Fine Tune 模块
@@ -660,7 +674,9 @@ YG_FT/
- 校验服务 token。 - 校验服务 token。
- 调用 Agent。 - 调用 Agent。
- 聚合状态。 - 聚合状态。
- 回调应用平台。 - 提供任务状态查询接口，供应用平台定时轮询。
- 每个单机多 GPU 算力节点都部署一套 Compute API，不依赖其他算力节点。
- 暴露节点健康、GPU、训练引擎、资源副本和文件网关状态。
### 7.2 Compute Agent ### 7.2 Compute Agent
@@ -735,9 +751,12 @@ YG_FT/
| `quota_usage` | 配额使用 | | `quota_usage` | 配额使用 |
| `storage_nodes` | 存储节点 | | `storage_nodes` | 存储节点 |
| `compute_nodes` | 算力节点 | | `compute_nodes` | 算力节点 |
| `compute_node_engines` | 算力节点训练引擎能力 |
| `gpu_devices` | GPU 设备 | | `gpu_devices` | GPU 设备 |
| `gpu_allocations` | GPU 分配记录 | | `gpu_allocations` | GPU 分配记录 |
| `compute_jobs` | 算力任务 | | `compute_jobs` | 算力任务 |
| `resource_replicas` | 数据集/模型/产物在算力节点的本地副本 |
| `resource_sync_jobs` | 应用平台编排的资源同步任务 |
| `training_engines` | 训练引擎 | | `training_engines` | 训练引擎 |
| `retention_policies` | 保留策略 | | `retention_policies` | 保留策略 |
| `cleanup_jobs` | 清理任务 | | `cleanup_jobs` | 清理任务 |
@@ -782,12 +801,14 @@ YG_FT/
- `file-gateway` - `file-gateway`
- `llama-factory-env` - `llama-factory-env`
多算力节点阶段，每台单机多 GPU 服务器都部署以上组件和宿主机挂载的 LLaMA-Factory。算力节点之间默认不互相访问，由应用平台统一调度和同步资源。
配置： 配置：
- `COMPUTE_NODE_ID` - `COMPUTE_NODE_ID`
- `SERVICE_TOKEN` - `SERVICE_TOKEN`
- `APP_CALLBACK_URL` - `ENABLE_APP_CALLBACK=false`
- `DATA_ROOT=/data/ft-platform` - `DATA_ROOT=/data/yg-ft`
- `LLAMA_FACTORY_PATH` - `LLAMA_FACTORY_PATH`
- `PYTHON_ENV_PATH` - `PYTHON_ENV_PATH`
- `GPU_VISIBLE_DEVICES` - `GPU_VISIBLE_DEVICES`
@@ -798,7 +819,7 @@ YG_FT/
- 前端只访问应用平台。 - 前端只访问应用平台。
- 应用平台可访问算力平台内部 API。 - 应用平台可访问算力平台内部 API。
- 算力平台可回调应用平台 internal callback。 - 第一阶段只开通应用平台主动访问算力平台内部 API，状态同步采用应用侧轮询。
- 算力平台不直接暴露给公网。 - 算力平台不直接暴露给公网。
- 文件下载通过应用平台签发令牌。 - 文件下载通过应用平台签发令牌。
@@ -939,9 +960,9 @@ YG_FT/
### 算力组 ### 算力组
- CE-A：Compute API、Agent、GPU 调度。 - CE-A：Compute API、Agent、GPU 调度、多节点健康检查。
- CE-B：LLaMA-Factory Adapter、日志解析、产物管理。 - CE-B：LLaMA-Factory Adapter、日志解析、产物管理。
- CE-C：File Gateway、本地磁盘、离线导入。 - CE-C：File Gateway、本地磁盘、离线导入、资源副本同步。
### 数据库/部署组 ### 数据库/部署组
@@ -954,7 +975,8 @@ YG_FT/
| --- | --- | --- | | --- | --- | --- |
| M1 基础治理 | 第 1-2 周 | 登录、用户、租户、项目、权限 | | M1 基础治理 | 第 1-2 周 | 登录、用户、租户、项目、权限 |
| M2 资源管理 | 第 3-4 周 | 模型、数据集、文件网关、离线导入 | | M2 资源管理 | 第 3-4 周 | 模型、数据集、文件网关、离线导入 |
| M3 训练主链路 | 第 5-7 周 | GPU 调度、LLaMA-Factory 训练、日志指标、产物 | | M3 训练主链路 | 第 5-7 周 | GPU 调度、LLaMA-Factory 训练、日志指标、产物、资源副本检查 |
| M3.5 多节点预留 | 第 7-8 周 | compute_nodes 管理、节点权重/标签、自动/手动调度、资源同步任务 |
| M4 数据处理和评测 | 第 8-9 周 | 数据处理、质量评分、自动评测 | | M4 数据处理和评测 | 第 8-9 周 | 数据处理、质量评分、自动评测 |
| M5 推理发布 | 第 10-11 周 | 推理服务、模型对比、生产发布审批 | | M5 推理发布 | 第 10-11 周 | 推理服务、模型对比、生产发布审批 |
| M6 企业治理收口 | 第 12 周 | 审批、审计、配额、清理、部署文档 | | M6 企业治理收口 | 第 12 周 | 审批、审计、配额、清理、部署文档 |
@@ -967,7 +989,8 @@ YG_FT/
- 项目成员只能访问授权项目资源。 - 项目成员只能访问授权项目资源。
- 模型和数据集支持资源级授权。 - 模型和数据集支持资源级授权。
- 上传数据集后可预览、编辑版本、用于训练。 - 上传数据集后可预览、编辑版本、用于训练。
- 训练任务可指定 GPU 并成功运行。 - 训练任务可自动调度节点/GPU，也可由管理员手动指定节点/GPU 并成功运行。
- 调度前可识别目标节点是否已有数据集和模型副本，缺失时能创建同步任务。
- 训练日志和指标实时可见。 - 训练日志和指标实时可见。
- 训练产物可登记、合并、发布测试服务。 - 训练产物可登记、合并、发布测试服务。
- 评测任务可生成样本级结果。 - 评测任务可生成样本级结果。
@@ -1078,7 +1101,7 @@ YG_FT/
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| 审批中心 | `/approvals`、`/approvals/pending`、`/approvals/mine`、`/approvals/:id` | 审批列表、详情、通过/驳回/撤回 | `/api/approvals` 系列 | `approval_instances`、`approval_steps` | 用户、项目 | | 审批中心 | `/approvals`、`/approvals/pending`、`/approvals/mine`、`/approvals/:id` | 审批列表、详情、通过/驳回/撤回 | `/api/approvals` 系列 | `approval_instances`、`approval_steps` | 用户、项目 |
| 审批模板 | `/approval-settings` | 动作策略、审批人规则、超时配置 | `/api/approval-templates` 系列 | `approval_templates` | 租户/项目 | | 审批模板 | `/approval-settings` | 动作策略、审批人规则、超时配置 | `/api/approval-templates` 系列 | `approval_templates` | 租户/项目 |
| 算力资源中心 | `/compute`、`/compute/gpus`、`/compute/queue`、`/compute/nodes` | GPU 卡片、节点状态、队列、优先级 | `/api/compute/*`、`/compute/*` 内部接口 | `compute_nodes`、`gpu_devices`、`compute_jobs`、`gpu_allocations` | Compute API/Agent | | 算力资源中心 | `/compute`、`/compute/gpus`、`/compute/queue`、`/compute/nodes` | GPU 卡片、节点状态、队列、优先级、节点新增/编辑、连接测试、启用/禁用、维护模式、节点权重/标签、本地资源副本 | `/api/compute/*`、`/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 /api/quotas/usage`、`GET/PUT /api/retention-policies` | `storage_nodes`、`storage_objects`、`cleanup_jobs`、`retention_policies` | 文件网关 | | 存储管理 | `/storage` | 磁盘占用、大文件、临时文件、checkpoint 清理 | `GET /api/quotas/usage`、`GET/PUT /api/retention-policies` | `storage_nodes`、`storage_objects`、`cleanup_jobs`、`retention_policies` | 文件网关 |
| 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | 筛选、详情、导出 | `GET /api/audit-logs`、`GET /api/login-logs`、`GET /api/download-logs` | `audit_logs`、`login_sessions` | 审计中间件 | | 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | 筛选、详情、导出 | `GET /api/audit-logs`、`GET /api/login-logs`、`GET /api/download-logs` | `audit_logs`、`login_sessions` | 审计中间件 |