zcdsj
/
llm_ask
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
llm_ask/docs/superpowers/specs/2026-04-30-llm-qa-system-de...

450 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 大模型智能问答客服系统 · 基于腾讯云 ADP 的接入方案
**日期：** 2026-04-30
**状态：** 待评审（v2）
**形态变化：** 从全栈自研 RAG，改为「腾讯云 ADP 提供 KB + 检索 + 生成 + 引用，外层应用提供身份/会话/权限/管控」
**技术栈：** Python / FastAPI / Vue3 / 腾讯云 ADP（LKE）/ 腾讯云 SMS / PostgreSQL / Redis
**v2 修订（2026-04-30）：**
- 登录方式由邮箱改为**手机号 + 短信验证码**
- 明确文档管理走**路线 A：透传 ADP 文档 OpenAPI**，列出实际可用接口
- 新增第十二章：综合可行性判断与替代路径评估
---
## 一、项目背景与目标
将企业内部的报销制度、软件操作手册、财务/科研流程、常见问题汇总等文档接入大模型，构建一套智能问答客服系统。用户可以用自然语言提问，系统给出答案并注明引用来源；支持上传截图辅助提问。
**核心目标（与原方案一致）：**
- 文档知识库化，降低重复人工咨询成本
- 答案可追溯，每条回答标注来源文档、章节、页码或段落
- 支持截图上传，辅助描述操作类问题
- 管理员可自助维护文档，无需开发介入
**本期路径调整：**
- 不再自研文档解析、切片、检索、重排、生成、引用对齐
- 改为基于腾讯云智能体开发平台（ADP / LKE）建立知识库与对话应用
- 外层自研一个 Web 应用，承担用户体系、会话留存、权限治理与调用编排
---
## 二、能力分工：ADP 给什么、我们做什么
**ADP（腾讯云智能体开发平台）已经原生提供：**
| 能力 | ADP 是否提供 | 说明 |
|---|---|---|
| 文档解析（PDF/Word/Excel/图片/Markdown 等） | ✅ | OCR+LLM+MLLM，复杂文档 98%+ 准确率，自动转 Markdown |
| 切片 / 索引 / 向量化 | ✅ | 控制台可配切分规则，平台维护索引 |
| 检索（RAG / Agentic RAG） | ✅ | 高召回+高准确，支持多步检索 |
| 重排 + 大模型生成 | ✅ | 可选 DeepSeek、混元、GLM、Kimi、MiniMax 等 |
| 引用来源回传 | ✅ | SSE 流里 `reference` 事件返回 doc_id / 名称 / 类型 / URL |
| 文档级标签 + 标签按用户隔离 | ✅ | 通过对话接口的 `custom_variables` 控制可检索文档范围 |
| 流式输出 | ✅ | `POST https://wss.lke.cloud.tencent.com/v1/qbot/chat/sse` |
| 文档增删改 API | ✅ | `CreateDoc` / `ModifyDoc` / `DescribeDoc` 等 |
| 联网搜索 | ✅ | `search_network` 参数控制 |
| 截图问答 | ✅ | content 支持 Markdown 图片格式，平台自带多模态识别 |
**外层应用要做的，是「用户体系 + 业务编排 + 调用治理」这一壳层：**
1. **企业用户体系**：邮箱注册/登录、验证码、JWT、角色、白名单域名、禁用即时生效——ADP 的 `visitor_biz_id` 只是访客 ID，没有真正的账号体系。
2. **会话历史持久化**：ADP session 主要服务多轮上下文，长期、跨设备的"我的会话列表"应在我们这边落库，便于审计、按用户筛选、合规留存。
3. **SSE 代理转发**：浏览器不能直接用 `bot_app_key` 调 ADP（密钥泄漏风险），必须经过我们的后端代理，并在代理层做鉴权、限流、日志、留存。
4. **知识库范围权限**：哪个角色/部门可看哪些文档，要在我们这边映射到 `custom_variables`（标签匹配）。
5. **管理员能力外壳**：用户管理；文档管理可选「内嵌 ADP 控制台 / 我们包一层 ADP API」二选一。
6. **审计与统计**：未命中、低置信、热门问题、Token 消耗，用于费用治理。
---
## 三、用户角色
| 角色 | 权限 |
|------|------|
| `employee`（员工/外部合作方） | 对话问答、查看本人历史会话 |
| `admin`（管理员） | 文档上传/删除/管理、用户管理（创建/角色分配/禁用）、KB 标签规则配置 |
---
## 四、整体架构
```text
用户浏览器 (Vue3 + Element Plus)
│ HTTPS
▼
Nginx
│
FastAPI 外层应用
├─ 认证模块（邮箱+密码 / 邮箱+验证码 / JWT / 黑名单）
├─ 用户与权限模块（角色、KB标签映射）
├─ 会话/消息持久化模块
├─ 对话代理模块（SSE 反向代理 → ADP）
├─ 文档管理模块（透传 ADP 文档 API）
└─ 审计/计量模块
│
├─ PostgreSQL（用户 / 会话 / 消息 / 引用 / 标签映射 / 调用账单）
├─ Redis（验证码 / 限流 / Token 黑名单）
│
└─→ 腾讯云 ADP
├─ 知识库（文档 + 标签 + 切片 + 向量）
├─ 应用（绑定 KB、模型、Prompt、工作流）
├─ /v1/qbot/chat/sse 对话端点
└─ 文档管理 API
```
注意：**OCR 不再独立接入阿里云**——截图直接以 Markdown 图片形式塞进 `content`，ADP 多模态自动识别。这一项可省。
---
## 五、核心模块设计
### 5.1 认证模块（手机号 + 短信验证码）
- **账号名：** 手机号（中国大陆 11 位，预留国际化字段 `country_code`，默认 `+86`）
- **注册管控：** 默认**关闭自助注册**，全部由 admin 后台手动创建；可选开启"白名单号段自助注册"（实际意义有限）
- **登录方式：**
- 手机号 + 短信验证码（**唯一登录方式**，不再做密码登录，简化运维与忘记密码流程）
- 6 位数字验证码，5 分钟有效，存 Redis
- **验证码防刷：**
- 同一手机号 60 秒内不可重复发送
- 同一手机号 24 小时内最多 10 次
- 同一 IP 每小时限制 10 次
- 图形验证码兜底：单 IP 单小时超过 5 次后强制图形码
- **Token 机制：**
- Access Token（JWT）：有效期 2 小时
- Refresh Token：有效期 7 天，存 Redis，可主动吊销
- 管理员禁用账号时，将该账号现有 Token 加入 Redis 黑名单，立即失效
- **短信服务：** **腾讯云 SMS 短信服务**（与 ADP 同一云厂商，密钥/账号/账单合一）
- 备用通道：阿里云短信（防止单通道故障）
- 上线前需完成签名 + 模板报备（约 2 个工作日）
- **预留字段：** `external_id`（用于后期对接企微/飞书/LDAP 单点登录时打通）
### 5.2 文档管理模块（路线 A：透传 ADP OpenAPI）
**本期明确采用路线 A**——所有文件管理都在我们后台内部完成，ADP 控制台不暴露给业务方，原因：
- 体验统一，admin 不需要切换两套系统
- 可叠加业务字段（部门、密级、上传人、审计日志）
- 后期切换底座 RAG 时，对外接口不变，前端零改动
**ADP 提供的可调用接口（已确认）：**
| 接口 | 用途 | 我方使用场景 |
|---|---|---|
| `DescribeStorageCredential` | 获取 COS 临时上传凭证 | 前端直传 COS，文件流不穿过我方服务器 |
| `SaveDoc` | 文档入库（含来源、标签、切分配置） | 前端上传完成后入 ADP |
| `ListDoc` | 文档列表 | admin 文档管理页主列表 |
| `DescribeDoc` | 文档详情（含解析状态） | 状态轮询 |
| `ModifyDoc` | 修改文档属性 | 改标签、改密级 |
| `RenameDoc` | 重命名 | 改名 |
| `DeleteDoc` | 删除 | 删除按钮 |
| `RetryDocParse` | 重试解析 | 解析失败时 |
| `StopDocParse` | 终止解析 | 解析卡死时 |
| `GetDocPreview` | 文档预览 | 引用来源点击查看原文 |
| `DescribeSegments` | 查切片详情 | 调试用 |
| `CreateQA` / `ListQA` / `ModifyQA` / `DeleteQA` | QA 库管理 | FAQ 沉淀（高频问答直接命中，不走 RAG） |
**上传链路设计：**
```text
admin 浏览器
│ 1. 选择文件，前端调我方 /api/docs/upload-credential
▼
FastAPI
│ 2. 鉴权 + 调 DescribeStorageCredential 拿临时凭证
▼
admin 浏览器
│ 3. 前端用临时凭证直传 COS
│ 4. 上传完成后调我方 /api/docs/save，带 cos_url + 业务字段（部门、密级、标签）
▼
FastAPI
│ 5. 调 SaveDoc 入 ADP；同时 documents_meta 落业务字段镜像
▼
admin 浏览器
│ 6. 列表页 5s 轮询 /api/docs?status，后端调 ListDoc/DescribeDoc 透传状态
```
**关键设计：文档标签 ↔ 角色/密级**
- 在 ADP 知识库里给每篇文档打标签，第一期**只用一个维度**：`level ∈ {public, internal, confidential}`
- 我们 DB 维护 `role_kb_label_rules`：哪个角色可命中哪些标签值
- 调用 SSE 时把规则结果写进 `custom_variables`，ADP 自动按标签过滤检索范围
- 部门维度 (`dept=finance`) 留给二期；不要一开始就做 N 维矩阵权限
**支持格式（沿用 ADP 默认）：**
- 文档：xlsx/xls/csv/md/txt/html/xmind/json/xml/log，单文件 ≤ 20MB
- 图片：jpg/png/jpeg/tiff/bmp/gif，单文件 ≤ 50MB
- 文档结构化、章节、页码全部由 ADP 解析层处理
**人日：** 从原 8 人日压缩到 **3 人日**（仅做透传适配、标签编辑 UI、状态轮询、上传链路）。
### 5.3 问答检索模块（最大瘦身）
原方案里的 Query 归一化、文档召回、章节召回、LLM 重排、段落精定位、Prompt 组装——**全部不再自己写**，由 ADP 应用配置完成。
**外层只剩一件事：SSE 反向代理。**
```text
浏览器 EventSource
│ GET /api/chat/sse?conversation_id=xxx&content=...
▼
FastAPI 鉴权 → 拉取 conversation 上下文 → 计算用户的 KB 标签 →
POST https://wss.lke.cloud.tencent.com/v1/qbot/chat/sse
body: {
bot_app_key,
session_id, # 我们生成并落库
visitor_biz_id: user.id,
content, # 文本 + ![](img_url)
custom_variables: {dept: "finance", level: "internal"},
streaming_throttle: 5
}
▼
逐事件回写浏览器（reply/reference/token_stat/error）
同时把 reply 拼成完整答案、引用来源、Token 用量落 messages 表
```
**ADP SSE 事件类型（关注的）：**
- `reply`：增量回复内容，`is_final` 标记完成
- `reference`：引用来源数组（id/type/name/url/doc_id），type=1 问答、type=2 文档片段、type=4 联网搜索
- `token_stat`：本次问答 Token 输入/输出/PU 消耗
- `thought`：（DeepSeek-R1 等推理模型）思考过程
- `error`：错误码与描述
### 5.4 截图上传
不再需要本地 OCR。前端把截图先上传到我方对象存储（或 ADP 提供的素材存储），拿到可访问 URL，把 `![](url)` 拼到 `content` 即可，ADP 端自动多模态解析。
如对图片机密性敏感，可走「上传到我方对象存储 + 短期签名 URL（5 分钟）+ 仅腾讯云出口可访问」。
### 5.5 数据模型（大幅瘦身）
```text
users
id, phone, country_code, external_id, role, is_active,
display_name, created_at
refresh_tokens
id, user_id, token_hash, expires_at, revoked
token_blacklist
jti, expires_at
conversations
id, user_id, title, adp_session_id, created_at
messages
id, conversation_id, role, content, sources_json,
adp_request_id, token_in, token_out, model_name, created_at
documents_meta -- 仅作为我方业务镜像，主数据在 ADP
id, adp_doc_id, name, tags_json, status,
uploaded_by, uploaded_at
role_kb_label_rules
id, role, label_key, label_values_json -- 例 admin → level=[public,internal,confidential]
usage_log -- 计量审计
id, user_id, conversation_id, token_in, token_out, pu_cost, created_at
```
**与原方案相比删除的表：**
- `document_sections`（章节索引）
- `doc_chunks`（段落索引 + tsv 全文检索）
- `document_aliases`（别名）
这些信息全部由 ADP 在内部维护。
### 5.6 前端页面
| 页面 | 访问角色 | 核心功能 |
|------|---------|---------|
| 登录页 | 所有人 | 手机号 + 短信验证码登录、图形码兜底、倒计时 |
| 对话页 | employee / admin | 左侧会话列表、右侧 SSE 流式对话、截图上传、引用来源展示（直接渲染 ADP `reference` 事件里的 name + url） |
| 文档管理页 | admin | 文档列表、上传、删除、标签编辑、解析状态轮询（透传 ADP 状态） |
| 用户管理页 | admin | 用户列表、创建账号、角色分配、禁用、**KB 标签可见范围配置** |
| 审计页（可选） | admin | 用量统计、未命中、Token / PU 消耗 |
---
## 六、技术选型
| 层次 | 选型 | 说明 |
|------|------|------|
| 前端 | Vue3 + Element Plus | 成熟后台组件生态 |
| 后端 | FastAPI + Python 3.11 | 异步支持较好，适合做 SSE 代理与编排 |
| 关系数据库 | PostgreSQL | 存用户、会话、消息、引用、标签映射、计量 |
| 缓存 | Redis | 验证码、黑名单、限流 |
| 大模型 / RAG | 腾讯云 ADP（LKE） | 知识库、检索、重排、生成、引用 |
| 流式输出 | SSE（Server-Sent Events） | FastAPI 反向代理 ADP 的 SSE，前端 `EventSource` 接收 |
| 短信 | 腾讯云 SMS（备用阿里云） | 发送登录验证码，需提前报备签名/模板 |
| 对象存储 | 腾讯云 COS | 文档上传中转、截图临时存放 |
| 进程管理 | systemd | FastAPI（uvicorn）以 systemd service 守护 |
| Python 环境 | venv | 应用依赖与系统 Python 隔离，`requirements.txt` 固定版本 |
| 敏感配置 | `.env` 文件 | `BOT_APP_KEY`、SMTP 授权码等通过环境变量注入，权限 600 |
**与原方案相比删除的依赖：**
- Celery / Redis Broker（不再需要后台解析任务）
- pdfplumber / python-docx / openpyxl（不再自解析）
- 阿里云 OCR（ADP 多模态原生支持）
- DeepSeek API 直连（改走 ADP 应用，模型在 ADP 侧选）
- PostgreSQL FTS / tsvector（不再做本地检索）
---
## 七、云端部署架构
```text
用户浏览器
|
HTTPS
|
【单台服务器】
|
Nginx
|
+-- Vue3 静态资源（/var/www/llm_ask）
|
+-- FastAPI（uvicorn，systemd service）
|
+-- PostgreSQL（本机，unix socket 连接）
+-- Redis（本机，127.0.0.1:6379）
+-- 腾讯云 ADP API（外部 SSE）
+-- 对象存储 / COS（截图临时存放，外部）
```
**推荐初期服务器配置：**
- 单台：4 核 8G ECS/CVM 即可（不再有解析任务，资源压力大幅下降）
- PostgreSQL：默认参数即可，数据量小
- Redis：`maxmemory 256mb`，`maxmemory-policy allkeys-lru`
**进程管理（systemd）：**
| 服务 | 启动命令 | 重启策略 |
|------|---------|---------|
| `llm-api` | `uvicorn app.main:app --workers 2 --port 8000` | `Restart=always` |
| `postgresql` | 系统包自带 | `Restart=on-failure` |
| `redis` | 系统包自带 | `Restart=on-failure` |
| `nginx` | 系统包自带 | `Restart=on-failure` |
不再需要 `llm-celery`。
---
## 八、人日重新估算
| 模块 | 原方案 | 新方案 | 备注 |
|---|---:|---:|---|
| 项目初始化 | 2 | 2 | |
| 认证模块 | 6 | **5** | 改手机号 + SMS，比 SMTP 略简 |
| 文档管理后端 | 8 | **3** | 透传 ADP API |
| 问答检索后端 | 7 | **3** | 仅 SSE 代理 + 标签注入 |
| OCR 集成 | 2 | **0** | ADP 多模态原生 |
| ADP 应用配置 + 联调 | — | **3** | 新增：建 KB、配应用、调切分、调 Prompt、调模型 |
| 标签 / 权限映射 | — | **2** | 新增：role → KB 标签规则 |
| 前端登录/注册 | 2 | 2 | |
| 前端对话页 | 7 | **5** | SSE 渲染逻辑略简化 |
| 前端文档管理页 | 3 | 3 | |
| 前端用户管理页 | 2 | **3** | 多了 KB 标签规则页 |
| 审计 / 计量页（可选） | — | 2 | 新增 |
| 集成测试 & 部署 | 5 | 4 | 不再有 Celery 解析任务 |
| Buffer | 6 | 4 | |
| **合计** | **50** | **≈ 41** | |
**工期参考：**
- 1 人独立开发：约 8 周
- 前后端 2 人并行：约 4 周即可上线
---
## 九、风险与对策
| 风险 | 影响 | 对策 |
|---|---|---|
| `bot_app_key` 泄漏 | 任何人都能直接调用应用、消耗 PU | 永远只在后端持有；前端只与我方 SSE 代理交互 |
| 知识库范围隔离失效 | 员工读到管理员级文档 | `custom_variables` 在后端注入，前端不可改；同时在 ADP 侧文档标签强制必填 |
| ADP 计费不可控 | PU 超额、模型调用激增 | usage_log 落库 + 单用户/单日 token 限额 + 异常告警 |
| ADP 故障 / 限流 | 全站不可用 | SSE 代理捕获 5xx 后回退「服务降级提示」，避免裸抛 |
| 厂商锁定 | 后续切换困难 | 把 ADP 调用抽象为 `LLMProvider` 接口，切换混元/百炼/自建 RAG 时只换实现 |
| 数据合规 | 财务/制度文档出企业边界 | 走腾讯云专属企业版 + 私有化区域；敏感文档前端预审 |
---
## 十、与原方案相比的取舍总结
**收益：**
- 工期从约 50 人日降到约 42 人日；并且核心 RAG 风险（解析准确率、检索召回、引用对齐）全部由腾讯云承担
- 文档解析、复杂表格、扫描件 OCR 直接达到工业级
- 模型可灵活切换（DeepSeek / 混元 / GLM / Kimi 等）无需改代码
- 后续要升级到 Agentic RAG / 工作流 / 多智能体，平台已就绪
- 运行时复杂度大幅下降：少一套 Celery、少一套解析依赖、单机资源需求减半
**代价：**
- 新增 PU 订阅与按量费用（按月/按年）
- 知识库与索引数据托管在腾讯云，需评估合规口径
- 与平台耦合，迁移成本较高（用 LLMProvider 抽象部分缓解）
---
## 十一、综合可行性判断与替代路径评估
### 结论：方案可行，且对当前项目是最优解。
**判断依据：**
- 财务/制度类文档对**解析准确率**极敏感（表格、合并单元格、扫描件混排），自研投入产出比最差，ADP 直接到位
- 项目用户量小（公司内部）、并发低，PU 计费完全 cover 得起
- 工期 50 → 41 人日，省下来的人日基本就是检索这块的踩坑预算
- 后期演进到工作流/多智能体（"先查制度再查表单再算金额"），ADP 已原生支持；自研要再投 20+ 人日
### 三个真实风险
**① 厂商锁定**
平台自带的"工作流、Agentic RAG、插件生态"越用越深耦合越紧。一年后想换方案会很痛。
- 对策：SSE 调用层抽象成 `LLMProvider` 接口；应用配置（系统 Prompt、模型选型、切分规则）维护一份**可导出的 YAML 副本**在 git 里，至少保证"知识库内容 + 业务编排"可迁移
**② 数据合规**
财务/科研流程文档进入腾讯云 KB——若有"敏感数据不出企业边界"的硬性合规口径，方案直接死。
- 对策：立项前与合规/法务确认；或采购 ADP 专属版/私有化部署（成本量级会上一层）
**③ "外壳"复杂度被低估**
ADP 的访客模型（`visitor_biz_id` + 标签）面向 ToC 客服场景设计，硬塞我们 ToB 的"角色/部门/密级"权限模型时，标签数会膨胀（dept × level × form 三维），管理成本不低。
- 对策：**第一期把权限做粗**，只用 `level ∈ {public, internal, confidential}` 一个维度；部门粒度二期再加
### 替代路径评估
| 方案 | 评价 | 是否采纳 |
|---|---|---|
| **自建 RAG（原方案）** | 解析坑深、引用对齐难、工期最长 | ✗ 已 pass |
| **腾讯云 LKE 原子能力**（用解析/向量/重排单点 API 自拼） | 比 ADP 灵活，但要自己实现编排+引用回传，回到自研工作量 | ✗ 性价比最差 |
| **Dify / FastGPT / RAGFlow 自部署** | 开源、零厂商锁定，但解析准确率不如 ADP 商业版（财务表格场景明显），且要自己运维向量库 | ✗ 解析瓶颈无法绕过 |
| **阿里百炼 / 字节扣子 / 讯飞星火智能体** | 能力对标 ADP，但下游云资源都在腾讯，没有理由跨云 | ✗ 同等不优 |
| **Coze 专业版** | 偏内容创作和 ToC Bot，企业 RAG 不是它强项 | ✗ 场景不匹配 |
| **腾讯云 ADP（本方案）** | 解析/检索/生成全链工业级、与短信和 COS 同云、可预算 | ✓ **采用** |
### 一条非必须的小优化
如果 admin 端文件管理诉求很轻量（只有上传/删除/标签），**可以不做路线 A，直接给 admin 角色开 ADP 控制台单点登录**——省 3 人日。但代价是 admin 看两个后台、无法叠加业务字段、审计断链。
**仍推荐路线 A**：3 人日换长期产品体验一致和审计能力，划算。
---
## 十二、后期演进路线
1. **多 KB 隔离：** 按部门 / 业务线建多个 ADP 知识库，应用层路由
2. **多智能体编排：** 在 ADP 配置 Workflow / Multi-Agent，处理复杂场景（如先查制度再查表单再算金额）
3. **企业 SSO：** 对接 LDAP / OAuth，替代邮箱注册
4. **私有化部署：** 数据合规进一步收紧时，评估 ADP 专有云或自建 RAG 回退
5. **用量分析：** 未命中问题反哺文档建设；高频问题做 FAQ 沉淀；按部门分摊 PU 成本
---
## 参考资料
- [腾讯云智能体开发平台（ADP）产品页](https://cloud.tencent.com/product/adp)
- [ADP 文档概述](https://cloud.tencent.com/document/product/1759/112702)
- [对话端接口文档（HTTP SSE）](https://cloud.tencent.com/document/product/1759/105561)
- [应用接入业务系统操作指南](https://cloud.tencent.com/document/product/1759/125067)
- [API 概览](https://cloud.tencent.com/document/api/1759/105114)
- [知识库操作指南](https://cloud.tencent.com/document/product/1759/119282)
- [计费概述（套餐订阅）](https://cloud.tencent.com/document/product/1759/127342)
- [LKE × DeepSeek 企业应用接入手册](https://blog.csdn.net/csdn565973850/article/details/146488631)
- [ADP 流式 API 接入实践](https://cloud.tencent.com/developer/article/2585684)
Reference in New Issue View Git Blame Copy Permalink