commit 570d0f531172f2c6c44be1fcdf176b43dc69b84d Author: caoqianming Date: Wed May 6 10:37:22 2026 +0800 Initial project documentation diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cf6efc9 --- /dev/null +++ b/.gitignore @@ -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/** diff --git a/docs/superpowers/specs/2026-03-31-llm-qa-system-design.md b/docs/superpowers/specs/2026-03-31-llm-qa-system-design.md new file mode 100644 index 0000000..21f1d43 --- /dev/null +++ b/docs/superpowers/specs/2026-03-31-llm-qa-system-design.md @@ -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. **用量统计：** 统计问答次数、热门问题、未命中问题、低置信问题 diff --git a/docs/superpowers/specs/2026-03-31-llm-qa-system-design.pdf b/docs/superpowers/specs/2026-03-31-llm-qa-system-design.pdf new file mode 100644 index 0000000..30b2a98 Binary files /dev/null and b/docs/superpowers/specs/2026-03-31-llm-qa-system-design.pdf differ diff --git a/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.docx b/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.docx new file mode 100644 index 0000000..5a8fcaa Binary files /dev/null and b/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.docx differ diff --git a/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.md b/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.md new file mode 100644 index 0000000..dbab828 --- /dev/null +++ b/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.md @@ -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 作为知识问答底座，自研企业业务门户，兼顾建设效率、文档解析能力、权限治理和后续扩展。 + +相比完全自研，本方案降低了文档解析、检索和引用对齐的技术风险；相比直接使用平台控制台，本方案保留了企业用户管理、文档权限、审计留痕和统一门户体验。 + +建议第一期聚焦财务制度、报销流程和操作手册等高频场景，先小范围试运行，再逐步扩展文档范围和用户范围。 diff --git a/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.pdf b/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.pdf new file mode 100644 index 0000000..61bab1d Binary files /dev/null and b/docs/superpowers/specs/2026-04-30-llm-qa-system-client-plan-adp.pdf differ diff --git a/docs/superpowers/specs/2026-04-30-llm-qa-system-design-adp.md b/docs/superpowers/specs/2026-04-30-llm-qa-system-design-adp.md new file mode 100644 index 0000000..132d143 --- /dev/null +++ b/docs/superpowers/specs/2026-04-30-llm-qa-system-design-adp.md @@ -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) diff --git a/docs/superpowers/specs/2026-04-30-llm-qa-system-technical-plan-adp.md b/docs/superpowers/specs/2026-04-30-llm-qa-system-technical-plan-adp.md new file mode 100644 index 0000000..bba29ad --- /dev/null +++ b/docs/superpowers/specs/2026-04-30-llm-qa-system-technical-plan-adp.md @@ -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