Gen AI

Relevance Tuning

You built a semantic search engine, but the 3rd result is actually better than the 1st result. Relevance tuning is the process of building test sets (judgements) and tweaking the retrieval weights until the best result is reliably at the top.

Why Does This Exist?

When you first launch a Semantic Search or RAG system, you will quickly notice that the search results are "okay, but not great."

A user searches for "login page error."
The search engine returns a document about "how to create a login page" at Rank 1.
The actual troubleshooting guide is buried at Rank 14.

You decide to fix this by switching from text-embedding-3-small to text-embedding-3-large. You test the "login page error" query, and it's fixed! But what you didn't realize is that your new embedding model just broke the results for 5,000 other queries.

Relevance Tuning is the discipline of treating Search Quality as a rigorous ML optimization problem. Instead of "eyeballing" the results, you build a massive test set, calculate strict metrics (like NDCG), and tune your pipeline (hybrid search weights, metadata filters, re-rankers) systematically.

Think of It Like This

Imagine you are adjusting the equalizer (EQ) sliders on a stereo. If you slide the "Bass" all the way up, your hip-hop track sounds amazing, but your acoustic track sounds terrible.

If you only test your EQ settings using one song, you will ruin the stereo for every other genre. You need a playlist of 50 different songs (a Judgement Set). Every time you touch a slider, you listen to a few seconds of all 50 songs and calculate an average score to ensure you improved the overall system, not just one track.

How It Actually Works

Relevance tuning requires three pillars:

1. The Judgement Set (The Golden Data)

You cannot tune what you cannot measure. The first step is creating a dataset of Queries mapped to their ideal Documents, scored by a human (or an LLM judge).

Query: reset password
Document A (Reset Instructions): Score: 3 (Perfect)
Document B (Login FAQ): Score: 1 (Marginal)
Document C (Pricing Page): Score: 0 (Irrelevant)

2. Offline Metrics

Once you have 1,000 queries in your Judgement Set, you run your search engine and compare its ranking to the golden ranking. We use metrics like:

Mean Reciprocal Rank (MRR): Measures how far down the user has to scroll to find the first perfect result. (Used for navigational queries).
NDCG (Normalized Discounted Cumulative Gain): The gold standard. It gives you a high score if all the relevant documents are at the top, and penalizes you heavily if a highly relevant document is pushed to Rank 10.

3. Tuning the Levers

Now that you have a single NDCG score for your entire engine, you can start tuning. You might:

Adjust the alpha weight in your Hybrid Search (e.g., 70% Semantic, 30% Lexical).
Add a Cross-Encoder Re-ranker at the end of the pipeline.
Apply a recency boost (multiplying the score by how new the document is). Every time you change a lever, you re-run the Judgement Set and check if the global NDCG went up.

Show Me the Code

Here is how you calculate NDCG for a single query using scikit-learn.

1from sklearn.metrics import ndcg_score2import numpy as np3
4# A human reviewer decided that for the query "password reset":5# Doc A is perfect (3), Doc B is okay (1), Doc C and D are irrelevant (0)6true_relevance = np.asarray([[3, 1, 0, 0]])7
8# Scenario 1: Your baseline search engine ranks them in this order:9# [Doc A, Doc C, Doc B, Doc D]10# We represent the ranking as arbitrary scores the engine assigned to the docs11baseline_scores = np.asarray([[0.9, 0.4, 0.5, 0.1]]) 12
13# Scenario 2: You add a Re-ranker, which fixes the order to:14# [Doc A, Doc B, Doc D, Doc C]15reranker_scores = np.asarray([[0.9, 0.8, 0.2, 0.3]])16
17# Calculate NDCG@4 (Normalized Discounted Cumulative Gain)18ndcg_baseline = ndcg_score(true_relevance, baseline_scores)19ndcg_tuned = ndcg_score(true_relevance, reranker_scores)20
21print(f"Baseline NDCG: {ndcg_baseline:.3f}")22print(f"Tuned NDCG:    {ndcg_tuned:.3f}")23
24# Output:25# Baseline NDCG: 0.90326# Tuned NDCG:    1.000 27# (1.0 means the ranking perfectly matches the human's ideal ranking!)

Watch Out For

Goodhart's Law (Optimizing the Offline Metric over the User). Offline metrics (NDCG) are just proxies for what the user actually wants. If you tune your engine perfectly to your 1,000-query Judgement Set, you might inadvertently overfit to those specific queries. Always validate major tuning changes with an Online A/B Test, measuring actual user behavior like Click-Through Rate (CTR) or "Time to Success". If NDCG goes up but CTR goes down, trust the CTR.

The Quick Version

Relevance Tuning is the iterative process of improving search results across an entire system.
It requires a Judgement Set (a list of queries and human-scored ideal results).
You use the Judgement Set to calculate offline metrics like NDCG or MRR.
By monitoring these metrics, you can safely tune the weights of your hybrid search, add re-rankers, and change embedding models without flying blind.