TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reorganize by module

Browse Source
This commit is contained in:
wren
2026-05-09 20:04:08 +08:00
parent 29873eaecd
commit c9d7a693b8
23 changed files with 2161 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/RAG/RAG后端上线清单.md
+310
View File
@@ -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`
docs/RAG/RAG聊天接口.md
+493
View File
@@ -0,0 +1,493 @@
# RAG 聊天接口
> 最后整理：2026-05-07
> 对应后端：`fastapi_modules/fastapi_leaudit/controllers/ragChatController.py`
> 统一前缀：`/api/v3/rag`
## 1. 目标与范围
本组接口用于替代旧的 `dify_chat/*` 对话代理，直接提供自有 RAG 聊天能力。
当前已落地能力：
- 获取当前用户可见的 RAG 应用
- 获取默认 RAG 应用
- 获取当前用户可见知识库
- 获取聊天页面参数
- 发起流式对话
- 查询会话列表
- 查询会话消息
- 重命名会话
- 删除会话
- 消息反馈
当前不在本文档范围内：
- 知识库 CRUD 管理
- 文档切分 / 入库任务
- Chroma 集合构建脚本
## 2. 鉴权与权限
### 2.1 鉴权方式
所有接口都要求请求头带：
```http
Authorization: Bearer <access_token>
```
JWT 解析逻辑见：
- `fastapi_common/fastapi_common_security/security.py`
- `fastapi_common/fastapi_common_security/jwtService.py`
JWT payload 至少会被后端消费这些字段：
- `user_id`
- `username`
- `area`
- `user_role`
- `type`，必须为 `access`
### 2.2 权限键
| 接口 | 权限 |
|------|------|
| `GET /api/v3/rag/apps` | `rag:app:read` |
| `GET /api/v3/rag/apps/default` | `rag:app:read` |
| `GET /api/v3/rag/datasets/my` | `rag:dataset:read` |
| `GET /api/v3/rag/chat/parameters` | `rag:chat:use` 或 `rag:app:read` 其一即可 |
| `POST /api/v3/rag/chat/messages` | `rag:chat:use` |
| `GET /api/v3/rag/chat/conversations` | `rag:conversation:read` |
| `GET /api/v3/rag/chat/conversations/{ConversationId}/messages` | `rag:conversation:read` |
| `PATCH /api/v3/rag/chat/conversations/{ConversationId}` | `rag:conversation:update` |
| `DELETE /api/v3/rag/chat/conversations/{ConversationId}` | `rag:conversation:delete` |
| `POST /api/v3/rag/chat/messages/{MessageId}/feedback` | `rag:message:feedback` |
说明：
- 权限检查使用 `HasAnyPermission`，即“列表中的任一权限命中即可通过”。
- 具体实现见 `fastapi_modules/fastapi_leaudit/services/impl/permissionServiceImpl.py`。
## 3. 通用返回格式
除流式接口外，统一返回：
```json
{
"code": 200,
"msg": "success",
"data": {}
}
```
权限不足时通常返回：
```json
{
"code": 403,
"msg": "当前用户没有对应权限",
"data": null
}
```
## 4. 接口列表
### 4.1 获取可见应用列表
`GET /api/v3/rag/apps`
用途：
- 聊天页面加载应用下拉
- 根据地区 / 省级角色做应用可见性过滤
请求参数：无
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"data": [
{
"appId": "1",
"appName": "法务问答",
"description": "默认烟草法务知识问答",
"isDefault": true
}
],
"total": 1
}
}
```
可见性规则：
- `provincial_admin` 可见全部启用应用
- 其他角色仅可见：
- `rag_chat_app.area = 用户 area`
- `rag_chat_app.area = '省级'`
- `rag_chat_app.area = ''`
- 或关联数据集 `rag_dataset.is_public = true`
### 4.2 获取默认应用
`GET /api/v3/rag/apps/default`
用途：
- 聊天页初始化默认应用
请求参数：无
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"appId": "1",
"appName": "法务问答",
"description": "默认烟草法务知识问答",
"isDefault": true
}
}
```
补充说明：
- 如果没有显式默认应用，会退回到当前用户可见的第一条应用。
- 如果完全没有可见应用，返回 `data: null`。
### 4.3 获取当前用户可见知识库
`GET /api/v3/rag/datasets/my`
用途：
- 聊天页展示“当前可用知识库”时使用
请求参数：无
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"data": [
{
"id": 1,
"name": "广东烟草法规库",
"description": "省级法规与制度",
"area": "省级",
"isPublic": true,
"isDefault": true,
"documentCount": 120,
"totalChunks": 8345,
"status": 1
}
],
"total": 1
}
}
```
### 4.4 获取聊天参数
`GET /api/v3/rag/chat/parameters`
查询参数：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `appId` | int | 否 | 指定应用 ID；不传则取默认应用 |
用途：
- 初始化开场白
- 初始化建议问题
- 初始化上传能力配置
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"openingStatement": "你好，我可以帮你解答烟草行业法务问题。",
"suggestedQuestions": [
"烟草专卖许可延续的法定条件是什么？",
"行政处罚文书审查重点有哪些？"
],
"userInputForm": [],
"fileUpload": {
"image": {
"enabled": false
}
}
}
}
```
### 4.5 发起流式对话
`POST /api/v3/rag/chat/messages`
请求体：
```json
{
"query": "烟草专卖许可证延续申请的审查要点是什么？",
"conversationId": null,
"appId": 1
}
```
字段说明：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | 是 | 用户问题，不能为空 |
| `conversationId` | string \| null | 否 | 会话 ID；新对话可传 `null` 或不传 |
| `appId` | int \| null | 否 | 应用 ID；不传则自动回退默认应用 |
返回类型：
- `text/event-stream`
SSE 事件 1：流式正文片段
```text
data: {"event":"message","task_id":"...","message_id":"...","conversation_id":"...","answer":"第一段内容","created_at":1746580000}
```
SSE 事件 2：流式结束
```text
data: {"event":"message_end","task_id":"...","message_id":"...","conversation_id":"...","metadata":{"usage":{"total_tokens":1234},"retriever_resources":[...],"suggested_questions":["问题1","问题2"]}}
```
SSE 事件 3：模型异常
```text
data: {"event":"error","task_id":"...","message_id":"...","code":"llm_error","message":"..."}
```
服务端行为说明：
- 若 `conversationId` 为空，会自动创建新会话
- 会先落一条 `role = user` 消息，再流式生成回答
- 流结束后会落一条 `role = assistant` 消息
- 若命中知识库，会把引用结果写入 `sources / metadata`
- 会根据对话内容追加 `suggested_questions`
### 4.6 获取会话列表
`GET /api/v3/rag/chat/conversations`
查询参数：
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `appId` | int | 否 | - | 按应用过滤 |
| `page` | int | 否 | `1` | 页码，从 1 开始 |
| `pageSize` | int | 否 | `20` | 每页数量，最大 100 |
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"data": [
{
"id": "b17d3b0b-xxxx-xxxx",
"name": "新对话",
"introduction": "",
"createdAt": 1746580000,
"updatedAt": 1746580066
}
],
"hasMore": false,
"limit": 20
}
}
```
### 4.7 获取会话消息
`GET /api/v3/rag/chat/conversations/{ConversationId}/messages`
路径参数：
| 参数 | 类型 | 说明 |
|------|------|------|
| `ConversationId` | string | 会话 ID |
查询参数：
| 参数 | 类型 | 必填 | 默认值 |
|------|------|------|--------|
| `page` | int | 否 | `1` |
| `pageSize` | int | 否 | `20` |
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"data": [
{
"id": "assistant-message-id",
"conversationId": "b17d3b0b-xxxx-xxxx",
"query": "烟草专卖许可证延续申请的审查要点是什么？",
"answer": "先核对主体资格，再核对经营条件……",
"feedback": {
"rating": "like"
},
"retrieverResources": [
{
"position": 1,
"dataset_id": "1",
"dataset_name": "广东烟草法规库",
"document_id": "12",
"document_name": "行政许可审查规范.pdf",
"segment_id": "chunk-1",
"score": 0.9132
}
],
"createdAt": 1746580000
}
],
"hasMore": false,
"limit": 20
}
}
```
说明：
- 返回结构是按“问答对”聚合后的结果，不是底层 `rag_message` 原始逐条结果。
### 4.8 重命名会话
`PATCH /api/v3/rag/chat/conversations/{ConversationId}`
请求体：
```json
{
"name": "许可证延续审查要点"
}
```
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"result": "success",
"name": "许可证延续审查要点"
}
}
```
### 4.9 删除会话
`DELETE /api/v3/rag/chat/conversations/{ConversationId}`
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"result": "success"
}
}
```
说明：
- 逻辑删除，实际是设置 `rag_conversation.deleted_at`
### 4.10 消息反馈
`POST /api/v3/rag/chat/messages/{MessageId}/feedback`
请求体：
```json
{
"rating": "like"
}
```
可选值：
- `like`
- `dislike`
- `null`
成功响应示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"result": "success"
}
}
```
## 5. 数据表对应关系
| 表 | 用途 |
|----|------|
| `rag_dataset` | 知识库定义、地区可见性、检索参数 |
| `rag_document` | 知识库文档、启停状态、命中次数 |
| `rag_chat_app` | 聊天应用配置、默认应用、应用绑定知识库 |
| `rag_conversation` | 用户会话 |
| `rag_message` | 底层消息落库，包含引用与反馈 |
## 6. 当前实现约束
- 当前只提供 `GET /datasets/my`，不提供知识库管理 CRUD
- `fileUpload.image.enabled` 固定为 `false`
- 检索依赖 Chroma；Chroma 不可用时，接口仍可回答，但会退化成无知识库上下文
- 建议问题 `suggestedQuestions` 由二次模型调用生成，失败时会降级为空数组
## 7. 联调建议
最小联调顺序：
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`
5. `GET /api/v3/rag/chat/conversations`
6. `GET /api/v3/rag/chat/conversations/{ConversationId}/messages`
优先检查：
- 401：JWT 是否有效
- 403：`rag:*` 权限是否已写入并分配
- 500：LLM、数据库、Chroma、知识库配置是否可用