项目概览
基于 RAGFlow 的 SaaS 系统手册 RAG 项目
基于自托管 RAGFlow v0.26.4，在 fxiaoke-handbook 知识库上搭建 CRM 产品手册问答：操作类走 Hybrid 检索，模块关系题条件开启 GraphRAG 与知识图谱， 版本发布事实走 MySQL 结构化侧车，闲聊与无关问题统一拒答。
结构化侧车：MySQL
fxiaoke_portfolio.saas_release_changelog · 12 条产品版本更新记录评测集：eval-v1，含文档定位、概念释义、实体检索、关系梳理、操作指引、版本升级记录（SQL）、无关拒答
需求背景
SaaS 软件配套手册数量多、模块交叉、版本迭代快。售前、实施与现场开发人员在交付过程中 经常需要在数百篇 HTML/PDF 手册里翻找配置步骤与版本差异，查找成本高、口径不一致。
本项目用 RAG 将纷享销客 CRM 手册构建为可检索知识库，结合版本更新结构化表， 让一线人员用自然语言提问即可获得有出处、可核对的操作方案或版本事实。
需求方案
意图分类（四路）
- 操作指引（handbook_simple）— 配置、流程、权限等 FAQ
- 关系梳理（handbook_relation）— 模块/对象关系，开知识图谱 GraphRAG
- 版本升级 · SQL（structured_query）— 版本号、强制升级、安全变更等表查询
- 无关拒答（out_of_scope）— 闲聊、股价、天气等超出语料范围
用户体验（已实现）
- 自然语言提问，自动识别意图并选择检索或 SQL 路径
- 回答附带 chunk 或 SQL 行溯源，支持跨轮 Memory 上下文
- 控制台展示意图标签、延迟、路由卡片与系统健康状态
- 一键触发 eval-v1 回归，多维指标实时刷新
评测集与指标（eval-v1）
题型覆盖：文档定位（能否找到正确章节）、概念释义、 实体检索、关系梳理（知识图谱）、操作指引、 版本升级记录（SQL）、无关拒答。 指标：意图准确率、路由精确率、Recall@K、Faithfulness、Correctness、延迟 P50/P90、稳定性（通过率）。
方案设计
双数据源 + 四路意图：手册 RAG、关系 GraphRAG、MySQL changelog、拒答。
- Embedding — text-embedding-v4
- Chat — deepseek-v4-flash / pro（意图 · 生成 · SQL）
- GraphRAG — 关系/概念题按需开启知识图谱，日常 FAQ 关闭以保延迟
- 编排服务 — FastAPI · MySQL changelog · 意图识别分路 Agent Skill 处理
- 解析监测 — 解析文档进度可视化监测（MySQL + 日志滚动）
核心能力
覆盖 RAGFlow 从入库、检索、分层智能体、Memory 到结构化侧车与回归评测的完整链路。
1. 知识库入库与解析
知识库 fxiaoke-handbook 收录约 265 篇纷享销客 CRM 产品手册，
解析为 534 个 chunk。Embedding 采用 text-embedding-v4（1024 维），
与 RAGFlow Hybrid 检索共用同一向量空间。
为何启用 GraphRAG：手册中模块、对象、流程之间存在大量交叉引用， 纯向量检索对「A 模块与 B 模块什么关系」类问题容易漏召回；GraphRAG 从 chunk 抽取实体与关系边， 构建知识图谱，在关系/概念题上做多跳补全。
已开启的 GraphRAG 增强：实体/关系抽取 → 子图合并（merge_subgraph）→ 图谱索引；检索侧支持「Use knowledge graph」开关，与 Hybrid 向量召回并联。
解析文档进度可视化监测：RAGFlow 长跑解析时 UI 进度条常停在 ~80%， 自研监测面板读取 MySQL 任务表与 executor 日志，实时展示 Parse / Embedding / GraphRAG 阶段。
ragflow-dataset-files.png
parse-monitor.png
2. 检索调试（Hybrid / GraphRAG）
操作指引类（关知识图谱）：以「如何查看 CRM 信息？」为例，答案集中在 CRM 信息模块说明， Hybrid 向量 + 关键词召回即可，关闭知识图谱避免多跳带来的额外延迟。
关系梳理类（开知识图谱）：以「CRM 与 PaaS 自定义对象在数据上如何配合？」为例， 手册中关联字段、对象归档分散在多篇文档，开启 GraphRAG 可串联跨文档的数据关联说明（比泛化的「模块之间什么关系」更易命中语料）。
ragflow-chat-faq.png
ragflow-chat-relation-e07.png
3. 智能体意图路由
FastAPI 编排层实现分层智能体架构：上层 Web 控制台接收提问并展示路由卡片； 中层 LLM 意图识别将问题分到四路；下层 Skill 分别调用 RAGFlow 检索、GraphRAG、Text2SQL 或拒答模板； 最底层对接 RAGFlow 知识库、MySQL 版本表与会话 Memory。
RAGFlow 侧另建 fxiaoke-handbook-agent（客户服务模板），画布可见 Categorize 分支与 Retrieval 节点， 与上层四路意图形成「UI 智能体 + 编排 Skill」双轨对照。
ragflow-agent.png
4. 问答与溯源
FastAPI 控制台在同一屏展示：左侧对话与 intent / 延迟 标签， 右侧路由详情（为何分到该分支）与溯源列表——RAG 题为 chunk 相似度与片段预览， SQL 题为生成的 SELECT 与结果行。答案正文严格基于召回或 SQL 行生成，便于实施核对。
console-trace-faq.png
console-trace-sql.png
5. eval-v1 回归评测
eval-v1 回归评测：多维度自动评测（意图准确率、路由精确率、Recall@K、 Faithfulness、Correctness、延迟分位）。运行栈：自托管 RAGFlow + MySQL + FastAPI 编排服务。
评测维度包括：文档能否定位到正确章节、概念释义是否忠实、实体/关系是否召回、 操作步骤是否可执行、版本 SQL 是否命中、无关问题是否稳定拒答。 当前 Intent Accuracy 100.0% · 详见下方 eval-v1 评测结果。
eval-v1 评测结果
覆盖四类意图与 SQL / 拒答边界。运行栈：自托管 RAGFlow + MySQL + FastAPI。
指标说明
- Intent Accuracy · 意图准确率
- 所有评测题中，LLM 意图分类与期望分支一致的比例（操作 / 关系 / SQL / 拒答）。
- Route Precision · 路由精确率
- 分类后实际执行路径是否正确：FAQ 是否走 Hybrid、关系题是否开 KG、版本题是否走 MySQL、无关题是否拒答。
- Recall@K · 召回准确
- 检索 top-k 片段是否覆盖期望关键词或正确 chunk（RAG 题）；SQL 题按命中表字段计。
- Faithfulness · 回答忠诚性
- 0–2 分：回答是否严格基于召回片段或 SQL 结果，少臆造、少跑题（2 为完全忠实）。
- Correctness · 答案正确性
- 0–2 分：在忠实前提下，信息是否完整可用、能否直接指导操作或决策。
- Latency P50 · 延迟 P50
- 所有评测题端到端耗时的 50 分位数（提问 → 意图 → 检索/SQL → 生成 → 返回）。
- Stability · 稳定性
- 本轮 eval 意图全部正确的通过率；与 Intent Accuracy 一致时表示无路由失败。
E01 如何查看 CRM 信息？ 操作指引 ✓ 6434ms
期望路由 操作指引 · 实际路由 操作指引
期望回答 应回答：说明 CRM 信息查看入口（工作 → CRM 信息等）与可见范围
回答摘要 根据知识库，查看 CRM 信息的方式如下： 1. **CRM 信息的概念**：CRM 信息统一展示与业务对象（如客户、联系人、商机、销售线索等）相关的所有关联活动，包括销售记录、服务记录、销售流程反馈、外勤签到、日志、分享、审批、任务、日程和指令等。 2. **查看入口**：可以在以下位置查看 CRM 信息： - **“工作”模块**（如工作台-服务管理） - **“CRM 信息”模块**（系统预置功能） - **业务对象详情页**（如客户详情页、联系人
E02 纷享销客中如何配置销售流程？ 操作指引 ✓ 5682ms
期望路由 操作指引 · 实际路由 操作指引
期望回答 应回答：销售流程/审批流程配置路径（PaaS、商机对象相关）
回答摘要 未在手册中找到关于如何配置销售流程的具体步骤说明。手册中提到，您可以在「业务扩展」中根据自身需求配置业务流程或审批流程（见#3.5 业务扩展），销售自动化模块也支持规范销售流程（见#3.2 销售自动化）。此外，商机对象中联合跟进人和售后人员分别对售前流程和后流程有操作权限（见配置相关团队数据权限部分）。但详细的配置操作指引（如入口、步骤、参数设置等）未提供。建议您联系纷享销客官方客服或查阅更详细的帮助文档。
E03 权限管理里角色怎么分配？ 操作指引 ✓ 6108ms
期望路由 操作指引 · 实际路由 操作指引
期望回答 应回答：管理角色与业务角色的分配方式
回答摘要 根据知识库，角色分配的操作如下： 1. **分配管理角色（后台管理权限）** - 路径：进入「系统管理 → 角色权限管理 → 管理功能权限」，先新建或选择一个管理角色。 - 分配员工：在「系统管理 → 角色权限设置」中找到该角色，点击进入员工分配页面，为员工勾选分配。 - 规则：一个角色可分配给多个员工，一个员工也可拥有多个角色，最终功能权限取所有角色的合集。 2. **分配业务角色（前台业务权限）** - 路径：在「系统管理 →
E04 如何新建或录入客户？ 操作指引 ✓ 8046ms
期望路由 操作指引 · 实际路由 操作指引
期望回答 应回答：新建或录入客户的操作步骤（手册有则引用，无则说明未覆盖）
回答摘要 根据知识库片段内容，**未找到关于如何新建或录入客户的具体操作步骤**。知识库中提及了与客户相关的场景（如工单新建时关联客户、客户查重、权限配置等），但未提供手动新建客户或导入客户的具体流程说明。建议参考系统中的“客户对象”相关帮助文档或联系管理员获取详细指引。
E05 怎么在系统里查看当前版本号？ 操作指引 ✓ 5422ms
期望路由 操作指引 · 实际路由 操作指引
期望回答 应回答：系统内查看版本号的方式；若无则如实说明手册未记载
回答摘要 未在手册中找到查看当前版本号的具体操作方法。
E06 客户管理与销售自动化模块之间是什么关系？ 关系梳理 · 知识图谱 ✓ 7754ms
期望路由 关系梳理 · 知识图谱 · 实际路由 关系梳理 · 知识图谱
期望回答 应回答：客户管理与销售自动化模块的从属/协作关系（需知识图谱）
回答摘要 根据提供的知识库片段，**未找到关于“客户管理与销售自动化模块之间关系”的明确描述**。 片段中仅提及： - 销售自动化是纷享CRM的核心模块，用于管理销售过程、客户和销售机会（如3.2节所示）。 - 客户管理可能隐含在销售自动化模块中，但未单独定义其与销售自动化的关系。 如需进一步了解，建议查阅手册中关于“销售自动化”与“客户管理”的具体章节。
E07 CRM 与 PaaS 自定义对象在数据上如何配合？ 关系梳理 · 知识图谱 ✓ 10580ms
期望路由 关系梳理 · 知识图谱 · 实际路由 关系梳理 · 知识图谱
期望回答 应回答：CRM 与 PaaS 自定义对象的数据关联、归档配合（需知识图谱）
回答摘要 根据提供的知识库片段，CRM 与 PaaS 自定义对象在数据上的配合主要体现在以下方面： 1. **关联关系建立**：通过 PaaS 平台创建自定义对象时，可以设置与其他对象（包括预置对象或其他自定义对象）的关联关系（如查找关联字段）。例如，在自定义对象【配送单】中，可通过查找关联字段指向客户对象，实现业务数据的关联。 - 来源：自定义对象概述中提及“可以建立该对象与其他对象的关联关系”。 2. **数据导入匹配规则**：在 CRM 导入数据时，使用自定义对象的
E08 客户资料在哪里可以查看？ 操作指引 ✓ 6722ms
期望路由 操作指引 · 实际路由 操作指引
期望回答 应回答：客户资料查看位置（客户详情页、客群侧边栏等，同义改写）
回答摘要 根据知识库片段，客户资料可以在以下位置查看： 1. **客群（企信）** 在【企信】-【客群】中，点击客户后右侧会展开**客户详情面板**（新版侧边抽屉式设计），可查看客户信息。 （来源：【26年01月】PaaS平台产品更新说明 - 1.1 客群右侧展开客户详情体验优化） 2. **CRM信息页面** 在“CRM信息”中统一展示与业务对象相关的所有关联活动信息，包括销售记录、服务记录等，可通过该页面快速查看客户跟进信息。 （来源：【
E09 录入一个新客户需要哪些步骤？ 操作指引 ✓ 6410ms
期望路由 操作指引 · 实际路由 操作指引
期望回答 应回答：录入新客户的步骤或线索转化路径（同义改写）
回答摘要 根据提供的知识库片段，未找到直接描述“录入一个新客户”具体步骤的内容。手册中主要涉及以下相关功能： - **新建查重**：在手动新建客户记录时，可根据预设规则自动检测重复数据（来源：小工具片段）。 - **从Excel导入创建对象**：可通过下载模板、填写数据并上传的方式批量创建客户对象（来源：从excel导入创建对象片段）。 如需手动录入单个客户，建议在CRM系统的客户列表页点击“新建”按钮进行操作，但具体步骤未在手册中详述。
E10 8.5.0 版本 CRM 模块有哪些更新？ 版本升级 · SQL ✓ 4576ms
期望路由 版本升级 · SQL · 实际路由 版本升级 · SQL
期望回答 应回答：8.5.0 版本 CRM 各模块更新条目（SQL 结果）
回答摘要 根据查询结果，8.5.0 版本 CRM 模块包含以下更新： - 客户管理：新增客户360时间轴，支持按商机/合同/服务工单聚合展示。 - 销售自动化：线索分配规则优化，支持按区域+行业双维度自动分配，减少人工转派。 - 权限管理：新增角色变更审计与导出，满足等保抽检字段要求。
E11 哪些版本更新要求强制升级？ 版本升级 · SQL ✓ 4222ms
期望路由 版本升级 · SQL · 实际路由 版本升级 · SQL
期望回答 应回答：列出要求强制升级的版本号（SQL 结果）
回答摘要 - release_version=8.4.1 - release_version=8.4.0
E12 2026 年 3 月有哪些安全类变更？ 版本升级 · SQL ✓ 4658ms
期望路由 版本升级 · SQL · 实际路由 版本升级 · SQL
期望回答 应回答：2026 年 3 月安全类变更记录（SQL 结果）
回答摘要 - 角色权限审计日志（2026-03-15，CRM 权限管理）：新增角色变更审计与导出，满足等保抽检字段要求。
E13 本公司下周股价是多少？ 无关拒答 ✓ 2098ms
期望路由 无关拒答 · 实际路由 无关拒答
期望回答 应拒答：超出手册与版本记录范围
回答摘要 抱歉，该问题超出纷享销客产品手册与版本更新记录的知识范围，我无法提供可靠答案。请尝试询问 CRM 操作、模块关系或版本发布记录相关问题。
E14 今天天气怎么样？讲个笑话吧。 无关拒答 ✓ 2194ms
期望路由 无关拒答 · 实际路由 无关拒答
期望回答 应拒答：超出手册与版本记录范围
回答摘要 抱歉，该问题超出纷享销客产品手册与版本更新记录的知识范围，我无法提供可靠答案。请尝试询问 CRM 操作、模块关系或版本发布记录相关问题。
踩坑记录
检索效果
- Prompt 过严导致保守拒答：检索已命中相关 chunk，但生成侧因「仅依据片段」约束过强而回答「未找到」→ 微调 system prompt，允许合理归纳。
- Route Trap：「查看版本号」类问题易误路由到 SQL；eval-v1 专门加入 route_trap 用例校验意图边界。
- 同义改写召回波动：「客户资料在哪里查看」与「如何查看 CRM 信息」召回 chunk 不完全一致 → 依赖 Hybrid 关键词 + 适当 top_k。
切块 · 向量化
- Embedding batch 超限：第三方 API 单批上限 10，解析配置拆出 16 → 修改 BATCH-SIZE 配置对齐上限。
- 进度条假卡 80%：Embedding 阶段 UI 长期停在 ~80%，实际仍在跑 → 自研日志滚动可视化监测面板判断真实进度。
GraphRAG · 知识图谱
- 合并阶段 bulk 超限：
GRAPHRAG_INSERT_BULK_SIZE默认 64 超过 API 上限 10，单篇实体关系 OK 但 merge 失败 → 调小 bulk（每篇约 25 点/边）。 - 实体/节点为 0：文章过短或截图占比高、文本不足 → 无法抽图。
- 大图谱 merge 超时：默认 180s 被
_run_with_retry掐死，缓存丢失需重抽 → 调高超时（已有 community issue）。 - GraphRAG 开但召回为空：同步调用异步函数 → 全部改为 async/await 后图谱召回正常。
- Chat 流式输出 DB 断开：LLM 生成耗时长导致 DB 连接超时 → 调大连接/读写超时。
响应速度优化
端到端延迟仍有优化空间。首轮链路 P50 约 30+ 秒，经下列优化已降至 约 10 秒（展示指标 13549ms）：
- Semantic Memory 摘要改异步，不阻塞主回答路径
- 意图识别与 RAGFlow 检索并行启动
- 换用更快 Chat 模型（flash 级）做意图与 FAQ 生成
- 降低召回 top_k，减少 rerank 输入
- Prompt 限制回答字数；无关拒答走独立快速模板
后续方向：分层检索缩短遍历、缓存高频 FAQ、关系题与 SQL 路径进一步并行。
项目链接
- GitHub · Rag_SaaS_Handbook（仅应用层代码：FastAPI 编排、前端控制台、评测脚本）
- ← 返回作品集首页
.env 密钥、RAGFlow Auth Token、
账号密码或含敏感信息的 RUNLOG 推送到 GitHub。RAGFlow 请按官方文档自托管，本项目只包含上层编排与评测。