zcdsj
/
llm_ask
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial project documentation

This commit is contained in:
caoqianming 2026-05-06 10:37:22 +08:00
commit 570d0f5311
8 changed files with 1495 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
.gitignore vendored Normal file
View File

@ -0,0 +1,11 @@
# Local helper scripts
cl.bat
col.bat
# Local Claude settings
.claude/settings.local.json
# Keep only Superpowers project specs under docs
docs/*
!docs/superpowers/
!docs/superpowers/**

311
docs/superpowers/specs/2026-03-31-llm-qa-system-design.md Normal file
View File

@ -0,0 +1,311 @@
# 大模型智能问答客服系统系统设计文档
**日期：** 2026-03-31
**状态：** 已确认
**技术栈：** Python / FastAPI / Vue3 / DeepSeek / PostgreSQL / Redis
---
## 一、项目背景与目标
将企业内部的报销制度、软件操作手册、财务/科研流程、常见问题汇总等文档接入大模型，构建一套智能问答客服系统。用户可以用自然语言提问，系统给出答案并注明引用来源；支持上传截图辅助提问。
**核心目标：**
- 文档知识库化，降低重复人工咨询成本
- 答案可追溯，每条回答标注来源文档、章节、页码或段落
- 支持截图上传，辅助描述操作类问题
- 管理员可自助维护文档，无需开发介入
**本期检索策略目标：**
- 前期不引入向量数据库与 embedding
- 以“先选文档，再选章节，再定位段落”为主链路，优先保证准确率和可解释性
- 允许用大模型对候选文档和章节做重排，但不让大模型承担全库检索职责
---
## 二、用户角色
| 角色 | 权限 |
|------|------|
| `employee`（员工/外部合作方） | 对话问答、查看本人历史会话 |
| `admin`（管理员） | 文档上传/删除/管理、用户管理（创建/角色分配/禁用） |
---
## 三、整体架构
```text
用户浏览器
├─ 员工：问答 + 截图上传
└─ 管理员：文档上传 / 文档管理 / 用户管理
│
▼
FastAPI 后端
├─ 认证模块
├─ 对话问答模块
├─ 文档管理模块
└─ 检索编排模块
│
├─ PostgreSQL
│ ├─ 用户/会话/消息
│ ├─ 文档元数据
│ ├─ 文档章节索引
│ └─ 文档段落索引
│
├─ Redis
│ ├─ 验证码 / 速率限制
│ └─ Celery Broker / Cache
│
├─ 本地文件系统
│ ├─ 原始文档
│ └─ 解析后的规范化文本
│
├─ DeepSeek Chat
│ ├─ 候选文档/章节重排
│ └─ 基于引用片段生成答案
│
└─ 阿里云 OCR
└─ 截图文字识别
```
---
## 四、核心模块设计
### 4.1 认证模块
- **账号名：** 邮箱地址
- **注册管控：** 关闭完全开放的自助注册；支持两种方式创建账号：
- 管理员后台手动创建（指定角色）
- 邮箱自助注册（仅限白名单域名，如 `@company.com`，可配置），默认角色 `employee`
- **登录方式：**
- 邮箱 + 密码
- 邮箱 + 验证码（6位数字，5分钟有效，存 Redis）
- **验证码防刷：**
- 同一邮箱 60 秒内不可重复发送
- 同一 IP 每小时限制 10 次
- **Token 机制：**
- Access Token（JWT）：有效期 2 小时
- Refresh Token：有效期 7 天，存 Redis，可主动吊销
- 管理员禁用账号时，将该账号现有 Token 加入 Redis 黑名单，立即失效
- **邮件服务：** QQ 邮箱 SMTP（`smtp.qq.com:465`，SSL，授权码鉴权）
### 4.2 文档管理模块
| 功能 | 说明 |
|------|------|
| 上传 | 支持 PDF、Word(.docx)、Excel(.xlsx)，单文件限制 50MB；服务端验证 Magic Bytes + 扩展名双重校验 |
| 原始文件存储 | 原始文件保存到本地文件系统，按文档 ID / 版本号分目录存放 |
| 解析 | PDF 用 `pdfplumber`，Word 用 `python-docx`，Excel 按 Sheet 转为规范化文本或 Markdown 表格 |
| 结构化 | 解析后生成三级结构：`document`、`section`、`chunk`；章节标题、层级、页码范围、段落顺序均保留 |
| 规范化文本落盘 | 每份文档额外保存解析后的文本产物，便于调试、离线检查和兜底检索 |
| 索引入库 | 文档标题、文件名、标签、章节标题、段落正文、来源位置全部写入 PostgreSQL |
| 异步处理 | Celery + Redis；上传后后台解析、结构化、索引化，前端显示状态 |
| 状态机 | `pending` -> `processing` -> `active` / `failed` |
| 删除 | 先将文档标记 `deleting`，再删索引、删解析文本、删原始文件，任一步失败均可幂等重试 |
| 更新（版本切换） | 新版本先入库为 `pending`；索引就绪后原子切换为 `active`，旧版本转 `superseded` |
**结构化原则：**
- 文档级：文件名、别名、标签、摘要
- 章节级：目录项、一级/二级/三级标题、页码范围、Sheet 名称
- 段落级：正文、表格文本、所属章节、顺序号、来源位置
### 4.3 问答检索模块
本期不使用向量检索，主链路采用“规则召回 + 大模型重排 + 段落精定位”。
**问答流程（SSE 流式输出）：**
```text
用户输入（文本 + 可选截图）
-> OCR 识别截图文字（阿里云 OCR）
-> 合并为最终 Query 文本
-> Query 归一化（术语、别名、关键词、数字、表单名）
-> 文档候选召回（文件名 + 标签 + 文档摘要 + FTS）
-> 章节候选召回（目录项/章节标题/小节标题 + FTS）
-> 大模型重排候选文档与章节
-> 在最终候选章节内做段落精定位
-> 取命中段落及相邻段扩展上下文
-> 组装 Prompt（系统提示 + 引用片段 + 历史 5 轮 + 用户问题）
-> 调用 DeepSeek Chat API（SSE 流式输出）
-> 返回答案 + 引用来源（文档名 + 章节标题 + 页码/段落号）
```
**设计原则：**
- 大模型只负责候选重排，不负责全库检索
- 先缩小范围，再精确定位，优先提升召回准确率
- 只在少量明确候选章节中做正文定位，避免把无关文档片段带进 Prompt
- 若未命中足够可信的文档/章节，明确回答“未在当前知识库中找到依据”
**查询归一化：**
- 术语同义词映射，如“报销/报账”“出差/差旅”“附件/上传材料”
- 抽取数字、金额、日期、制度名、表单名
- 去除无意义停用词，保留关键短语
**候选控制：**
- 文档候选最多 5 个
- 章节候选最多 8 到 12 个
- 大模型重排后仅保留 1 到 3 个章节
- 最终送入生成模型的正文片段控制在 6 到 12 段
**Prompt 设计原则：**
- 模型只能基于提供的引用片段回答
- 依据不足时必须明确说不知道或未找到
- 在答案末尾输出引用片段编号，系统映射成文档名、章节、页码或段落号
- 多轮对话只携带最近 5 轮历史
**后期扩展点：**
- 检索层抽象为 `RetrieverInterface`
- 重排层抽象为 `RerankerInterface`
- 后期可平滑增加 BM25 增强、RRF 融合、向量检索、Reranker 模型
### 4.4 数据模型（核心表）
```text
users
id, email, hashed_password, role, is_active, created_at
refresh_tokens
id, user_id, token_hash, expires_at, revoked
token_blacklist
jti, expires_at
documents
id, name, file_path, normalized_text_path, status, version_num,
supersedes_id, created_by, created_at, summary, tags_json
document_aliases
id, document_id, alias
document_sections
id, document_id, parent_section_id, title, level,
page_start, page_end, section_order, title_tokens
doc_chunks
id, document_id, section_id, chunk_index, text,
source_location, page_no, paragraph_no, tsv
conversations
id, user_id, title, created_at
messages
id, conversation_id, role, content, sources_json, created_at
```
**说明：**
- `documents.summary` 用于文档候选粗筛和大模型重排输入
- `document_sections` 是本期准确率的关键索引层
- `doc_chunks.tsv` 用于 PostgreSQL 全文检索
- `source_location` 统一映射为“页码 / 段落号 / Sheet 名称 / 章节路径”
### 4.5 前端页面
| 页面 | 访问角色 | 核心功能 |
|------|---------|---------|
| 登录/注册页 | 所有人 | 双模式登录、邮箱注册（白名单域名）、验证码发送 |
| 对话页 | employee / admin | 左侧会话列表、右侧 SSE 流式对话、截图上传、引用来源展示 |
| 文档管理页 | admin | 文档列表、上传、删除、解析状态查看、版本切换状态 |
| 用户管理页 | admin | 用户列表、创建账号、角色分配、禁用（即时生效） |
---
## 五、技术选型
| 层次 | 选型 | 说明 |
|------|------|------|
| 前端 | Vue3 + Element Plus | 成熟后台组件生态 |
| 后端 | FastAPI + Python 3.11 | 异步支持较好，适合 AI 服务编排 |
| 关系数据库 | PostgreSQL | 存用户、会话、文档元数据、章节索引、段落索引；支持 FTS |
| 缓存 / 队列 | Redis | 验证码、黑名单、限流、Celery Broker |
| 文件存储 | 本地文件系统 | 存原始文档与解析后的规范化文本，挂载独立数据盘 |
| 异步任务 | Celery + Redis | 文档解析、结构化、索引化后台执行 |
| 检索方式 | PostgreSQL FTS + 规则打分 | 前期不引入向量库，优先准确率与可解释性 |
| 重排方式 | DeepSeek Chat | 对候选文档与章节做小范围重排 |
| OCR | 阿里云 OCR | 截图文字识别 |
| 生成模型 | DeepSeek Chat | 基于引用片段生成答案 |
| 流式输出 | SSE（Server-Sent Events） | FastAPI 原生支持，前端 `EventSource` 接收 |
| 邮件 | QQ 邮箱 SMTP（465/SSL） | 发送验证码，额外成本低 |
| 进程管理 | systemd | FastAPI（uvicorn）、Celery Worker 均以 systemd service 守护 |
| Python 环境 | venv | 应用依赖与系统 Python 隔离，`requirements.txt` 固定版本 |
| 敏感配置 | `.env` 文件 | API Key、SMTP 授权码、OCR Key 等全部通过环境变量注入，文件权限 600 |
---
## 六、云端部署架构
所有服务部署在同一台物理服务器上，通过 systemd 管理各进程，无需容器化。
```text
用户浏览器
|
HTTPS
|
【同一台服务器】
|
Nginx
|
+-- Vue3 静态资源（/var/www/llm_ask）
|
+-- FastAPI（uvicorn，systemd service）
|
+-- PostgreSQL（本机，unix socket 连接）
+-- Redis（本机，127.0.0.1:6379）
+-- Celery Worker（systemd service，concurrency=2）
+-- 本地文件系统（独立数据盘挂载点，如 /data/llm_ask）
+-- DeepSeek API（外部）
+-- 阿里云 OCR API（外部）
```
**推荐初期服务器配置：**
- 单台服务器：8核16G ECS/CVM
- PostgreSQL、Redis、FastAPI、Celery、Nginx 全部同机部署
- 数据盘单独挂载（存文档文件），系统盘与数据分离
- PostgreSQL 调优：`shared_buffers = 2GB`，`effective_cache_size = 6GB`
- Redis 限制：`maxmemory 512mb`，`maxmemory-policy allkeys-lru`
- Celery：`--concurrency=2`，避免文档解析时内存峰值压垮其他服务
**进程管理（systemd）：**
| 服务 | 启动命令 | 重启策略 |
|------|---------|---------|
| `llm-api` | `uvicorn app.main:app --workers 2 --port 8000` | `Restart=always` |
| `llm-celery` | `celery -A app.worker worker --concurrency=2` | `Restart=always` |
| `postgresql` | 系统包自带 | `Restart=on-failure` |
| `redis` | 系统包自带 | `Restart=on-failure` |
| `nginx` | 系统包自带 | `Restart=on-failure` |
---
## 七、人日估算
| 模块 | 工作内容 | 人日 |
|------|---------|:----:|
| 项目初始化 | 目录结构、venv、systemd service 模板、`.env` 规范 | 2 |
| 认证模块 | 邮箱注册/登录、验证码、防刷、JWT、Refresh Token、角色权限 | 6 |
| 文档管理后端 | 上传、校验、解析、结构化、章节索引、段落索引、状态机、补偿删除、版本切换 | 8 |
| 问答检索后端 | Query 归一化、文档召回、章节召回、LLM 重排、段落精定位、Prompt 组装、SSE 输出 | 7 |
| OCR 集成 | OCR 接入、与 Query 合并 | 2 |
| 前端：登录/注册 | 双模式登录、注册、验证码交互 | 2 |
| 前端：对话页 | 会话列表、SSE 流式渲染、截图上传、引用来源展示 | 7 |
| 前端：文档管理页 | 上传、列表、处理状态轮询、删除 | 3 |
| 前端：用户管理页 | 用户列表、创建、角色分配、禁用 | 2 |
| 集成测试 & 部署 | 云端部署、域名、SSL、systemd 服务配置、联调 | 5 |
| Buffer | 调试、需求微调、第三方 API 联调 | 6 |
| **合计** | | **50** |
**工期参考：**
- 1 人独立开发：约 9 到 10 周
- 前后端 2 人并行：约 5 到 6 周可上线基础版本
- 后期升级到混合检索：额外约 5 到 8 人日
---
## 八、后期演进路线
1. **检索增强：** 从 PostgreSQL FTS 升级到 BM25 / 更细粒度规则打分
2. **混合检索：** 在现有 `RetrieverInterface` 基础上增加向量检索，与词法检索融合
3. **重排增强：** 用专门的 reranker 模型替代通用聊天模型做候选重排
4. **文件存储迁移：** 本地文件系统迁移到阿里云 OSS
5. **SSO 集成：** 对接企业 LDAP / 统一认证
6. **用量统计：** 统计问答次数、热门问题、未命中问题、低置信问题

BIN
docs/superpowers/specs/2026-03-31-llm-qa-system-design.pdf Normal file
View File

Binary file not shown.

BIN
docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.docx Normal file
View File

Binary file not shown.

285
docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.md Normal file
View File

@ -0,0 +1,285 @@
# 大模型智能问答客服系统 · 产品与实施方案（甲方版）
**日期：** 2026-04-30
**版本：** v1.0
**面向对象：** 甲方业务负责人、信息化负责人、项目管理人员
**建设方式：** 自研业务门户 + 腾讯云智能体开发平台 ADP
---
## 一、建设背景
企业内部存在大量财务制度、报销规范、科研流程、系统操作手册和常见问题材料。员工在办理报销、填报系统、查询制度时，经常需要人工咨询财务、行政或系统管理员，重复问题多、响应不稳定、知识更新依赖人工传达。
本项目拟建设一套大模型智能问答客服系统，将企业内部文档统一纳入知识库。员工可以像日常聊天一样提问，系统基于正式文档自动生成答案，并展示引用来源，帮助员工快速找到制度依据和操作步骤。
---
## 二、建设目标
本期建设目标包括：
- 建立统一的企业知识问答入口
- 支持员工用自然语言查询制度、流程和操作问题
- 回答内容提供来源文档，便于追溯和核验
- 支持上传截图辅助描述系统操作问题
- 管理员可自行上传、更新、删除知识文档
- 支持账号管理、权限控制、问答留痕和用量统计
本项目不以替代制度原文为目标。系统回答用于提高查询效率，关键事项仍以正式制度文件和业务部门解释为准。
---
## 三、总体方案
系统采用「业务门户 + 腾讯云 ADP 知识问答能力」的建设方式。
```text
员工 / 管理员
|
智能问答客服系统
|-- 登录认证
|-- 智能问答
|-- 会话历史
|-- 文档管理
|-- 用户管理
|-- 审计统计
|
腾讯云 ADP
|-- 文档解析
|-- 知识库
|-- 智能检索
|-- 大模型生成
+-- 引用来源返回
```
腾讯云 ADP 负责底层大模型、知识库、文档解析、智能检索和引用来源。项目自研部分负责企业用户登录、权限、文档管理页面、问答页面、审计和业务集成。
这种方式相比完全自研 RAG 系统，建设周期更短，文档解析能力更成熟，后续也便于扩展智能体、工作流和多模型能力。
---
## 四、用户角色
| 角色 | 主要能力 |
|---|---|
| 普通员工 | 登录系统、发起问答、上传截图、查看本人历史会话、查看答案来源 |
| 管理员 | 上传和维护文档、管理用户、配置文档可见范围、查看问答和用量统计 |
---
## 五、功能范围
### 5.1 员工端功能
| 功能 | 说明 |
|---|---|
| 手机号登录 | 使用手机号和短信验证码登录，无需记忆密码 |
| 智能问答 | 输入自然语言问题，系统基于知识库生成答案 |
| 流式回答 | 答案逐步输出，减少等待感 |
| 来源引用 | 展示答案依据的文档名称、片段或链接 |
| 截图提问 | 上传操作截图，辅助描述报错、页面或流程问题 |
| 历史会话 | 查看本人历史问答记录 |
### 5.2 管理员端功能
| 功能 | 说明 |
|---|---|
| 用户管理 | 创建用户、设置角色、禁用账号 |
| 文档上传 | 上传制度、手册、FAQ 等资料 |
| 文档维护 | 查看解析状态，修改名称和标签，删除过期文档 |
| 密级管理 | 按公开、内部、保密等等级控制可见范围 |
| 问答审计 | 查看用户问答记录，用于问题追踪和知识优化 |
| 用量统计 | 统计问答次数、Token / PU 消耗和热点问题 |
---
## 六、知识范围
本期建议接入以下类型文档：
- 财务报销制度
- 差旅费、会议费、采购、合同等管理办法
- 报账平台操作手册
- 科研项目流程说明
- 常见问题 FAQ
- 业务部门确认可公开给目标用户查询的制度文件
不建议第一期接入：
- 未经确认的历史草稿
- 含个人隐私、薪酬、敏感科研数据的材料
- 权限边界不清晰的内部文件
- 没有责任部门维护的过期文档
---
## 七、权限与安全
### 7.1 登录安全
- 用户通过手机号和短信验证码登录
- 默认关闭开放注册，由管理员创建账号
- 管理员可禁用离职或不再使用系统的账号
- 验证码设置发送频率限制，防止恶意刷短信
### 7.2 文档可见范围
第一期建议按文档密级控制：
| 密级 | 说明 | 建议可见角色 |
|---|---|---|
| 公开 | 全员可查询的制度、手册和 FAQ | 普通员工、管理员 |
| 内部 | 企业内部员工可查询的管理文件 | 普通员工、管理员 |
| 保密 | 仅管理员或指定角色可查询 | 管理员或授权人员 |
所有上传文档必须选择密级。未设置密级的文档不进入正式知识库，避免权限边界不清导致误答。
### 7.3 数据安全
- 大模型应用密钥只保存在服务端，不暴露给浏览器
- 用户问题、答案、引用来源和操作记录保存在业务系统中
- 截图使用短期访问链接，仅供本次问答识别
- 重要文档是否允许进入云端知识库，需由甲方完成合规确认
---
## 八、实施步骤
### 阶段一：准备与确认
预计 3-5 个工作日。
- 确认首批知识文档范围
- 确认用户角色和文档密级规则
- 开通腾讯云 ADP、COS、SMS 等服务
- 完成短信签名和模板报备
- 确认部署服务器、域名和 HTTPS 证书
### 阶段二：系统开发
预计 3-4 周。
- 搭建前后端基础框架
- 完成手机号登录和用户管理
- 完成问答页面和流式回答
- 接入 ADP 对话接口和引用来源展示
- 完成文档上传、解析状态、删除和标签维护
- 完成会话历史、审计和基础用量统计
### 阶段三：知识库配置与联调
预计 1 周。
- 导入首批文档
- 配置 ADP 知识库、模型、Prompt 和检索规则
- 调整文档切片和回答口径
- 验证引用来源准确性
- 验证不同角色的可见范围
### 阶段四：试运行与验收
预计 1-2 周。
- 选择小范围用户试运行
- 收集无答案、答错、引用不准等问题
- 优化 FAQ 和知识文档
- 完成权限、安全、性能和功能验收
- 形成上线交付材料
---
## 九、交付内容
| 类别 | 交付物 |
|---|---|
| 系统功能 | 员工问答端、管理员后台、文档管理、用户管理、审计统计 |
| 知识库 | 首批文档导入、标签配置、ADP 应用配置 |
| 部署环境 | 前端、后端、数据库、缓存、Nginx、HTTPS |
| 文档资料 | 操作手册、部署说明、管理员使用说明、验收测试记录 |
| 培训支持 | 管理员培训、试运行问题处理、上线支持 |
---
## 十、项目周期与投入
在资料、账号、云资源和甲方确认流程配合顺畅的情况下，预计周期为：
| 人员配置 | 周期 |
|---|---|
| 1 名全栈开发为主 | 约 8-10 周 |
| 前端 + 后端 2 人并行 | 约 5-6 周 |
工作量估算约 55 人日。实际周期受以下因素影响：
- 首批文档数量和质量
- 文档密级和权限规则复杂度
- 短信签名、域名、服务器等资源开通速度
- 甲方试运行反馈和验收流程
- 是否增加企业微信、飞书、LDAP 等单点登录
---
## 十一、甲方配合事项
| 事项 | 说明 |
|---|---|
| 提供首批文档 | 建议先提供 20-50 份高频制度和操作手册 |
| 指定业务负责人 | 负责确认回答口径、制度有效性和优先级 |
| 指定管理员 | 负责后续文档上传、更新和用户维护 |
| 确认数据合规 | 明确哪些文档可以进入云端知识库 |
| 开通云资源 | ADP、COS、SMS、服务器、域名、证书 |
| 参与试运行 | 提供典型问题，反馈答错、漏答和引用问题 |
---
## 十二、验收建议
建议从以下维度验收：
| 维度 | 验收方式 |
|---|---|
| 登录与权限 | 不同角色账号登录，验证可见文档范围 |
| 问答准确性 | 准备 50-100 个典型问题，检查答案和引用 |
| 文档维护 | 管理员上传、修改、删除文档并验证生效 |
| 截图问答 | 上传典型系统截图，验证识别和回答效果 |
| 审计留痕 | 检查问答记录、引用、用户操作和用量统计 |
| 异常处理 | 模拟无答案、服务异常、权限不足等场景 |
问答类系统不建议以“100% 准确回答所有问题”作为验收标准。更合理的标准是：高频、明确、有文档依据的问题能稳定回答；无依据或权限不足的问题能明确拒答或提示联系人工。
---
## 十三、主要风险与应对
| 风险 | 说明 | 应对 |
|---|---|---|
| 文档质量不稳定 | 旧制度、扫描件、重复版本会影响回答质量 | 上线前清理文档，指定责任部门维护 |
| 答案口径争议 | 制度解释可能涉及业务判断 | 以引用来源为准，关键事项保留人工确认入口 |
| 权限配置错误 | 文档密级配置不当可能造成误检索 | 强制密级、管理员复核、权限测试 |
| 云端合规要求 | 部分资料可能不允许进入云端知识库 | 立项前完成合规确认，必要时采用专属版或私有化 |
| 使用费用波动 | 问答量增加会带来模型或 PU 消耗 | 设置用量统计、限额和告警 |
| 平台依赖 | 底层依赖腾讯云 ADP | 保留原始文档和业务数据，关键配置形成备份 |
---
## 十四、后续扩展
系统稳定运行后，可按需扩展：
- 接入企业微信、飞书或统一身份认证
- 按部门建立独立知识库
- 建立高频问题 FAQ，提升回答速度和稳定性
- 接入业务系统数据，支持报销单状态、流程进度等查询
- 增加智能工单，在无法回答时自动转人工处理
- 引入多智能体工作流，处理“先查制度、再查表单、再给办理建议”的复杂场景
---
## 十五、方案总结
本方案以腾讯云 ADP 作为知识问答底座，自研企业业务门户，兼顾建设效率、文档解析能力、权限治理和后续扩展。
相比完全自研，本方案降低了文档解析、检索和引用对齐的技术风险；相比直接使用平台控制台，本方案保留了企业用户管理、文档权限、审计留痕和统一门户体验。
建议第一期聚焦财务制度、报销流程和操作手册等高频场景，先小范围试运行，再逐步扩展文档范围和用户范围。

BIN
docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.pdf Normal file
View File

Binary file not shown.

449
docs/superpowers/specs/2026-04-30-llm-qa-system-design-adp.md Normal file
View File

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

439
docs/superpowers/specs/2026-04-30-llm-qa-system-technical-plan-adp.md Normal file
View File

@ -0,0 +1,439 @@
# 大模型智能问答客服系统 · 技术方案（腾讯云 ADP 版）
**日期：** 2026-04-30
**版本：** v1.0
**面向对象：** 技术评审、开发实施、运维部署
**技术栈：** Python / FastAPI / Vue3 / Element Plus / 腾讯云 ADP / 腾讯云 SMS / 腾讯云 COS / PostgreSQL / Redis
---
## 一、方案结论
本项目采用「腾讯云 ADP 提供知识库、文档解析、检索、生成和引用；自研业务系统提供账号、权限、会话、审计和调用代理」的架构。
不再自研文档解析、OCR、切片、向量化、召回、重排和引用对齐。自研系统只保留企业应用必须具备、且 ADP 不适合直接承担的能力：
- 手机号短信验证码登录、JWT、账号禁用和角色控制
- 用户会话和问答消息长期留存
- ADP SSE 接口代理，避免 `bot_app_key` 暴露到浏览器
- 文档上传、标签、密级、解析状态和审计管理
- 基于角色的知识库标签过滤
- Token / PU 用量记录、限额和告警
该路径能显著降低 RAG 自研风险，尤其适合财务制度、报销流程、操作手册等复杂文档问答场景。
---
## 二、系统边界
### 2.1 ADP 负责
| 能力 | 说明 |
|---|---|
| 文档解析 | PDF、Word、Excel、图片等文档解析，包含 OCR 和结构化处理 |
| 知识切片 | 按 ADP 应用配置完成切片、索引和向量化 |
| 知识检索 | RAG / Agentic RAG、多轮检索、召回和重排 |
| 答案生成 | 由 ADP 应用绑定模型、Prompt 和工作流 |
| 引用来源 | 通过 SSE `reference` 事件返回文档、片段、URL 等来源信息 |
| 文档 OpenAPI | 文档上传、列表、详情、修改、删除、解析重试、预览等 |
| 多模态理解 | 截图通过 Markdown 图片 URL 传入 `content`，由 ADP 识别 |
### 2.2 自研系统负责
| 模块 | 说明 |
|---|---|
| 认证与用户 | 手机号 + 短信验证码登录，管理员创建账号，角色和禁用状态 |
| 权限治理 | 将用户角色转换为 ADP `custom_variables`，控制可检索标签范围 |
| 会话留存 | 保存会话、问题、答案、引用、模型、Token、PU 消耗 |
| SSE 代理 | 后端持有 `bot_app_key`，统一鉴权、限流、转发和错误处理 |
| 文档管理 | 包装 ADP 文档 API，叠加业务字段、标签校验和审计日志 |
| 统计审计 | 用户用量、热门问题、失败请求、未命中问题、费用统计 |
---
## 三、总体架构
```text
用户浏览器（Vue3 + Element Plus）
|
HTTPS
|
Nginx
|
FastAPI 业务后端
|-- 认证模块：手机号 / 短信验证码 / JWT / Refresh Token
|-- 用户权限模块：角色 / 账号禁用 / KB 标签规则
|-- 会话模块：会话列表 / 消息落库 / 引用落库
|-- 对话代理模块：POST 流式接口 -> ADP SSE
|-- 文档管理模块：透传并包装 ADP 文档 OpenAPI
|-- 审计计量模块：Token / PU / 错误 / 操作日志
|
|-- PostgreSQL：业务数据
|-- Redis：验证码、限流、Token 黑名单
|-- 腾讯云 COS：文档上传中转、截图临时存储
|
+-- 腾讯云 ADP
|-- 知识库：文档、标签、切片、索引
|-- 应用：模型、Prompt、工作流、检索配置
|-- 对话接口：/v1/qbot/chat/sse
+-- 文档管理 API
```
---
## 四、认证与账号设计
### 4.1 登录方式
- 唯一登录方式：手机号 + 短信验证码
- 手机号格式：默认中国大陆 `+86`，字段预留 `country_code`
- 自助注册：默认关闭
- 账号创建：由管理员后台创建用户，指定姓名、手机号、角色和状态
### 4.2 验证码规则
- 6 位数字验证码
- Redis 保存，5 分钟有效
- 同一手机号 60 秒内不可重复发送
- 同一手机号 24 小时最多 10 次
- 同一 IP 每小时最多 10 次
- 单 IP 单小时超过 5 次后要求图形验证码
### 4.3 Token 规则
- Access Token：JWT，2 小时有效
- Refresh Token：7 天有效，只保存哈希值
- 管理员禁用账号后，现有 Token 加入 Redis 黑名单并立即失效
- Refresh Token 支持主动吊销和单用户全量吊销
---
## 五、文档管理设计
### 5.1 采用路线
采用「自研后台包装 ADP 文档 OpenAPI」路线。业务管理员不直接进入 ADP 控制台，所有文档管理都在本系统完成。
这样做的原因：
- 统一产品体验
- 能叠加部门、密级、上传人、审计状态等业务字段
- 能在上传前强制校验标签和权限
- 后续切换底层 RAG 服务时，前端接口可保持稳定
### 5.2 核心 ADP 接口
| 接口 | 用途 |
|---|---|
| `DescribeStorageCredential` | 获取 COS 临时上传凭证 |
| `SaveDoc` | 文件上传完成后保存到 ADP 知识库 |
| `ListDoc` | 查询文档列表 |
| `DescribeDoc` | 查询文档详情和解析状态 |
| `ModifyDoc` | 修改文档属性和标签 |
| `RenameDoc` | 重命名文档 |
| `DeleteDoc` | 删除文档 |
| `RetryDocParse` | 重试解析失败文档 |
| `StopDocParse` | 停止解析任务 |
| `GetDocPreview` | 获取文档预览 |
| `DescribeSegments` | 查询切片，供调试和验收使用 |
| `CreateQA` / `ListQA` / `ModifyQA` / `DeleteQA` | FAQ 问答库维护 |
### 5.3 上传链路
```text
1. 管理员选择文件
2. 前端调用 /api/docs/upload-credential
3. 后端鉴权，调用 ADP DescribeStorageCredential
4. 前端使用临时凭证直传 COS
5. 前端调用 /api/docs/save，提交文件 URL、名称、密级、标签
6. 后端校验标签，调用 ADP SaveDoc
7. 后端写入 documents_meta 和操作日志
8. 前端轮询 /api/docs/{id}，展示解析状态
```
### 5.4 标签与密级
第一期只使用一个强制标签维度：
```text
level = public | internal | confidential
```
建议规则：
- `employee` 可检索：`public`、`internal`
- `admin` 可检索：`public`、`internal`、`confidential`
- 文档上传和修改时必须填写 `level`
- 未打标签文档不得发布到可检索知识库
- 每日巡检 ADP 文档列表，发现空标签、异常标签立即告警
注意：ADP 按标签过滤时，需确认平台对「未打标签知识」的处理策略。为避免权限绕过，本系统必须从业务流程上禁止未打标签文档进入正式知识库。
---
## 六、问答代理设计
### 6.1 前后端交互
不采用 `EventSource GET /api/chat/sse?content=...` 承载问题内容。原因是问题文本、截图 URL 和上下文可能较长，放在 query 中存在 URL 长度、日志泄漏和编码问题。
推荐采用：
```text
前端 fetch POST /api/chat/stream
body: {
conversation_id,
content,
image_ids[]
}
后端 POST ADP /v1/qbot/chat/sse
前端通过 ReadableStream 消费后端返回的流
```
如浏览器兼容性要求必须使用 EventSource，可改成两段式：
```text
POST /api/chat/request 创建请求，返回 request_id
GET /api/chat/sse 只携带 request_id 订阅流
```
### 6.2 ADP 请求组装
后端负责组装 ADP 请求体：
```json
{
"bot_app_key": "${BOT_APP_KEY}",
"session_id": "adp-session-id",
"visitor_biz_id": "user-id",
"content": "用户问题 + Markdown 图片 URL",
"custom_variables": {
"level": ["public", "internal"]
},
"streaming_throttle": 5
}
```
其中：
- `bot_app_key` 只保存在后端环境变量
- `visitor_biz_id` 使用我方用户 ID
- `session_id` 与我方 `conversations.adp_session_id` 绑定
- `custom_variables` 由后端根据角色计算，前端不可传入或覆盖
### 6.3 SSE 事件处理
后端需要处理并落库的事件：
| 事件 | 处理方式 |
|---|---|
| `reply` | 增量转发给前端，并拼接完整答案 |
| `reference` | 保存引用来源，前端用于展示来源文档 |
| `token_stat` | 保存输入、输出、PU 消耗 |
| `thought` | 默认不展示给普通用户，可配置为调试模式展示 |
| `error` | 映射为业务错误码，记录日志并返回友好提示 |
### 6.4 中断与一致性
- 用户主动取消时，后端停止读取 ADP 流
- 浏览器断开时，后端关闭上游连接
- 若回答未完成，消息状态标记为 `interrupted`
- 若 ADP 返回错误，消息状态标记为 `failed`
- 完整回答、引用和 Token 统计应在同一事务或可恢复流程中写入
---
## 七、截图上传设计
截图不再接入本地 OCR。处理方式：
```text
1. 前端上传截图到我方 COS 临时目录
2. 后端生成 5 分钟有效的签名 URL
3. 发送问题时，将图片以 Markdown 格式拼入 content
4. ADP 读取图片并完成多模态理解
5. 我方消息表保存内部对象 key，不长期保存临时 URL
```
安全要求：
- 截图与正式文档分桶或分目录存储
- 截图对象设置生命周期，默认 7-30 天清理
- 临时 URL 只用于本次 ADP 调用
- 历史会话回看如需展示截图，由我方重新签发短期 URL
- 敏感截图是否允许进入 ADP 多模态识别，应由甲方合规确认
---
## 八、数据模型
```text
users
id, phone, country_code, external_id, role, is_active,
display_name, created_at, updated_at
sms_codes
phone, code_hash, scene, expires_at, attempts
refresh_tokens
id, user_id, token_hash, expires_at, revoked_at, created_at
token_blacklist
jti, expires_at
conversations
id, user_id, title, adp_session_id, created_at, updated_at
messages
id, conversation_id, role, content, status,
sources_json, adp_request_id, token_in, token_out,
pu_cost, model_name, created_at
documents_meta
id, adp_doc_id, name, level, tags_json, status,
uploaded_by, uploaded_at, updated_at
role_kb_label_rules
id, role, label_key, label_values_json, updated_at
usage_log
id, user_id, conversation_id, message_id,
token_in, token_out, pu_cost, created_at
operation_logs
id, actor_id, action, target_type, target_id,
detail_json, created_at
```
---
## 九、部署方案
### 9.1 初期部署
```text
单台云服务器
|-- Nginx
|-- Vue3 静态资源
|-- FastAPI + uvicorn workers
|-- PostgreSQL
|-- Redis
+-- systemd 管理服务
外部云服务
|-- 腾讯云 ADP
|-- 腾讯云 COS
+-- 腾讯云 SMS
```
推荐配置：
- 4 核 8G 云服务器
- 系统盘 100G 起
- PostgreSQL 本机部署
- Redis 本机部署，`maxmemory 256mb`
- Nginx 负责 HTTPS、静态资源和反向代理
### 9.2 环境变量
```text
DATABASE_URL
REDIS_URL
JWT_SECRET
ADP_BOT_APP_KEY
ADP_API_SECRET_ID
ADP_API_SECRET_KEY
TENCENT_SMS_SECRET_ID
TENCENT_SMS_SECRET_KEY
COS_BUCKET
COS_REGION
```
`.env` 文件权限设置为 `600`，生产环境不提交到代码仓库。
---
## 十、测试与验收
### 10.1 功能测试
- 手机号验证码登录、刷新 Token、退出登录
- 管理员创建、禁用、启用用户
- 文档上传、解析状态轮询、重试、删除
- 文档标签必填校验
- 普通用户问答、管理员问答、多轮会话
- 截图上传并参与问答
- 引用来源展示和点击预览
### 10.2 权限测试
| 测试项 | 预期 |
|---|---|
| employee 查询 public 文档 | 可回答 |
| employee 查询 internal 文档 | 可回答 |
| employee 查询 confidential 文档 | 不可回答 |
| admin 查询 confidential 文档 | 可回答 |
| 文档未设置 level | 不允许保存或发布 |
| 前端伪造 custom_variables | 后端忽略 |
### 10.3 异常测试
- ADP 超时
- ADP 5xx
- ADP 限流
- 短信发送失败
- COS 上传失败
- SSE 中途断开
- 文档解析失败
- Token 过期或黑名单命中
---
## 十一、风险与对策
| 风险 | 影响 | 对策 |
|---|---|---|
| ADP 密钥泄漏 | 外部直接调用并产生费用 | 密钥只在后端保存，前端永不接触 |
| 标签权限失效 | 用户检索到越权文档 | 强制标签、后端注入、巡检空标签、权限测试矩阵 |
| ADP 服务不可用 | 问答能力中断 | 统一降级提示，记录失败，必要时人工客服兜底 |
| 费用不可控 | PU 或模型调用超预算 | usage_log、单用户日限额、管理员告警 |
| 数据合规争议 | 文档不能进入云端知识库 | 立项前确认合规口径，必要时采购专属版或私有化 |
| 厂商锁定 | 后续迁移成本增加 | `LLMProvider` 抽象、ADP 配置 YAML 备份、文档源文件自持 |
---
## 十二、人日估算
| 模块 | 估算 |
|---|---:|
| 项目初始化与基础框架 | 2 人日 |
| 认证、短信、Token、限流 | 5 人日 |
| 用户和角色权限 | 3 人日 |
| ADP 文档 API 包装 | 5 人日 |
| 对话流式代理 | 5 人日 |
| 会话、消息、引用落库 | 3 人日 |
| 截图上传与临时 URL | 2 人日 |
| 前端登录和主布局 | 3 人日 |
| 前端对话页 | 5 人日 |
| 前端文档管理页 | 4 人日 |
| 前端用户管理页 | 3 人日 |
| 审计和用量统计 | 2 人日 |
| ADP 应用配置与联调 | 4 人日 |
| 测试、部署、验收修复 | 5 人日 |
| Buffer | 4 人日 |
| **合计** | **约 55 人日** |
说明：该估算比上一版更保守，主要补入了 SSE 异常处理、权限测试、标签巡检、截图安全和 ADP 联调成本。
---
## 十三、参考资料
- 腾讯云智能体开发平台 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
- ADP 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