TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9c86bf59e5c50132580d3197f9d172cdfeeb0d82
leaudit-platform-backend/docs/RAG后端上线清单.md
T

7.3 KiB
Raw Blame History

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

如果线上使用虚拟环境：

source .venv/bin/activate
pip install -e .

如果只补增量依赖：

source .venv/bin/activate
pip install chromadb

建议最终仍执行一次完整依赖同步，避免环境漂移。

5. 数据库执行顺序

5.1 先执行结构脚本

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 再执行权限种子

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 在跑，先停掉，避免旧代码消费任务：

pkill -f "celery.*fastapi_admin.celery_app:celery_app" || true

如果你们线上是用进程管理器托管 worker，则用对应管理命令停止。

步骤 2：更新代码并安装依赖

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：

source .venv/bin/activate
python run.py

如果线上不是 reload=True 的开发模式，建议使用你们现有的生产启动命令重启主进程，不要直接照抄开发命令。

步骤 5：重启 Celery worker

仓库已提供脚本 scripts/start_worker.sh：

./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 代码级快速检查

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 数据库检查

SELECT tablename
FROM pg_tables
WHERE schemaname = 'public' AND tablename LIKE 'rag_%'
ORDER BY tablename;

SELECT count(*)
FROM permissions
WHERE permission_key LIKE 'rag:%';

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 View Git Blame Copy Permalink