13 KiB
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 参数校验、命令生成和日志解析基础能力。- 企业治理与基础能力：登录鉴权（
/modelTF/login、/modelTF/me）；用户中心（列表/创建/启停、重置密码POST /modelTF/users/{id}/reset-password，保护账号不可重置、空密码回退platform123）；租户与配额、留存策略（嵌套于/modelTF/tenants/{id}/retention-policy）；项目空间与成员/角色，/modelTF/projects/{id}/archive受待审批变更拦截（409）；资源授权GET/PUT /modelTF/resources/{type}/{id}/acl；审批中心（待办/历史/模板）/modelTF/approvals/*、/modelTF/approval-templates/*；审计中心GET /modelTF/system/audit-logs及导出；平台性能/modelTF/system-info、/modelTF/compute/gpus；日志查看/modelTF/log-files、/modelTF/log-content、/modelTF/training-log-*；服务看板聚合/modelTF/dashboard/stats。
企业治理模块完成状态
范围：平台基础与企业治理（用户中心、多租户、项目隔离、审批、审计、资源授权、看板）。
| 模块 | 路由 | 后端接口 | 状态 |
|---|---|---|---|
| 登录 | /login |
POST /modelTF/login、GET /modelTF/me |
✅ 已完成 |
| 用户设置 | /user-settings 等 |
/modelTF/users（CRUD）、/modelTF/users/{id}/reset-password、页面权限 |
⚠️ 重置密码已完成；页面权限精细控制 UI 待补全 |
| 平台性能 | /hardware |
/modelTF/system-info、/modelTF/compute/gpus |
✅ 已完成 |
| 查看日志 | /logs、/training-log/:id |
/modelTF/log-files、/modelTF/log-content、/modelTF/training-log-* |
✅ 已完成 |
| 租户管理 | /tenants、/tenants/:id |
/modelTF/tenants/*、配额、留存（嵌套） |
✅ 已完成（留存为嵌套式，未独立成资源） |
| 项目空间 | /projects、/projects/:id |
/modelTF/projects/*、成员、角色、归档拦截 |
✅ 已完成 |
| 资源授权 | 弹窗 | GET/PUT /modelTF/resources/{type}/{id}/acl |
✅ 已完成 |
| 审批中心 | /approvals、/approvals/templates |
/modelTF/approvals/*、/modelTF/approval-templates/* |
✅ 已完成 |
| 审计中心 | /audit-logs |
GET /modelTF/system/audit-logs、导出 |
✅ 已完成（接口挂在 system 下） |
| 服务看板 | /dashboard |
GET /modelTF/dashboard/stats |
✅ 已完成 |
说明：
audit、retention模块当前未拆为独立 REST 路由——审计接口挂在system下、留存策略嵌套于租户资源；用户「页面权限」精细控制 UI 仍为占位，待后续版本补齐。数据层当前为内存/本地存储实现，生产环境按docs/postgres-schema.sql迁移 PostgreSQL。
首次环境准备（新人 / 新机器）
后端与算力服务都运行在 WSL2 中（Windows 原生 Python / anaconda 依赖不兼容）。第一次拉代码、机器上没有任何环境时，按下面顺序一次性准备好；日常启动见下方「后端启动」「算力服务启动」。
1. 基础运行时
- WSL2：Windows 终端执行
wsl --install（默认 Ubuntu），重启生效。 - Python ≥ 3.9（推荐 3.12），在 WSL 内确认：
版本过低或未安装：
python3 --versionsudo apt update && sudo apt install -y python3.12 python3.12-venv python3-pip。 - Node.js 18+：前端在 Windows 终端安装并运行（不要放进 WSL，否则热更新跨
/mnt文件系统很慢）。
2. 数据库 PostgreSQL（首次需自建）
后端默认连接 postgresql+psycopg://yg_ft:change_me@localhost:15432/yg_ft。首次没有数据库时，推荐用 Docker 一键起：
docker run -d --name yg_ft_pg -p 15432:5432 \
-e POSTGRES_USER=yg_ft -e POSTGRES_PASSWORD=change_me -e POSTGRES_DB=yg_ft \
postgres:16
无 Docker 时，可在 WSL 内 sudo apt install -y postgresql 后手动建库与用户。后端首次启动会自动建表并写入内置管理员账号（详见「后端启动」）。
3. 后端 / 算力 venv 首次创建
后端与算力各有独立 venv，首次需在 WSL 中创建并安装依赖（完整命令见下方启动小节）：
- 后端：
cd /home/wang/yg_ft/backend && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt - 算力：
cd /home/wang/yg_ft && source compute/.venv/bin/activate && pip install -r compute/requirements.txt（compute 使用绝对导入compute.*，须在仓库根目录操作）
4. 前端首次安装
在 Windows 终端：
cd \\wsl.localhost\Ubuntu\home\wang\yg_ft\frontend
npm install
npm run dev
后端启动
后端需在 WSL 终端 中启动：Windows 的 anaconda 环境依赖不兼容，且项目 venv 为 Linux 版（使用
bin/activate而非Scripts）。若.wslconfig使用networkingMode=mirrored，uvicorn 必须绑定--host 0.0.0.0才能被 Windows 侧localhost访问。
# 在 WSL 终端中执行
cd /home/wang/yg_ft/backend
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 17861 --reload
默认接口前缀为 /modelTF，例如：
GET /modelTF/health
POST /modelTF/login
GET /modelTF/model-manage
GET /modelTF/dataset-manage
GET /modelTF/fine-tune
GET /modelTF/compute/nodes
本地运行时默认 PostgreSQL 连接：
DATABASE_URL=postgresql+psycopg://yg_ft:change_me@localhost:15432/yg_ft
本地启动前需要确保 PostgreSQL 已监听 localhost:15432，并已创建 yg_ft 数据库和 yg_ft 用户。后端启动后会自动创建当前运行表并写入内置管理员账号，运行数据统一写入 PostgreSQL。
开发阶段内置登录账号：
| 角色 | 账号 | 密码 | 说明 |
|---|---|---|---|
| 超级管理员 | admin |
admin123 |
拥有当前全部页面权限 |
| 操作员 | operator |
operator123 |
拥有业务操作相关页面权限 |
以上账号仅用于本地开发和联调。生产环境初始化后应立即修改密码，或改为企业统一身份认证/管理员初始化流程。
前端启动
cd frontend
npm install
npm run dev
前端开发服务默认运行在 http://localhost:16801，并通过 Vite proxy 将 /modelTF 转发到 http://localhost:17861。
算力服务启动
算力服务同样需在 WSL 终端 中启动，且拥有独立虚拟环境（不复用后端 venv）。代码使用绝对导入
compute.*，因此必须从**仓库根目录（/home/wang/yg_ft）**执行，不能先cd compute再启动（否则报No module named 'compute'）。若.wslconfig使用networkingMode=mirrored，uvicorn 需绑定--host 0.0.0.0才能被 Windows 侧localhost访问。
# 在 WSL 终端中执行（必须位于仓库根目录 yg_ft/）
cd /home/wang/yg_ft
source compute/.venv/bin/activate
uvicorn compute.api.main:app --host 0.0.0.0 --port 19100 --reload
默认 COMPUTE_MODE=real。真实 GPU 接入时，在每台算力服务器上部署 Compute API、Agent、File Gateway 和 LLaMA-Factory，应用平台通过 compute_nodes.api_base_url 和 compute_nodes.file_gateway_url 主动轮询。仅在隔离联调环境可显式设置 COMPUTE_MODE=simulator 或 COMPUTE_EXECUTION_MODE=simulator。
日志
后端日志模块位于 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/下的标准接口，不在应用平台后端直接拼接训练命令。 - 敏感信息不得写入日志，生产环境密钥通过环境变量或密钥管理系统注入。