feat: 添加后端架构、计算模块及部署文档
This commit is contained in:
wuyongtao
109
docs/backend-logging.md
Normal file
109
docs/backend-logging.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# 后端日志模块说明
|
||||
|
||||
本文档对应页面/功能模块：全平台通用能力、系统设置、审计中心、任务详情、训练任务日志、运维监控。
|
||||
|
||||
## 设计目标
|
||||
|
||||
- 后端服务统一使用 `backend/app/core/logging.py` 初始化日志。
|
||||
- 日志文件按日期命名，单个文件超过 20MB 自动滚动。
|
||||
- 日志只保留最近 10 天，过期文件自动清理。
|
||||
- 业务日志使用 JSON Lines 格式，便于 Filebeat、Vector、Logstash、ELK、OpenSearch 等日志平台采集。
|
||||
- `ERROR` 及以上日志独立写入错误日志文件，便于告警与问题定位。
|
||||
- 日志字段必须包含代码文件、行号、函数、日志内容、请求 ID、进程和线程信息。
|
||||
|
||||
## 文件命名
|
||||
|
||||
默认日志目录由 `LOG_DIR` 控制，本地默认是 `./logs`。
|
||||
|
||||
```text
|
||||
logs/
|
||||
backend-2026-07-16.log # INFO/ERROR 等全部应用日志，JSON Lines
|
||||
backend-2026-07-16.1.log # 当天主日志超过 20MB 后滚动产生
|
||||
error-2026-07-16.log # ERROR/CRITICAL 错误日志，JSON Lines
|
||||
error-2026-07-16.1.log # 当天错误日志超过 20MB 后滚动产生
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
```env
|
||||
LOG_LEVEL=INFO
|
||||
LOG_DIR=./logs
|
||||
LOG_FILE_PREFIX=backend
|
||||
LOG_ERROR_FILE_PREFIX=error
|
||||
LOG_MAX_BYTES=20971520
|
||||
LOG_RETENTION_DAYS=10
|
||||
```
|
||||
|
||||
## JSON 字段
|
||||
|
||||
每一行都是一个完整 JSON 对象。
|
||||
|
||||
```json
|
||||
{
|
||||
"@timestamp": "2026-07-16T13:20:10.123",
|
||||
"level": "INFO",
|
||||
"logger": "app.access",
|
||||
"message": "request completed method=GET path=/api/v1/health status_code=200 duration_ms=3.12 client=127.0.0.1",
|
||||
"module": "logging",
|
||||
"function": "request_logging_middleware",
|
||||
"file": "D:\\AI\\codex-code\\YG_FT\\backend\\app\\core\\logging.py",
|
||||
"line": 169,
|
||||
"process": 1234,
|
||||
"thread": 5678,
|
||||
"thread_name": "MainThread",
|
||||
"request_id": "6f9d1c3c-8be0-4c8d-a5b2-18f9d41f9a0c"
|
||||
}
|
||||
```
|
||||
|
||||
异常日志会额外包含：
|
||||
|
||||
```json
|
||||
{
|
||||
"exception": "Traceback ..."
|
||||
}
|
||||
```
|
||||
|
||||
## 使用方式
|
||||
|
||||
业务代码中不要直接 `print`，统一使用：
|
||||
|
||||
```python
|
||||
from app.core.logging import get_logger
|
||||
|
||||
logger = get_logger(__name__)
|
||||
|
||||
logger.info("dataset uploaded dataset_id=%s", dataset_id)
|
||||
logger.warning("gpu queue is busy project_id=%s", project_id)
|
||||
logger.exception("training job failed job_id=%s", job_id)
|
||||
```
|
||||
|
||||
`logger.exception(...)` 只能在 `except` 代码块中使用，它会自动写入堆栈信息，并同时进入主日志和错误日志。
|
||||
|
||||
## FastAPI 接入
|
||||
|
||||
应用入口 `backend/app/main.py` 已完成接入：
|
||||
|
||||
```python
|
||||
settings = get_settings()
|
||||
configure_logging(settings)
|
||||
setup_request_logging(app)
|
||||
```
|
||||
|
||||
请求日志会自动生成或透传 `X-Request-ID`，并在响应头中返回同一个请求 ID，方便前端、后端、算力服务、日志平台串联排障。
|
||||
|
||||
## ELK/日志平台采集建议
|
||||
|
||||
- 采集路径：`/app/logs/*.log` 或生产环境挂载后的日志目录。
|
||||
- 解析方式：按行读取，每行作为 JSON 文档解析。
|
||||
- 索引建议：
|
||||
- 主日志：`yg-ft-backend-*`
|
||||
- 错误日志：`yg-ft-backend-error-*`
|
||||
- 推荐保留字段：`@timestamp`、`level`、`logger`、`message`、`file`、`line`、`function`、`request_id`、`tenant_id`、`project_id`、`job_id`。
|
||||
- 业务开发后续应在关键模块日志中补充 `tenant_id`、`project_id`、`job_id` 等上下文字段，便于企业审计和问题定位。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 当前日志落本地磁盘，生产环境建议把日志目录挂载到独立数据盘。
|
||||
- 日志文件保留 10 天是应用侧兜底策略，企业侧长期留存应由 ELK、对象存储或归档服务承担。
|
||||
- 敏感字段如 token、密码、密钥、原始用户数据内容不得写入日志。
|
||||
- 算力节点和应用节点分开部署时，建议两侧都采用 JSON Lines 格式，并使用统一 `request_id/job_id` 贯穿链路。
|
||||
305
docs/deployment-plan.md
Normal file
305
docs/deployment-plan.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 模型微调平台后期部署方案
|
||||
|
||||
本文档对应页面/功能模块：系统设置、算力资源、训练任务、任务详情、模型管理、数据集管理、审批中心、审计中心、运维监控。
|
||||
|
||||
## 1. 部署目标
|
||||
|
||||
平台需要支持单机多 GPU 训练、本地磁盘文件存储、LLaMA-Factory 训练框架，并预留未来接入其他训练平台的能力。部署设计需要把“应用平台”和“算力平台”边界明确拆开：
|
||||
|
||||
- 应用平台：面向用户、权限、项目、模型、数据集、审批、审计、任务编排和 API。
|
||||
- 算力平台：面向 GPU、训练进程、训练框架、本地工作目录、训练日志和产物。
|
||||
- 训练框架：当前固定 LLaMA-Factory，后续通过 Engine Adapter 标准接入其他框架。
|
||||
|
||||
结论：算力平台和训练框架应该部署在 GPU 算力服务器上。原因是训练框架需要直接访问 GPU、CUDA、驱动、模型权重、本地数据集切片、训练工作目录和训练进程。应用平台可以与算力平台同机部署，也可以独立部署，但不建议在无 GPU 的应用服务器上直接运行 LLaMA-Factory。
|
||||
|
||||
## 2. 服务清单
|
||||
|
||||
| 服务 | 部署位置 | 职责 |
|
||||
| --- | --- | --- |
|
||||
| Nginx | 应用服务器或算力服务器 | 前端静态资源、反向代理、TLS 终止 |
|
||||
| Frontend | Nginx 静态目录 | 平台控制台 |
|
||||
| Backend API | 应用服务器 | FastAPI 接口、鉴权、元数据、审批、审计、任务编排 |
|
||||
| Backend Worker | 应用服务器 | 异步任务、状态同步、通知、审计归档 |
|
||||
| PostgreSQL | 应用服务器或独立数据库服务器 | 业务元数据、权限、审批、审计 |
|
||||
| Redis | 应用服务器或独立缓存服务器 | 队列、锁、短期状态、幂等控制 |
|
||||
| Compute API | GPU 算力服务器 | 只对应用平台开放的内部算力接口 |
|
||||
| Compute Agent | GPU 算力服务器 | GPU 发现、资源锁定、训练进程管理 |
|
||||
| File Gateway | GPU 算力服务器 | 本地文件上传、下载、离线导入、产物访问 |
|
||||
| LLaMA-Factory | GPU 算力服务器 | 实际训练、评测、合并、导出 |
|
||||
| 日志采集 Agent | 两侧服务器 | 采集应用日志、训练日志、系统日志 |
|
||||
|
||||
## 3. 目录与存储规划
|
||||
|
||||
建议生产环境把文件、日志、数据库数据分盘挂载：
|
||||
|
||||
```text
|
||||
/opt/yg-ft/
|
||||
app/ # 应用服务代码
|
||||
compute/ # 算力服务代码
|
||||
config/ # 环境配置和服务配置
|
||||
logs/
|
||||
backend/ # 后端 JSON Lines 日志
|
||||
compute/ # 算力服务日志
|
||||
training/ # 训练过程日志
|
||||
data/
|
||||
datasets/ # 数据集文件
|
||||
models/ # 基座模型、微调模型、导出模型
|
||||
jobs/ # 训练任务工作目录
|
||||
artifacts/ # 评测报告、adapter、checkpoint、导出包
|
||||
```
|
||||
|
||||
本地文件存储建议按租户、项目、资源类型分区：
|
||||
|
||||
```text
|
||||
/data/yg-ft/
|
||||
tenants/{tenant_id}/
|
||||
projects/{project_id}/
|
||||
datasets/{dataset_id}/
|
||||
models/{model_id}/
|
||||
jobs/{job_id}/
|
||||
```
|
||||
|
||||
## 4. 方案一：所有服务部署在算力服务器
|
||||
|
||||
### 4.1 适用场景
|
||||
|
||||
- PoC、试点环境、演示环境。
|
||||
- 小团队共用一台单机多 GPU 服务器。
|
||||
- 网络隔离要求不高，部署资源有限。
|
||||
|
||||
### 4.2 拓扑
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U["用户浏览器"] --> N["Nginx/Frontend"]
|
||||
N --> B["Backend API"]
|
||||
B --> DB["PostgreSQL"]
|
||||
B --> R["Redis"]
|
||||
B --> C["Compute API"]
|
||||
C --> A["Compute Agent"]
|
||||
A --> L["LLaMA-Factory"]
|
||||
A --> G["GPU/CUDA"]
|
||||
A --> FS["本地磁盘文件存储"]
|
||||
```
|
||||
|
||||
### 4.3 部署方式
|
||||
|
||||
同一台 GPU 服务器部署：
|
||||
|
||||
- `frontend` 构建后由 Nginx 托管。
|
||||
- `backend-api` 使用 Uvicorn/Gunicorn 或容器运行。
|
||||
- `backend-worker` 独立进程运行。
|
||||
- `postgres` 和 `redis` 可使用 Docker Compose 或系统服务。
|
||||
- `compute-api`、`compute-agent`、`file-gateway` 与 LLaMA-Factory 在同机运行。
|
||||
- 训练产物、数据集、模型和日志都放在本地数据盘。
|
||||
|
||||
### 4.4 优点
|
||||
|
||||
- 部署简单，路径共享容易。
|
||||
- 上传数据、训练读取、产物归档都在本机完成，I/O 链路短。
|
||||
- 适合快速验证平台功能。
|
||||
|
||||
### 4.5 风险
|
||||
|
||||
- 应用服务、数据库、训练任务抢占同一台服务器资源。
|
||||
- GPU 训练高负载可能影响 API 响应。
|
||||
- 数据库与文件存储容灾能力弱。
|
||||
- 安全边界不清晰，企业生产不推荐长期使用。
|
||||
|
||||
### 4.6 端口建议
|
||||
|
||||
| 服务 | 端口 | 暴露范围 |
|
||||
| --- | --- | --- |
|
||||
| Nginx | 80/443 | 用户网段 |
|
||||
| Backend API | 8000 | 仅 Nginx、本机 |
|
||||
| Compute API | 9100 | 仅 Backend API、本机 |
|
||||
| File Gateway | 9101 | 仅 Backend API、本机 |
|
||||
| PostgreSQL | 5432 | 本机或内网 |
|
||||
| Redis | 6379 | 本机或内网 |
|
||||
|
||||
## 5. 方案二：应用服务与算力/训练服务独立部署
|
||||
|
||||
### 5.1 适用场景
|
||||
|
||||
- 企业生产环境。
|
||||
- 有独立应用服务器、数据库服务器和 GPU 算力服务器。
|
||||
- 需要清晰网络边界、权限边界和运维职责。
|
||||
- 未来可能扩展多台 GPU 服务器或多种训练框架。
|
||||
|
||||
### 5.2 拓扑
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U["用户浏览器"] --> N["应用区 Nginx/Frontend"]
|
||||
N --> B["应用区 Backend API"]
|
||||
B --> DB["PostgreSQL"]
|
||||
B --> R["Redis"]
|
||||
B -- "内部 HTTPS/mTLS + 服务 Token" --> C["算力区 Compute API"]
|
||||
C --> A["Compute Agent"]
|
||||
A --> L["LLaMA-Factory"]
|
||||
A --> G["GPU/CUDA"]
|
||||
A --> FS["算力服务器本地磁盘"]
|
||||
A -- "状态回调/日志摘要" --> B
|
||||
```
|
||||
|
||||
### 5.3 部署边界
|
||||
|
||||
应用服务器部署：
|
||||
|
||||
- Nginx。
|
||||
- Frontend。
|
||||
- Backend API。
|
||||
- Backend Worker。
|
||||
- PostgreSQL 或数据库连接。
|
||||
- Redis 或队列连接。
|
||||
- 审批、审计、系统配置、用户中心等应用能力。
|
||||
|
||||
GPU 算力服务器部署：
|
||||
|
||||
- Compute API。
|
||||
- Compute Agent。
|
||||
- File Gateway。
|
||||
- LLaMA-Factory。
|
||||
- CUDA、NVIDIA Driver、NCCL、PyTorch、训练依赖。
|
||||
- 本地训练工作目录、模型目录、数据集缓存、产物目录。
|
||||
|
||||
### 5.4 互通方式
|
||||
|
||||
应用平台调用算力平台：
|
||||
|
||||
- 协议：内部 HTTPS REST，后续可扩展 gRPC。
|
||||
- 鉴权：服务间 Token，生产建议 mTLS + IP 白名单。
|
||||
- 幂等：训练任务提交使用 `Idempotency-Key` 或 `job_id`。
|
||||
- 回调：算力平台向应用平台回调任务状态、指标摘要、产物索引。
|
||||
- 拉取：应用平台也可以定时轮询 Compute API，避免回调失败导致状态丢失。
|
||||
|
||||
文件互通：
|
||||
|
||||
- 小文件：前端上传到 Backend API，再由 Backend API 转发或同步到 File Gateway。
|
||||
- 大文件：Backend API 创建上传会话，前端通过受控地址分片上传到 File Gateway。
|
||||
- 离线数据：管理员把数据放到算力服务器指定目录，应用平台登记离线导入任务。
|
||||
- 产物下载：应用平台校验权限后，向 File Gateway 申请短期下载地址。
|
||||
|
||||
状态互通：
|
||||
|
||||
- Backend API 是业务状态的最终来源。
|
||||
- Compute Agent 是训练进程状态的事实来源。
|
||||
- Worker 定时对账，把 `queued/running/succeeded/failed/cancelled` 等状态同步回业务库。
|
||||
|
||||
### 5.5 优点
|
||||
|
||||
- 应用服务稳定性不受 GPU 训练高负载直接影响。
|
||||
- 数据库和审计能力更适合纳入企业基础设施。
|
||||
- 算力节点可以逐步扩展，不影响前端和应用后端。
|
||||
- 安全边界更清晰，便于设置防火墙、堡垒机、服务账号和审计策略。
|
||||
|
||||
### 5.6 风险
|
||||
|
||||
- 文件传输链路比单机部署复杂。
|
||||
- 需要处理跨服务器网络失败、回调失败、任务状态对账。
|
||||
- 需要明确模型、数据集、产物在应用侧和算力侧的索引关系。
|
||||
|
||||
## 6. Compute API 接入标准
|
||||
|
||||
为预留其他训练平台，应用平台只依赖统一算力接口，不直接依赖 LLaMA-Factory 命令。
|
||||
|
||||
训练引擎适配器应提供：
|
||||
|
||||
- `validate_config(config)`：校验训练参数和模板。
|
||||
- `build_command(job)`：生成训练命令或执行计划。
|
||||
- `start(job)`：启动训练进程。
|
||||
- `stop(job_id)`：停止训练进程。
|
||||
- `status(job_id)`：查询训练状态。
|
||||
- `collect_metrics(job_id)`：采集 loss、learning rate、epoch、step 等指标。
|
||||
- `collect_artifacts(job_id)`：登记 checkpoint、adapter、导出模型、评测报告。
|
||||
- `parse_log(line)`：解析训练日志。
|
||||
|
||||
第一版适配器：
|
||||
|
||||
```text
|
||||
compute/engines/llama_factory/
|
||||
```
|
||||
|
||||
后续其他框架：
|
||||
|
||||
```text
|
||||
compute/engines/xtuner/
|
||||
compute/engines/deepspeed_custom/
|
||||
compute/engines/openrlhf/
|
||||
```
|
||||
|
||||
## 7. 环境变量建议
|
||||
|
||||
应用平台：
|
||||
|
||||
```env
|
||||
APP_ENV=prod
|
||||
API_PREFIX=/api
|
||||
DATABASE_URL=postgresql+asyncpg://yg_ft:***@postgres:5432/yg_ft
|
||||
REDIS_URL=redis://redis:6379/0
|
||||
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
|
||||
```
|
||||
|
||||
算力平台：
|
||||
|
||||
```env
|
||||
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=***
|
||||
LLAMA_FACTORY_HOME=/opt/LLaMA-Factory
|
||||
YG_FT_DATA_ROOT=/data/yg-ft
|
||||
LOG_DIR=/opt/yg-ft/logs/compute
|
||||
CUDA_VISIBLE_DEVICES=0,1,2,3
|
||||
```
|
||||
|
||||
## 8. 日志与监控
|
||||
|
||||
应用平台：
|
||||
|
||||
- 采集 `backend-YYYY-MM-DD.log` 和 `error-YYYY-MM-DD.log`。
|
||||
- 按 `request_id`、`tenant_id`、`project_id`、`job_id` 检索。
|
||||
- ERROR 日志触发告警。
|
||||
|
||||
算力平台：
|
||||
|
||||
- 采集 Compute API 日志、Agent 日志、训练原始日志。
|
||||
- 训练日志需要按 `job_id` 独立归档。
|
||||
- 关键指标包括 GPU 利用率、显存、磁盘容量、训练队列长度、失败率。
|
||||
|
||||
## 9. 安全要求
|
||||
|
||||
- Compute API 不对公网开放。
|
||||
- 应用平台和算力平台之间使用服务账号鉴权，生产建议 mTLS。
|
||||
- File Gateway 下载地址必须短期有效，并绑定租户、项目、资源权限。
|
||||
- 日志不得输出密码、Token、密钥、数据集原文敏感内容。
|
||||
- 审计日志留存周期按租户或企业配置执行，应用日志短期留存，长期归档交给日志平台。
|
||||
|
||||
## 10. 部署检查清单
|
||||
|
||||
- PostgreSQL 已初始化 `docs/postgres-schema.sql`。
|
||||
- Redis 可连通。
|
||||
- 后端 `GET /api/v1/health` 正常。
|
||||
- Compute API 健康检查正常。
|
||||
- Compute Agent 能识别 GPU、显存、CUDA 版本。
|
||||
- LLaMA-Factory 能在命令行完成最小训练样例。
|
||||
- 应用平台能提交训练任务到 Compute API。
|
||||
- 任务状态能从算力平台同步回应用平台。
|
||||
- 数据集上传、离线导入、产物下载路径权限正确。
|
||||
- 后端 JSON 日志可被日志平台解析。
|
||||
- ERROR 日志能触发告警。
|
||||
- 日志、数据集、模型、产物所在磁盘容量有监控和告警。
|
||||
|
||||
## 11. 仍需确认的问题
|
||||
|
||||
- 生产环境是否已有统一 ELK/OpenSearch、Filebeat/Vector 标准配置。
|
||||
- 数据库和 Redis 是否由企业基础设施统一提供，还是由项目自行部署。
|
||||
- 是否需要 PostgreSQL 主备、备份恢复、审计日志长期归档的明确 SLA。
|
||||
- 大文件上传是否需要断点续传、限速、病毒扫描或 DLP 检测。
|
||||
- 应用服务器与算力服务器之间是否允许双向访问，还是只能应用侧主动访问算力侧。
|
||||
- 是否需要未来支持多台 GPU 节点调度；如果需要，Compute API 需要提前设计节点注册和调度策略。
|
||||
Reference in New Issue
Block a user