5f6e7523cf
- 支持从 PostgreSQL 数据库拉取结构化数据作为训练来源 - 新增 DPO (Direct Preference Optimization) 输出类型 - 支持 chosen/rejected 字段的编辑、校验和发布 - 完善数据预处理切分逻辑和元数据管理 - 移除 OCR 扫描 PDF 功能，保持基础文本解析能力 Co-Authored-By: Claude <noreply@anthropic.com>
280 lines
11 KiB
Markdown
280 lines
11 KiB
Markdown
# YG_FT 模型微调平台
|
||
|
||
YG_FT 是一个面向企业治理场景的模型微调平台，覆盖用户中心、多租户、项目隔离、数据集管理、模型管理、训练任务、评测、推理、审批流、审计留存、算力调度和训练引擎适配。
|
||
|
||
当前前端已有基础页面，后端与算力平台已按多人协作开发方式建立工程骨架，并开始实现正式系统主链路能力。当前代码和 SQL 均作为后续生产演进基线维护，不再以一次性演示或静态 Mock 为开发准则。
|
||
|
||
## 总体架构
|
||
|
||
```text
|
||
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
|
||
bash ./start.sh
|
||
```
|
||
|
||
脚本会自动补装后端 `requirements.txt`，然后同时启动前端 `http://localhost:16801` 和后端
|
||
`http://127.0.0.1:17861`，按 `Ctrl+C` 会同时停止两个服务。脚本不会自动安装
|
||
前端依赖，也不会启动 PostgreSQL、Redis 或算力服务。
|
||
|
||
仅检查依赖和端口而不启动服务：
|
||
|
||
```bash
|
||
bash ./start.sh --check
|
||
```
|
||
|
||
本地启动推荐只配置数据库主机。脚本会复用 `docker/app/.env` 中已有的
|
||
`POSTGRES_USER`、`POSTGRES_PASSWORD` 和 `POSTGRES_DB`，端口默认使用
|
||
PostgreSQL 标准端口 `5432`：
|
||
|
||
```bash
|
||
DATABASE_HOST='www.caoxiaozhu.com' bash ./start.sh
|
||
```
|
||
|
||
也可以在 `docker/app/.env` 中增加：
|
||
|
||
```env
|
||
DATABASE_HOST=www.caoxiaozhu.com
|
||
```
|
||
|
||
需要使用非标准端口时再设置 `DATABASE_PORT`。`DATABASE_URL` 仍可作为完整连接串
|
||
高级覆盖项；终端环境变量优先级最高。脚本不会输出数据库密码。
|
||
|
||
## 后端启动
|
||
|
||
```bash
|
||
cd backend
|
||
python -m venv .venv
|
||
.venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
uvicorn app.main:app --reload --port 17861
|
||
```
|
||
|
||
默认接口前缀为 `/modelTF`，例如：
|
||
|
||
```text
|
||
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`）：
|
||
|
||
```env
|
||
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 的超时秒数 |
|
||
|
||
### 推荐启动命令（远程数据库）
|
||
|
||
```cmd
|
||
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` | 拥有业务操作相关页面权限 |
|
||
|
||
以上账号仅用于本地开发和联调。生产环境初始化后应立即修改密码，或改为企业统一身份认证/管理员初始化流程。
|
||
|
||
## 前端启动
|
||
|
||
```bash
|
||
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. 构建镜像**（首次或依赖变更后）：
|
||
|
||
```cmd
|
||
cd /d E:\yg_ft
|
||
docker build -f docker/compute/Dockerfile.compute -t yg-ft-compute-api:latest .
|
||
```
|
||
|
||
**2. 启动容器**：
|
||
|
||
```cmd
|
||
cd docker/compute
|
||
cp .env.example .env
|
||
docker compose up -d
|
||
```
|
||
|
||
**3. 验证**：
|
||
|
||
```cmd
|
||
curl http://localhost:19100/health
|
||
```
|
||
|
||
> 注意：构建上下文必须是项目根目录 `E:\yg_ft`（`docker build` 最后的 `.`），因为 Dockerfile 需要 `COPY compute/requirements.txt`。
|
||
|
||
### 方式二：本地开发启动
|
||
|
||
**Windows (cmd)：**
|
||
|
||
```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：**
|
||
|
||
```bash
|
||
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`
|
||
|
||
默认输出：
|
||
|
||
```text
|
||
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 部署入口
|
||
|
||
应用服务器：
|
||
|
||
```bash
|
||
cd docker/app
|
||
cp .env.example .env
|
||
docker compose up -d
|
||
```
|
||
|
||
算力服务器：
|
||
|
||
```bash
|
||
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/` 下的标准接口，不在应用平台后端直接拼接训练命令。
|
||
- 敏感信息不得写入日志，生产环境密钥通过环境变量或密钥管理系统注入。
|