上一篇《前端也能搞懂 RAG用 JS 手写一条最小检索增强链路》把链路跑通了。但能跑和跑得准是两回事。这篇记录我把链路接到真实文档后踩的四个坑——切块的两个极端、连接被重置、高分却答非所问。每个坑都附现象、排查、解法和背后原理。写在前面为什么跑通之后才是真正的开始第一篇里我用几段干净的示例文本就把 RAG 跑通了算向量、比相似度、拼 prompt、调模型一气呵成。但那是实验室环境。真把一篇结构化的 markdown 技术文档喂进去问题立刻冒出来召回的内容驴唇不对马嘴、建库时接口直接报错、明明分数很高答案却跑偏。这四个坑分别卡在 RAG 链路的几个位置坑 1、坑 2 在入口——文档怎么切块切太碎丢上下文、切太大被稀释两个极端都会拉低检索上限坑 3 在中间——把几十段文本一次性发给 embedding 接口连接被重置坑 4 在出口——相似度分数很高却不代表这段内容真能回答问题。它们有个共同点都不是代码语法错误而是看起来没问题、跑起来才暴露的工程问题。这正是面试时最能体现你真做过的部分。坑 1文档切块不当让 RAG 答非所问这一坑要回答的问题一篇 markdown 文档到底该怎么切成块现象召回一句光秃秃的标题我把一篇带多级标题、表格、代码块的技术文档直接放进 RAG检索回来的内容很不合理——经常召回一句孤零零的标题或者半截没头没尾的正文。AI 拿着这种料,自然答得不知所云。排查不靠猜打印每一块看我没有凭感觉改代码而是先写了个切块自测node knowledge.js把每一块的字数和前 40 个字打印出来。一眼就看到93 段里一大半是坏块集中在三类标题单独成块比如## 1. 市面上的缓存策略概览整块只有一句标题、没有正文。召回它等于拿到一句废话。标题和正文被切散### 3.1 为什么需要 KV Cache和它下面的正文成了两块。命中正文那块时丢了这段在讲啥的上下文。符号噪声被当正文目录、表格的管道符| 向量 | 变换 |、|---|、代码块被当成普通文本。这些符号 embedding 出来方向是乱的。根因很快定位到我最初用的是**“按空行切段的朴素切法。它对付自然段落还行但对结构化文档水土不服**——结构化文档的语义边界是标题层级”根本不是空行。解法从按空行切改成按标题聚合思路是顺着文档自己的结构切每遇到一个#标题就开一个新块把标题下面的正文都收进这一块块首拼上标题路径如章 节 小节让每一块自带归属、能被独立理解加代码围栏跟踪内部的#比如 Python 注释不能误判成标题——这是我改完第一版后发现代码块里的# 污染了标题栈专门补的一刀超长小节再按句号二次切避免一块塞进太多主题。结果很直接93 段噪声块 → 30 段干净块每块都带章节路径。同一个问题检索最高分从 0.4 级的噪声命中提升到 0.7 级的精准命中。拿个最小示例跑一遍可复现口说无凭贴一份会同时踩中上面三类坏块的最小文档复制下来存成sample.md就能复现## 1. 缓存策略概览 ## 2. KV Cache ### 2.1 为什么需要 推理时每一步都要重算历史 token 的 K 和 V开销随长度上涨。 把 K、V 缓存下来下一步直接复用 python # cache 是个 dict按层存 cache[layer] (k, v) ### 2.2 命中率 | 场景 | 命中率 | |------|------| | 多轮对话 | 高 |按空行切朴素切法切出来一堆坏块## 1. 缓存策略概览单独成块光标题没正文、### 2.1 为什么需要和它的正文被切散成两块、代码里的# cache 是个 dict这行注释可能被误当成标题、表格的|---|也单独成块。按标题聚合则切成干净的两块每块自带标题路径[块1] 2. KV Cache 2.1 为什么需要 推理时每一步都要重算…把 K、V 缓存下来…含 python 代码块 [块2] 2. KV Cache 2.2 命中率 | 场景 | 命中率 | …## 1. 缓存策略概览这种纯标题被并进下文或跳过代码块里的#因为有围栏跟踪不再污染标题栈。这就是 30 段干净块的由来。背后原理块的质量 检索的天花板RAG 检索的最小单位是块。块的质量直接决定检索质量garbage in, garbage out。切块不是无脑按某个分隔符切而要顺着文档的语义结构切并让每一块携带足够上下文标题路径能被独立理解。一句话总结我把切块从按空行升级成按标题聚合 带标题路径还处理了代码块内#的误判把 93 段噪声块压到 30 段干净块检索从 0.4 级噪声命中提到 0.7 级精准命中——切块质量是 RAG 检索质量的天花板这步没做好后面全白搭。几个可能被追问的点为什么不把整篇文档当一个块检索粒度太粗召回一大坨里相关的只有一句既稀释相似度正是下面坑 2 的问题又浪费 token。表格、代码块怎么办现在让它们留在所属小节内靠周围正文提供语义。更讲究的做法是把表格转述成自然语言句子再 embedding降低符号噪声。还能更好吗能超长块改用带重叠overlap的滑窗切避免切口处语义断裂。我知道天花板在哪这一版先用够用的方案跑通。坑 2片段切太大相似度反被稀释这一坑要回答的问题块是不是越大、信息越全越好现象最完整的那段说明文分数反而最低坑 1 解决了切太碎我一度顺势以为那就尽量切大块、信息全一点更保险。结果做检索实验时被打脸。基准句怎么退货拿三个候选去打分候选片段相似度长度退货0.94622 字退款时效是多久0.7923中商品签收后7天内可无理由退货需保持包装完好0.7077一整句说明文最完整、最该当答案的那段说明文分数0.7077反而最低比光秃秃两个字的退货0.9462低了一大截。排查长片段的语义焦点被稀释了embedding 是把整段文字压成一个向量——一段话里塞的主题越多这个向量越像各主题的平均值语义焦点越散。短问句怎么退货焦点极集中而那段说明文里还混着7天“无理由”包装完好一堆次要信息跟问句方向一对齐相似度就被这些无关分量拉低了。这跟坑 1 正好是两个相反的极端坑 1 是切太碎丢上下文这里是切太大焦点被稀释。解法块大小有个甜区一块只装一个主题别把整节几百字塞进同一块坑 1 里超长小节按句号二次切就是为这件事服务的多大算合适没有银弹要结合检索分数实测调——块太大就拆、召回丢了上下文就合。背后原理检索比的是语义焦点不是信息量相似度高低取决于两个向量方向有多一致而不是哪段信息更全。片段越长越杂方向越偏离问句分数越低。所以知识库片段要尽量完整是个直觉陷阱——完整 ≠ 好召回。一句话总结我实测发现一整句退货说明0.7077的检索分反而低于两个字的退货0.9462因为长片段把语义焦点稀释了。切块大小有个甜区太碎丢上下文坑 1、太大被稀释本坑要按检索分数实测去调。举一反三换个格式边界就换个东西坑 1 和坑 2 合起来其实是同一句话切块要顺着文档的语义边界切——markdown 的边界恰好是标题层级。换个文档格式边界就变了文档类型语义边界在哪典型的坑纯文本 txt段落 / 句子无显式结构只能定长滑窗容易切断句子Markdown本文标题层级#代码块内的#被误判成标题PDF提取后比 md 更脏跨页断句、页眉页脚、表格变乱码得先清洗再切HTML / 网页DOM 结构h1/p 去掉导航和广告标签与噪声内容混进正文代码函数 / 类而不是行按行切会把一个函数劈成两半说明这次我只亲手做了 markdown 这一种上表其余格式是同一原理的迁移、不是我都踩过——但先找到该格式的语义边界、再顺着它切这条原则是通用的。坑 3Embedding 批量请求被重置连接ECONNRESET这一坑要回答的问题几十段文本一次发给接口为什么会断现象换了知识库建库直接报错切块优化后知识库从 21 段短文本换成 30 段更长的块。结果调用 embedding 接口直接报fetch failed底层错误是ECONNRESET——连接被对端重置向量根本建不起来。排查抓住唯一变量先看错误类型ECONNRESET是传输层连接被重置不是接口返回的 4xx 业务错误。这说明请求根本没被正常处理完而不是参数错了。对照改动找单一变量代码一行没动唯一的变化是input数组变大了段数变多 单段更长单个请求体明显变大。下判断embedding 接口对单次请求的批大小/体积有上限超了之后服务端直接断连而不是优雅地返回一个错误码。解法分批 重试两点改动就够了把input数组分批——每批 16 条逐批请求再把各批向量拼接起来对瞬时网络错误重试一次等 1 秒再发。// 伪代码核心就两件事——分批、对瞬时错误兜一次constBATCH_SIZE16asyncfunctionembedAll(texts){constvectors[]for(leti0;itexts.length;iBATCH_SIZE){constbatchtexts.slice(i,iBATCH_SIZE)vectors.push(...awaitembedWithRetry(batch))}returnvectors}asyncfunctionembedWithRetry(batch,retriedfalse){try{returnawaitembed(batch)}catch(e){if(!retried){// 瞬时抖动等 1 秒重试一次awaitnewPromise(rsetTimeout(r,1000))returnembedWithRetry(batch,true)}throwe}}背后原理调外部接口的两个默认假设调任何第三方接口都要默认它有两件事有体积上限、会偶发抖动。分批把大请求拆小绕开体积上限重试兜住瞬时网络波动。这是调用第三方 API 的通用健壮性手段不只 embedding 适用。一句话总结段数变多后 embedding 请求体过大触发了 ECONNRESET我改成每批 16 条分批发送 失败重试一次既绕开接口的批量体积上限又兜住偶发的网络抖动。几个可能被追问的点批大小 16 怎么定的经验值 留余量远低于接口上限即可。要精确可以二分试出上限再打个折。重试会不会有副作用embedding 是幂等的同样文本返回同样向量、不产生写操作重试安全。如果是有副作用的写接口就要加幂等键再重试。坑 4语义检索高分 ≠ 能回答这一坑要回答的问题相似度分数高就代表这段能回答问题吗现象干扰项的分数逼近真答案我用怎么退货做检索专门放了一个干扰项怎么换货。结果候选句相似度实际能不能回答退货政策是什么0.8081✅ 是怎么换货0.8051❌ 同领域但不是一回事两者只差 0.003。但换货 ≠ 退货这是答非所问的内容分数却几乎和真答案一样高。光看分数排序根本分不开。排查这是我主动设计出来的实验这个坑不是偶然撞上的是我做控制变量实验时主动设计的——基准句 vs 候选句打分专门放了同领域但不同事的干扰项换货、改地址。实测发现干扰项的分数能逼近真答案仅靠分数排序无法区分相关和能回答。解法不是一招是多层兜底Top-K 相似度阈值控制召回数量过滤掉勉强相关的但阈值很难一刀切——这里真答案和干扰项只差 0.003一刀切要么都留、要么都砍所以更关键的是 RAG 的system 强约束——“只根据资料回答没有就说不知道” 低 temperature让模型即使召回了边缘内容也不乱编。我用奶茶店知识库实测过问一个库里根本没有的问题检索被阈值滤空后AI 老实回无法回答而不是硬编一段。这就是多层兜底的价值。背后原理检索是 RAG 质量的天花板相似度衡量的是语义方向接近但语义接近不等于能回答这个问题。检索召回是 RAG 质量的天花板——召回错了下游模型再强也救不回来。这也是为什么不能把 RAG 当万能它赢在私有知识和不幻觉但只要检索召回不对就全盘皆输。一句话总结我实测发现换货和退货只差 0.003、干扰项分数能逼近真答案说明相似度高 ≠ 能回答。所以 RAG 不能只靠 Top-K要叠阈值过滤 强约束 prompt 低温兜底而且检索质量是整个 RAG 的天花板这是我对 RAG 局限最深的认知。几个可能被追问的点阈值到底怎么定不是拍脑袋是先把全量分数打印出来看分布找断层在明显的分数落差处划线。还有更强的解法吗有用rerank 重排序模型对 Top-K 结果二次精排比纯向量相似度更懂能不能回答或混合检索向量 关键词 BM25 互补。RAG 和直接问模型怎么选我做过对比实验私有知识问题 RAG 完胜直接问会编、RAG 精准引用且标出处库里没有的问题 RAG 拒答更安全但公开常识题 RAG 反而更差——会因文档没写而拒答不如直接问。所以 RAG 不是用得越多越好要看问题类型。结语真正值钱的不是这 4 个答案这四个坑串起来是 RAG 的一条质量链切块质量 → 建库稳定性 → 检索准确性 坑1 太碎 / 坑2 太大 坑 3 坑 4但比记住这条链更重要的是它们底下藏着的两条共同线索——这才是我想留给你的东西。第一条这四个坑全和直觉相反。“切大块信息更全、更保险”——坑 2 说不焦点会被稀释“分数高的就是对的答案”——坑 4 说不换货和退货只差 0.003“代码一行没动就不会出错”——坑 3 说不光是数据变大就能把连接搞断。在 RAG 工程里凭感觉拍的板大多会被实测打脸。既然直觉靠不住第二条线索才是真正的主角把中间状态打印出来用眼睛看。坑 1 打印每一块的字数和预览坑 2、坑 4 打印检索分数的分布坑 3 死盯住唯一变量。我没有一次是靠猜改对的——全靠把黑盒的中间产物摊开看块长什么样、向量打几分、请求体多大。这才是这篇文章真正想给你的面试官不会因为你背得出换货 0.8051而记住你但会因为你一遇到检索翻车就说我先把每块、每个分数打印出来看一眼而对你高看一眼。具体的知识点会过时、会被问到死角但让黑盒变透明这套排查方法换个框架、换个场景照样好使。至于 RAG 本身一句话收尾就够它没有魔法——模型再强也只能基于你喂进去的料回答。这四个坑说到底都在保证同一件事喂进去的、取出来的是干净的、是对的。第一篇教你把链路跑通这一篇想说的是跑通只是起点能把为什么跑不准一层层拆开看的人才算真的会 RAG。原创声明本文首发于我的个人博客 rjy92.github.io。如需转载请注明出处。如果这篇文章帮到了你欢迎在以下平台关注、交流掘金https://juejin.cn/spost/7654961236196442163CSDNhttps://blog.csdn.net/u012565530/article/details/162295714