Two-Stage Hybrid Retrieval: BM25, Dense Embeddings, RRF, and Cross-Encoder Reranking

Build and benchmark a two-stage hybrid search pipeline combining Okapi BM25, BGE bi-encoder embeddings, Reciprocal Rank Fusion (RRF), and MS MARCO cross-encoder reranking across exact-identifier and semantic-paraphrase slices.

Open Seas 22 min read November 12, 2026 Code on GitHub
0
Two-Stage Hybrid Retrieval: BM25, Dense Embeddings, RRF, and Cross-Encoder Reranking

Series · Part 4 of 4

Embeddings & Reranking Foundations

View full track →
  1. 01 Sentence Embeddings from Scratch with PyTorch
  2. 02 Bi-Encoders: Fast Semantic Search at Scale
  3. 03 Cross-Encoders: Precision Reranking for Search
  4. 04 Two-Stage Hybrid Retrieval: BM25, Dense Embeddings, RRF, and Cross-Encoder Reranking
On this page (12 sections)

Ship a dense vector index into production for an engineering team, and the first bug report arrives within an afternoon. An on-call engineer pastes postgres query failed with SQLSTATE 55P03 or aws g5.12xlarge node hardware specs into search, and the bi-encoder returns a general PostgreSQL deadlock guide (40P01) or a single-GPU g5.2xlarge sizing note at rank #1. Swap the backend back to pure Okapi BM25 keyword search, and those exact identifier lookups snap into place, only for natural-language questions like “serving newest waiting callers first and dropping timed-out requests during overload” to miss the LIFO Admission Queues runbook entirely because the query and passage share zero domain nouns.

Neither failure is a bug in your vector database or inverted index. Each retrieval paradigm compresses text through an incompatible bottleneck: lexical scoring demands exact token overlap, while fixed-width dense embeddings smooth away rare alphanumeric identifiers across subword pieces. Production retrieval systems resolve this tension by pairing hybrid candidate generation (BM25 + dense embeddings fused via Reciprocal Rank Fusion) with stage-two cross-encoder reranking.

This tutorial is Part 4 of the Embeddings & Reranking Foundations series:

  1. Part 1: Sentence Embeddings from Scratch with PyTorch: Tokenization, mean pooling, L2 normalization, and cosine similarity mechanics.
  2. Part 2: Bi-Encoders for Fast Semantic Search: Precomputed dense vector indexes and nearest-neighbor candidate generation.
  3. Part 3: Cross-Encoders for Precision Reranking: Joint query-document self-attention with MS MARCO sequence classifiers.
  4. Part 4 (this guide): Assembling and benchmarking a complete Two-Stage Hybrid Retrieval system (BM25Okapi + BAAI/bge-small-en-v1.5 + RRF + cross-encoder/ms-marco-MiniLM-L-6-v2) across diagnostic query slices.

Before Setting Sail

  • Python 3.11+ with a virtual environment
  • Familiarity with bi-encoders and cross-encoders from Parts 2 and 3
  • pip install sentence-transformers rank-bm25 pydantic pydantic-settings numpy torch
  • CPU works out of the box (~180 MB model weights); GPU optional for sub-50ms reranking

Complete Runnable Benchmark Repository

All source modules, the 48-chunk infrastructure corpus, the 28 graded evaluation queries, and the pytest suite live in github.com/steve-largo/largo-tutorials/tree/main/retrieval-systems/hybrid-search-reranking. Every metric table and terminal trace in this guide comes directly from running benchmark.py locally.

When you evaluate retrieval quality using a single blended average across all user queries, lexical and semantic errors cancel each other out and hide structural blind spots. On technical documentation, incidents, and RAG knowledge bases, user traffic splits into two distinct regimes:

  • Exact identifier queries (exact_id): Stack-trace symbols (ERR_SSL_PROTOCOL_ERROR, X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY), cloud instance SKUs (g5.12xlarge vs g5.2xlarge), database error codes (SQLSTATE 55P03 vs 40P01), container exit statuses (139 vs 137), and CLI flags (--max-num-batched-tokens). WordPiece and BPE tokenizers split g5.12xlarge into ["g", "##5", ".", "12", "##xl", "##arge"], placing g5.12xlarge and g5.2xlarge at nearly identical coordinates in 384-dimensional space.
  • Conceptual paraphrase queries (semantic_paraphrase): Symptom-first descriptions where the user describes behavior rather than canonical runbook terminology, such as asking how to “stop forgotten uncommitted database sessions from blocking schema migrations” when the runbook is titled Expiring Abandoned Snapshots Hold Back MVCC Horizons.

A two-stage hybrid architecture separates recall (Stage 1: ensuring the right chunks enter the candidate pool regardless of phrasing) from precision (Stage 2: jointly attending across query and candidate tokens to sort the top context window):

                        ┌─────────────────────────────┐
                        │  Incoming User / RAG Query  │
                        └──────────────┬──────────────┘
                                       │
                   ┌───────────────────┴───────────────────┐
                   ▼                                       ▼
    ┌─────────────────────────────┐         ┌─────────────────────────────┐
    │  Lexical Inverted Postings  │         │   Dense Bi-Encoder Index    │
    │  BM25Okapi (score > 0 hits) │         │  bge-small-en-v1.5 (384-d)  │
    └──────────────┬──────────────┘         └──────────────┬──────────────┘
                   │ Top-25 ranks                          │ Top-25 ranks
                   └───────────────────┬───────────────────┘
                                       ▼
                   ┌───────────────────────────────────────┐
                   │ Stage 1: Reciprocal Rank Fusion (RRF) │
                   │   score(d) = Σ 1 / (60 + rank_m(d))   │
                   └───────────────────┬───────────────────┘
                                       │ Top-25 fused candidates
                                       ▼
                   ┌───────────────────────────────────────┐
                   │ Stage 2: Cross-Encoder Reranking Gate │
                   │  ms-marco-MiniLM-L-6-v2 ([CLS] q [SEP] d) │
                   └───────────────────┬───────────────────┘
                                       │
                                       ▼
                        ┌─────────────────────────────┐
                        │  Top-5 Precision Passages   │
                        └─────────────────────────────┘

Each layer in the funnel compensates for a specific geometric limitation of the layers before it:

Stage ComponentRepresentationQuery ComplexityPrimary StrengthFailure Mode Alone
BM25OkapiSparse term frequenciesSub-millisecond postingsRare SKUs, flags, error codesZero recall under vocabulary shift
Bi-Encoder (bge-small)Single 384-d unit vector1 encoder pass + dot productParaphrases and concept neighborhoodsBlurs 1-token SKU and code diffs
Stage-1 RRF (k=60)Ordinal rank sumMicroseconds (dict merge)High candidate recall without tuningSingle-stream hits get diluted in top-5
Cross-Encoder (MiniLM-L-6)Joint [CLS] q [SEP] d tokensN transformer passesToken-by-token relevance interactionToo expensive to scan whole corpus

Why Linear Score Blending Breaks (and How RRF Fixes It)

A natural first instinct when combining BM25 and vector search is convex linear interpolation:

score_linear(q, d) = alpha * bm25_norm(q, d) + (1 - alpha) * cosine_sim(q, d)

In practice, linear score fusion is fragile across production query distributions for three mathematical reasons:

  1. Incompatible codomains and tail shapes: Okapi BM25 is unbounded above ([0, +inf)). Its raw magnitude scales with query token count and inverse document frequency: a two-token query (CUDA_LAUNCH_BLOCKING=1 flag) peaks near 9.4, while a seven-token stack trace peaks above 26.0. Meanwhile, L2-normalized transformer embeddings occupy a narrow cone in 384-dimensional space (R^384) where even completely unrelated infrastructure passages score 0.48 to 0.60 cosine similarity and exact matches cluster around 0.78 to 0.86.
  2. Per-query min-max instability: Normalizing BM25 per query via (s - s_min) / (s_max - s_min) forces the highest-scoring lexical document to 1.0 even when BM25 found no real match. On a semantic query where 47 chunks score 0.0 and one tangential chunk matches the word "requests" with a weak BM25 score of 1.4, min-max normalization promotes that distractor to 1.000, letting it outrank a true semantic match!
  3. Encoder swaps invalidate calibration: Upgrading your embedding model from all-MiniLM-L6-v2 to BAAI/bge-small-en-v1.5 shifts the mean and variance of cosine similarities, silently breaking any tuned alpha threshold.

Reciprocal Rank Fusion (RRF), introduced by Cormack, Clarke, and Buettcher (SIGIR 2009), sidesteps raw score calibration completely by discarding score magnitudes and aggregating 1-based ordinal ranks:

RRF(d) = sum_{m in M(d)} [ 1 / (k + rank_m(d)) ]

Here M(d) is the subset of retrievers that returned document d, rank_m(d) in {1, 2, ...} is its 1-based position in retriever m, and k = 60 is a smoothing constant. Look at how k = 60 shapes rank incentives:

  • Consensus beats single-stream outliers: A passage ranked #2 in both BM25 and Dense earns 1 / (60 + 2) + 1 / (60 + 2) = 2 / 62 ≈ 0.03226. A passage ranked #1 in BM25 alone (and absent from Dense top-25) earns 1 / (60 + 1) ≈ 0.01639. Dual-stream agreement rises cleanly to the top of Stage 1.
  • Dampened top-rank sensitivity: Without k = 60 (pure reciprocal rank 1 / rank), rank #1 (1.000) carries twice the weight of rank #2 (0.500), allowing a noisy #1 keyword false positive to dominate a document sitting at #3 in both streams (0.333 + 0.333 = 0.667). Adding k = 60 flattens the gap between rank #1 (0.01639) and rank #3 (0.01587) so multi-retriever evidence governs top ranks, while single-stream #1 specialists still comfortably clear the top-25 cutoff for Stage-2 reranking.
  • Strict scale invariance: Any strictly monotonic rescaling of either retriever’s scores produces the exact same ordinal ranks and therefore identical RRF outputs.

Never Feed Zero-Score BM25 Padding into RRF

Python libraries like rank_bm25 return a dense NumPy score array over all N documents in the corpus, assigning 0.0 to every document that matched zero query tokens. If your wrapper slices argsort()[:25] without filtering score > 0.0, queries with only two lexical hits pad ranks 3 through 25 with arbitrary zero-score chunks, awarding them unearned 1 / (60 + rank) RRF credit! Always filter BM25 results to score > 0.0 so lexical lists reflect true inverted-index posting hits.

Step 1: Project Contracts and Immutable Configuration

Create a clean workspace and install pinned dependencies:

mkdir -p hybrid-search-reranking && cd hybrid-search-reranking
python3 -m venv .venv
.venv/bin/pip install \
  "numpy>=2.0.0,<3.0.0" \
  "pydantic>=2.10.0,<3.0.0" \
  "pydantic-settings>=2.8.0,<3.0.0" \
  "rank-bm25>=0.2.2,<1.0.0" \
  "sentence-transformers>=3.4.0,<6.0.0" \
  "torch>=2.4.0,<3.0.0" \
  "pytest>=8.3.0,<10.0.0"

Define frozen Pydantic v2 contracts in schemas.py first so corpus loaders, retrievers, rerankers, and metric calculators exchange validated value objects rather than untyped dictionaries:

# schemas.py
from __future__ import annotations

from typing import Literal
from pydantic import BaseModel, ConfigDict, Field, field_validator

SAFE_ID_PATTERN = r"^[a-z0-9][a-z0-9_-]{2,63}$"

QuerySlice = Literal["exact_id", "semantic_paraphrase"]
PipelineName = Literal["bm25_only", "dense_only", "hybrid_rrf", "hybrid_rrf_rerank"]


class CorpusChunk(BaseModel):
    """A single indexed engineering runbook or architecture reference chunk."""

    model_config = ConfigDict(frozen=True)

    chunk_id: str = Field(pattern=SAFE_ID_PATTERN)
    domain: str = Field(pattern=SAFE_ID_PATTERN)
    title: str = Field(min_length=5, max_length=160)
    text: str = Field(min_length=40, max_length=2000)


class EvalQuery(BaseModel):
    """A ground-truth benchmark query tagged with its diagnostic slice and graded relevance."""

    model_config = ConfigDict(frozen=True)

    query_id: str = Field(pattern=SAFE_ID_PATTERN)
    query_slice: QuerySlice
    query_text: str = Field(min_length=4, max_length=400)
    relevant_grades: dict[str, int] = Field(min_length=1)

    @field_validator("relevant_grades")
    @classmethod
    def validate_grades(cls, grades: dict[str, int]) -> dict[str, int]:
        for chunk_id, grade in grades.items():
            if grade < 1 or grade > 3:
                raise ValueError(f"Grade for {chunk_id!r} must be in 1..3, got {grade}")
        if not any(grade >= 2 for grade in grades.values()):
            raise ValueError("Each query requires at least one primary chunk (grade >= 2)")
        return grades


class ScoredCandidate(BaseModel):
    """A ranked candidate chunk emitted by a retrieval or reranking stage."""

    model_config = ConfigDict(frozen=True)

    chunk_id: str = Field(pattern=SAFE_ID_PATTERN)
    rank: int = Field(ge=1)
    score: float
    bm25_rank: int | None = Field(default=None, ge=1)
    dense_rank: int | None = Field(default=None, ge=1)
    rrf_score: float | None = None
    rerank_score: float | None = None

Notice relevant_grades: dict[str, int] on EvalQuery. Binary relevance (0 or 1) cannot tell whether your retriever placed the exact runbook answering the alert at rank #1 (grade = 2) or put a tangentially related sibling runbook ahead of it (grade = 1). Graded labels let nDCG@10 reward exact primary ordering while Recall@5 tracks multi-chunk context coverage.

Next, isolate model names, cutoff budgets, and hardware selection inside an immutable BaseSettings object in config.py:

# config.py
from __future__ import annotations

import re
from functools import lru_cache
from pydantic import Field, field_validator, model_validator
from pydantic_settings import BaseSettings, SettingsConfigDict

_MODEL_ID_PATTERN = re.compile(r"^[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?$")
_ALLOWED_DEVICES = frozenset({"cpu", "cuda", "mps"})


class RetrievalSettings(BaseSettings):
    """Process-startup configuration loaded from HYBRID_RETRIEVAL_* env vars."""

    model_config = SettingsConfigDict(
        frozen=True,
        env_prefix="HYBRID_RETRIEVAL_",
        extra="ignore",
    )

    bi_encoder_model: str = Field(default="BAAI/bge-small-en-v1.5")
    cross_encoder_model: str = Field(default="cross-encoder/ms-marco-MiniLM-L-6-v2")
    rrf_k: int = Field(default=60, ge=1, le=500)
    stage1_top_k: int = Field(default=25, ge=5, le=200)
    rerank_top_k: int = Field(default=5, ge=1, le=100)
    eval_top_k: int = Field(default=10, ge=5, le=100)
    rerank_batch_size: int = Field(default=32, ge=1, le=256)
    warmup_queries: int = Field(default=3, ge=0, le=20)
    latency_repeats: int = Field(default=3, ge=1, le=20)
    seed: int = Field(default=42, ge=0)
    device: str = Field(default="cpu")

    @field_validator("bi_encoder_model", "cross_encoder_model")
    @classmethod
    def validate_model_identifier(cls, value: str) -> str:
        if ".." in value or not _MODEL_ID_PATTERN.match(value):
            raise ValueError(f"Invalid Hugging Face repo ID: {value!r}")
        return value

    @model_validator(mode="after")
    def validate_cutoff_ordering(self) -> RetrievalSettings:
        if self.rerank_top_k > self.stage1_top_k or self.eval_top_k > self.stage1_top_k:
            raise ValueError("rerank_top_k and eval_top_k must not exceed stage1_top_k")
        return self


@lru_cache(maxsize=1)
def load_settings() -> RetrievalSettings:
    return RetrievalSettings()

Validating rerank_top_k <= stage1_top_k and eval_top_k <= stage1_top_k at startup prevents a subtle evaluation bug: if Stage 1 only forwards 5 candidates to Stage 2, evaluating MRR@10 or nDCG@10 silently truncates ranks 6 through 10.

Step 2: Designing a Corpus with Sibling Hard Negatives

Toy retrieval demos often index one document about Python, one about baking sourdough, and one about car tires. Any encoder scores 1.000 when topics are separated by miles in embedding space. Real engineering knowledge bases contain clusters of sibling runbooks sharing 80% of their domain vocabulary.

In corpus.py, we construct 48 engineering runbooks across 8 infrastructure domains (6 sibling chunks per domain: tls-ingress, gpu-compute, llm-serving, http-resilience, postgres-storage, k8s-runtime, vector-indexing, and linux-observability), paired with 28 evaluation queries (14 in exact_id and 14 in semantic_paraphrase):

# corpus.py (excerpt showing sibling chunks and two-slice queries)
from schemas import CorpusChunk, EvalQuery

CORPUS_CHUNKS: tuple[CorpusChunk, ...] = (
    CorpusChunk(
        chunk_id="gpu-sku-g5-12xlarge",
        domain="gpu-compute",
        title="AWS g5.12xlarge Instance PCIe Topology and Interconnect Limits",
        text=(
            "The g5.12xlarge instance pairs four NVIDIA A10G 24 GB GPUs (96 GB aggregate VRAM) "
            "with 48 vCPUs and 192 GiB host RAM. Because A10G boards on g5.12xlarge lack NVLink "
            "bridges, all tensor-parallel all-reduce collectives traverse PCIe Gen4 lanes, making "
            "pipeline parallelism or 4-way quantized sharding preferable over ring reductions."
        ),
    ),
    CorpusChunk(
        chunk_id="gpu-sku-g5-2xlarge",
        domain="gpu-compute",
        title="Single-GPU g5.2xlarge Sizing for 7B-8B Inference",
        text=(
            "An AWS g5.2xlarge node provides one NVIDIA A10G GPU with 24 GB GDDR6 memory, "
            "600 GB/s memory bandwidth, and 8 vCPUs. It fits an 8-billion-parameter FP8 or AWQ "
            "INT4 model comfortably with 8 GB to 14 GB remaining for paged KV cache blocks."
        ),
    ),
    CorpusChunk(
        chunk_id="http-load-shedding-lifo",
        domain="http-resilience",
        title="LIFO Admission Queues and Deadline-Aware Load Shedding",
        text=(
            "Under saturation, first-in first-out request queues force every arriving packet to "
            "wait behind stale work whose upstream caller timeout has already elapsed. Switching "
            "admission control to last-in first-out ordering with active sojourn-time eviction "
            "serves recent arrivals immediately and sheds expired backlog items at minimal CPU cost."
        ),
    ),
    # ... 45 additional sibling chunks across TLS, vLLM, PostgreSQL, K8s, Vector, and Linux
)

EVAL_QUERIES: tuple[EvalQuery, ...] = (
    EvalQuery(
        query_id="q_exact_02",
        query_slice="exact_id",
        query_text="aws g5.12xlarge node hardware specs and sharding guidance",
        relevant_grades={"gpu-sku-g5-12xlarge": 2, "gpu-sku-g5-2xlarge": 1},
    ),
    EvalQuery(
        query_id="q_sem_07",
        query_slice="semantic_paraphrase",
        query_text="serving newest waiting callers first and dropping timed-out requests during overload",
        relevant_grades={"http-load-shedding-lifo": 2, "http-jitter-circuit-breaker": 1},
    ),
    # ... 26 additional queries (14 exact_id + 14 semantic_paraphrase total)
)

Compare how q_exact_02 and q_sem_07 stress opposite halves of the architecture:

  • On q_exact_02, both gpu-sku-g5-12xlarge and gpu-sku-g5-2xlarge discuss AWS NVIDIA A10G 24 GB GPUs and inference sizing; only the exact SKU string g5.12xlarge separates the grade=2 multi-GPU PCIe runbook from the grade=1 single-GPU node card.
  • On q_sem_07, the query asks about “serving newest waiting callers first and dropping timed-out requests during overload”, whereas http-load-shedding-lifo speaks of “last-in first-out ordering with active sojourn-time eviction” and “expired backlog items”.

Step 3: Implementing the Four Retrieval Stages

In retrievers.py, we define lightweight DenseEncoder and PairReranker Protocol interfaces so unit tests run in milliseconds with deterministic fake encoders while benchmark.py injects SentenceTransformer and CrossEncoder adapters.

Pay special attention to tokenize_lexical. Naive whitespace splitting leaves leading -- prefixes attached to CLI flags (--max-num-batched-tokens fails to match max-num-batched-tokens), while aggressive punctuation stripping shatters net.ipv4.tcp_tw_reuse and g5.12xlarge into noisy single-digit fragments ("12", "1", "4"). Our regex [a-z0-9]+(?:[._=-][a-z0-9]+)* strips leading punctuation while keeping internal dots, underscores, hyphens, and =1 assignments intact:

# retrievers.py
from __future__ import annotations

import re
from collections.abc import Mapping, Sequence
from typing import Protocol

import numpy as np
from rank_bm25 import BM25Okapi
from sentence_transformers import CrossEncoder, SentenceTransformer
from schemas import CorpusChunk, ScoredCandidate

_TOKEN_RE = re.compile(r"[a-z0-9]+(?:[._=-][a-z0-9]+)*")
_STOPWORDS = frozenset({
    "a", "an", "and", "are", "as", "at", "be", "by", "for", "from",
    "in", "into", "is", "it", "of", "on", "or", "our", "that", "the",
    "to", "via", "when", "with",
})


class DenseEncoder(Protocol):
    def encode_texts(self, texts: Sequence[str]) -> np.ndarray: ...


class PairReranker(Protocol):
    def score_pairs(self, pairs: Sequence[tuple[str, str]]) -> np.ndarray: ...


def format_chunk_passage(chunk: CorpusChunk) -> str:
    return f"{chunk.title}. {chunk.text}"


def tokenize_lexical(text: str) -> list[str]:
    tokens = _TOKEN_RE.findall(text.lower())
    filtered = [tok for tok in tokens if tok not in _STOPWORDS]
    return filtered if filtered else tokens


class BM25LexicalRetriever:
    """Exact lexical retriever backed by Okapi BM25 over non-zero posting hits."""

    def __init__(self, chunks: Sequence[CorpusChunk]) -> None:
        self._chunks = tuple(chunks)
        tokenized = [tokenize_lexical(format_chunk_passage(c)) for c in self._chunks]
        self._bm25 = BM25Okapi(tokenized)

    def search(self, query: str, top_k: int = 25) -> list[ScoredCandidate]:
        query_tokens = tokenize_lexical(query)
        if not query_tokens:
            return []
        raw_scores = np.asarray(self._bm25.get_scores(query_tokens), dtype=np.float64)
        matched = [i for i in range(len(self._chunks)) if float(raw_scores[i]) > 0.0]
        ordered = sorted(
            matched,
            key=lambda i: (-float(raw_scores[i]), self._chunks[i].chunk_id),
        )[: min(top_k, len(matched))]
        return [
            ScoredCandidate(
                chunk_id=self._chunks[i].chunk_id,
                rank=rank,
                score=float(raw_scores[i]),
                bm25_rank=rank,
            )
            for rank, i in enumerate(ordered, start=1)
        ]


class DenseBiEncoderRetriever:
    """Cosine-similarity vector retriever over unit-L2-normalized embeddings."""

    def __init__(self, chunks: Sequence[CorpusChunk], encoder: DenseEncoder) -> None:
        self._chunks = tuple(chunks)
        self._encoder = encoder
        matrix = self._encoder.encode_texts([format_chunk_passage(c) for c in self._chunks])
        norms = np.linalg.norm(matrix, axis=1, keepdims=True)
        self._embeddings = matrix / np.clip(norms, 1e-12, None)

    def search(self, query: str, top_k: int = 25) -> list[ScoredCandidate]:
        q_vec = self._encoder.encode_texts([query])[0]
        q_norm = float(np.linalg.norm(q_vec))
        if q_norm > 0.0:
            q_vec = q_vec / q_norm
        sims = self._embeddings @ q_vec
        ordered = sorted(
            range(len(self._chunks)),
            key=lambda i: (-float(sims[i]), self._chunks[i].chunk_id),
        )[: min(top_k, len(self._chunks))]
        return [
            ScoredCandidate(
                chunk_id=self._chunks[i].chunk_id,
                rank=rank,
                score=float(sims[i]),
                dense_rank=rank,
            )
            for rank, i in enumerate(ordered, start=1)
        ]

Now add the pure reciprocal_rank_fusion combiner and the two-stage TwoStageHybridRetriever class. Notice how every ScoredCandidate preserves bm25_rank, dense_rank, rrf_score, and rerank_score so you can audit exactly why any chunk moved up or down across stages:

# retrievers.py (continued)
def reciprocal_rank_fusion(
    lexical_results: Sequence[ScoredCandidate],
    dense_results: Sequence[ScoredCandidate],
    rrf_k: int = 60,
    top_k: int = 25,
) -> list[ScoredCandidate]:
    """Fuse lexical and dense ranked lists via scale-free RRF: sum(1 / (k + rank))."""
    rrf_scores: dict[str, float] = {}
    bm25_ranks: dict[str, int] = {}
    dense_ranks: dict[str, int] = {}

    for item in lexical_results:
        rrf_scores[item.chunk_id] = rrf_scores.get(item.chunk_id, 0.0) + 1.0 / (rrf_k + item.rank)
        bm25_ranks[item.chunk_id] = item.rank

    for item in dense_results:
        rrf_scores[item.chunk_id] = rrf_scores.get(item.chunk_id, 0.0) + 1.0 / (rrf_k + item.rank)
        dense_ranks[item.chunk_id] = item.rank

    def _sort_key(cid: str) -> tuple[float, int, str]:
        best_rank = min(bm25_ranks.get(cid, 10**9), dense_ranks.get(cid, 10**9))
        return (-rrf_scores[cid], best_rank, cid)

    ranked_ids = sorted(rrf_scores, key=_sort_key)[:top_k]
    return [
        ScoredCandidate(
            chunk_id=cid,
            rank=rank,
            score=rrf_scores[cid],
            bm25_rank=bm25_ranks.get(cid),
            dense_rank=dense_ranks.get(cid),
            rrf_score=rrf_scores[cid],
        )
        for rank, cid in enumerate(ranked_ids, start=1)
    ]


class TwoStageHybridRetriever:
    """Stage-1 BM25+Dense RRF candidate generator followed by Cross-Encoder reranking."""

    def __init__(
        self,
        chunks: Sequence[CorpusChunk],
        stage1: HybridRRFRetriever,
        reranker: PairReranker,
        stage1_top_k: int = 25,
        rerank_top_k: int = 5,
    ) -> None:
        self._passage_by_id: Mapping[str, str] = {
            c.chunk_id: format_chunk_passage(c) for c in chunks
        }
        self._stage1 = stage1
        self._reranker = reranker
        self.stage1_top_k = stage1_top_k
        self.rerank_top_k = rerank_top_k

    def search(self, query: str, top_k: int | None = None) -> list[ScoredCandidate]:
        output_k = top_k if top_k is not None else self.rerank_top_k
        stage1_pool = self._stage1.search(query, top_k=max(self.stage1_top_k, output_k))
        if not stage1_pool:
            return []

        pairs = [(query, self._passage_by_id[cand.chunk_id]) for cand in stage1_pool]
        cross_scores = self._reranker.score_pairs(pairs)
        rescored = sorted(
            zip(stage1_pool, cross_scores, strict=True),
            key=lambda item: (-float(item[1]), item[0].rank, item[0].chunk_id),
        )[:output_k]

        return [
            ScoredCandidate(
                chunk_id=cand.chunk_id,
                rank=new_rank,
                score=float(logit),
                bm25_rank=cand.bm25_rank,
                dense_rank=cand.dense_rank,
                rrf_score=cand.rrf_score,
                rerank_score=float(logit),
            )
            for new_rank, (cand, logit) in enumerate(rescored, start=1)
        ]

Why We Normalize Embeddings Explicitly Even When the Model Claims To

In Getting Started with Amazon S3 Vectors and Part 2: Bi-Encoders, we noted that inner-product indexes (embeddings @ q_vec or faiss.IndexFlatIP) assume unit-norm inputs. Enforcing matrix / np.clip(norms, 1e-12, None) inside DenseBiEncoderRetriever guarantees true directional cosine similarity even if a caller swaps in an unnormalized custom encoder later.

Step 4: Measuring Graded Quality and Tail Latency

To evaluate each pipeline from complementary angles, benchmark.py computes four quality metrics alongside warmed-up p50 and p95 query latency:

  1. Recall@5: Fraction of all relevant runbooks (grade >= 1, both primary and supporting chunks) captured inside a tight 5-chunk RAG prompt budget.
  2. Recall@25: Fraction of relevant runbooks present in the 25-chunk Stage-1 candidate pool handed to the cross-encoder. If Stage 1 misses a chunk here, Stage 2 can never recover it.
  3. MRR@10 (Primary Target): Mean Reciprocal Rank (1 / rank) of the authoritative grade = 2 runbook within the top 10. Placing a tangential grade = 1 chunk at rank #1 and the real grade = 2 answer at rank #3 yields MRR = 0.333, exposing sibling confusion immediately.
  4. nDCG@10 (Graded): Normalized Discounted Cumulative Gain with exponential gain:
DCG@10  = sum_{i=1..10} [ (2^rel_i - 1) / log2(i + 1) ]
nDCG@10 = DCG@10 / IDCG@10

With rel in {0, 1, 2}, the primary runbook contributes gain 2^2 - 1 = 3 while the companion runbook contributes 2^1 - 1 = 1.

# benchmark.py (core metric definitions)
import math
from collections.abc import Mapping, Sequence


def compute_recall_at_k(
    ranked_ids: Sequence[str],
    relevant_grades: Mapping[str, int],
    k: int,
) -> float:
    relevant_ids = {cid for cid, grade in relevant_grades.items() if grade >= 1}
    if not relevant_ids:
        return 0.0
    return sum(1 for cid in ranked_ids[:k] if cid in relevant_ids) / len(relevant_ids)


def compute_mrr_at_k(
    ranked_ids: Sequence[str],
    relevant_grades: Mapping[str, int],
    k: int,
    primary_min_grade: int = 2,
) -> float:
    primary_ids = {cid for cid, g in relevant_grades.items() if g >= primary_min_grade}
    for idx, cid in enumerate(ranked_ids[:k], start=1):
        if cid in primary_ids:
            return 1.0 / idx
    return 0.0


def compute_ndcg_at_k(
    ranked_ids: Sequence[str],
    relevant_grades: Mapping[str, int],
    k: int,
) -> float:
    dcg = sum(
        ((2 ** relevant_grades.get(cid, 0)) - 1.0) / math.log2(idx + 1.0)
        for idx, cid in enumerate(ranked_ids[:k], start=1)
        if relevant_grades.get(cid, 0) > 0
    )
    ideal = sorted((g for g in relevant_grades.values() if g > 0), reverse=True)[:k]
    idcg = sum(((2**rel) - 1.0) / math.log2(idx + 1.0) for idx, rel in enumerate(ideal, start=1))
    return dcg / idcg if idcg > 0.0 else 0.0

Run the test suite and benchmark on an 8-vCPU AMD EPYC 7B12 Linux machine (device=cpu):

.venv/bin/pytest -v
.venv/bin/python benchmark.py
Measured Pytest and 4-Stage Retrieval Scorecard (AMD EPYC 7B12 CPU)
============================= test session starts ==============================
platform linux -- Python 3.13.15, pytest-9.2.0, pluggy-1.7.0
collected 7 items

tests/test_hybrid_retrieval.py::test_settings_and_schema_validation PASSED [ 14%]
tests/test_hybrid_retrieval.py::test_corpus_and_query_referential_integrity PASSED [ 28%]
tests/test_hybrid_retrieval.py::test_lexical_tokenizer_and_bm25_exact_identifiers PASSED [ 42%]
tests/test_hybrid_retrieval.py::test_reciprocal_rank_fusion_scale_invariance PASSED [ 57%]
tests/test_hybrid_retrieval.py::test_information_retrieval_metrics_exact_math PASSED [ 71%]
tests/test_hybrid_retrieval.py::test_two_stage_pipeline_wiring_with_injected_fakes PASSED [ 85%]
tests/test_hybrid_retrieval.py::test_end_to_end_four_stage_benchmark_invariants PASSED [100%]

============================== 7 passed in 27.04s ==============================

=== Two-Stage Hybrid Retrieval Benchmark (48 chunks, 28 queries, device=cpu) ===
Models: bi_encoder=BAAI/bge-small-en-v1.5 | cross_encoder=cross-encoder/ms-marco-MiniLM-L-6-v2 | rrf_k=60

Pipeline                                         | Recall@5 | Recall@25 | MRR@10 | nDCG@10 |  p50 ms |  p95 ms
--------------------------------------------------------------------------------------------------------------
1. BM25 Only                                     |    0.661 |     0.714 |  0.804 |   0.767 |    0.16 |    0.21
2. Dense Bi-Encoder Only                         |    0.786 |     1.000 |  0.889 |   0.888 |   20.12 |   23.83
3. Hybrid BM25 + Dense RRF (k=60)                |    0.732 |     1.000 |  0.862 |   0.854 |   23.16 |   26.66
4. Two-Stage Hybrid RRF + Cross-Encoder (top-25) |    0.821 |     1.000 |  0.938 |   0.906 |  542.14 |  716.95

=== Diagnostic Slice Breakdown (exact_id vs semantic_paraphrase) ===
Pipeline                                         | Exact R@5 | Exact nDCG | Sem R@5 | Sem nDCG
----------------------------------------------------------------------------------------------
1. BM25 Only                                     |     0.714 |      0.896 |   0.607 |    0.637
2. Dense Bi-Encoder Only                         |     0.821 |      0.891 |   0.750 |    0.884
3. Hybrid BM25 + Dense RRF (k=60)                |     0.786 |      0.929 |   0.679 |    0.778
4. Two-Stage Hybrid RRF + Cross-Encoder (top-25) |     0.821 |      0.931 |   0.821 |    0.881

Dissecting the Scorecard: Why Stage 1 Needs Stage 2

Look closely at both tables, starting with the overall progression and then breaking out the two diagnostic query slices (exact_id vs semantic_paraphrase):

Pipeline (Measured on CPU)Overall Recall@5Overall MRR@10Overall nDCG@10CPU p50 (ms)
1. BM25 Only0.6610.8040.7670.16
2. Dense Bi-Encoder (bge-small)0.7860.8890.88820.12
3. Stage-1 Hybrid RRF (k=60)0.7320.8620.85423.16
4. Two-Stage Hybrid + Cross-Encoder0.8210.9380.906542.14

Now inspect the per-slice MRR@10 and nDCG@10 figures from the JSON report to see why each stage behaves the way it does:

PipelineExact MRR@10Exact nDCG@10Semantic MRR@10Semantic nDCG@10
1. BM25 Only1.0000.8960.6070.637
2. Dense Bi-Encoder Only0.8670.8910.9110.884
3. Stage-1 Hybrid RRF (k=60)0.9640.9290.7600.778
4. Two-Stage Hybrid + Cross-Encoder0.9640.9310.9110.881

Three engineering findings jump out of these measured numbers:

1. BM25 Nails Exact Primary Identifiers (1.000 MRR) Yet Stalls at 0.714 Recall

On all 14 exact_id queries, identifier-aware BM25 places the exact matching runbook (g5.12xlarge, SQLSTATE 55P03, exit code 139, ERR_SSL_PROTOCOL_ERROR, TcpExtListenOverflows) at rank #1 (1.000 MRR@10) in 0.16 ms (p50). Meanwhile, BAAI/bge-small-en-v1.5 drops to 0.867 MRR@10 on exact_id because sibling SKUs (g5.12xlarge vs g5.2xlarge) and sibling error codes (UO vs UF) compress into overlapping subword embeddings. Adding Stage-1 RRF restores exact_id MRR@10 from 0.867 to 0.964 and lifts exact_id nDCG@10 from 0.891 to 0.929 at minimal extra latency (23.16 ms vs 20.12 ms).

2. Unweighted RRF Is a Candidate Generator, Not a Precision Top-5 Ranker

Notice a result that surprises many teams who deploy Stage-1 RRF without a reranker: on semantic_paraphrase queries, unweighted RRF (0.778 nDCG@10, 0.679 Recall@5) actually scores lower at top-5 than running the dense bi-encoder alone (0.884 nDCG@10, 0.750 Recall@5), even though RRF achieves a 1.000 Recall@25 across the candidate pool!

Inspecting a single query trace (q_sem_07) explains the exact mechanism:

Measured Score Trace on q_sem_07 (Semantic Paraphrase)
Query: 'serving newest waiting callers first and dropping timed-out requests during overload'

Rank 1: http-load-shedding-lifo  | bm25_rk=None | dense_rk=   1 | rrf=0.01639 | ce_logit=+3.993
Rank 2: envoy-flag-uo-overflow   | bm25_rk=   1 | dense_rk=  17 | rrf=0.02938 | ce_logit=-7.643
Rank 3: http-429-retry-after     | bm25_rk=   5 | dense_rk=   5 | rrf=0.03077 | ce_logit=-7.809
Rank 4: linux-sysctl-somaxconn   | bm25_rk=   8 | dense_rk=   7 | rrf=0.02963 | ce_logit=-9.853
Rank 5: k8s-conntrack-table-full | bm25_rk=   2 | dense_rk=None | rrf=0.01613 | ce_logit=-10.206

Look at the rrf column vs the ce_logit column:

  • http-load-shedding-lifo shares zero lexical tokens with the query (bm25_rk=None), so its RRF score receives only its Dense #1 contribution: 1 / (60 + 1) = 0.01639.
  • Meanwhile, distractors like http-429-retry-after (bm25_rk=5, dense_rk=5, RRF = 0.03077) and envoy-flag-uo-overflow (bm25_rk=1 on the generic words "requests" and "overload", dense_rk=17, RRF = 0.02938) collect contributions from both streams, pushing http-load-shedding-lifo down to rank #7 in Stage-1 RRF!
  • Because http-load-shedding-lifo stays safely inside the top-25 RRF pool (1.000 Recall@25), Stage-2 ms-marco-MiniLM-L-6-v2 reads the query alongside all 25 passages, assigns +3.993 to LIFO Admission Queues and -7.643 or lower to every distractor, and vaults the true runbook straight back to Rank 1. Across all 28 queries, Stage 2 lifts overall Recall@5 to 0.821, MRR@10 to 0.938, and nDCG@10 to 0.906, outperforming every single-stage retriever.

Out-of-Domain Short Codes Can Fool Web-Trained Cross-Encoders

In q_exact_06 (envoy 503 error with response flag UO in access logs), BM25 ranks envoy-flag-uo-overflow at #1 and envoy-flag-uf-connect at #2, whereas ms-marco-MiniLM-L-6-v2 scores UF (+7.414) slightly ahead of UO (+6.907) because MS MARCO web queries rarely hinge on two-letter proxy telemetry codes. When exact domain codes carry high business weight, either fine-tune your cross-encoder on domain pairs (as shown in Part 3) or add a small lexical exact-identifier boost alongside the cross-encoder logit.

Sizing stage1_top_k for Your Latency Budget

Cross-encoder latency scales linearly with stage1_top_k because Stage 2 executes a transformer forward pass for every (query, candidate) pair. Sweeping stage1_top_k across 10, 15, 25, 40 on our 8-vCPU EPYC machine (single-pass timing after model warmup) reveals a clear pareto frontier:

stage1_top_k PoolStage-1 RRF Recall@kStage-2 Recall@5Stage-2 nDCG@10CPU p50 (ms)
k = 100.9290.8040.908213.6
k = 150.9460.8210.909431.4
k = 251.0000.8210.906529.2
k = 401.0000.8210.906787.7

Use these measured and hardware-calibrated numbers to match your pipeline to your serving SLA:

  • Sub-50ms CPU-only services (typeahead, high-QPS internal search): Skip the CPU cross-encoder on the synchronous path and serve Weighted RRF (w_lex / (k + r_lex) + w_dense / (k + r_dense) with w_dense = 1.5 and w_lex = 1.0 so single-stream semantic #1 hits stay inside top-5) in ~23 ms measured CPU latency.
  • Interactive RAG and agent tool calls (150 ms to 800 ms retrieval budget): Run the full Two-Stage Hybrid RRF + Cross-Encoder pipeline. On CPU-only workers, set stage1_top_k between 15 and 25 (431 ms to 542 ms measured p50). On a single NVIDIA T4 or L4 GPU (where ms-marco-MiniLM-L-6-v2 processes ~830 to 1,050 pairs/sec as benchmarked in Part 3), batched Stage-2 reranking of 25 to 50 candidates finishes in roughly 20 to 50 ms (estimated from T4 batch throughput), giving you full two-stage precision inside a 90ms end-to-end retrieval budget.
  • Mutable vs immutable knowledge: Two-stage hybrid retrieval solves finding the right static document across lexical and semantic phrasing shifts. When your agent also tracks mutable user facts that supersede earlier turns over months of conversation, pair hybrid document RAG with slot-reconciled state consolidation as benchmarked in Stateful Agent Memory and synthesized in Where Production AI Reliability Comes From.

Key Takeaways

  1. Aggregate RAG scores hide opposing blind spots: Always split evaluation queries into exact_id (SKUs, error codes, flags) and semantic_paraphrase slices with sibling hard negatives in every domain.
  2. RRF eliminates score-calibration drift: Summing 1 / (60 + rank) merges unbounded BM25 scores and anisotropic cosine similarities without fragile min-max scaling, provided you filter out zero-score BM25 padding first.
  3. Stage-1 RRF maximizes candidate recall (1.000 Recall@25), while Stage-2 Cross-Encoders deliver top-5 precision (0.821 Recall@5, 0.938 MRR@10, 0.906 nDCG@10): Joint query-document attention rescues single-stream semantic hits that unweighted RRF pushes below dual-stream distractors.
  4. Right-size stage1_top_k to hardware: Reranking 15 to 25 hybrid candidates captures the recall ceiling while keeping CPU latency ~33% lower than k=40 and GPU batch latency under 50ms.

Further Reading

Found this walkthrough useful?
0
Mile Marker 106 emblem

Steven W. White · Software engineer and AI systems builder writing from the Florida coast

Independent engineering notes, measured hardware benchmarks, and runnable code from Mile Marker 106.

Keep Exploring

Related Guides

Concept Map →

Discussion

Loading comments...