# Rag Pipeline

构建或调优 RAG 检索管道时使用, , 涵盖文档分块策略与参数、稠密嵌入（BGE-M3、余弦相似度、ANNOY/HNSW 选型）、稀疏嵌入（TF-IDF 到...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill rag-pipeline -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill rag-pipeline -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill rag-pipeline -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill rag-pipeline -g -a gemini-cli -y`

## Description

构建或调优 RAG 检索管道时使用, , 涵盖文档分块策略与参数、稠密嵌入（BGE-M3、余弦相似度、ANNOY/HNSW 选型）、稀疏嵌入（TF-IDF 到 BM25）、混合检索三阶段（并行召回、RRF 融合、跨编码器重排序）与 recall@k/MRR/nDCG 指标，含稀疏 vs 稠密的胜负判断。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# RAG 检索管道

## 何时使用
- 从零搭建知识库检索（分块 → 索引 → 检索 → 注入生成）
- 选型检索路线：稠密 vs 稀疏 vs 混合；ANN 索引 ANNOY vs HNSW
- 检索质量不达标时定位调优（分块大小、融合方式、是否加重排序）
- 建立检索质量的度量与验收标准
- 判断某类查询为何召回失败（语义相似 vs 精确匹配）
- 为记忆系统或知识组织层提供底层检索能力

## 核心原则
- RAG 核心流程只有三步：**检索相关片段 → 注入上下文 → LLM 基于上下文生成**。检索器决定答案上限，生成器决定兑现程度；答不好先在检索层定位，别急着调 prompt。
- RAG 的存在理由：模型训练数据有截止日期，知识库可随时更新, , 用外部知识库的广度和时效性补模型之短。
- 系统构成就两块：**检索器**（从知识库找相关片段）+ **生成器**（通常是 LLM，拿片段作上下文生成答案）。调优对象主要是检索器。
- 分块必不可少，原因有二：嵌入模型有输入长度限制，整篇文档压成一个向量会多主题混杂、语义被稀释；检索的目标是只注入相关部分，块太大会连带引入无关内容、浪费窗口稀释注意力。
- 稠密懂语义、稀疏懂字面，各有盲区：搜"HTTP-403"，稀疏精确命中而稠密可能返回泛泛的"服务器错误"；搜"kitty"，稠密能找到只写"cat"的文档而稀疏不能。没有单一策略在所有场景可靠, , 生产级默认混合检索。
- 分块有固有缺陷：任何切分策略都会切断块与原始上下文的联系（"该公司收入增长了 3%", , 哪家公司？哪个季度？）。要么在索引期为每块生成上下文前缀再索引（`book/chapter3.md`「RAG 技巧：上下文感知检索」），要么靠重排序补救。
- 混合检索三阶段各司其职、层层递进：**并行检索**（双路各自召回）→ **结果融合**（统一候选池）→ **神经重排序**（候选池精排）。融合不替代重排，重排也不替代融合。
- 两路得分不可直接比较：余弦相似度（0-1）与 BM25（0 到几十）量纲分布迥异，融合必须抛开原始得分。
- 稀疏 vs 稠密的胜负判断（按查询类型选路或混路）：

  | 查询类型 | 稠密 | 稀疏 | 结论 |
  |------|------|------|------|
  | 同义/换说法（kitty vs cat） | 胜 | 负 | 靠稠密 |
  | 精确代码/编号（HTTP-403） | 易泛化 | 胜 | 靠稀疏 |
  | 技术术语、人名 | 一般 | 胜 | 靠稀疏 |
  | 多语言/跨语言查询 | 胜 | 负 | 靠稠密 |
  | 概念性、描述性问题 | 胜 | 一般 | 靠稠密 |

  混合检索 + 重排序是覆盖全部类型的生产默认。

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/rag-pipeline/SKILL.md