21 KiB

Raw Permalink Blame History

大模型智能问答客服系统 · 基于腾讯云 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 图片格式，平台自带多模态识别

外层应用要做的，是「用户体系 + 业务编排 + 调用治理」这一壳层：

企业用户体系：邮箱注册/登录、验证码、JWT、角色、白名单域名、禁用即时生效——ADP 的 visitor_biz_id 只是访客 ID，没有真正的账号体系。
会话历史持久化：ADP session 主要服务多轮上下文，长期、跨设备的"我的会话列表"应在我们这边落库，便于审计、按用户筛选、合规留存。
SSE 代理转发：浏览器不能直接用 bot_app_key 调 ADP（密钥泄漏风险），必须经过我们的后端代理，并在代理层做鉴权、限流、日志、留存。
知识库范围权限：哪个角色/部门可看哪些文档，要在我们这边映射到 custom_variables（标签匹配）。
管理员能力外壳：用户管理；文档管理可选「内嵌 ADP 控制台 / 我们包一层 ADP API」二选一。
审计与统计：未命中、低置信、热门问题、Token 消耗，用于费用治理。

三、用户角色

角色	权限
`employee`（员工/外部合作方）	对话问答、查看本人历史会话
`admin`（管理员）	文档上传/删除/管理、用户管理（创建/角色分配/禁用）、KB 标签规则配置

四、整体架构

用户浏览器 (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）

上传链路设计：

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 反向代理。

浏览器 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 数据模型（大幅瘦身）

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（不再做本地检索）

七、云端部署架构

用户浏览器
    |
  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 人日换长期产品体验一致和审计能力，划算。

十二、后期演进路线

多 KB 隔离： 按部门 / 业务线建多个 ADP 知识库，应用层路由
多智能体编排： 在 ADP 配置 Workflow / Multi-Agent，处理复杂场景（如先查制度再查表单再算金额）
企业 SSO： 对接 LDAP / OAuth，替代邮箱注册
私有化部署： 数据合规进一步收紧时，评估 ADP 专有云或自建 RAG 回退
用量分析： 未命中问题反哺文档建设；高频问题做 FAQ 沉淀；按部门分摊 PU 成本

21 KiB Raw Permalink Blame History Unescape Escape