docs: 新增 Ragflow 搭建实施方案

覆盖架构切分、知识库、方案引擎状态机、双场景、Eval 与实施顺序。 Co-authored-by: haijd <haijd@163.com>
2026-09-18 08:04:27 +00:00
parent 84846bcc8a
commit 93b0867eb3
2 changed files with 247 additions and 1 deletions
@@ -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？  
@@ -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 + 依赖列表 |