xianjing-ai/docs/Ragflow实施方案.md

鲜境 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 + 依赖列表