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