AI Agent Guide 交互版
第三阶段 · RAG 系统实战 主线问题:deleteAccount API 返回 409 怎么排查?

混合检索、查询改写与重排

纯向量检索能找到“意思相近”的段落,但遇到接口名、错误码这类硬线索时容易混入语义噪音。RAG 检索不是一次 top-K,而是一条“先召回、再融合、最后精排”的流水线。

30 秒版 · 只记这 3 句 实验台打分与排名为教学示意
  1. 01 向量抓语义,BM25 抓精确词与报错码,两者互补不能二选一。
  2. 02 RRF 只看排名不看原始分数尺度,天然适合把多路召回合成候选池。
  3. 03 Reranker 用 Cross-Encoder 逐 token 交互,把真正回答问题的证据提到 Top-3。
常见 Demo 做法
用户问题 → 向量 top-5 → 塞给 LLM

问“deleteAccount API 返回 409”,容易召回“账号注销后删除资料”这类主题接近但无法解释 409 根因的噪音片段。

生产级检索链路
召回(BM25 + 向量)→ RRF 融合 → Reranker

前面关心“有没有漏掉硬线索和同义表达”,中间用排名合并候选池,最后由 Reranker 挑出真正能回答问题的证据。

检索要分三步:召回、融合和精排

点击左侧三个阶段,查看每一层到底解决什么问题,以及输入输出是如何流转的:

BM25 与向量检索:为什么不是二选一

BM25 负责抓精确词(接口名 deleteAccount、错误码 409、条款号),越罕见的词权重越高;向量检索负责抓同义表达(比如用户问“降低延迟”,文档写“提升响应速度”)。两者噪音来源完全不同,点击下面实验台的三个问题切换对比:

交互实验台 01 · 召回层对照

BM25 精确词匹配 vs 向量语义检索

切换不同类型的问题,直观对比两路召回分别捞回了什么正确答案,又各自混进了什么噪音。

BM25 关键词召回 精确词 / 词频统计
Vector 向量语义召回 Embedding 语义距离

查询改写与 RRF:把多路召回合成候选池

上线查询改写(Multi-Query Retrieval)后,原始问题会被扩展成 3 条不同角度的检索入口(例如补充 HTTP 409 Conflict、数据库约束冲突)。但一定要守住一条底线:查询改写只能用于检索,不能直接当事实来源,最终回答必须基于真实文档片段。

多路召回拿到结果后,BM25 分数和余弦相似度量纲不同,不能直接相加。RRF(Reciprocal Rank Fusion) 不看原始分数,只按排名投票:score(d) = Σ 1 / (k + rank_i(d))(来源:Cormack et al., SIGIR 2009)。在下面调节常数 k 或开启查询改写,实时查看候选池得分与排名变化:

交互实验台 02 · RRF 融合计算器

多路排名融合:实时计算 fusedScore

基于本章 deleteAccount API 返回 409 真实候选数据,调节平滑常数 k 或叠加查询改写路径。

平滑常数 k(默认 60,越大越削弱头部单一路径优势) k = 60
融合排名 文档片段 ID BM25 名次 向量名次 RRF 融合总分
工程实现参考:查询改写降级(rewriteQuery)与 RRF 融合函数

1. 查询改写(带受控词表约束与 JSON 失败降级):

query-rewrite.ts
async function rewriteQuery(query: string): Promise<string[]> {
  const response = await anthropic.messages.create({
    model: llmModel,
    max_tokens: 600,
    messages: [{ role: "user", content: `把问题改写成 3 个检索入口,只返回 JSON 数组:${query}` }],
  });
  const textBlock = response.content.find((b) => b.type === "text");
  const text = textBlock?.type === "text" ? textBlock.text : "[]";

  try {
    const parsed = JSON.parse(text) as unknown;
    if (Array.isArray(parsed)) {
      return parsed.filter((item): item is string => typeof item === "string").slice(0, 3);
    }
  } catch {
    // 改写失败时退回原问题,保证主检索链路不断
  }
  return [query];
}

2. RRF 倒数排名融合(k = 60,随上方实验台滑块实时同步):

rrf-fusion.ts
function reciprocalRankFusion(bm25Results: ScoredChunk[], vectorResults: ScoredChunk[], limit = 5) {
  const k = 60;
  const byId = new Map<string, HybridChunk>();
  for (const doc of chunks) byId.set(doc.id, { ...doc, bm25Score: 0, vectorScore: 0, fusedScore: 0 });

  bm25Results.forEach((r, idx) => {
    const item = byId.get(r.id);
    if (item) { item.bm25Score = r.score; item.fusedScore += 1 / (k + idx + 1); }
  });
  vectorResults.forEach((r, idx) => {
    const item = byId.get(r.id);
    if (item) { item.vectorScore = r.score; item.fusedScore += 1 / (k + idx + 1); }
  });

  return [...byId.values()].filter((d) => d.fusedScore > 0).sort((a, b) => b.fusedScore - a.fusedScore).slice(0, limit);
}

Reranker:从候选池里挑出真正能回答的证据

RRF 把被多路看好的片段收进了候选池,但它只看名次,无法细粒度判断“这段话到底能不能回答当前问题”。Reranker(Cross-Encoder)相当于“把问题和每个候选片段放在同一张卷子上一起看”(来源:Sentence Transformers、百炼 qwen3-rerank 文档)。点击下面右侧任意候选片段,看 Reranker 如何区分“真证据”和“伪相关噪音”:

交互实验台 03 · 精排层审证据台

RRF 候选池 vs Reranker 精排打分(Top-N)

点击左侧候选片段,查看 Cross-Encoder 为什么把 security-001 顶到第一,同时压低只讲前端提示或其它接口的噪音。

先猜后验 用户搜 deleteAccount API 返回 409,Reranker 为什么能把 api-002(讲 deleteAccount 参数)压到低分?
工程实现参考:调用百炼 qwen3-rerank 接口与完整示例路径

完整可运行脚本见 examples/rag/hybrid-search-reranking/hybrid-search-rerank.ts(运行命令:npx tsx --env-file=.env examples/rag/hybrid-search-reranking/hybrid-search-rerank.ts)。

qwen3-rerank.ts
async function rerank(query: string, candidates: HybridChunk[], topN = 3) {
  const response = await fetch("https://dashscope.aliyuncs.com/compatible-api/v1/reranks", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ANTHROPIC_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: rerankModel,
      query,
      documents: candidates.map((c) => c.text),
      top_n: topN,
      instruct: "Given a web search query, retrieve relevant passages that answer the query.",
    }),
  });
  if (!response.ok) throw new Error(`Rerank failed: ${response.status}`);
  const data = (await response.json()) as { results: Array<{ index: number; relevance_score: number }> };
  return data.results.map((item) => ({ ...candidates[item.index], rerankScore: item.relevance_score }));
}
常见踩坑提醒 1. 不要直接相加 BM25 和向量分数:两者量纲不同,请用 RRF。
2. 不要把 Reranker 当成最终事实裁判:它只负责把候选排好序,证据不足时依然要靠后续的引用校验与拒答机制兜底。

能力定位与上线迭代顺序

不要一上来就把所有开关全打开,按下面的能力分工和迭代节奏稳步推进(可点击标签快速高亮对应阶段):

BM25 · 召回层
抓精确词与硬线索

接口名(deleteAccount)、错误码(409)、配置项和条款号。默认起点:limit = 20。

向量检索 · 召回层
抓同义表达与近义说法

解决“用户说降延迟、文档写提响应”的字面不一致问题。默认起点:limit = 20。

查询改写 · 召回增强
补全用户没说全的检索入口

用受控词表扩写 3 条查询,失败时自动退回原问题。切忌把改写结果当事实证据。

RRF · 融合层
按排名投票合并候选池

不直接相加异构分数,只看多路名次累加 1 / (60 + rank),把共同看好的片段推前。

Reranker · 精排层
逐条审证据,只送 Top-N

Cross-Encoder 把问题和片段放在一起打分,从 Top-20~50 里精挑 Top-5 交给 LLM。

工程上线迭代顺序
1. 双路+RRF → 2. 加 Rerank → 3. 按需改写

先跑通 BM25 + 向量 + RRF;答案在候选但靠后时加 Rerank;召回不到再开改写或做路由。