# 大模型智能问答客服系统 · 基于腾讯云 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)