# Dify 搭建 ESP32 设备文档 RAG 问答助手

## 一、为什么做这个项目

日常开发中，工程师经常要查阅 ESP32 系列芯片的技术文档——引脚定义、ADC 注意事项、深度睡眠功耗这些细节。官方文档以英文为主，翻找费时，而且很多关键信息（比如"ADC2 与 Wi-Fi 共用射频路径"）往往藏在大段文字里。于是我想做一个问答助手：用户用自然语言提问，系统基于技术文档给出**带依据**的答案。传统方案是维护一份 FAQ，但覆盖不全、更新成本高。RAG（检索增强生成）正好解决这个问题：先检索知识库，再让大模型基于上下文作答，答案可溯源，还能自动覆盖新文档。

## 二、为什么选 Dify

选 Dify 有三个原因：第一，它内置知识库、向量检索、RAG 等开箱即用的能力，不用自己写向量数据库和检索代码；第二，可视化编排工作流，意图识别、条件分支、知识检索、LLM 节点可以拖拽串联，迭代极快；第三，支持混合检索、Rerank 等高级能力，方便后续优化。模型方面，中文语料我选 bge-m3 做 Embedding，生成模型用千问，成本与效果比较均衡。

## 三、知识库构建：数据是根本

RAG 的效果上限取决于语料质量。我把 ESP32 系列（经典款、S2、S3、C3、C6）的技术资料整理成一份结构化的《ESP32 设备技术文档》，覆盖型号对比、引脚与 GPIO、电源与低功耗、内存、无线、外设接口、开发板、开发框架、FAQ 等章节，语料采用"段落式文章"风格，每段一个完整语义。上传 Dify 后，分段参数设置为：分段标识符 \n（段落边界）、最大长度 1024 字符、重叠 50 字符，保证每个片段由完整段落组成、语义自包含。

这里有一个重要教训：**分段太小会从句子中间硬切，导致检索片段语义残缺。** 我最初想把分段压到 300，测试后发现长段落被切得支离破碎，回答经常缺上下文，最后统一用 1024，命中质量明显提升。RAG 项目七分在数据，真不是一句空话。

## 四、工作流编排：意图识别 + 两次分支

工作流是项目的核心，整体结构如下：

> 用户输入 → 意图识别（代码节点）→ 条件分支①：greeting / human_service / error 直接回复；其余进入知识检索 → 条件分支②：检索结果为空走闲聊 LLM，有结果走 RAG LLM

意图识别用一段基于短语匹配的 Python 代码实现，输入用户 query，输出 `type`、`response`、`need_rag`、`original_query` 四个字段，把"你好""谢谢""转人工"这类寒暄和人工服务请求在检索前就拦截掉，避免无意义的检索开销。分类结果用条件分支①判断：三类意图直接回复对应话术，其余才真正触发检索。

知识检索节点的查询我特意用 `original_query`（原文）而非处理后的文本，保持问题原貌。检索后再次分支：`result` 为空说明知识库没覆盖，走闲聊 LLM 兜底，既答天气这类闲聊，也用大模型自身知识补充；`result` 非空走 RAG LLM，提示词要求严格基于上下文回答、不添油加醋，并对知识库未覆盖的情况给出"仅供参考"的说明。

## 五、测试与踩坑

测试围绕三条线：意图识别是否走对分支、知识库命中是否相关、边界情况是否有合理出口。最典型的一个 bug：问"今天天气怎么样"，早期版本会误判成打招呼——因为短语匹配把"怎么样"这种短词也做了**包含匹配**，被长句包含进去。修复方法是收紧规则：只对 4 字以上的关键短语做包含匹配，短词只做完全相等匹配，问题立刻解决。另外还测了模糊缩写（GPIO34）、中英混问（esp32 deep sleep 电流）、知识库未覆盖的问题等，确保每个分支都有合理出口。

## 六、总结

通过 Dify，我用很少的代码搭起了"意图识别 + 知识检索 + RAG + 闲聊兜底"的完整问答助手。最大的体会：**数据质量决定上限，分支设计决定体验**。语料的结构和分段粒度直接决定命中质量；工作流的关键是用分支把寒暄、技术问答、兜底拆开，各走各的路，互不干扰。后续我计划接入 Rerank 精排提升准确率，并增加文档自动同步，让知识库随官方文档持续更新。