wren
311 lines
7.4 KiB
Markdown
311 lines
7.4 KiB
Markdown
# RAG 后端上线清单
|
||
|
||
适用范围：
|
||
- 仓库：`leaudit-platform`
|
||
- 本次上线内容：自有 RAG 聊天后端、`/api/v3/rag/*` 接口、`rag_*` 表结构、`rag:*` 权限
|
||
|
||
## 1. 上线前确认
|
||
|
||
- 代码已包含以下变更：
|
||
- `fastapi_modules/fastapi_leaudit/controllers/ragChatController.py`
|
||
- `fastapi_modules/fastapi_leaudit/services/impl/ragChatServiceImpl.py`
|
||
- `fastapi_modules/fastapi_leaudit/services/impl/ragDatasetServiceImpl.py`
|
||
- `scripts/创建sql/schema_add_rag_chat.sql`
|
||
- `scripts/创建sql/user_rbac_seed.sql`
|
||
- `pyproject.toml` 已加入 `chromadb`
|
||
- 发布分支已经合并到目标部署分支。
|
||
- 数据库备份已完成，至少备份：
|
||
- `permissions`
|
||
- `role_permissions`
|
||
- `role_route`
|
||
- `sys_routes`
|
||
- 全部 `rag_*` 表
|
||
|
||
## 2. 配置优先级
|
||
|
||
后端配置加载顺序见 `fastapi_admin/config/_loader.py`：
|
||
|
||
1. `app.toml`
|
||
2. `app.{APP_ENV}.toml`
|
||
3. `app.ai.toml`
|
||
4. 已存在的环境变量
|
||
|
||
结论：
|
||
- 生产环境如果通过环境变量注入，优先级最高。
|
||
- 如果继续使用 TOML，建议把生产密钥放到 `app.ai.toml` 或外部环境变量，不要直接把敏感值写死在默认 `app.toml`。
|
||
|
||
## 3. 必备环境变量 / 配置项
|
||
|
||
### 3.1 基础服务配置
|
||
|
||
来自 `fastapi_admin/config/_settings.py`：
|
||
|
||
- `APP_HOST`
|
||
- `APP_PORT`
|
||
- `JWT_SECRET_KEY`
|
||
- `DB_HOST`
|
||
- `DB_PORT`
|
||
- `DB_NAME`
|
||
- `DB_USER`
|
||
- `DB_PASSWORD`
|
||
- `REDIS_HOST`
|
||
- `REDIS_PORT`
|
||
- `REDIS_DB`
|
||
- `REDIS_PASSWORD`
|
||
- `OSS_ENDPOINT`
|
||
- `OSS_BASE_URL`
|
||
- `OSS_ACCESS_KEY`
|
||
- `OSS_SECRET_KEY`
|
||
- `OSS_BUCKET`
|
||
|
||
### 3.2 RAG / LLM 配置
|
||
|
||
来自 `fastapi_modules/fastapi_leaudit/rag_engine/config.py`：
|
||
|
||
- `LLM_BASE_URL`
|
||
- `LLM_MODEL`
|
||
- `LLM_API_KEY`
|
||
- `RAG_LLM_TEMPERATURE`
|
||
- `RAG_LLM_MAX_TOKENS`
|
||
- `RAG_LLM_TIMEOUT`
|
||
|
||
### 3.3 Chroma 配置
|
||
|
||
二选一：
|
||
|
||
- 远程 Chroma：
|
||
- `RAG_CHROMA_HOST`
|
||
- `RAG_CHROMA_PORT`
|
||
- `RAG_CHROMA_TOKEN`（如有鉴权）
|
||
- `RAG_CHROMA_AUTH_HEADER`（默认 `X-Chroma-Token`）
|
||
- 本地持久化 Chroma：
|
||
- `RAG_CHROMA_PERSIST_DIR`
|
||
|
||
说明：
|
||
- 如果不配置 `RAG_CHROMA_HOST`，代码会走本地 `PersistentClient`。
|
||
- 如果 Chroma 依赖缺失或不可用，服务能启动，但检索会退化成“无上下文回答”。
|
||
|
||
### 3.4 可选检索参数
|
||
|
||
- `RAG_VECTOR_TOP_K`
|
||
- `RAG_RERANK_TOP_K`
|
||
- `RAG_BM25_TOP_K`
|
||
- `RAG_RRF_K`
|
||
- `RAG_QUERY_REWRITING`
|
||
- `RAG_HYBRID_SEARCH`
|
||
- `RAG_RERANKING`
|
||
- `RAG_EMBED_URL`
|
||
- `RAG_EMBED_KEY`
|
||
- `RAG_EMBED_MODEL`
|
||
- `RAG_EMBED_DIM`
|
||
- `RAG_EMBED_BATCH_SIZE`
|
||
- `RAG_RERANKER_URL`
|
||
- `RAG_RERANKER_KEY`
|
||
- `RAG_RERANKER_MODEL`
|
||
|
||
说明：
|
||
- 当前聊天主流程已经能工作；即使没有完整 embedding/reranker 配置，只要现有 Chroma 集合可用，也可以先上线基础聊天。
|
||
- 更细的召回参数也可以放在 `rag_dataset.retrieval_model` 里按知识库配置。
|
||
|
||
## 4. 依赖安装
|
||
|
||
### 4.1 Python 依赖
|
||
|
||
本次新增依赖：
|
||
|
||
- `chromadb>=0.5.23`
|
||
|
||
如果线上使用虚拟环境：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
pip install -e .
|
||
```
|
||
|
||
如果只补增量依赖：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
pip install chromadb
|
||
```
|
||
|
||
建议最终仍执行一次完整依赖同步，避免环境漂移。
|
||
|
||
## 5. 数据库执行顺序
|
||
|
||
### 5.1 先执行结构脚本
|
||
|
||
```bash
|
||
psql -v ON_ERROR_STOP=1 \
|
||
-h <DB_HOST> -p <DB_PORT> -U <DB_USER> -d <DB_NAME> \
|
||
-f scripts/创建sql/schema_add_rag_chat.sql
|
||
```
|
||
|
||
作用：
|
||
- 创建 `rag_dataset / rag_document / rag_chat_app / rag_conversation / rag_message`
|
||
- 对已存在表补字段、补索引、补 `updated_at` 触发器
|
||
|
||
### 5.2 再执行权限种子
|
||
|
||
```bash
|
||
psql -v ON_ERROR_STOP=1 \
|
||
-h <DB_HOST> -p <DB_PORT> -U <DB_USER> -d <DB_NAME> \
|
||
-f scripts/创建sql/user_rbac_seed.sql
|
||
```
|
||
|
||
作用：
|
||
- 补 `rag:*` 权限
|
||
- 补角色授权
|
||
- 同步需要的菜单/路由元数据
|
||
|
||
### 5.3 当前已验证结果
|
||
|
||
本地已在目标库执行并验证：
|
||
|
||
- 已存在 5 张 `rag_*` 表
|
||
- 已存在 7 条 `rag:*` 权限
|
||
- `super_admin / provincial_admin / admin / common` 均已获得这 7 条权限
|
||
|
||
## 6. 重启顺序
|
||
|
||
推荐顺序如下。
|
||
|
||
### 步骤 1：停 Celery worker
|
||
|
||
如果当前有 worker 在跑，先停掉，避免旧代码消费任务：
|
||
|
||
```bash
|
||
pkill -f "celery.*fastapi_admin.celery_app:celery_app" || true
|
||
```
|
||
|
||
如果你们线上是用进程管理器托管 worker，则用对应管理命令停止。
|
||
|
||
### 步骤 2：更新代码并安装依赖
|
||
|
||
```bash
|
||
git pull
|
||
source .venv/bin/activate
|
||
pip install -e .
|
||
```
|
||
|
||
### 步骤 3：执行数据库脚本
|
||
|
||
按“第 5 节”的先后顺序执行：
|
||
|
||
1. `scripts/创建sql/schema_add_rag_chat.sql`
|
||
2. `scripts/创建sql/user_rbac_seed.sql`
|
||
|
||
### 步骤 4：重启 FastAPI 主服务
|
||
|
||
如果用 `uvicorn` 直接启动，参考 `run.py`：
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
python run.py
|
||
```
|
||
|
||
如果线上不是 `reload=True` 的开发模式，建议使用你们现有的生产启动命令重启主进程，不要直接照抄开发命令。
|
||
|
||
### 步骤 5：重启 Celery worker
|
||
|
||
仓库已提供脚本 `scripts/start_worker.sh`：
|
||
|
||
```bash
|
||
./scripts/start_worker.sh
|
||
```
|
||
|
||
它会自动读取：
|
||
- `LEAUDIT_WORKER_CONCURRENCY`
|
||
- `LEAUDIT_WORKER_QUEUE_URGENT`
|
||
- `LEAUDIT_WORKER_QUEUE_NORMAL`
|
||
|
||
### 步骤 6：如有反向代理，再做一次健康检查
|
||
|
||
- Nginx / 网关 upstream 是否恢复
|
||
- 80/443 -> FastAPI upstream 是否正常
|
||
|
||
## 7. 上线后验证
|
||
|
||
### 7.1 代码级快速检查
|
||
|
||
```bash
|
||
python -m compileall fastapi_modules/fastapi_leaudit
|
||
```
|
||
|
||
### 7.2 路由检查
|
||
|
||
已知应存在 10 条 `/v3/rag` 路由：
|
||
|
||
- `GET /api/v3/rag/apps`
|
||
- `GET /api/v3/rag/apps/default`
|
||
- `GET /api/v3/rag/datasets/my`
|
||
- `GET /api/v3/rag/chat/parameters`
|
||
- `POST /api/v3/rag/chat/messages`
|
||
- `GET /api/v3/rag/chat/conversations`
|
||
- `GET /api/v3/rag/chat/conversations/{ConversationId}/messages`
|
||
- `PATCH /api/v3/rag/chat/conversations/{ConversationId}`
|
||
- `DELETE /api/v3/rag/chat/conversations/{ConversationId}`
|
||
- `POST /api/v3/rag/chat/messages/{MessageId}/feedback`
|
||
|
||
### 7.3 数据库检查
|
||
|
||
```sql
|
||
SELECT tablename
|
||
FROM pg_tables
|
||
WHERE schemaname = 'public' AND tablename LIKE 'rag_%'
|
||
ORDER BY tablename;
|
||
```
|
||
|
||
```sql
|
||
SELECT count(*)
|
||
FROM permissions
|
||
WHERE permission_key LIKE 'rag:%';
|
||
```
|
||
|
||
```sql
|
||
SELECT r.role_key, count(*)
|
||
FROM role_permissions rp
|
||
JOIN roles r ON r.id = rp.role_id
|
||
JOIN permissions p ON p.id = rp.permission_id
|
||
WHERE p.permission_key LIKE 'rag:%'
|
||
GROUP BY r.role_key
|
||
ORDER BY r.role_key;
|
||
```
|
||
|
||
### 7.4 接口联通检查
|
||
|
||
至少验证这 4 个接口：
|
||
|
||
1. `GET /api/v3/rag/apps`
|
||
2. `GET /api/v3/rag/apps/default`
|
||
3. `GET /api/v3/rag/chat/parameters`
|
||
4. `POST /api/v3/rag/chat/messages`
|
||
|
||
关注点：
|
||
- 401：JWT 或登录态异常
|
||
- 403：`rag:*` 权限未生效
|
||
- 404：控制器未注册 / 网关路径未转发
|
||
- 500：LLM、Chroma、数据库连接或 JSON 字段异常
|
||
|
||
## 8. 常见风险
|
||
|
||
- `chromadb` 未安装：服务启动不一定报错，但首次检索时会退化
|
||
- Chroma 集合为空：可以聊天，但没有知识库上下文
|
||
- `LLM_BASE_URL / LLM_API_KEY / LLM_MODEL` 配错：流式对话会直接失败
|
||
- 只执行权限脚本、不执行结构脚本：接口可能启动，但落库时报错
|
||
- 只重启 API、不重启 worker：后台异步任务仍可能跑旧代码
|
||
|
||
## 9. 建议的最短上线动作
|
||
|
||
按最快可落地顺序：
|
||
|
||
1. 备份数据库
|
||
2. `git pull`
|
||
3. `source .venv/bin/activate && pip install -e .`
|
||
4. 执行 `scripts/创建sql/schema_add_rag_chat.sql`
|
||
5. 执行 `scripts/创建sql/user_rbac_seed.sql`
|
||
6. 重启 FastAPI 主服务
|
||
7. 重启 `scripts/start_worker.sh`
|
||
8. 验证 `/api/v3/rag/apps` 和 `/api/v3/rag/chat/messages`
|
||
|