diff --git a/README.md b/README.md index fa279b6..90e70a5 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,14 @@ | 文件 | 说明 | |------|------| -| [docs/技术方案建议书.md](./docs/技术方案建议书.md) | 决策依据、平台对比、架构、7 周映射、风险 | +| [docs/技术方案建议书.md](./docs/技术方案建议书.md) | 自研/二开决策、Dify vs Ragflow、许可 | +| [docs/Ragflow实施方案.md](./docs/Ragflow实施方案.md) | **选定 Ragflow 后怎么搭**（架构、知识库、方案引擎、分期） | | [uploads/](./uploads/) | 原始合同、进度表、建议书、验收标准 | +## 若已定 Ragflow + +按 [Ragflow实施方案](./docs/Ragflow实施方案.md)：自托管 Ragflow 做检索 → 自研方案引擎做追问/判定/转人工 → 首期只接一个渠道。 + ## 建议立刻确认 1. 首期唯一渠道：网站还是 Facebook？ diff --git a/docs/Ragflow实施方案.md b/docs/Ragflow实施方案.md new file mode 100644 index 0000000..c70b36a --- /dev/null +++ b/docs/Ragflow实施方案.md @@ -0,0 +1,241 @@ +# 鲜境 AI 客服 · Ragflow 搭建方案 + +> 前提：底座选 **Ragflow（自托管，Apache-2.0）**；「意图 → 追问 → 方案生成 → 转人工」用**自研薄方案引擎**补齐，不把业务逻辑只画在厂商画布里。 + +--- + +## 1. 总体架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 渠道层 │ +│ 网站插件 / FB（首期只做一个） │ 销售端：录音上传或实时转写入口 │ +└───────────────┬─────────────────────────────┬───────────────┘ + │ │ + ▼ ▼ +┌──────────────────────────┐ ┌─────────────────────────────┐ +│ 方案引擎 API（自研） │ │ ASR 服务（场景二） │ +│ · 会话状态 / 追问槽位 │◄───│ 云 ASR 或私有 Whisper │ +│ · 意图分类 │ └─────────────────────────────┘ +│ · 方案判定树 + 产品组合 │ +│ · 置信度 / 敏感词 → 转人工 │ +│ · 方案文本模板 │ +└──────────┬───────────────┘ + │ 检索 API（query → chunks + citation） + ▼ +┌──────────────────────────┐ ┌─────────────────────────────┐ +│ Ragflow（自托管） │ │ 人工席 │ +│ · Dataset 知识库 │ │ Chatwoot / 企微 / 飞书 │ +│ · 解析·切块·Embedding │ │ 低置信度工单 + 对话记录推送 │ +│ · 召回·重排·引用 │ └─────────────────────────────┘ +│ ·（可选）内置 Chat 仅调试用 │ +└──────────────────────────┘ + │ + ▼ +┌──────────────────────────┐ +│ 模型层 │ +│ LLM：智谱等（可切私有化） │ +│ Embedding：与库同环境 │ +└──────────────────────────┘ +``` + +**职责切分（务必守住）：** + +| 组件 | 负责 | 不负责 | +|------|------|--------| +| Ragflow | 资料入库、检索、引用片段 | 业务判定树、渠道 UI、人工工单主流程 | +| 方案引擎 | 多轮状态、追问、匹配产品组合、出方案、转人工策略 | 重做一套向量库 | +| 渠道/ASR/人工席 | 触达与交接 | 知识解析 | + +--- + +## 2. 环境与部署 + +### 2.1 建议拓扑（首期） + +- 单机或一小集群：`Docker Compose` 部署 Ragflow（含其依赖的 ES/Infinity、MySQL、MinIO、Redis 等，以官方 compose 为准）。 +- 方案引擎：独立服务（建议 **Python FastAPI** 或 **Node/Hono**），与 Ragflow 同 VPC。 +- 对象存储：产品原文 PDF/Word 放 MinIO 或客户 OSS；Ragflow 只存解析结果与向量。 +- 配置：模型 Key、Ragflow API Key 进环境变量，不进仓库。 + +### 2.2 模型 + +| 用途 | 建议 | 说明 | +|------|------|------| +| 对话 / 方案生成 | 智谱 GLM 等国产 API | 合同要求数据可控；可按成本换模型 | +| Embedding | Ragflow 推荐且已验证的中英模型 | **一经选定勿随意换**（换则全量重建） | +| ASR | 先云端；涉密再私有化 Whisper | 场景二 | + +### 2.3 许可与交付物 + +- 开源清单写明：Ragflow = Apache-2.0；方案引擎为定制代码（归甲方）；列出传递依赖。 +- 保留 Ragflow 版权声明即可，无 Dify 类「去 Logo / 多租户」附加条款问题。 + +--- + +## 3. 知识库怎么建（Ragflow 内） + +### 3.1 Dataset 划分（建议） + +不要做成一个「大杂烩库」： + +| Dataset | 内容 | 用途 | +|---------|------|------| +| `products` | 型号、参数、适用工况、禁忌 | 产品组合匹配时的硬事实 | +| `solutions` | 历史方案、两大类技术选型说明 | 方案话术与结构 | +| `faqs` | 高频询盘 Q&A | 降重复劳动 | +| `policies` | 敏感词、不可承诺条款（可选） | 护栏 | + +### 3.2 入库规范（W1 和甲方定） + +- 每份文档元数据：`产品线`、`技术大类(A/B)`、`型号`、`语言`、`版本日期`。 +- 优先：**结构化表（型号×参数）+ 方案范文**；纯长 PDF 靠解析，但关键参数尽量表结构化。 +- 切块：参数表用「按行/按型号」策略；方案用「按章节」；入库后做 **Recall 测试**（人工出 30 个真实问法看片段对不对）。 + +### 3.3 检索调用方式 + +方案引擎只调 Ragflow **检索 API**（或官方 SDK），拿到： + +- `content` / `score` / `document` / 引用定位 +- 再交给 LLM **仅基于引用**生成；无命中则追问或转人工，禁止空编参数。 + +--- + +## 4. 方案引擎怎么搭（自研核心） + +### 4.1 会话状态机（最小闭环） + +``` +新会话 + → 意图识别（咨询/比价/售后/无关…） + → 若「方案咨询」：进入技术大类判定 + → 追问槽位未满：生成下一个问题 + → 槽位已满：检索 + 判定树 → 产品组合 + → 渲染方案模板 → 返回用户 + → 低置信 / 敏感 / 用户要人工 → 转人工 + 留资 +``` + +### 4.2 追问槽位（示例，W1 由业务专家定稿） + +按鲜境「两大类技术」分别设必问项，例如： + +- 应用场景 / 工况环境 +- 处理对象或指标范围 +- 产能或规模 +- 现场约束（空间、已有设备、预算区间） +- 交付区域/语言（若接海外询盘） + +槽位存会话表（Postgres/SQLite 首期均可），不要只靠模型「记忆」。 + +### 4.3 判定树 + 产品组合 + +- 专家规则优先：`IF 大类=A AND 工况=X AND 指标∈[…] THEN 推荐型号组合` +- RAG 补充：方案说明、话术、注意事项从 `solutions`/`products` 检索填空 +- 输出结构固定：`推荐组合` + `理由（带引用）` + `需人工确认项` + `下一步留资` + +### 4.4 接口草图 + +``` +POST /chat # 渠道统一入口：session_id + message +POST /sessions/:id/handoff +POST /ingest/notify # 可选：资料更新后重建/增量索引钩子 +GET /admin/evals # 评测任务与结果 +``` + +渠道插件、FB Webhook、销售录音页都只打 `/chat`。 + +--- + +## 5. 两场景落地 + +### 场景一：线上 24h 咨询（合同：只做一个高频渠道） + +1. 选定网站 **或** FB。 +2. 嵌入聊天窗 / Webhook → 方案引擎。 +3. UI 展示：回复 +（可选）引用折叠；「转人工」「留电话」。 +4. 转人工：创建 Chatwoot 会话或推企微，附带槽位摘要与最近检索命中。 + +### 场景二：销售辅助 + +1. 上传录音或对接会议转写 → ASR 文本。 +2. 文本进入同一状态机（可跳过寒暄意图，直接抽槽位）。 +3. 输出「可发给客户的方案草稿」+ 内部注意点；由销售确认后发送。 + +--- + +## 6. 人工接管与后台 + +| 能力 | 做法 | +|------|------| +| 转人工 | 引擎规则触发 → Chatwoot/企微；超时未接则留资入库 | +| 对话追溯 | 引擎写 `messages` 表；可同步一份到人工席 | +| 知识维护 | 业务在 Ragflow 控制台更新 Dataset；重大变更跑 Recall 抽样 | +| 效果看板 | 首期：导出日志 + 简单页（任务完成率、转人工率、Eval 分数）；勿一上来做大屏 | + +--- + +## 7. AI Eval（对着附件三） + +| 指标 | 做法 | +|------|------| +| 意图识别 ≥85% | 200 条标注；引擎意图模块离线测 | +| 方案匹配 ≥80% | 专家盲测「引擎方案 vs 专家方案」 | +| 任务完成 ≥70% | 日志：未转人工且用户达方案/留资 | +| 幻觉 ≤5% | 抽检：断言中参数是否出现在引用 chunk | +| 敏感泄露 =0% | 正则+词表扫描回复 | + +评测集与判定树一样：**外置文件**，不锁在 Ragflow 里。 + +--- + +## 8. 推荐实施顺序（可不绑死 7 周） + +| 步 | 做什么 | 完成标准 | +|----|--------|----------| +| 1 | Compose 拉起 Ragflow；接通 LLM/Embedding | 控制台可聊「基于空库」 | +| 2 | 灌入一小撮真实产品+方案；Recall 测试 | 业务说「找得对」 | +| 3 | 定稿判定树与槽位；引擎跑通 API | Postman 多轮能出方案结构 | +| 4 | 护栏：无检索不编参数；转人工；留资 | 故意问库外问题会转人工 | +| 5 | 接一个渠道 + 基础聊天 UI | 真实访客可走通 | +| 6 | 场景二 ASR 联调 | 一段销售录音能出草稿 | +| 7 | Eval 全量 + UAT | 附件三阈值或书面差距说明 | +| 8 | 生产部署、备份、监控、开源清单 | 可交接 | + +--- + +## 9. 仓库/工程建议（乙方交付形态） + +``` +/infra # docker-compose、备份脚本 +/engine # 方案引擎（状态机、判定、调 Ragflow） +/web-widget # 网站聊天插件（若渠道是网站） +/eval # 评测集、脚本 +/knowledge # 元数据说明、判定树 YAML、产品表（原文大文件可外链） +/docs # 部署说明、开源清单、运维手册 +``` + +定制成果在 `engine` / `knowledge` / `eval`；Ragflow 用官方镜像，**尽量不 Fork 魔改核心**（升级痛苦）。二开以「配置 + 外围服务」为主。 + +--- + +## 10. 风险与戒条 + +1. 不要用 Ragflow 默认 Chat 直接当生产客服终态——缺槽位与判定，难稳过方案匹配。 +2. 不要把判定树只写在 Prompt 里——要结构化规则 + 检索填空。 +3. 换 Embedding / 大改切块 = 重建索引 + 重做 Recall。 +4. 首期渠道只做一个；双渠道等订阅期再加。 +5. 双栈再挂 Dify：仅当自研编排人力不够时临时用，默认不必。 + +--- + +## 11. 和合同交付的对应 + +| 合同/验收项 | 落在哪 | +|-------------|--------| +| 知识库可检索、可维护 | Ragflow Dataset + 权限 | +| 智能问答多轮 | 方案引擎状态机 | +| 方案自动生成 | 判定树 + 检索 + 模板 | +| 人工接管 | 引擎策略 + Chatwoot/企微 | +| 对话记录/看板 | 引擎库表 + 轻量看板 | +| AI Eval 阈值 | `/eval` + 专家盲测 | +| 开源清单 | Ragflow Apache-2.0 + 依赖列表 |