diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 5ef763d..0000000 --- a/Dockerfile +++ /dev/null @@ -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 \ No newline at end of file diff --git a/README.md b/README.md index f27a031..1614838 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,8 @@ logs/error-YYYY-MM-DD.log - `docs/system-development-plan.md`：多人协作开发计划，按前端、后端、DB、部署拆分。 - `docs/backend-logging.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`。 +## 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`。 diff --git a/compute/__init__.py b/compute/__init__.py new file mode 100644 index 0000000..fe51931 --- /dev/null +++ b/compute/__init__.py @@ -0,0 +1 @@ +"""Compute platform package.""" diff --git a/compute/api/main.py b/compute/api/main.py new file mode 100644 index 0000000..d79c1d7 --- /dev/null +++ b/compute/api/main.py @@ -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() diff --git a/compute/requirements.txt b/compute/requirements.txt new file mode 100644 index 0000000..922f92e --- /dev/null +++ b/compute/requirements.txt @@ -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 diff --git a/docker-compose.yml b/docker-compose.yml deleted file mode 100644 index 897c8e7..0000000 --- a/docker-compose.yml +++ /dev/null @@ -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 \ No newline at end of file diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..fc3a6ca --- /dev/null +++ b/docker/README.md @@ -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://: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://:9100 +FILE_GATEWAY_BASE_URL=http://: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://:9100 +FILE_GATEWAY_BASE_URL=http://: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://:9100/health +GET http://: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 构建产物。 diff --git a/docker/app/.env.example b/docker/app/.env.example new file mode 100644 index 0000000..5df8086 --- /dev/null +++ b/docker/app/.env.example @@ -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 diff --git a/docker/app/Dockerfile.backend b/docker/app/Dockerfile.backend new file mode 100644 index 0000000..5fd505d --- /dev/null +++ b/docker/app/Dockerfile.backend @@ -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"] diff --git a/docker/app/Dockerfile.frontend b/docker/app/Dockerfile.frontend new file mode 100644 index 0000000..341c147 --- /dev/null +++ b/docker/app/Dockerfile.frontend @@ -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 diff --git a/docker/app/docker-compose.yml b/docker/app/docker-compose.yml new file mode 100644 index 0000000..655dd3c --- /dev/null +++ b/docker/app/docker-compose.yml @@ -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: diff --git a/docker/compute/.env.example b/docker/compute/.env.example new file mode 100644 index 0000000..7a57bb0 --- /dev/null +++ b/docker/compute/.env.example @@ -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 diff --git a/docker/compute/Dockerfile.compute b/docker/compute/Dockerfile.compute new file mode 100644 index 0000000..20d0b61 --- /dev/null +++ b/docker/compute/Dockerfile.compute @@ -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"] diff --git a/docker/compute/docker-compose.yml b/docker/compute/docker-compose.yml new file mode 100644 index 0000000..d77a2d6 --- /dev/null +++ b/docker/compute/docker-compose.yml @@ -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 diff --git a/docs/backend-api-design.md b/docs/backend-api-design.md index 32ac458..0d6b572 100644 --- a/docs/backend-api-design.md +++ b/docs/backend-api-design.md @@ -687,7 +687,7 @@ page=1&page_size=20&keyword=xxx&sort=-created_at ## 12. 仍需确认的问题 -1. 部署形态：单机多 GPU、K8s、多训练节点，还是只在一台服务器上调度？ +1. 部署形态已确认：多算力节点仍按“单机多 GPU 节点”管理，不引入 K8s；每台 GPU 服务器独立部署 Compute API/Agent/File Gateway/LLaMA-Factory。 2. 文件存储：使用本地磁盘、NAS、MinIO，还是对象存储？是否需要断点续传？ 3. 训练框架：是否固定使用 LLaMA-Factory？是否还要支持 Transformers 原生、DeepSpeed、Accelerate？ 4. 权限粒度：页面级权限是否足够，还是需要到数据集/模型/任务的所有者与项目空间级权限？ @@ -836,12 +836,58 @@ page=1&page_size=20&keyword=xxx&sort=-created_at | 方法 | 路径 | 说明 | | --- | --- | --- | | 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/queue` | 任务队列 | | GET | `/api/compute/jobs/{id}` | 算力任务详情 | | POST | `/api/compute/jobs/{id}/retry` | 重试任务 | | 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 响应字段： @@ -884,6 +930,13 @@ GPU 响应字段： "job_type": "fine_tune", "engine": "llama_factory", "priority": "normal", + "scheduler": { + "mode": "auto", + "requested_node_id": null, + "required_tags": ["A800"], + "preferred_tags": ["llama_factory"], + "min_gpu_memory_mb": 40960 + }, "resource_request": { "gpu_count": 1, "gpu_ids": [0], @@ -897,10 +950,46 @@ GPU 响应字段： "dataset_path": "/data/ft-platform/.../datasets/train.jsonl", "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 文件网关与离线导入 | 方法 | 路径 | 说明 | @@ -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` | 审批列表和审批动作 | | 审批设置 | `/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}` | 磁盘占用、下载、留存 | | 审计中心 | `/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` | 引擎能力和健康 | diff --git a/docs/demo-development-plan.md b/docs/demo-development-plan.md new file mode 100644 index 0000000..dca8aa4 --- /dev/null +++ b/docs/demo-development-plan.md @@ -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。 diff --git a/docs/deployment-plan.md b/docs/deployment-plan.md index 1c69bfe..df8d693 100644 --- a/docs/deployment-plan.md +++ b/docs/deployment-plan.md @@ -139,7 +139,7 @@ flowchart LR A --> L["LLaMA-Factory"] A --> G["GPU/CUDA"] A --> FS["算力服务器本地磁盘"] - A -- "状态回调/日志摘要" --> B + B -- "定时轮询任务状态/指标/产物索引" --> C ``` ### 5.3 部署边界 @@ -170,8 +170,8 @@ GPU 算力服务器部署： - 协议：内部 HTTPS REST，后续可扩展 gRPC。 - 鉴权：服务间 Token，生产建议 mTLS + IP 白名单。 - 幂等：训练任务提交使用 `Idempotency-Key` 或 `job_id`。 -- 回调：算力平台向应用平台回调任务状态、指标摘要、产物索引。 -- 拉取：应用平台也可以定时轮询 Compute API，避免回调失败导致状态丢失。 +- 状态同步：默认由应用平台定时轮询 Compute API，拉取任务状态、指标摘要和产物索引。 +- 回调策略：第一阶段关闭算力侧回调，避免算力服务器访问应用服务器，减少双向网络策略开通。 文件互通： @@ -196,9 +196,46 @@ GPU 算力服务器部署： ### 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 接入标准 为预留其他训练平台，应用平台只依赖统一算力接口，不直接依赖 LLaMA-Factory 命令。 @@ -241,6 +278,9 @@ LOG_DIR=/opt/yg-ft/logs/backend COMPUTE_API_BASE_URL=https://compute.internal:9100 COMPUTE_SERVICE_TOKEN=*** 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_API_PORT=9100 FILE_GATEWAY_PORT=9101 -APP_CALLBACK_BASE_URL=https://app.internal/api/v1/compute/callbacks -APP_SERVICE_TOKEN=*** +COMPUTE_SERVICE_TOKEN=*** +ENABLE_APP_CALLBACK=false LLAMA_FACTORY_HOME=/opt/LLaMA-Factory +LLAMA_FACTORY_HOST_PATH=/opt/LLaMA-Factory YG_FT_DATA_ROOT=/data/yg-ft LOG_DIR=/opt/yg-ft/logs/compute CUDA_VISIBLE_DEVICES=0,1,2,3 @@ -295,11 +336,74 @@ CUDA_VISIBLE_DEVICES=0,1,2,3 - 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://:9100 +FILE_GATEWAY_BASE_URL=http://: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 标准配置。 -- 数据库和 Redis 是否由企业基础设施统一提供，还是由项目自行部署。 +- PostgreSQL/Redis 开发阶段采用项目自带部署；生产阶段是否切换企业统一基础设施，以及对应 SLA 仍需确认。 - 是否需要 PostgreSQL 主备、备份恢复、审计日志长期归档的明确 SLA。 - 大文件上传是否需要断点续传、限速、病毒扫描或 DLP 检测。 -- 应用服务器与算力服务器之间是否允许双向访问，还是只能应用侧主动访问算力侧。 -- 是否需要未来支持多台 GPU 节点调度；如果需要，Compute API 需要提前设计节点注册和调度策略。 +- 应用服务器与算力服务器默认只开通应用侧主动访问算力侧；如后续需要实时回调，再单独评估双向网络策略。 +- 多算力节点已按单机多 GPU 节点扩展设计；仍需确认是否需要节点组、租户绑定节点、同步限速和资源副本清理审批。 diff --git a/docs/platform-architecture-requirements.md b/docs/platform-architecture-requirements.md index b2591b2..176dbf0 100644 --- a/docs/platform-architecture-requirements.md +++ b/docs/platform-architecture-requirements.md @@ -80,7 +80,7 @@ flowchart LR - 应用平台调用算力平台必须携带 `X-Service-Token` 或 mTLS 证书。 - 算力平台不信任前端用户身份，只信任应用平台下发的租户、项目、任务和资源上下文。 -- 所有任务回调必须带签名，避免伪造状态。 +- 第一阶段不默认启用算力侧回调，应用平台通过定时轮询 Compute API 同步任务状态；如未来启用回调，必须带签名，避免伪造状态。 核心通信接口： @@ -93,7 +93,7 @@ flowchart LR | 应用 -> 算力 | `GET /compute/resources/gpus` | 查询 GPU 状态 | | 应用 -> 算力 | `POST /compute/files/upload` | 上传文件到算力本地磁盘 | | 应用 -> 算力 | `GET /compute/files/{object_id}/download` | 下载文件 | -| 算力 -> 应用 | `POST /api/internal/compute-callbacks/jobs` | 回调任务状态、指标、产物 | +| 应用 -> 算力 | `GET /compute/jobs?status=running` | 定时轮询任务状态、指标、产物索引 | ## 3. 本地磁盘存储设计 @@ -149,6 +149,8 @@ flowchart LR ## 4. 单机多 GPU 资源调度 +第一版可以先以单个算力节点跑通主链路，但数据模型、接口和页面需要按多算力节点预留。多节点阶段仍然采用“每台 GPU 服务器 = 一个单机多 GPU 节点”的模式，不引入 Kubernetes。 + ### 4.1 GPU 资源模型 每张 GPU 需要记录： @@ -183,6 +185,25 @@ flowchart LR - 支持任务队列优先级：`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.1 引擎抽象 @@ -421,6 +442,9 @@ LLaMA-Factory 适配器负责： - 队列中的任务。 - 资源配额：租户/项目/用户维度。 - 算力节点 Agent 状态。 +- 算力节点新增/编辑、连接测试、启用/禁用、维护模式。 +- 节点权重、标签、训练引擎版本、LLaMA-Factory 健康状态。 +- 节点本地资源副本：数据集、模型、checkpoint、adapter 和导出模型缓存。 - 训练引擎健康状态。 ### 8.5 文件与存储管理 @@ -650,6 +674,8 @@ LLaMA-Factory 适配器负责： 10. 是否需要对外提供标准 API 给其他系统调用训练、评测、推理能力？ 11. 是否需要接入企业统一身份认证，例如 LDAP、OIDC、企业微信、钉钉？ 12. 是否需要成本核算：按租户/项目统计 GPU 小时、磁盘占用、模型调用量？ +13. 多算力节点是否需要节点组、租户绑定节点或项目绑定节点策略？ +14. 跨节点资源同步是否需要限速、同步窗口和管理员审批？ ## 13. 推荐决策补充 @@ -658,15 +684,17 @@ LLaMA-Factory 适配器负责： 1. 本地磁盘主存储放在算力服务器，应用服务器只保留上传临时文件。临时文件默认保留 24 小时，成功转发到算力文件网关后可立即进入清理队列。 2. 第一版不支持 MIG、GPU 分片和多任务共享同一张 GPU。一张 GPU 同一时间只分配给一个训练任务或一个推理服务。GPU 数据模型预留 `partition_type`、`parent_gpu_uuid`、`memory_total_mb`，便于后续扩展 MIG。 3. 第一版不做自动抢占。支持任务优先级和排队；停止他人任务需要审批或平台管理员权限。 -4. 第一版必须支持离线导入已有模型和数据集目录。导入由算力 Agent 扫描、校验、登记，并归属指定租户和项目。 -5. 模型发布区分测试服务和生产服务。测试服务项目内可启动并默认限流；生产服务必须审批。 -6. 数据脱敏和数据质量评分作为数据处理模块的一等能力进入第一期，先实现规则版脱敏、格式校验、重复率、完整性、长度分布等指标。 -7. 人工评测/复核作为第二期功能，但第一期需在数据库和页面入口预留人工复核状态与修订字段。 -8. 第一版支持从 checkpoint 手动恢复训练，不做自动失败续训。失败任务可选择 checkpoint 重试。 -9. 第一版必须支持 checkpoint 自动清理策略：默认保留最近 3 个、最优 2 个；已发布模型关联 checkpoint 不自动删除；失败任务 checkpoint 默认保留 14 天。 -10. 第一版提供内部 API，第二期再开放面向其他系统的标准 API、API Key、限流和 Webhook。 -11. 第一版使用本地账号，预留 OIDC/LDAP 字段和认证 provider 抽象；第二期接入企业统一身份认证。 -12. 第一版做 GPU 小时、磁盘占用、任务时长、推理调用量等用量统计；第二期再做成本单价和账单核算。 +4. 多算力节点仍按“单机多 GPU 节点”管理，每个节点独立部署算力服务和 LLaMA-Factory；节点之间不互相访问，由应用平台统一调度和资源同步。 +5. 多节点调度默认自动选择节点，同时支持管理员/高级用户手动指定节点；调度优先考虑节点健康、标签、权重、空闲 GPU、队列长度和资源副本是否已存在。 +6. 第一版必须支持离线导入已有模型和数据集目录。导入由算力 Agent 扫描、校验、登记，并归属指定租户和项目。 +7. 模型发布区分测试服务和生产服务。测试服务项目内可启动并默认限流；生产服务必须审批。 +8. 数据脱敏和数据质量评分作为数据处理模块的一等能力进入第一期，先实现规则版脱敏、格式校验、重复率、完整性、长度分布等指标。 +9. 人工评测/复核作为第二期功能，但第一期需在数据库和页面入口预留人工复核状态与修订字段。 +10. 第一版支持从 checkpoint 手动恢复训练，不做自动失败续训。失败任务可选择 checkpoint 重试。 +11. 第一版必须支持 checkpoint 自动清理策略：默认保留最近 3 个、最优 2 个；已发布模型关联 checkpoint 不自动删除；失败任务 checkpoint 默认保留 14 天。 +12. 第一版提供内部 API，第二期再开放面向其他系统的标准 API、API Key、限流和 Webhook。 +13. 第一版使用本地账号，预留 OIDC/LDAP 字段和认证 provider 抽象；第二期接入企业统一身份认证。 +14. 第一版做 GPU 小时、磁盘占用、任务时长、推理调用量等用量统计；第二期再做成本单价和账单核算。 以上决策需要同步反映在接口文档、数据库 SQL、前端页面和部署方案中。第一版实现不再阻塞于这些问题的反复确认，除非实际部署环境与假设明显冲突。 diff --git a/docs/postgres-schema.sql b/docs/postgres-schema.sql index b9e602b..221a475 100644 --- a/docs/postgres-schema.sql +++ b/docs/postgres-schema.sql @@ -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 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 ( id uuid PRIMARY KEY DEFAULT gen_random_uuid(), tenant_id uuid REFERENCES tenants(id) ON DELETE CASCADE, diff --git a/docs/system-development-plan.md b/docs/system-development-plan.md index 27d675e..a25f91e 100644 --- a/docs/system-development-plan.md +++ b/docs/system-development-plan.md @@ -156,7 +156,7 @@ - API Key 管理。 - OpenAPI 文档。 - 请求限流。 -- Webhook 回调。 +- Webhook 回调作为外部系统集成的可选能力，不作为算力状态同步默认方案。 - 外部系统发起训练、评测、推理。 ### 1.11 企业统一身份认证 @@ -487,6 +487,9 @@ YG_FT/ - 任务队列。 - Agent 健康状态。 - 租户/项目配额。 +- 算力节点新增、编辑、连接测试、启用、禁用、维护模式。 +- 节点权重、标签、训练引擎版本和本地资源副本。 +- 自动调度和手动指定节点入口。 联调接口： @@ -567,16 +570,27 @@ YG_FT/ 开发内容： - 算力平台客户端。 +- 算力节点管理：地址、File Gateway、权重、标签、启用状态、维护状态。 +- 自动/手动调度策略。 +- 调度前检查模型/数据集在目标节点的资源副本。 +- 缺失资源时创建同步任务，通过目标节点 File Gateway 写入本地磁盘。 - 创建 compute job。 - 查询状态和日志。 -- 状态回调验签。 +- 应用侧定时轮询 Compute API，同步任务状态、日志摘要和产物索引。 - 任务状态映射。 交付接口： - `GET /api/compute/gpus` - `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 模块 @@ -660,7 +674,9 @@ YG_FT/ - 校验服务 token。 - 调用 Agent。 - 聚合状态。 -- 回调应用平台。 +- 提供任务状态查询接口，供应用平台定时轮询。 +- 每个单机多 GPU 算力节点都部署一套 Compute API，不依赖其他算力节点。 +- 暴露节点健康、GPU、训练引擎、资源副本和文件网关状态。 ### 7.2 Compute Agent @@ -735,9 +751,12 @@ YG_FT/ | `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` | 清理任务 | @@ -782,12 +801,14 @@ YG_FT/ - `file-gateway` - `llama-factory-env` +多算力节点阶段，每台单机多 GPU 服务器都部署以上组件和宿主机挂载的 LLaMA-Factory。算力节点之间默认不互相访问，由应用平台统一调度和同步资源。 + 配置： - `COMPUTE_NODE_ID` - `SERVICE_TOKEN` -- `APP_CALLBACK_URL` -- `DATA_ROOT=/data/ft-platform` +- `ENABLE_APP_CALLBACK=false` +- `DATA_ROOT=/data/yg-ft` - `LLAMA_FACTORY_PATH` - `PYTHON_ENV_PATH` - `GPU_VISIBLE_DEVICES` @@ -798,7 +819,7 @@ YG_FT/ - 前端只访问应用平台。 - 应用平台可访问算力平台内部 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-C：File Gateway、本地磁盘、离线导入。 +- CE-C：File Gateway、本地磁盘、离线导入、资源副本同步。 ### 数据库/部署组 @@ -954,7 +975,8 @@ YG_FT/ | --- | --- | --- | | M1 基础治理 | 第 1-2 周 | 登录、用户、租户、项目、权限 | | M2 资源管理 | 第 3-4 周 | 模型、数据集、文件网关、离线导入 | -| M3 训练主链路 | 第 5-7 周 | GPU 调度、LLaMA-Factory 训练、日志指标、产物 | +| M3 训练主链路 | 第 5-7 周 | GPU 调度、LLaMA-Factory 训练、日志指标、产物、资源副本检查 | +| M3.5 多节点预留 | 第 7-8 周 | compute_nodes 管理、节点权重/标签、自动/手动调度、资源同步任务 | | M4 数据处理和评测 | 第 8-9 周 | 数据处理、质量评分、自动评测 | | M5 推理发布 | 第 10-11 周 | 推理服务、模型对比、生产发布审批 | | 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` | 用户、项目 | | 审批模板 | `/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` | 文件网关 | | 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | 筛选、详情、导出 | `GET /api/audit-logs`、`GET /api/login-logs`、`GET /api/download-logs` | `audit_logs`、`login_sessions` | 审计中间件 |