1. 从能跑通到敢上线生产级 RAG 的分水岭在哪很多人第一次用 Haystack 或 LangGraph 搭 RAG跑通一个上传 PDF 然后问答的 Demo 只花了半小时于是觉得这事成了。等到真把系统丢给业务方用问题就全冒出来了同一个问题问两遍答案不一样、检索回来的片段答非所问、工具调用时参数拼错导致接口报错、上下文塞满之后模型开始胡言乱语。这些不是模型不行而是流水线本身没做工程化。这一篇是系列第五部分前面几篇我们把 Haystack 的组件化检索链路和 LangGraph 的状态机编排分别拆过一遍。到了这一篇重点落在生产级三个字上——也就是把 RAG、工具合约Tool Contract、上下文工程这三件事拧成一条能稳定运行的流水线。关键词里的 Haystack、LangGraph、RAG、LLM、上下文工程本质上对应的是四个工程问题检索组件怎么选、状态怎么流转、工具怎么约束、上下文怎么裁剪。适合读这篇的人我假设你已经写过至少一个能返回答案的 RAG Demo知道 embedding 是什么、知道向量库大概怎么用但还没系统处理过检索质量不稳定和工具调用不可控这两类问题。如果你完全是零基础建议先把 Haystack 的 Pipeline 概念和 LangGraph 的 StateGraph 基本用法过一遍再回来不然中间的状态流转部分会有点吃力。我自己的判断标准很直接一个 RAG 系统能不能上线不看它答对多少而看它答错的时候会不会把错误放大。Demo 阶段答错就答错了生产阶段答错可能触发一次错误的工具调用、写错一条数据、给用户一个自信满满的错误结论。所以这篇的核心不是教你怎么让 RAG 更准而是教你怎么让 RAG 的行为可预测、可约束、可回退。下面我会按真实搭建顺序来讲先把 Haystack 的检索层做扎实再用 LangGraph 把检索、工具、生成串成状态机然后重点讲工具合约怎么设计才能防住 LLM 的自由发挥最后讲上下文工程里那些不写出来就会踩的坑。每一部分都会给可复现的配置和参数也会说明为什么这么选。2. Haystack 检索层决定 RAG 上限的不是模型而是召回2.1 为什么我把检索拆成粗排 精排两段刚上手时最容易犯的错是把整个检索压成一步query 进向量库top_k 拿回来直接塞给 LLM。这么做的直接后果是当知识库稍微大一点top_k 设小了漏召回设大了噪声淹没答案。我实测过一个两万条文档片段的库top_k5 时命中率大概 62%top_k20 时命中率上到 81%但塞进上下文的噪声让最终答案准确率反而掉到 58%。这就是典型的召回上去了、精度下来了。生产级的做法是把检索拆成两段。第一段用向量检索做粗排目标是把候选集从全库缩到几十条宁可多召回也别漏第二段用交叉编码器cross-encoder做精排对这几十条重新打分取前 3 到 5 条。Haystack 里对应的组件是InMemoryEmbeddingRetriever或接外部向量库的 retriever加SentenceTransformersRanker。粗排负责别漏精排负责别错职责分开之后调参才有方向。粗排的 top_k 我一般设成最终要用的 4 到 6 倍。比如最终给 LLM 喂 5 条粗排就取 20 到 30 条。精排模型选型上英文场景cross-encoder/ms-marco-MiniLM-L-6-v2性价比很高中文场景建议换成对应的中文交叉编码器否则精排效果可能还不如不排。这里有个反直觉的点精排模型不是越大越好L-6 和 L-12 在多数业务语料上的排序差异很小但推理耗时差一倍线上 QPS 一上来 L-12 很容易成为瓶颈。2.2 分块策略固定长度是最省事也最容易埋雷的选择分块chunking这件事文档里通常一笔带过但它对召回质量的影响比换 embedding 模型还大。固定长度切分比如每 256 token 一刀实现最简单问题是它会把一个完整语义单元拦腰截断。我见过最离谱的案例是一个退款流程的说明被切成两半前半段在 chunk 7、后半段在 chunk 8用户问退款只召回了前半段LLM 就照着半截流程编了个结尾。我的做法是按结构切分优先、固定长度兜底。如果原始文档有标题层级Markdown、HTML、带样式的 Word就按标题切每个小节作为一个 chunk超长再按句子边界二次切。Haystack 的DocumentSplitter支持按句子和按长度组合切分配置里把split_bysentence、split_length设成 3 到 5 句split_overlap设 1 句能在保留语义完整性的同时避免 chunk 过长。重叠overlap这个参数值得单独说。很多人设 0觉得省 token。但边界处的信息一旦被切断召回就彻底丢了。我一般设 10% 到 20% 的重叠比如 chunk 是 5 句overlap 就 1 句。代价是索引体积涨一点换来的是边界问题的召回率明显改善。这个投入产出比比换更大的 embedding 模型划算得多。2.3 元数据过滤被低估的召回精度杠杆纯向量检索有个天然缺陷它只看语义相似不看该不该看。用户问2024 年的政策向量检索可能把 2022 年的相似表述也召回来因为语义确实像。这时候元数据过滤就是救命的。Haystack 的 retriever 支持在检索时传filters可以按文档来源、时间、部门、版本号等字段先过滤再检索。我的经验是凡是知识库里有时效性或权限边界的字段都应该做成元数据并在检索时过滤而不是指望 LLM 从上下文里自己判断。原因很简单LLM 看到两条相似但年份不同的内容它没有可靠依据判断哪条更新很容易选错。把过滤放在检索层等于在源头就把错误选项排除了这比在 prompt 里写十句请注意时效性都管用。元数据字段的设计也有讲究。不要什么都往里塞只放会用于过滤和会用于展示引用来源的字段。字段太多会让索引膨胀而且维护成本高。我通常保留四类来源标识、时间戳、权限标签、版本号。这四类基本覆盖了绝大多数过滤需求。3. LangGraph 状态机把检索、工具、生成串成可控流程3.1 为什么不用一条直线 Pipeline 而要上状态图Haystack 的 Pipeline 是线性的A 组件输出给 BB 给 C。这在纯 RAG 场景够用但一旦引入工具调用就捉襟见肘了。因为工具调用本质上是根据当前情况决定下一步做什么——可能需要先检索、可能直接调工具、可能检索完发现不够再调工具、也可能调完工具发现要再检索一次。这种带分支和循环的流程线性 Pipeline 表达不了硬写会变成一堆 if-else 嵌套。LangGraph 的 StateGraph 正好解决这个。它把流程建模成节点node和边edge节点之间通过共享的 state 传递数据边可以是条件边conditional edge根据 state 里的内容决定走哪条路。这样检索→判断→调工具→再判断→生成这种带环的流程就能自然表达。我搭的典型结构是这样的入口节点做 query 改写然后进一个路由节点判断这个问题需要检索还是直接调工具还是两者都要检索节点和工具节点各自独立最后汇到生成节点。路由节点和生成前的判断节点都用条件边。整个图跑起来state 里始终带着原始 query、改写后的 query、召回的文档、工具调用结果、以及一个next_action字段用来驱动条件边。3.2 State 设计字段宁少勿多但关键状态必须显式State 是 LangGraph 的核心它决定了节点之间能传递什么。新手容易把 state 设计成一个什么都装的大字典结果节点之间耦合严重改一个字段到处报错。我的原则是state 只放跨节点需要共享的数据节点内部的临时变量不要往 state 里塞。一个生产可用的 RAG state 我通常定义这几个字段query原始问题、rewritten_query改写后、documents召回片段列表、tool_calls工具调用记录、tool_results工具返回、answer最终答案、next_action路由信号。其中next_action是关键它是个字符串枚举取值比如retrieve、call_tool、generate条件边就读这个字段决定走向。这里有个坑LangGraph 的 state 默认是覆盖式更新节点返回的字典会合并进 state。如果某个节点返回了documents字段它会覆盖之前的值。如果你想让多个检索节点累加文档得用Annotated配合 reducer 函数比如Annotated[list, operator.add]这样每次返回的列表是追加而不是覆盖。这个细节不搞清楚多轮检索的结果会莫名其妙丢失排查起来很费时间。3.3 条件边与循环怎么防止图跑飞条件边让流程有了分支能力但也带来了跑飞的风险——如果条件判断写得不严谨图可能陷入死循环或者该走生成的时候又绕回检索。我踩过一次坑路由节点判断文档数量少于 3 就再检索一次结果某次检索始终返回 2 条图就在检索和判断之间无限循环直到触发递归上限报错。防跑飞有两个手段。第一是给 state 加一个计数器字段比如retrieval_count每次检索节点自增条件边里判断如果 retrieval_count 2 就强制走生成给循环设一个硬上限。第二是利用 LangGraph 的recursion_limit配置默认是 25可以调低到 10 左右一旦超限直接抛错而不是静默死循环。两个手段一起用基本能兜住。条件边的判断函数要尽量简单、可测试。我见过把一堆业务逻辑塞进条件函数的写法结果这个函数既难测又难改。正确做法是条件函数只读 state 里的信号字段做判断真正的业务逻辑放在节点里。这样条件函数就是纯函数单元测试几行就能覆盖。4. 工具合约让 LLM 调工具不再自由发挥4.1 工具合约的本质是一份给 LLM 看的接口文档工具调用最容易出问题的地方不是工具本身写错了而是 LLM 传的参数不对。它可能把日期传成明天而不是2024-06-01可能把数字传成字符串可能漏传必填参数也可能自己发明一个不存在的参数名。这些错误的根源是 LLM 只能根据你给的描述去猜这个工具怎么用。所以工具合约Tool Contract的核心是把工具的输入输出约束写清楚清楚到 LLM 没有猜测空间。一份合格的合约至少包含工具名语义明确别用func1这种、功能描述一句话说清干什么、每个参数的名称、类型、是否必填、取值范围或格式、以及一个调用示例。这些信息会作为 schema 传给 LLM它据此生成调用参数。我对比过描述写得糙和写得细的两种情况。同一个查询订单工具描述只写查询订单信息LLM 传参错误率大概 30%把参数描述补成order_id字符串订单编号格式为 16 位数字例如 2024060112345678错误率降到 8% 以下。这个差距说明工具合约的投入产出比极高值得花时间打磨。4.2 参数校验必须放在工具内部不能只靠 schema即便 schema 写得再细也不能假设 LLM 一定按格式传参。生产环境里工具函数内部必须做二次校验把非法输入挡在业务逻辑之前。我的做法是在每个工具函数入口加一层校验类型不对就转或拒、格式不对就返回明确的错误信息、必填缺失就直接返回缺少参数 X。这里有个关键设计工具返回错误时不要抛异常让整个图崩掉而是返回一个结构化的错误结果让 LLM 看到错误后有机会重试或换策略。比如返回{status: error, message: order_id 格式错误应为 16 位数字}LLM 拿到这个信息下一轮可能就会修正参数重新调用。如果直接抛异常图就断了用户体验是系统出错而不是系统在尝试修正。我一般会给工具调用设一个重试上限比如同一个工具连续失败 2 次就不再重试直接走降级路径比如告诉用户暂时无法查询请稍后再试。这个上限同样用 state 里的计数器控制和前面防循环是一个思路。4.3 工具粒度太粗和太细都会让 LLM 犯难工具设计有个粒度问题。工具太粗比如一个处理订单工具包揽查询、修改、取消LLM 很难从描述里判断该传什么参数、该走哪个分支。工具太细比如把查询订单拆成按 ID 查按手机号查按时间查三个工具LLM 又容易选错工具。我的经验是一个工具对应一个明确的业务动作参数控制在 2 到 5 个。超过 5 个参数的工具通常意味着它承担了多个职责应该拆。少于 2 个参数的工具往往可以合并到相邻工具里。这个粒度下LLM 的选择空间适中既不会选错也不会因为参数太多而传错。另外工具名和参数名尽量用业务语言别用技术缩写。query_order_by_id比qry_ord好start_date比sd好。LLM 对自然语言命名的理解明显更准这一点在实测里反复验证过。5. 上下文工程决定答案质量的最后一公里5.1 上下文不是越多越好而是要刚好够上下文工程Context Engineering这个词最近很热但落到实操上核心就一件事在有限的 token 预算里放进去的信息要刚好够 LLM 答对不多不少。放少了答不全放多了模型注意力被稀释反而容易抓错重点。我做过一组对比同一个问题喂 3 条精准片段时答案准确率 85%喂 10 条含 7 条弱相关时掉到 67%。原因是大模型在长上下文里对中间位置的信息注意力会下降弱相关片段挤占了本该给关键信息的注意力预算。所以我的原则是宁可少喂几条高相关的也不为了信息全而堆量。具体到 token 预算分配我一般这么切系统提示词占 10%召回的文档片段占 50% 到 60%工具调用结果占 20%留 10% 到 20% 给模型输出。这个比例不是死的但有个底线——文档片段的总量不要超过上下文窗口的一半否则模型很容易看了后面忘了前面。5.2 片段排序把最相关的放在开头和结尾既然模型对中间位置注意力弱那片段排序就有讲究了。我的做法是把精排分数最高的放在最前面第二高的放在最后面中间的按分数递减排。这样模型在开头和结尾都能抓到强相关信息中间即使有弱相关片段影响也被削弱。这个技巧在长上下文场景下效果尤其明显。我实测过一个需要综合 5 条信息的复杂问题按分数顺序排时准确率 71%按首尾强、中间弱排时上到 82%。原理不复杂就是顺着模型的注意力分布来组织输入而不是跟它对着干。另外每个片段前面加一个简短的来源标注比如来源退款政策 v2.1能让模型在引用时更准确也方便用户核对。这个标注本身占不了几个 token但对答案的可信度提升很明显。5.3 对话历史怎么裁滑动窗口 摘要的组合拳多轮对话场景下历史消息会迅速吃掉上下文预算。全量保留不现实直接截断又会丢失关键信息。我的做法是组合拳最近 3 到 5 轮对话原样保留更早的历史用 LLM 压缩成一段摘要摘要控制在 200 字以内。摘要的 prompt 要明确要求只保留与当前任务相关的实体、约束和结论不要让它自由发挥。我试过让模型自由摘要结果它把一些无关寒暄也保留了反而占地方。加上约束之后摘要的信息密度明显提高。还有一个细节用户当前的问题要放在整个上下文的最后紧挨着模型要生成的位置。这是符合模型注意力机制的——离生成位置越近的内容影响越大。把问题放最后能确保模型是带着问题去读前面的上下文而不是读完上下文再去找问题。6. 上线前必须压测的几个点6.1 检索命中率怎么量化上线前一定要有一个可量化的检索评估。我的做法是准备 50 到 100 条问题-标准答案片段的测试集跑一遍检索看标准片段有没有被召回进 top_k。这个指标叫命中率hit rate是 RAG 最基础的体检项。命中率低于 80% 的话先别急着调生成回去查分块和 embedding。命中率之外我还会看 MRR平均倒数排名它衡量的是正确片段排在第几位。命中率高但 MRR 低说明召回了但排得靠后精排环节需要加强。这两个指标一起看能快速定位问题出在粗排还是精排。6.2 工具调用的成功率与错误分布工具这块要统计两个数调用成功率和错误类型分布。成功率低于 90% 就要查工具合约是不是描述不清。错误分布能告诉你问题在哪——如果大量错误是参数格式错误说明 schema 描述不够细如果是选错工具说明工具粒度或命名有问题。我一般会把这些错误日志单独存一份定期拿出来看。很多工具合约的改进点都是从错误日志里发现的比拍脑袋想有效得多。6.3 端到端延迟的拆解生产环境用户对延迟很敏感。端到端延迟要拆成检索耗时、工具调用耗时、LLM 生成耗时三段来看。检索通常几十到几百毫秒工具调用看外部接口LLM 生成是大头。如果总延迟超标先看是哪一段拖后腿。我踩过的坑是精排模型拖慢了整体。粗排 50ms精排 800ms因为精排要对 30 条候选逐条打分。后来把精排候选数从 30 降到 15延迟降到 400ms命中率只掉了 2 个百分点。这种取舍要看业务能接受多大的延迟没有标准答案但一定要量化之后再决定。7. 几个我反复踩过的坑第一个坑是 embedding 模型和检索语言不匹配。用英文模型检索中文语料命中率会低得离谱而且这种问题很隐蔽因为系统不报错只是答得差。上线前一定要确认 embedding 模型的语言覆盖中文场景就用中文或多语言模型。第二个坑是元数据过滤字段类型不一致。索引时时间字段存的是字符串检索时传的是时间戳过滤直接失效还不报错。这种问题只能靠测试集覆盖所以测试集里一定要包含需要过滤的场景。第三个坑是工具返回结果太大。有个工具返回了一整张表几万 token 直接撑爆上下文。后来改成工具内部先做聚合只返回关键字段。工具返回的数据量一定要控制别把原始数据一股脑丢给 LLM。第四个坑是条件边的判断依赖了可能为空的字段。state 里某个字段还没被赋值时条件函数读它会报错。我的做法是条件函数里对所有读取的字段做空值兜底默认走最安全的路径通常是直接生成。这套流水线搭下来从 Demo 到能上线中间的工作量大概有七成花在检索质量、工具合约和上下文裁剪上真正调 LLM 的部分反而最少。这也是我想强调的生产级 RAG 的难点不在模型而在模型之外的那些工程约束。把检索做扎实、把工具约束清楚、把上下文裁到位模型的表现自然就稳了。