Reference · Lesson 0004

Reciprocal Rank Fusion (RRF) Cheat Sheet

Printable. Designed to live next to your editor.

The formula

RRF(d) = Σᵢ  wᵢ / (k + rankᵢ(d))

• d = document / chunk
• i = index over rankers (vector, BM25, …)
• rankᵢ(d) = 1-indexed position of d in ranker i's list
• k = smoothing constant (Cormack et al. default: 60)
• wᵢ = weight for ranker i (sum to 1.0 across rankers, optional)
• If d is missing from ranker i, its contribution is 0.

Our constants (from config.py)

Rank-decay table (k = 60)

Top 5 ranks contribute almost identically. After rank 50, contributions are still non-trivial. After rank 100, they're down to ~38% of rank-1.

Algorithm (pseudocode)

function RRF(rank_lists, weights, k=60):
    # rank_lists: dict[ranker_name → list of doc_ids]   (rank 1 first)
    # weights:    dict[ranker_name → float]
    scores = {}
    for name, rlist in rank_lists.items():
        w = weights[name]
        for rank, doc in enumerate(rlist, start=1):
            scores[doc] = scores.get(doc, 0) + w / (k + rank)
    return sorted(scores.items(), key=lambda x: -x[1])

How our HybridSearch.search does it

vec_results  = vector_store.vector_search(query_vec, top_k=top_k * 2)
bm25_results = bm25.search(query,              top_k=top_k * 2)
scores = {}

# Vector list: starts each chunk with vector contribution
for rank, r in enumerate(vec_results):
    cid = r["id"]
    scores[cid] = {
        "rrf_score":    VECTOR_WEIGHT / (RRF_K + rank + 1),
        "vector_rank":  rank + 1,
        "bm25_rank":    None,
        "vector_score": 1 - r["score"],   # cosine in [0,1]
    }

# BM25 list: adds BM25 contribution (or starts a new entry)
for rank, r in enumerate(bm25_results):
    cid = r["doc_id"]
    boost = BM25_WEIGHT / (RRF_K + rank + 1)
    if cid in scores:
        scores[cid]["rrf_score"] += boost
        scores[cid]["bm25_rank"] = rank + 1
    else:
        scores[cid] = hit_from_bm25_only(cid, ..., rank + 1, boost)

return sorted(scores.values(), key=lambda x: -x["rrf_score"])[:top_k]

Fusion algorithm comparison

When to change k

Default k=60 is fine for almost everything. Don't tune it before you've first tuned your actual rankers.

When to change weights

Common RRF failure modes

• Both rankers miss: the chunk just isn't there. Not RRF's fault.
• One ranker is broken: if cosine is returning random results, the RRF score is dominated by BM25 (and vice versa). Sanity-check each ranker independently before debugging RRF.
• Top-k too small in the inner calls: the top_k * 2 fudge factor in our code exists because RRF can rescue a chunk ranked 7 in cosine but 1 in BM25. If you fetch only top_k from each, you exclude the rescue candidates.
• You try to use RRF score as a probability: it's not. It's a relative ranking signal. The absolute number 0.016 has no meaning across queries.

Glossary