DeerFlow：RAG文档问答系统搭建与调优全记录

最近我把手头一个基于检索增强生成RAG做文档问答的参考实现整理成了完整笔记项目代号就叫 DeerFlow。简单来说它解决的是“文档很多、答案很难找”的问题——把几十份甚至上千份 PDF、Word、Markdown 投进去通过离线索引加在线检索加大模型生成让用户可以用自然语言直接提问系统给出带来源引用的回答。这套东西在企业知识库、内部制度问答、学术资料检索这类场景非常实用。这篇笔记我会以一套完整可跑通的方案为主线把架构选型、环境搭建、核心实现、调优过程和踩坑记录都写清楚适合正在做 RAG 应用、知识库问答的开发者参考。1. DeerFlow 项目到底在解决什么问题1.1 为什么不用裸的大模型问答很多人最开始的想法很直接把文档喂给大模型让它“记住”然后随便问。这个思路在少量短文本上勉强能跑但一旦文档数量多起来、内容更新频繁问题就全出来了。大模型的上下文窗口是有限的几千上万份文档不可能一次塞进去就算硬塞进去模型对细节的记忆也会被稀释回答开始张冠李戴。更关键的是大模型本身的“自信”很容易误导人。它对一个没有见过的问题会依照训练时的统计规律编造一个看起来合理的回答也就是所谓的幻觉。内部制度文档、技术规范这类资料要求的是“答案必须有出处”而不是“答案听起来很顺”。所以 DeerFlow 从一开始就放弃了纯提示词注入的方案改用 RAG 管线先检索出与问题真正相关的文档片段再把片段作为依据交给模型生成答案。这样模型回答的每一个关键信息都能在原始资料里找到对应位置。1.2 可插拔的流水线设计DeerFlow 的核心是一条五段式流水线文档解析、文本切分、向量化索引、候选召回、重排序与生成。每一段都是独立模块接口固定内部实现可以随时替换。这种设计的直接好处是调试成本低。我实际跑下来的感受是RAG 应用最大的问题在于“不知道到底哪一环节出了问题”。用户说答案不对可能是因为文档没解析干净可能是因为切分把一句话从中间砍断了可能是因为向量检索召回不到相关片段也可能是因为生成提示词没写清楚。如果所有环节耦合在一起定位问题会非常痛苦。拆开之后每个环节都能单独验证、单独调参、单独替换出问题时顺着管线逐段排查效率会高很多。另一个好处是组件的可替换性。向量库可以换、Embedding 模型可以换、LLM 可以换只要接口一致其余部分不用动。后期如果想从开源模型切换到商用接口或者想换一个效果更好的 Embedding 模型改动都控制在一个模块内部。1.3 向量召回加重排序的双阶段设计DeerFlow 的检索策略是“先宽后严”第一阶段用向量相似度把候选集放大第二阶段用重排序模型做精排。这个设计有几个层面的考虑。如果只依赖向量检索召回质量通常不够稳定。向量检索擅长语义匹配但对细节的辨识力偏弱经常会把主题相近但内容不相关的片段排到前面。如果只依赖重排序模型也不行——重排序模型一般只能处理几十条候选不可能对上万个文档块一一打分。所以正确姿势是把两段串起来先用低成本的向量检索从海量块里粗筛出 50 到 100 个候选再用重排序模型对这几十个候选逐条打分最后把最相关的 5 到 10 个片段送进生成模块。这个漏斗式的思路很像招聘流程简历初筛放宽条件把可能合适的人都捞进来笔试面试再精挑细选。初筛太严会漏掉潜在候选人终筛太松会让不合适的人混进去。DeerFlow 里的 TopK 参数其实就是这个漏斗的开口大小调参的本质是在“召回率”和“精度”之间找平衡点。2. 环境搭建与依赖准备2.1 运行环境与虚拟环境DeerFlow 涉及的依赖比较多而且部分库对 Python 版本比较敏感。我建议使用 Python 3.10 及以上的版本创建独立的虚拟环境来隔离依赖不要直接装在系统全局环境里。在 Ubuntu 这类 Linux 环境下的操作基本是这样python3.10 -m venv deerflow-env source deerflow-env/bin/activate pip install --upgrade pipWindows 上把第二行换成激活脚本路径即可。虚拟环境有两个实际好处一是避免与系统其他项目发生包冲突二是后期升级或删除依赖时不会影响到别的项目。我见过不少人图省事直接全局安装结果一个包版本变了好几个项目同时出问题排查起来非常头疼。2.2 组件依赖选型清单整个项目用到的组件大致分成五类文档解析、文本切分、向量数据库、Embedding 模型、LLM 接入。这里我给出我实际用过的、比较稳的组合参考。组件类别推荐选择说明文档解析用通用文档解析库组合PDF、Word、Markdown 分别处理保留结构信息文本切分基于递归字符切分器改造按标题、段落、句子边界优先保留重叠窗口向量数据库轻量级开源向量库优先单机部署简单支持持久化适合中小规模Embedding 模型中文语义效果稳定的开源向量模型维度适中推理资源需求可控重排序模型交叉编码器类精排模型对候选片段逐条打分精度高LLM 接入兼容通用接口即可本地部署或远程 API 都能切换选型时我有几个判断标准组件必须开源、社区活跃、接口文档完整。社区活跃度很重要因为这类组件迭代快活跃的项目通常 bug 修复及时文档也更新得快。另外尽量选带有标准接口的组件比如向量库遵循统一的检索接口LLM 接入走通用的 OpenAI 兼容协议这样将来替换成本最低。2.3 配置项与环境变量DeerFlow 的配置我放在了一个单独的 YAML 文件里敏感信息用.env文件管理不写进代码也不提交到版本库。一个典型的配置文件结构大致如下# config.yaml embedding: model_name: your-embedding-model-path dimension: 768 batch_size: 32 vectorstore: persist_directory: ./data/vectorstore collection_name: deerflow_docs retrieval: embed_top_k: 50 rerank_top_k: 5 llm: base_url: ${LLM_BASE_URL} api_key: ${LLM_API_KEY} model_name: your-chat-model temperature: 0.1 max_tokens: 1024.env文件里放实际的密钥和地址LLM_BASE_URLhttp://localhost:8000/v1 LLM_API_KEYsk-local-test-key把密钥放到配置文件之外主要是为了防止误提交。我踩过一次坑把测试用的 API Key 直接写进了 YAML 文件后来推送到仓库才发现虽然是个测试 Key但更换一次凭证的流程也够折腾。从那次以后凡是密钥类的信息一律走环境变量配置文件里只留引用标记。3. 核心实现细节与实操要点3.1 文档解析与切分检索质量的真正上限这是整个 DeerFlow 里最容易偷懒、也最容易翻车的地方。我一开始图省事直接用最简单的固定长度切分按字符数硬切结果检索效果非常差。后来才意识到一个关键事实切分质量决定了检索质量的上限后面所有模型再怎么调都弥补不了切分阶段造成的损失。固定长度切分的问题在于它完全忽略文本结构。一个段落可能讲到一半被切断一个表格被拆成两半一段代码块中间断开。用户的问题是“这个表格里的字段含义是什么”结果相关片段被切得支离破碎向量化之后语义不完整召回自然失败。正确的做法是感知结构的切分优先按标题层级切其次按段落切再按句子切每一块尽量保持语义完整。切分参数上我实测下来比较稳的范围是每个块的 Token 数在 256 到 512 之间相邻块之间有 50 到 100 个 Token 的重叠。重叠不是浪费它是为了让跨块的语义保持连续。比如一句话刚好落在前一块的末尾如果完全没有重叠这句话后半段就孤立了检索时可能因为信息不完整而降低匹配度。对于表格类内容我的经验是把 Markdown 格式的表格转换成保留行表头语义的文本描述再作为一个独立块。比如表格项目状态定义 状态名: 待开始 定义: 项目已创建尚未分配负责人 状态名: 进行中 定义: 项目已有负责人开发工作正在进行这样转换之后表格的语义能被向量模型更好地理解检索“待开始状态的业务含义”这类问题时命中率明显提升。3.2 向量索引构建与 Embedding 选型Embedding 模型是把文本变成向量的核心它的效果直接决定向量检索的召回上限。选型时我主要看四个维度中文语义效果、向量维度、推理资源、许可证友好度。中文语义效果是首要因素。同一个词在不同语境下含义可能完全不同比如“苹果”既可以是水果也可以是公司这对向量模型是很大的挑战。一个中文语料上训练得好的模型能在这种歧义场景下把向量分布拉开。判断效果的方法也很直接拿自己领域里有代表性的几十个句子做相似度测试看 top 命中是否合理不要盲目相信榜单数据。向量维度影响存储和计算开销。768 维的向量在几万条块规模下完全没压力但如果文档量到几十万甚至上百万块维度越高存储占用和检索耗时都会上升。中小规模项目我建议优先考虑 768 维左右的中等规模模型效果和性能比较平衡。索引构建的过程在 DeerFlow 里大致是这样对切分好的每个文本块调用 Embedding 模型生成向量连同文本内容和元数据一起写入向量库。文档多的时候注意分批处理不要一次性把所有文本塞进内存否则很容易直接 OOM。from your_vectorstore import VectorStore store VectorStore(persist_directory./data/vectorstore) for batch in chunked(documents, size64): vectors embedding_model.encode(batch.contents) store.add( idsbatch.ids, embeddingsvectors, documentsbatch.contents, metadatasbatch.metadatas, )这里批大小 64 是我常用的起始值如果显存或内存充足可以加大不足就减小。重点是要稳创建索引阶段崩一次后面的排错时间都不少花在重新索引上。3.3 重排序与 TopK 的选择重排序模型是整个检索链里提升精度最明显的环节。它的作用和初筛完全不同初筛用向量相似度快速把候选集扩大重排序则用交叉编码器把查询和候选片段一起编码精细计算相关性。DeerFlow 里的默认参数是第一阶段召回 50 个候选第二阶段重排序后取前 5 个。这个配置在通用场景下是一个不错的起点但实际使用中要结合文档规模和问题类型调整。我做了几组对比实验结果整理成表配置组合检索命中率回答引用完整度单次查询耗时只做向量检索TopK10约 61%部分回答引用不相关0.8 秒向量检索 TopK50 重排序取 TopK5约 84%回答引用质量明显提升1.6 秒向量检索 TopK100 重排序取 TopK10约 87%回答内容更全面2.4 秒可以看到加了重排序之后命中率提升非常明显而进一步扩大候选集带来的收益就有限了但耗时增加了不少。所以实际使用时要根据场景权衡如果对延迟敏感用 50 加 5 的组合如果更看重答案的完整性比如做学术资料问答可以用 100 加 10。还有一个重要参数是重排序的分数阈值。不同模型的分数分布差异很大有的集中在 0.8 到 0.9有的分布在整个区间。我建议先在真实数据上跑一遍观察分数分布再决定阈值。低于阈值的片段直接丢弃避免把不太相关的内容送到生成模块去干扰回答。3.4 生成侧提示词与引用溯源检索做得再好生成提示词写得不清楚答案质量照样会垮。DeerFlow 的生成提示词遵循几个原则限制回答依据、教模型承认不知道、强制标注来源。以下是我实际使用的基础版提示词你是一个文档问答助手。请严格按照下面提供的资料片段回答问题。 要求 1. 回答只能基于资料片段不得使用你自己的常识补充。 2. 如果资料片段无法回答问题请明确回答“资料中没有找到相关信息”。 3. 每一条关键信息后面用 [来源编号] 标注它出自哪个片段。 4. 回答尽量简洁用条目或段落形式组织。 资料片段 [片段 1]... [片段 2]... 问题... 回答这个提示词的要点在于“来源编号”和“拒绝回答”两项。它们看似简单但对回答质量影响巨大。来源编号让用户可以反向核查回答的真实性也倒逼模型不要脱离资料胡编拒绝回答的设定让模型在没有依据时敢于说实话而不是硬凑一段话。我实测过一个场景用户问“请假超过七天是否需要提前两个工作日申请”资料里只规定了三天以内的流程并没有七天以上的描述。规范版本的回答是“资料中未找到超过七天请假流程的相关规定但三天以内的流程要求是在休假前两个工作日提交申请”既说明了未覆盖的情况也给出了已有信息用户可以据此判断。这种输出的可信度远高于模型凭感觉编一个答案。4. 从跑通到调优的完整实操记录4.1 第一次端到端运行实录与问题排查我第一次跑通 DeerFlow 时的数据是一批公司内部制度文档总共约 40 份涵盖出差报销、请假流程、设备采购、信息安全等主题。按流程配置好环境依赖把文档放进去构建索引然后启动问答服务。第一个问题是“差旅住宿费用报销的最高标准是多少”。结果模型回答了一长串关于报销流程的通用内容却没有给出具体的金额标准。这个输出格式上很像那么回事但关键信息完全没答到点子上。我按管线逐段排查。先查文档解析结果PDF 里“费用标准”部分的表格确实被解析出来了但检查切分后的块时发现表格内容被切成了两段数字和说明文字被分开。再查向量检索结果Top10 里居然没有包含费用标准的片段。这就定位了问题切分破坏了表格的语义完整性导致向量表示时丢失了关键信息。于是我调整了表格的解析策略把表格整体保留为一个独立块并转成文本描述。重建索引后第一个问题的检索命中立即恢复正常。整个过程给我的感受是RAG 应用出问题时最忌讳直接换模型、调温度参数那样基本都是碰运气。正确思路是从数据侧开始排查解析、切分、索引、召回、生成一层层验证问题通常很快就浮出水面。4.2 检索质量调优的三组实验为了验证不同环节对最终效果的影响我用同一份文档集做了三组实验。每一组都固定生成模型不变只调整检索侧参数。第一组是基线方案默认 512 Token 的切分大小向量检索直接取 TopK10不加重排序。回答效果最差表现为参考文献命中不稳定、回答内容偶尔包含无关信息。原因是 TopK10 召回的候选数量太小一旦前面几个候选相关性不高后面也没有更多候选可以替代。第二组方案在基线基础上加了重排序向量检索先召回 50 个候选再用重排序模型取前 5 个。效果提升非常显著回答引用的准确度高了很多。原因是重排序模型能更精细地判断查询与片段的相关性把真正相关的片段排到前面过滤掉向量相似度高但主题不符的噪声。第三组方案在第二组基础上做了切分优化按文档标题结构切分重叠窗口从 0 加到 64 Token表格独立成块。效果进一步提升尤其是涉及数值、标准、流程细节的问题命中率明显上升。这说明切分优化的收益在细节型问题上最明显因为这类问题对片段的语义完整性要求最高。三组实验的结论是重排序带来的收益最大切分优化带来的收益次之单纯扩大向量检索候选数带来的收益最小。这也验证了那个老结论——RAG 系统里检索质量对最终回答的影响远大于生成模型本身。4.3 用最小评估集合做回归验证调参过程中我养成了一个习惯维护一个最小评估集。这个评估集由 20 个典型问题组成覆盖文档里最常见的几类查询数值型问题报销标准、限额、流程型问题申请步骤、审批顺序、概念型问题名词解释、定义。每个问题标注了期望的答案来源。每次改动配置或切分策略我都会跑一遍这 20 个问题统计两个指标检索命中率期望来源是否出现在最终传入生成模型的片段中和回答引用完整度大模型输出是否正确标注了来源。这个习惯帮我避免了一个常见陷阱改了一个参数手动测了 3 个问题感觉效果好实际上整体是在波动并没有稳定提升。用评估集跑回归不需要太复杂的工具一个简单的 Python 脚本就能完成。把问题和期望来源记在 JSON 文件里跑完检索后检查候选片段是否包含期望来源自动统计命中率。这个方法维护成本很低却能给出相对客观的效果判断比拍脑袋测两个问题靠谱得多。import json from your_retriever import retrieve_fragments with open(eval_set.json, r, encodingutf-8) as f: eval_set json.load(f) hit 0 for item in eval_set: fragments retrieve_fragments(item[question], top_k10) if any(item[expected_source] in frag for frag in fragments): hit 1 print(f命中率: {hit}/{len(eval_set)})5. 常见问题与排查技巧实录5.1 文档上传后检索不到先查索引链路我在项目里遇到过好几次“明明文档加了就是检索不到”的情况。排查时先确认三个节点文档是否成功解析、切分后是否有内容、向量库是否真正写入了数据。最容易出问题的是解析环节。有些 PDF 其实是扫描件里面根本没有可提取的文本层解析出来是空白。这种情况需要先做 OCR或者确认源文档是否真的包含文本。我习惯在解析后打印每个文档的字符数一眼就能看出哪个文档是空壳。python check_parse.py --input ./docs --output ./parsed这个脚本会输出每个文档的解析字符数和切分块数。字符数为零的直接单独处理。5.2 答案答非所问九成是切分或召回问题如果检索结果里没有相关内容生成模型再强也答不对。排查时先用检索模块单独测试看看关停生成只留检索时返回的片段是否真的和问题相关。我遇到过一种很典型的情况用户的问题用词和文档里的用词完全不同但表达的是同一个意思。比如文档里写“入离职手续”用户问“员工入职流程”。这时候靠关键词匹配肯定不行要看向量召回是否能把语义拉通。如果召回结果不理想优先考虑换更合适的中文 Embedding 模型而不是调整切分参数。5.3 回答生硬、不带引用检查提示词是否要求了来源有一次我改完生成模型后所有回答都变得非常流畅但没有来源编号。排查后发现是新模型的指令遵循能力没有旧模型好提示词里的“用 [来源编号] 标注”没有被严格执行。解决办法有两个方向一是换一个指令遵循能力更强的模型二是把提示词里的来源要求放到更靠前的位置并增加一个输出格式示例。后者通常立竿见影因为大多数模型对提示词末尾的要求容易忽略对早出现的要求把握得更准。5.4 内存和显存占用过高分批处理与流式生成大批量文档构建索引时内存占用经常飙升。我用的办法是把索引构建改成批量处理每次只处理几十个块同时设置合理批大小避免一次加载全部文档。生成侧的显存压力主要通过流式输出缓解另外在加载模型时合理设置量化参数也能显著降低显存占用。如果文档量和并发量再往上走就要考虑向量库的分布式方案但那是下一步的优化方向不建议一开始就上。5.5 问题排查速查表现象排查方向常见解法文档检索不到解析、切分、索引链路检查解析字符数确认向量库写入成功检索到但答案不对切分完整性、召回 TopK优化切分策略加入重排序回答不带引用提示词指令调整提示词顺序增加输出示例检索结果明显不相关Embedding 模型选型换中文效果更好的向量模型构建索引时 OOM批处理策略减小批大小分批写入查询速度慢候选集过大减小第一阶段的 TopK控制重排序候选这套速查表是我在项目里反复用到的排障路径。绝大多数问题都能在上面三个节点之一找到根源数据链路、检索策略、生成提示词。先把这三层验证完再考虑换模型的事。整理完 DeerFlow 这套项目笔记我最深的体会是RAG 应用真正考验人的不是模型选得多新、技术栈多热闹而是把数据处理的每一个细节都做到位。文档解析不干净、切分不合理、检索参数拍脑袋、提示词没有约束任何一环偷懒最终都会以答案质量差的形式还回来。最后再分享一个小技巧检索效果不好时先别急着换大模型去检查你的文档解析和切分——这是我把这套管线从跑通到调优踩了无数坑之后最想提醒自己的一条。