外面讲 RAG 的文章一开口就是「检索增强生成」的三段论定义，我不重复这个。这篇只回答一个问题：这套系统是怎么跑通的。 全文按两条线走——「存」和「找」。每个环节末尾有一句话小结，链到我已经写好的深拆文章，想抠细节的点开看，不想抠的看完这条线也够你搭出同款。

定调：RAG 就两件事，存和找

一句话把 RAG 说尽：把公司文档喂给大模型之前，先检索出最相关的几段，让模型只根据资料回答。所以系统的上限在哪里？我的结论是：RAG 的上限在检索，不在大模型。 模型只负责把资料组织成人话，检索决定它能看到什么。资料给错了，再贵的模型也只是把错误说得更流畅。

顺带回答一个选型问题：为什么是 RAG 而不是微调？这是整个系列的前置判断，我在 「RAG 还是微调？大模型应用 3 种模式别选错」 里拆过——企业知识库这种「资料持续更新、答案必须可溯源」的场景，RAG 是默认答案，不在这里展开。

下面进入正题。

存这条线：让知识库有进有出

环节一：文档入库，本质是一套状态机

第一版我图省事，上传即入库，很快就后悔了——知识库变成垃圾堆，什么过期报价单、写了一半的文档都在里面被检索出来。现在的设计：

• 格式：支持 txt / docx / pdf / xlsx，上传后统一解析成纯文本；
• 元数据：文档表带完整生命周期字段——密级、访问范围、归属部门、版本号，改了哪版一清二楚；
• 状态机：草稿 → 入库 → 已发布 → 下架。只有 published 状态的文档块参与检索；发布后锁死，想改必须先下架，重新入库会覆盖旧向量。

这个状态机不值钱吗？太值钱。密级和访问范围让「哪个部门能问什么」有了落点，这是企业知识库和个人玩具的分水岭。

一句话小结：入库不是把文件塞进数据库，是给它上户口。 至于文档怎么切块、切完检索到小块要不要回查整篇，我另外写过 「RAG 父页面召回？这 3 种场景不值得做」，先把边界讲清楚，别盲目上父文档召回。

环节二：切块 + 向量化，三个坑替你们踩了

长文档切成小 chunk，用 bge-m3 转成向量，存进 Chroma 向量库（我库里从头到尾就一个 collection，没必要整花活）。提问时把问题也转向量，找距离最近的片段——这就是向量检索的全部原理，剩下的全是工程细节。

踩坑实录，三条都真金白银花时间：

1. Chroma 查询的 include 参数要传字符串数组，随手传个字符串就报错；
2. metadata 字段名统一用下划线，混用驼峰和下划线会让你查库时一脸懵；
3. query 和入库必须用同一个 embedding 模型——换模型不是升级，是两个宇宙的对不上，换模型就得全量重灌，新旧向量绝不混库（同维度也不行）。

一句话小结：向量检索翻车，八成是入库和查询不同路。

找这条线：四步把答案捞上来

环节三：双路粗召——向量 + 手写 BM25

纯向量检索有个死穴：专有名词、缩写、产品型号会翻车，向量对这种精确匹配就是不准。所以关键词这一路必须有。

我没上 ES 这种现成轮子，BM25 引擎是自己手写的（这大概是最能体现「手搓」的一个环节）：

• jieba 中文分词 + 倒排索引，核心参数 k1=1.5、b=0.75，没有引第三方 BM25 库；
• Nitro 服务启动时从数据库里 published 状态的 chunks 预热建索引，零冷启动，预热失败也不阻塞服务启动；
• 召回后回查数据库补全文，向量库只管「找到哪块」，不管「给出全文」。

检索时两路并行：向量和 BM25 各粗召 top-20，用 Promise.allSettled 包着——单路挂了，另一路自动兜底，服务不停摆。

一句话小结：混合检索 = 广撒网两路并行 + 一路挂掉另一路兜底。 四步怎么搭、每步参数怎么定，看 「RAG 检索总跑偏？混合检索四步直接抄」。

环节四：RRF 融合——扔掉分数，只认名次

两路都召回了，分数没法直接比：向量给的是余弦相似度，BM25 给的是另一套量纲，硬加权平均是玄学。

我的方案是 RRF（Reciprocal Rank Fusion），k=60：分数全部扔掉，只用名次。两路都认的片段自然浮到前面，融合后取 top-20。每一路的名次都记进日志，后面调试全靠它。

一句话小结：量纲不同别硬融合，名次是唯一通用货币。 k 值为什么取 60、融合细节，同样在 混合检索四步 里拆过。

环节五：Query 改写——用户不会提问，系统替他补全

真实用户的提问又短又含糊：「那个多少钱」「上次说的发货呢」。直接拿这种话去检索，神仙难救。

所以在粗召前面加了一步改写：规则 6 条、类型 6 种，输出 JSON，temperature 压到 0.1；两道成本短路（首条消息无历史直接跳过、启发式指代词判断），失败全部降级用原话。最关键的一条设计：改写只用于检索，生成时模型看到的还是用户原话——改写错了不污染答案。

一句话小结：改写是给检索器用的，不是给用户看的。 四步流程看 「RAG 怕问得含糊？Query 改写四步直接抄」，规则和类型清单看 「RAG 改写没头绪？6 规则配 6 类型直接抄」。

环节六：精排 + 生成——最后五段决定答案质量

粗召是广撒网，top-20 里良莠不齐。最后一步用 bge-reranker-v2-m3 做 cross-encoder 精排：把问题和每条候选成对过一遍模型，逐条打分重排，只取 top-5 注入上下文，交给 DeepSeek 流式输出（SSE，打字机效果）。rerank 服务不可用时自动降级：按 RRF 分或召回原始序截断——精度掉一点，服务不断。

生成侧的 system prompt 上了硬约束：只根据资料回答，找不到就说找不到，不许编。 配合前端把命中片段的名次、来源全部展示出来，答错了能追责到具体文档。

一句话小结：精排是唯一「问题+资料同场打分」的环节，值得为它留降级通道。

全链路可观测：效果差的时候，先知道差在哪

最后一环不是某个算法，是工程习惯：

• 混合 / 纯关键词 / 纯向量三种模式页面一键切换，同一个问答抽屉按 mode 切换，切模式时强制重建组件清掉历史答案，防止新旧混着看；
• 单独的关键词检索、向量检索调试接口，支持单路对比；还有个 retrieveOnly 开关——只看检索结果，不触发生成；
• 每一路的名次、得分全部打日志。

这套 observability 的回报巨大：用户反馈「答得烂」，我十分钟就能定位是检索没捞到、还是捞到了模型没用好。排查思路我写成了一篇 「RAG 效果差怎么调试？面试官要听的排查思路」，面试和干活都用得上。

说点效果，也说实话

链路参数都在明处：双路各 top-20、RRF 融合取 top-20、精排取 top-5、k=60、k1=1.5、b=0.75。但你要问我「准确率提升多少个百分点」——说实话没有脸说，因为我没建标准评估集，上线前后的评测数字我没记下来，这是这期的欠账，补上评测再写。我唯一敢负责的话是：加精排和改写之前，专有名词类问题经常答不上来；之后这类问题基本能稳定命中——这是体感，不是数据。

手搓一圈最大的收获不在算法，在心态：RAG 系统 80% 的工程问题，最后都归结为「数据进库时没管好，查询进来时没接住」。 状态机、日志、降级通道，这些最土的工程实践，恰恰是 AI 应用最缺的东西。

这是「老朱的 RAG 系列」总开篇，六个环节各有一篇深拆，链接都在文中。下一篇不在 RAG 系列里，但和这套系统的账单直接相关：四个 AI API 平台的价格/速度/稳定性实测对比——手搓很爽，token 很贵，怎么选不花冤枉钱，下篇见。

这篇拆我自己项目（Nuxt3 企业知识库，Nitro + TiDB + Chroma）里跑着的混合检索：BM25 怎么打分、RRF 的 k 为什么是 60、有向量召回了为什么还要精排。代码全部真实在跑，参数直接抄。

为什么要两路

向量检索单干有毛病：换个说法问很准，但专有名词、条款号、缩写型号就拉胯——搜型号给你一堆「看着很像」的，偏偏不是原文。关键词检索反过来：字面命中稳，近义表达没辙。

所以两路都要：向量路（Chroma bge-m3，强在近义表达）+ 关键词路（手写 BM25，强在专有名词/术语），各取所长。

第 1 步：并行粗召

两路并行，各捞 20 条（COARSE_TOP_K = 20），用 Promise.allSettled——一路挂了另一路照常出，向量服务抖动不拖垮整个问答。向量路带 status=published 过滤，关键词路召回后回查 TiDB document_chunks 补全内容（listChunksByIds + Map 保序）。

第 2 步：BM25 这一路的两个旋钮

BM25 公式（对查询 q 中每个词项 qi 累加对文档 d 的得分）：

score(q, d) = Σ IDF(qi) · tf(qi,d)·(k1+1) / (tf(qi,d) + k1·(1 - b + b·|d|/avgdl))
IDF(qi)     = ln((N - df(qi) + 0.5) / (df(qi) + 0.5) + 1)

• k1=1.5 管词频饱和：一个词在文档里出现 10 次，不代表比出现 1 次相关 10 倍，得分要收敛
• b=0.75 管长文惩罚：长文档天然词多，不打折就被大段废话霸榜

我的真实打分代码（server/utils/bm25.ts，零依赖手写，倒排索引 token → (chunkId, tf)）：

const df = posting.size
// IDF：用 +1 平滑避免负值；罕见词区分度高、IDF 大
const idf = Math.log((N - df + 0.5) / (df + 0.5) + 1)
// 词频饱和项：tf 越大得分越高，但受 k1 限制避免高频词刷分
// 文档长度归一化：长文档天然 tf 高，用 b 参数抑制
const norm = 1 - this.b + this.b * (doc.length / (this.avgdl || 1))
const tfComponent = (tf * (this.k1 + 1)) / (tf + this.k1 * norm)
score += idf * tfComponent

为什么手写不上 ES：我这量级（全库 172 个 chunk）引 Elasticsearch 纯属找罪受。启动插件从 TiDB 全量捞 published 分块，分词建倒排一次预热，零冷启动；失败也不阻塞启动，BM25 降级空结果，向量路仍可用。avgdl 用增量公式维护（增删文档各一行数学），不为一个平均值遍历全库。

第 3 步：RRF 融合，扔掉分数只排名次

余弦分卡在 0~1，BM25 分没有上限（能到 30+），直接加权就是关公战秦琼。RRF（Reciprocal Rank Fusion）只看名次：

score(d) = Σ 1/(k + rank_i(d))    // k=60，某路未命中则不参与累加

直觉算例（k=60）：

• 两路都排第 1：1/61 + 1/61 ≈ 0.0328
• 只有一路排第 1：1/61 ≈ 0.0164
• 一路第 1、另一路第 20：1/61 + 1/80 ≈ 0.0289

→ 两路都认的才浮上来。 k 是平滑常数：k 越小头部名次优势越大，k=60 是论文经验值，把第 1 和第 2 名的差距抹平，不让某一路一票定生死；候选池小的话 k 可调低。真实实现（server/utils/rrf.ts）：

export function rrf(rankedLists: string[][], k = 60): FusedResult[] {
  const scores = new Map<string, number>()
  const ranksMap = new Map<string, Array<number | null>>()
  rankedLists.forEach((list, listIndex) => {
    list.forEach((id, idx) => {
      const rank = idx + 1 // 名次从 1 开始
      const contribution = 1 / (k + rank)
      scores.set(id, (scores.get(id) ?? 0) + contribution)
      // ranks 记录每路名次，未出现记 null，便于调试观察
      let ranks = ranksMap.get(id)
      if (!ranks) { ranks = new Array(rankedLists.length).fill(null); ranksMap.set(id, ranks) }
      ranks[listIndex] = rank
    })
  })
  // ...按融合分降序输出
}

融合取 top-20（FUSE_TOP_K = 20）；一路为空自动退化单路。

第 4 步：精排，最不能省的一步

入库时分块是单独算向量的，跟你的问题从没同框比过——粗召本质是盲选。reranker（cross-encoder，硅基流动 bge-reranker-v2-m3）把「问题+每条候选」拼成一对喂进模型逐条打分，慢，但准。

只对融合后的 20 条精排（成本可控），取前 5 进上下文（FINAL_TOP_K = 5）。rerank 服务不可用就自动降级按 RRF 分排——链路永不整条挂掉。

然后生成：DeepSeek deepseek-chat SSE 流式，先推 sources（来源文档+页码）再推 delta，前端引用卡片比答案先渲染。

调试方法：三模式对照

这是整条链路我最推荐抄的东西——检索模式做成 hybrid / bm25 / vector 三档开关，召回策略是唯一变量，后面统一走精排+生成。同一个问题三档各跑一遍，控制台按模式打印两路名次/得分，谁拖后腿一眼看见。另有 /api/rag/keyword-search、/api/rag/vector-search 单路调试接口和 retrieveOnly（只看检索不生成）。

速查表

RAG 的上限在检索，不在大模型。下一篇讲检索的第一站：Query 改写。

本篇最早于 2026 年 10 月 13 日发布于小红书，此为含完整代码与数据的博客版。

我把自己 Nuxt3 知识库（my-nuxt-app）的调试工具链整个做成了一套排查方法，这篇按层过一遍。

总原则：控制变量 + 只看检索不生成

两条铁律贯穿所有排查：

1. 召回策略是唯一变量。我把检索做成 hybrid / bm25 / vector 三档模式开关，同一问题各跑一遍，后面的精排、生成完全一致——谁拖后腿一眼看见。
2. 检索和生成分开验。有 retrieveOnly 开关：只看召回了哪些片段、名次如何，不跑生成。答案不对，先确认是「没捞到」还是「捞到了模型没用好」，这两件事的修法完全不同。

分层排查

层 1：入库（文档→分块→向量）

七步建库链路：知识整理 → 清理格式化 → 内容切分 → 向量化 → 挂元数据 → 载入向量库 → 集成。效果差的病根很多在这：切太碎丢上下文，切太粗检索不准。

我项目的真实分块参数：递归切分器 chunker.ts，目标 800 字符（标题→空行段落→句号→硬切四层降级，短文档直接一片不硬切）；BM25 侧启动全量预热——最新实测：172 个 chunk / 3015 个词项，建索引 2688ms（TiDB 拉取+分词+倒排全算上）。

排查动作：随机抽几个 chunk 看语义是否自包含；问一个已知有答案的问题，确认目标 chunk 的文本入库时没被解析器吃掉（表格/PDF 是重灾区）。

层 2：检索（两路单测）

关键词路和向量路各留了单路调试接口：/api/rag/keyword-search、/api/rag/vector-search——单路粗召、不精排，专治「不知道哪路烂」。

典型病症对照：

• 专有名词/条款号/型号搜不到 → 关键词路问题：查分词（我的 BM25 用中文分词器切 query 和文档，分词烂则倒排全烂）、查索引预热是否成功（控制台看 docs/vocab 数）
• 换个说法就搜不到 → 只有 BM25 在干活，向量路没接上或阈值过严
• 召回一堆语义相近但没用的 → 向量路正常但缺精排，去层 4

层 3：融合（RRF 名次日志）

两路各召 top20，RRF 融合（score=Σ1/(60+rank)）。FusedResult 里我专门存了每个 id 的 ranks: [向量路名次, BM25路名次]（未命中记 null），服务端控制台按模式打印——融合后排名怪，直接看是「一路强推」还是「两路共认」。

坑：别把余弦分和 BM25 分直接加权，量纲不同（0~1 vs 无上限），必须转名次。

层 4：精排

粗召本质是盲选——入库时分块单独算的向量，从没和你的问题同框比过。精排用 cross-encoder（bge-reranker-v2-m3）把「问题+候选」成对打分，融合 top20 → 精排 top5。

排查信号：召回明明有正确答案却排在 15 名开外进不了上下文 → 看 rerank 分数；rerank 服务挂了会自动降级按 RRF 分排，日志里有标记，别把降级的锅算到检索头上。

层 5：生成

检索没问题、答案还是烂，才轮到生成层：prompt 里资料怎么拼、有没有约束「只用资料作答、引用标来源页码」、模型是不是被无关片段带偏（top5 塞太多噪声也是病，回头减 FINAL_TOP_K）。

常见三病因（课件口径 + 我的实战对应）

1. 文档处理和切割颗粒度问题 → 层 1
2. 召回不准，想命中的片段排序太靠后 → 层 2/3/4
3. 检索到了但整合生成没用对 → 层 5

对应五个提准手段（我项目落了的标 ✓）：切分技巧 ✓（递归四层+短文档保护）、取相邻片段（父页面类方案，评估后我没做）、多召回+rerank ✓（20→5）、混合检索 ✓（BM25+向量）、Query 重写 ✓（改写只进检索）。

面试话术一句话

「我调试 RAG 的路径是分层二分：先用 retrieveOnly 把检索和生成切开，再用三模式开关把两路召回切开，每层都有接口和名次日志。定位到层之后，改参数—回归—再定位，不靠玄学。」

这就是面试官要听的：不是你知道多少技巧，而是你有能把问题范围每次减半的方法。

本篇最早于 2026 年 10 月 10 日发布于小红书，此为博客完整版。