Chapter: How to Test RAG Retrievers (Hands-On)

To build reliable Retrieval-Augmented Generation (RAG) applications, evaluation must be conducted at every level of system architecture. A production-grade evaluation suite operates across three progressive levels: Component-level, Pipeline/Workflow-level, and Application-level.

This chapter focuses on Component-Level Evaluation, isolating and rigorously benchmarking the Retriever. We cover the mathematical principles of vector retrieval metrics, expose the architectural flaws of traditional chunk-ID evaluations, introduce LLM-as-a-judge contextual metrics, and walk through step-by-step code experiments to optimize retrieval quality.

1. RAG Evaluation Architecture & Project Setup

Evaluating a complex LLM system after full deployment makes root-cause debugging nearly impossible. Component-level evaluation applies software engineering unit-testing principles to AI: each standalone module—first the Retriever, then the Generator—is benchmarked and optimized before integration.

To support repeatable evaluation and regression testing across model iterations, a standardized directory structure decouples source code, raw data, test suites, and reference datasets.

Dependency Setup via uv

Using uv guarantees reproducible virtual environments and ultra-fast dependency resolution:

# Initialize Python 3.11 environment and install required libraries
uv init --python 3.11
uv add langchain langchain-community langchain-openai openai deepeval pytest python-dotenv chromadb sentence-transformers

2. Building the Naive Retriever: From Transcripts to Vector Store

The primary responsibility of a retriever is to ingest user queries, convert them into dense vector embeddings, and search a vector database to retrieve the top-$K$ semantically relevant chunks.

Cleaning Ingestion Pipelines

Raw knowledge source files (e.g., .vtt subtitle transcripts) contain dense timestamp metadata. Retaining timestamps during semantic embedding pollutes the vector space, creating artificial distance between adjacent text blocks.

Stripping timestamps while extracting structural metadata (such as source session IDs) creates clean semantic blocks while preserving source citations.

Baseline Implementation (src/retriever.py)

The following module handles data ingestion, timestamp stripping, chunking, persistent Chroma vector indexing, and retriever query execution.

import os
import glob
from dotenv import load_dotenv
from langchain_community.document_loaders import TextLoader
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma

load_dotenv()

DATA_DIR = "data"
CHROMA_DIR = "chroma_store"

def load_transcripts(data_dir: str):
    """Loads VTT files, strips timestamps, and attaches session metadata."""
    documents = []
    vtt_files = glob.glob(os.path.join(data_dir, "*.vtt"))
    
    for file_path in vtt_files:
        session_name = os.path.basename(file_path).replace(".vtt", "")
        with open(file_path, "r", encoding="utf-8") as f:
            lines = f.readlines()
        
        clean_lines = []
        for line in lines:
            # Filter VTT headers, timestamps, and empty lines
            if "-->" in line or line.strip().isdigit() or line.startswith("WEBVTT"):
                continue
            if line.strip():
                clean_lines.append(line.strip())
        
        full_text = " ".join(clean_lines)
        doc = Document(
            page_content=full_text,
            metadata={"source": session_name}
        )
        documents.append(doc)
    return documents

def build_retriever(chunk_size=750, chunk_overlap=100, k=5, embedding_model="text-embedding-3-small"):
    """In-memory or persistent vector store creation and retriever construction."""
    embeddings = OpenAIEmbeddings(model=embedding_model)
    
    if os.path.exists(CHROMA_DIR) and os.listdir(CHROMA_DIR):
        vector_store = Chroma(
            persist_directory=CHROMA_DIR, 
            embedding_function=embeddings
        )
    else:
        documents = load_transcripts(DATA_DIR)
        text_splitter = RecursiveCharacterTextSplitter(
            chunk_size=chunk_size, 
            chunk_overlap=chunk_overlap
        )
        chunks = text_splitter.split_documents(documents)
        print(f"Total chunks indexed: {len(chunks)}")
        
        vector_store = Chroma.from_documents(
            documents=chunks,
            embedding=embeddings,
            persist_directory=CHROMA_DIR
        )
        
    return vector_store.as_retriever(search_kwargs={"k": k})

if __name__ == "__main__":
    retriever = build_retriever()
    query = "What is regression testing?"
    results = retriever.invoke(query)
    print(f"\nRetrieved {len(results)} chunks for query: '{query}'")
    for idx, doc in enumerate(results):
        print(f"\n--- Chunk {idx+1} (Source: {doc.metadata['source']}) ---")
        print(doc.page_content[:200] + "...")

3. Failure Modes & Mathematical Evaluation Metrics

A retriever can fail in two distinct ways during execution:

Mathematical Definitions

1. Recall: Measures the proportion of relevant ground-truth contexts captured by the retriever relative to all available ground-truth contexts in the knowledge base.

2. Precision: Measures the purity of the retrieved context set by calculating the proportion of retrieved chunks that are actually relevant.

The Precision-Recall Trade-off ($K$-Parameter Tension)

There is an inherent trade-off between Precision and Recall controlled by the parameter $K$ (number of retrieved chunks):

An ideal retriever maximizes both metrics simultaneously, pushing both values toward $1.0$.

4. The Flaw of Hardcoded Chunk-ID Evaluation (Recall@K)

A common legacy strategy for evaluating retrievers relies on mapping benchmark questions directly to fixed chunk IDs in the vector database.

The Naive Chunk-ID Mapping Approach

[
  {
    "question": "What is regression testing?",
    "expected_chunk_ids": [72, 89, 100]
  }
]

Why Chunk-ID Evaluations Fail in Production Engineering

While computationally simple, evaluating against hardcoded chunk IDs creates a severe architectural flaw known as the Chunk-Invalidation Cascade:

5. Modern Evaluation Methodology: Contextual Recall & Contextual Precision

To bypass chunk-ID fragility, modern evaluation frameworks (e.g., RAGAS, DeepEval) decouple ground-truth reference data from vector database indices. Instead of tracking chunk IDs, the golden dataset pairs queries with an Ideal Answer synthesized directly from the original knowledge source.

Golden Dataset Entry:
  - Input Query: "What is regression testing?"
  - Expected Ideal Answer: "Regression testing runs an eval suite against modified software to verify that new code changes do not break existing baseline functionality."

Contextual Recall Execution Workflow

Contextual Recall uses an LLM-as-a-Judge to evaluate semantic coverage without referring to chunk boundaries:

Contextual Precision & Rank Awareness

Standard precision treats all retrieved items equally, regardless of position. However, downstream LLMs pay more attention to information at the beginning or end of a context window (the "Lost in the Middle" phenomenon). Therefore, Contextual Precision must be Rank-Aware.

Contextual Precision evaluates whether relevant chunks are placed higher in the retrieved ranking ($K$).

Rank-Aware Calculation Formula

Where:

• $P@k = \frac{\text{Number of Relevant Chunks in Top } k}{k}$
• $v_k \in \{0, 1\}$ is a binary indicator of whether the chunk at position $k$ is relevant.

Comparative Breakdown: Case A vs. Case B

Consider $K = 5$ retrieved chunks, with $2$ relevant chunks ($R$) and $3$ irrelevant noise chunks ($N$):

Case A (Optimal Ranking):  [ R,  R,  N,  N,  N ]
Case B (Suboptimal Rank):  [ N,  N,  N,  R,  R ]

Standard Precision scores both cases as $2/5 = 0.40$. Rank-aware Contextual Precision correctly ranks Case A ($1.00$) significantly higher than Case B ($0.325$).

6. Golden Dataset Engineering Strategies

A golden evaluation dataset requires two columns: input (the question) and expected_output (the ideal ground-truth answer based only on the knowledge domain).

Strategies for Generating Golden Datasets

1. Manual / Hand-Authored Construction: Subject Matter Experts (SMEs) draft questions and ideal answers from scratch.
   • Pros: Zero hallucination risk, extremely high quality.
   • Cons: Highly unscalable, expensive.
2. LLM-Assisted Drafting + Human Review: An advanced model (e.g., Claude 3.5 Sonnet) generates questions and ideal answers from source text, followed by rigorous human domain expert auditing.
   • Pros: Excellent speed-to-quality balance, cost-effective.
   • Cons: Requires mandatory human verification to prune out-of-domain knowledge leaks.
3. Automated Synthesizers (e.g., DeepEval Synthesizer): Programmatic extraction using AST or LLM text chunking primitives.
   • Pros: Completely automated.
   • Cons: Often yields synthetic, robotic queries that do not match realistic user prompt distributions.
4. Production Log Harvesting: Extracting live production query logs coupled with positive user feedback (e.g., thumbs-up signals).
   • Pros: Captures real-world user distribution.
   • Cons: Only available after deployment.

7. DeepEval Integration & Evaluation Pipeline Mechanics

DeepEval structures test execution around three core primitives:

The Retriever Test Suite (evals/eval_retriever.py)

This test script loads the golden dataset, runs the retriever to collect runtime context, evaluates the retrieved context using ContextualRecallMetric and ContextualPrecisionMetric, and prints structured diagnostic logs.

import json
import os
from dotenv import load_dotenv
from deepeval import evaluate
from deepeval.test_case import LLMTestCase
from deepeval.metrics import ContextualRecallMetric, ContextualPrecisionMetric
from src.retriever import build_retriever

load_dotenv()

GOLDEN_DATASET_PATH = "goldens/retriever_golds.json"
JUDGE_MODEL = "gpt-4o"
SCORE_THRESHOLD = 0.70

def load_golden_dataset(path: str):
    with open(path, "r", encoding="utf-8") as f:
        return json.load(f)

def run_retriever_evaluation():
    golds = load_golden_dataset(GOLDEN_DATASET_PATH)
    retriever = build_retriever(chunk_size=1000, chunk_overlap=150, k=5)
    
    test_cases = []
    
    print(f"Preparing test cases for {len(golds)} evaluation entries...")
    for entry in golds:
        query = entry["input"]
        expected_output = entry["expected_output"]
        
        # Invoke retriever to get runtime contexts
        retrieved_docs = retriever.invoke(query)
        retrieved_contexts = [doc.page_content for doc in retrieved_docs]
        
        # Construct DeepEval LLMTestCase
        test_case = LLMTestCase(
            input=query,
            actual_output="[Generator Evaluated Separately]",  # Placeholder for component testing
            expected_output=expected_output,
            retrieved_content=retrieved_contexts
        )
        test_cases.append(test_case)
        
    # Configure Contextual Metrics with GPT-4o Judge
    recall_metric = ContextualRecallMetric(
        threshold=SCORE_THRESHOLD,
        model=JUDGE_MODEL,
        include_reason=True
    )
    
    precision_metric = ContextualPrecisionMetric(
        threshold=SCORE_THRESHOLD,
        model=JUDGE_MODEL,
        include_reason=True
    )
    
    # Run DeepEval framework evaluation
    print("\nExecuting DeepEval Component Evaluation...")
    results = evaluate(
        test_cases=test_cases,
        metrics=[recall_metric, precision_metric]
    )
    return results

if __name__ == "__main__":
    run_retriever_evaluation()

8. Systematic Retriever Optimization

Improving retrieval quality requires an empirical, hypothesis-driven benchmark approach. Each component modification—adjusting chunk boundaries, adding re-ranking layers, or switching embedding models—must be evaluated against the baseline.

Integrating a Re-Ranker (src/reranker.py)

A re-ranker acts as a secondary filter. While vector similarity search (Bi-Encoder) quickly retrieves candidate chunks, a Cross-Encoder re-ranker scores the query directly against each retrieved chunk to re-order them by relevance.

Re-Ranker Implementation (src/reranker.py)

from typing import List
from langchain_core.documents import Document
from sentence_transformers import CrossEncoder

class ContextReranker:
    def __init__(self, model_name: str = "cross-encoder/ms-marco-MiniLM-L-6-v2"):
        self.model = CrossEncoder(model_name)

    def rerank(self, query: str, docs: List[Document], top_n: int = 5) -> List[Document]:
        if not docs:
            return []
        
        # Create (Query, Chunk Text) sentence pairs for the Cross-Encoder
        pairs = [[query, doc.page_content] for doc in docs]
        scores = self.model.predict(pairs)
        
        # Combine documents with their cross-encoder score
        doc_score_pairs = list(zip(docs, scores))
        # Sort descending by relevance score
        sorted_pairs = sorted(doc_score_pairs, key=lambda x: x[1], reverse=True)
        
        return [doc for doc, score in sorted_pairs[:top_n]]

Empirical Optimization Pipeline

Summary of System Benchmark Results

The table below tracks performance across four system optimization iterations:

9. Summary and Key Takeaways

• Component-Level Modular Isolation: Always evaluate RAG retrievers independently from the generator. Evaluating an end-to-end RAG system without component-level tests makes it difficult to pinpoint whether errors stem from bad context retrieval or generator hallucinations.
• Dual Failure Modes: Retrievers fail either through Context Omission (evaluated via Recall) or Context Pollution (evaluated via Precision). Both metrics must be optimized together.
• The Precision-Recall Trade-off: Increasing the retrieval parameter $K$ improves recall by broadening context coverage, but degrades precision by introducing noisy chunks.
• Flaw of Chunk-ID Metrics: Traditional Recall@K anchored to hardcoded document chunk IDs fails whenever chunking strategies or parameters change. Redefine evaluation frameworks around ground-truth ideal answers instead.
• Contextual Recall via LLM Judges: Contextual Recall measures whether the atomic claims of a ground-truth answer are present across the set of retrieved chunks.
• Contextual Precision is Rank-Aware: Contextual Precision penalizes systems that place irrelevant chunks near the top of the context window, helping prevent downstream LLM positional bias ("Lost in the Middle").
• Golden Dataset Integrity: Ground-truth answers must reflect the knowledge base rather than external knowledge sources (like web search).
• High-Impact Optimizations: Modern re-rankers (such as Cross-Encoders) significantly improve Contextual Precision by re-ordering relevant chunks to top positions before passing context to the generator.