docs: reorganize by module
This commit is contained in:
wren
@@ -0,0 +1,310 @@
|
||||
# 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/schema_add_rag_chat.sql`
|
||||
- `scripts/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/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/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/schema_add_rag_chat.sql`
|
||||
2. `scripts/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/schema_add_rag_chat.sql`
|
||||
5. 执行 `scripts/user_rbac_seed.sql`
|
||||
6. 重启 FastAPI 主服务
|
||||
7. 重启 `scripts/start_worker.sh`
|
||||
8. 验证 `/api/v3/rag/apps` 和 `/api/v3/rag/chat/messages`
|
||||
|
||||
Reference in New Issue
Block a user