AI Agent Guide Interactive
Part 3 · Production RAG Systems Running query: How to debug deleteAccount API returning 409?

Hybrid Search, Query Rewriting & Reranking

Pure vector search finds semantically similar passages, but pulls in topical noise when queries hinge on exact identifiers like API names or error codes. Production RAG retrieval is not a single top-K call; it is a three-stage pipeline: recall, fuse, then rerank.

30-Second TL;DR · 3 Core Takeaways Simulated lab scores for illustration
  1. 01 Dense vectors capture semantics while BM25 catches exact terms and error codes. Run both, not one or the other.
  2. 02 RRF fuses rankings without normalizing raw score scales, making it ideal for combining multi-path recall into one pool.
  3. 03 A Cross-Encoder Reranker scores query-document pairs jointly, promoting true answers into the final Top-3.
Typical Demo Setup
Query → Vector Top-5 → Prompt LLM

Asking about "deleteAccount API returning 409" often retrieves generic account-deletion policies that share the topic but never explain the 409 root cause.

Production Retrieval Pipeline
Recall (BM25 + Vector) → RRF Fusion → Reranker

First maximize coverage across exact terms and paraphrases, next merge lists by rank, and finally let a Reranker pick the chunks that actually answer the question.

Retrieval in Three Stages: Recall, Fusion, and Rerank

Select each stage on the left to inspect what problem it solves and how inputs and outputs flow across the pipeline:

BM25 vs. Vector Search: Complementary, Not Mutually Exclusive

BM25 excels at exact lexical matches (endpoint names like deleteAccount, status codes like 409, config keys) where rarer tokens carry higher weight. Vector search excels at paraphrases and semantic intent (matching "reduce latency" to "improve response time"). Because their noise profiles differ completely, switch between the three queries below to compare both paths side by side:

Interactive Lab 01 · Recall Comparison

BM25 Lexical Search vs. Dense Vector Search

Switch query types to see which true evidence each retriever surfaces—and what kind of noise slips into each list.

BM25 Keyword Recall Exact Terms / TF-IDF
Dense Vector Recall Embedding Distance

Query Rewriting & RRF: Merging Multi-Path Recall

With Multi-Query Retrieval, an LLM expands the original question into 3 complementary search queries (for example, adding HTTP 409 Conflict or database constraint violation). Keep one hard rule in mind: rewritten queries are only for retrieval, never a source of truth—final answers must be grounded in actual document chunks.

Once multiple retrievers return lists, you cannot simply add BM25 scores and cosine similarities because their scales are incompatible. RRF (Reciprocal Rank Fusion) ignores raw scores and votes strictly by rank: score(d) = Σ 1 / (k + rank_i(d)) (source: Cormack et al., SIGIR 2009). Adjust k or enable the query-rewrite path below to watch the fused candidate pool update live:

Interactive Lab 02 · RRF Fusion Calculator

Multi-Path Rank Fusion: Live fusedScore

Using candidates for deleteAccount API returning 409, adjust the smoothing constant k or toggle the query-rewrite recall path.

Smoothing constant k (default 60; higher values dampen single-path top-rank dominance) k = 60
Fused Rank Chunk ID BM25 Rank Vector Rank RRF Fused Score
Implementation Reference: Query Rewriting Fallback (rewriteQuery) & RRF Fusion

1. Query rewriting with safe JSON fallback:

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: `Rewrite the question into 3 search queries. Return a JSON array only: ${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 {
    // Fall back to the original query if parsing fails so retrieval never breaks
  }
  return [query];
}

2. Reciprocal Rank Fusion (k = 60, synced live with the slider above):

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: Promoting True Evidence from the Candidate Pool

RRF gathers chunks favored across multiple retrievers, but because it only inspects rank positions, it cannot tell whether a passage actually answers the user's question. A Cross-Encoder Reranker reads the query and each candidate chunk together in a single forward pass (sources: Sentence Transformers, DashScope qwen3-rerank docs). Click any candidate below to inspect how the Reranker separates real evidence from surface-level noise:

Interactive Lab 03 · Reranker Evidence Judge

RRF Candidate Pool vs. Reranker Precision Scoring (Top-N)

Select a candidate on the left to see why the Cross-Encoder keeps security-001 at #1, promotes db-constraint-02, and demotes UI-only or wrong-endpoint noise.

Predict First For the query deleteAccount API returning 409, why does the Reranker push api-002 (which mentions API troubleshooting) down to a low score?
Implementation Reference: Calling DashScope qwen3-rerank API & Runnable Script

Full runnable script: examples/rag/hybrid-search-reranking/hybrid-search-rerank.ts (run with 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 }));
}
Common Pitfalls 1. Never sum raw BM25 and vector scores directly: their scales are incompatible; use RRF instead.
2. Never treat a Reranker as a factuality verifier: it only orders existing candidates. When evidence is missing, downstream citation checks and abstention logic must still catch it.

Component Roles & Production Rollout Order

Do not flip every switch on day one. Roll out each layer incrementally based on where retrieval actually fails (filter by stage below):

BM25 · Recall
Catch Exact Terms & Hard Clues

Endpoint names (deleteAccount), error codes (409), config flags, and clause IDs. Sensible baseline: limit = 20.

Vector Search · Recall
Catch Paraphrases & Intent

Bridges vocabulary gaps like "reduce latency" vs. "improve response speed". Sensible baseline: limit = 20.

Query Rewrite · Recall Boost
Expand Underspecified Queries

Generate up to 3 controlled rewrites with automatic fallback to the raw query. Never cite rewritten queries as evidence.

RRF · Fusion
Merge Pools by Rank Voting

Avoids heterogeneous score normalization by summing 1 / (60 + rank) across paths so consensus chunks rise to the top.

Reranker · Precision
Judge Evidence, Send Top-N

A Cross-Encoder scores query-chunk pairs jointly, narrowing Top-20–50 candidates down to the cleanest Top-5 for the LLM.

Rollout Sequence
1. Hybrid + RRF → 2. Rerank → 3. Rewrite

Ship BM25 + Vector + RRF first. Add a Reranker when the right chunk is recalled but buried. Add query rewriting only when recall itself misses.