YG_FT 模型微调平台

YG_FT 是一个面向企业治理场景的模型微调平台，覆盖用户中心、多租户、项目隔离、数据集管理、模型管理、训练任务、评测、推理、审批流、审计留存、算力调度和训练引擎适配。

当前前端已有基础页面，后端与算力平台已按多人协作开发方式建立工程骨架，并开始实现正式系统主链路能力。当前代码和 SQL 均作为后续生产演进基线维护，不再以一次性演示或静态 Mock 为开发准则。

总体架构

YG_FT/
  frontend/                 # 前端控制台
  backend/                  # FastAPI 应用平台后端
    app/
      api/v1/               # 对前端暴露的 REST API
      core/                 # 配置、日志、中间件、权限等基础能力
      db/                   # 数据库连接、迁移、事务工具
      modules/              # 业务模块目录
      schemas/              # Pydantic 入参/出参模型
      services/             # 跨模块应用服务
      workers/              # 后台任务入口
    requirements.txt        # 后端 Python 第三方依赖
  compute/                  # 算力平台与训练框架适配层
    api/                    # 内部 Compute API
    agent/                  # 单机多 GPU 调度与进程管理
    engines/llama_factory/  # LLaMA-Factory 适配器
    file_gateway/           # 本地文件上传、下载、导入、产物管理
  docs/                     # 需求、接口、数据库、开发计划和部署文档
  docker/                   # 容器化配置

平台分层

层级	职责	主要目录
前端控制台	用户操作入口、任务看板、项目/模型/数据集/训练/审批/审计页面	frontend/
应用平台后端	用户中心、多租户、RBAC/ABAC、项目隔离、元数据、审批流、审计、API 编排	backend/
算力平台	GPU 发现、资源锁定、训练进程管理、日志采集、产物归档、任务状态同步	compute/
训练引擎	当前固定接入 LLaMA-Factory，预留其他训练平台适配标准	compute/engines/
数据层	PostgreSQL、Redis、本地文件存储、日志归档	docs/postgres-schema.sql

当前开发基线

• 使用 FastAPI 提供统一 API 响应结构 { code, message, data }。
• 本地运行阶段统一使用 PostgreSQL，后端启动时会在 PG 中初始化当前运行表和系统内置账号；模型、数据集、算力节点、GPU、微调任务等业务数据必须通过页面、接口或正式导入流程产生。
• 支持登录、模型管理、数据集管理、微调任务创建/启动/停止/进度轮询。
• 支持训练日志、loss 指标、checkpoint 和训练产物接口；真实训练执行器接入前，联调状态机必须通过显式环境变量开启。
• 支持多算力节点、GPU、任务队列、资源副本和资源同步状态接口。
• 前端新增 /compute 算力节点页面，展示节点地址、权重、标签、启用状态、GPU、队列和资源副本。
• compute/engines/llama_factory/adapter.py 提供 LLaMA-Factory 参数校验、命令生成和日志解析基础能力。

前后端一键启动

首次使用前请确保前端依赖已安装、PostgreSQL 已可用。之后在项目根目录执行：

bash ./start.sh

脚本会自动补装后端 requirements.txt，然后同时启动前端 http://localhost:16801 和后端 http://127.0.0.1:17861，按 Ctrl+C 会同时停止两个服务。脚本不会自动安装 前端依赖，也不会启动 PostgreSQL、Redis 或算力服务。

仅检查依赖和端口而不启动服务：

bash ./start.sh --check

本地启动推荐只配置数据库主机。脚本会复用 docker/app/.env 中已有的 POSTGRES_USER、POSTGRES_PASSWORD 和 POSTGRES_DB，端口默认使用 PostgreSQL 标准端口 5432：

DATABASE_HOST='www.caoxiaozhu.com' bash ./start.sh

也可以在 docker/app/.env 中增加：

DATABASE_HOST=www.caoxiaozhu.com

需要使用非标准端口时再设置 DATABASE_PORT。DATABASE_URL 仍可作为完整连接串 高级覆盖项；终端环境变量优先级最高。脚本不会输出数据库密码。

后端启动

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 17861

默认接口前缀为 /modelTF，例如：

GET /modelTF/health
POST /modelTF/login
GET /modelTF/model-manage
GET /modelTF/dataset-manage
GET /modelTF/fine-tune
GET /modelTF/compute/nodes
GET /modelTF/data-convert

数据库配置

后端通过 backend/.env 文件配置数据库连接（自动加载，override=True）：

DATABASE_URL=postgresql+psycopg://用户:密码@数据库地址:端口/库名
COMPUTE_SERVICE_TOKEN=change_me

支持远程数据库。连接池参数已针对远程库优化（connect_timeout=30、max_size=20、max_waiting=50）。

环境变量

变量	默认值	说明
DATABASE_URL	postgresql+psycopg://yg_ft:change_me@localhost:15432/yg_ft	数据库连接串
COMPUTE_SERVICE_TOKEN	""	算力服务认证 token，需与 compute 一致
COMPUTE_STATUS_SYNC_MODE	polling	off 禁用轮询（远程库慢时推荐）
COMPUTE_POLL_INTERVAL_SECONDS	3	轮询间隔秒数
COMPUTE_REQUEST_TIMEOUT_SECONDS	5	调 compute 的超时秒数

推荐启动命令（远程数据库）

cd /d E:\yg_ft\backend
set COMPUTE_STATUS_SYNC_MODE=off
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 17861

开发阶段内置登录账号：

角色	账号	密码	说明
超级管理员	admin	admin123	拥有当前全部页面权限
操作员	operator	operator123	拥有业务操作相关页面权限

以上账号仅用于本地开发和联调。生产环境初始化后应立即修改密码，或改为企业统一身份认证/管理员初始化流程。

前端启动

cd frontend
npm install
npm run dev

前端开发服务默认运行在 http://localhost:16801，并通过 Vite proxy 将 /modelTF 转发到 http://localhost:17861。

算力服务启动

算力服务是一个 FastAPI 应用，同时承载 Compute API（模型训练/推理/GPU 管理）和 File Gateway（文件上传下载）路由。Docker 部署时对外暴露两个端口（19100 和 19101）均指向同一服务，方便应用平台分别配置 api_base_url 和 file_gateway_url。本地开发只需启动一个进程。

方式一：Docker 启动（推荐）

1. 构建镜像（首次或依赖变更后）：

cd /d E:\yg_ft
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .

2. 启动容器：

cd docker/compute
cp .env.example .env
docker compose up -d

3. 验证：

curl http://localhost:19100/health

注意：构建上下文必须是项目根目录 E:\yg_ft（docker build 最后的 .），因为 Dockerfile 需要 COPY compute/requirements.txt。

方式二：本地开发启动

Windows (cmd)：

cd /d E:\yg_ft\compute
set PYTHONPATH=E:\yg_ft
.\.venv\Scripts\python.exe -m uvicorn api.main:app --reload --host 0.0.0.0 --port 19100

PYTHONPATH=E:\yg_ft 是必需的，因为代码使用 from compute.agent... 绝对导入。 --host 0.0.0.0 让其他机器可以通过 IP 访问（算力节点测试需要）。

Linux / macOS：

cd compute
PYTHONPATH=.. uvicorn api.main:app --reload --host 0.0.0.0 --port 19100

算力节点配置

在平台的「算力节点」页面新增节点，填入：

• Compute API：http://你的IP:19100
• File Gateway：http://你的IP:19101

本机测试用 http://localhost:19100。

环境变量说明

变量	默认值	说明
COMPUTE_MODE	real	real / simulator，仅隔离联调用 simulator
COMPUTE_EXECUTION_MODE	real	训练执行模式
COMPUTE_SERVICE_TOKEN	change_me	服务间认证 token，需与 backend 一致
COMPUTE_AUTH_ENABLED	true	是否开启 token 认证
MODELTF_ROUTE_PREFIX	/modelTF	API 路由前缀

应用平台通过数据库 compute_nodes 表中的 api_base_url 和 file_gateway_url 主动轮询算力节点状态。

日志

后端日志模块位于 backend/app/core/logging.py，说明文档见：

• docs/backend-logging.md

默认输出：

logs/backend-YYYY-MM-DD.log
logs/error-YYYY-MM-DD.log

日志格式为 JSON Lines，单个文件不超过 20MB，只保留最近 10 天。

主要文档

• docs/platform-architecture-requirements.md：平台需求、功能模块、页面补全建议。
• docs/menu-functional-requirements.md：当前菜单、二级路由、规划菜单、功能需求、接口和数据库映射。
• docs/backend-api-design.md：FastAPI 接口分组、参数定义、权限说明。
• docs/postgres-schema.sql：PostgreSQL 数据库脚本，包含权限、用户中心、多租户、审批、审计等模型。
• docs/system-development-plan.md：多人协作开发计划，按前端、后端、DB、部署拆分。
• docs/team-development-plan.md：3-4 人并行开发分工计划，按人员边界标注页面、接口、数据库和交付节奏。
• docs/first-version-development-plan.md：当前系统主链路开发计划，覆盖前端、后端、DB、Compute API、GPU 和 LLaMA-Factory 适配。
• docs/backend-logging.md：后端日志模块使用说明。
• docs/deployment-plan.md：后期部署方案，覆盖单机算力服务器部署与应用/算力分离部署。
• docker/README.md：Docker 部署入口，包含应用服务器和算力服务器两套 Compose 使用方式。

Docker 部署入口

应用服务器：

cd docker/app
cp .env.example .env
docker compose up -d

算力服务器：

cd docker/compute
cp .env.example .env
docker compose up -d

两套 Compose 均采用代码外挂方式运行，镜像只包含运行时环境和第三方依赖。项目根目录不再保留 Dockerfile 和 docker-compose.yml，部署时统一进入 docker/app 或 docker/compute 目录执行。

后续开发原则

• 接口实现优先遵循 docs/backend-api-design.md。
• 数据库实现优先遵循 docs/postgres-schema.sql，后续通过 Alembic 迁移管理变更。
• 前端页面与后端接口、数据库表之间的映射以文档中的“对应页面/功能模块”为准。
• 训练引擎适配必须通过 compute/engines/ 下的标准接口，不在应用平台后端直接拼接训练命令。
• 敏感信息不得写入日志，生产环境密钥通过环境变量或密钥管理系统注入。