← Learn / Notebooks

Models & toolsTechnicalStudy guide

RAG: HNSW, Hybrid Retrieval and Tool Use

Study retrieval-augmented generation, HNSW search, lexical–dense rank fusion, reranking, context evaluation, and guarded tool execution through a synthetic Python lab.

Before you start: You should understand transformer inference, vector similarity, basic probability, and Python functions and dictionaries.

AI-assisted study notebook · Published 2026-11-16. Separate automated source and visual reviews passed; these checks are not independent expert fact verification. Source audit · Review record.

Parametric memory and retrieval-augmented generation

Lewis and colleagues distinguish knowledge represented in a generator’s parameters from an external document index. Their RAG model combines a learned retriever with a sequence generator: the retrieved document is a latent variable, rather than a guaranteed factual answer. Updating an index and retraining a generator are therefore different operations. Lewis et al.

For input x, output tokens y₁…yₙ, and document z, RAG-Sequence uses the top-K approximation below. One document conditions the entire sequence inside each product; the outer sum combines alternative document-conditioned probabilities. The DPR retriever scores documents using separately encoded query and document vectors.

RAG-Sequence: p(y|x) ≈ Σz∈top-K pη(z|x) ∏i=1…N pθ(yᵢ|x,z,y<ᵢ). Retriever: pη(z|x) ∝ exp(Ed(z)ᵀEq(x)). RAG-Token instead permits a different latent document at each output position. These are probability constructions, not instructions to concatenate every retrieved passage.

The practical design studied here assembles several selected passages into one prompt. It does not implement that marginalization or train a RAG model. Its objective is to make candidate selection, evidence placement, and tool permissions inspectable. A citation is an address for checking support; this design does not treat citation presence as proof of truth.

Scope and limits. This guide preserves the distinction between approximate vector search, relevance ranking, source support, and authorization. The lab uses invented document identifiers and relevance grades. It implements neither embeddings nor HNSW, BM25, a reranker, an LLM judge, or an MCP transport. Its results explain mechanics and cannot establish production accuracy, latency, or security.

In the proposed indexing design, each chunk carries a stable identifier, parent document, source revision, and access scope. Chunk boundaries follow useful document structure; overlap is a tunable choice. Parent expansion must preserve the same access restrictions. Keep lexical and dense indexes aligned to the same revision so that fusion does not silently join incompatible document versions. These are explicit design choices for this example, not properties supplied automatically by RAG.

HNSW layers and search parameters

HNSW builds nested proximity graphs. Every element belongs to layer zero; progressively fewer elements reach higher layers through randomized level assignment. Query search starts at the top, greedily improves its entry point, descends, and uses a larger search set at the base. Upper layers provide coarse routing, while the base supports more detailed exploration. This is approximate nearest-neighbor search: the closest vectors can be missed. HNSW, Algorithms 1–5

The paper’s logarithmic scaling discussion is conditional; its strict analysis begins with exact Delaunay graphs and then considers approximations. It should not be converted into a universal worst-case O(log N) guarantee for arbitrary embeddings, filters, or recall targets. Nor is every upper-layer edge necessarily long or every base-layer edge short.

Separate construction choices from query-time search effort
ParameterMeaningTradeoff to measure
MConnections selected for a newly inserted element; layer degree caps are separate details.More links increase graph storage and can support higher recall.
efConstructionSearch-list size used while building connections.More construction work may improve graph quality, with diminishing returns.
efSearch / efQuery-time size of the retained nearest-neighbor search list.More search work generally improves recall at a latency cost.

The hnswlib documentation calls the query parameter ef and requires it to be at least the requested neighbor count. It is not an exact cap on distance computations. Its guidance is implementation-specific; benchmark the chosen library and corpus instead of treating a range such as M=16–64 as a universal optimum. hnswlib parameter documentation

For a synthetic exhaustive baseline with N vectors of dimension d, evaluating N dot products takes O(Nd) arithmetic, excluding selection and memory effects. Compare HNSW’s returned IDs with that baseline using the same vectors, distance, and allowed corpus. This measures ANN recall, not whether the documents answer a human question. A perfect approximation to a poor embedding ranking remains a poor semantic retriever.

Lexical and dense retrieval with reciprocal rank fusion

BM25 combines query-term contributions with term-frequency saturation and document-length normalization. One common form is Σt∈Q IDF(t)·f(t,D)(k₁+1)/[f(t,D)+k₁(1−b+b|D|/avgdl)]. Here f counts a term, |D| and avgdl use consistent length units, k₁ controls saturation, and b controls length normalization. The factor k₁+1 is a common scaling convention; implementations and IDF definitions differ. BM25 scores should not be described as universally positive and unbounded. Robertson and Zaragoza, §3.4–3.5

Dense and lexical rankings can contribute different candidates. RRF avoids comparing their raw score magnitudes: with one-based ranks, score(d)=Σr containing d1/(c+rankr(d)). A missing document contributes zero in this finite-list implementation. The original paper calls the constant k; this guide uses c to distinguish it from an evaluation cutoff. Its authors fixed k=60 after pilot experiments, which does not establish a universal optimum. Cormack et al.

In this design, both retrievers search only an authorized scope. Their candidate lists meet at fusion; a reranker then chooses material for context assembly. RRF rewards repeated appearances but discards score margins. It cannot recover a document absent from both lists. Candidate depth, fusion constant, duplicate policy, and tie handling therefore belong in the experiment record.

A query and authenticated identity enter corpus authorization. The authorized query branches to BM25 and dense HNSW rankings. Both lists join at RRF, followed by reranking and context selection, then generation with citations.

Download editable retrieval diagram

Diagram reading. Every arrow represents data passed to the next operation. The two outgoing authorization arrows carry the same permitted scope to independent lexical and dense searches. Their incoming fusion arrows carry ranked IDs, not interchangeable relevance probabilities. The remaining arrows carry candidates and then selected evidence. A failed authorization stops before either search; that rejection path is omitted from this data-flow view. The last box names an intended output format, not a factuality guarantee.

Consider the invented query “Does AX-17 support mode Z?” A lexical branch might recover the exact identifier while a dense branch recovers a paraphrase. That is a test case to include, not a claim that dense retrieval always fails on identifiers. Add confusable identifiers and missing-answer cases to see whether fusion improves useful recall or merely adds distractors.

Reranking and context selection

Where query and document representations interact
ArchitectureInteractionReusable document work
Bi-encoderCompare independently encoded vectors.Document vectors can be indexed offline.
ColBERT late interactionFor each query token, take its maximum document-token similarity; sum those maxima.Document token vectors can be computed offline.
BERT cross-encoderEncode the query and candidate passage jointly to predict relevance.The joint representation depends on the query.

Nogueira and Cho use BERT to rescore retrieved passages, feeding query and passage as its two input segments. This requires scoring each candidate pair, although pairs can be batched. “K candidates” means K pair evaluations, not necessarily K separate accelerator launches. Their study supports a retrieve-then-rerank architecture, not a fixed top-50 rule or universal superiority over every bi-encoder. Passage Re-ranking with BERT, §2

ColBERT preserves token-level interaction while separating encoding. Its MaxSim operation differs from both a single pooled dot product and joint cross-attention. Retaining many token vectors introduces storage considerations absent from a one-vector representation; actual storage depends on dimensions, precision, compression, and indexing. ColBERT, §3; Sentence Transformers’ multi-vector explanation.

Liu and colleagues found position-sensitive performance in their multi-document QA and key-value retrieval experiments, often favoring evidence near the beginning or end over the middle. These results motivate position tests. They do not prove that placing the two highest-ranked chunks at opposite ends improves every model or task. Lost in the Middle

For the teaching design, use a context budget B=W−I−Q−O−H, where W is the chosen total token allowance, I instructions, Q query, O reserved output, and H formatting overhead. Assume W=4096, I=600, Q=96, O=800, and H=100; B=2500 tokens. These are invented values, not a model specification. Select evidence within that budget, preserve source boundaries, and measure actual tokenization in a real deployment.

A useful context experiment holds candidates fixed while changing order, truncation, and redundant chunks. Separately vary candidate depth to test retrieval. This avoids crediting an ordering change for a retrieval change. Record which supporting spans survive assembly: a relevant document ID does not help when the answer-bearing passage was truncated before generation.

Retrieval metrics and limits of model-based evaluation

The original RAGAS paper separates faithfulness, answer relevance, and context relevance. Faithfulness estimates the fraction of extracted answer statements supported by supplied context. Answer relevance generates questions from an answer and compares their embeddings with the user’s question. Context relevance estimates how much context is useful. These are different proxies, and the paper explicitly acknowledges dependence on the evaluator LLM. RAGAS, §§3 and 8

The current Ragas documentation also describes context precision and recall variants. Context precision rewards relevant chunks appearing early; it is not merely an unordered signal-to-noise ratio. LLM-based context recall compares reference-answer claims with retrieved context and therefore needs a reference. Do not label every Ragas metric reference-free, or mix the original paper’s triad with later API names. Context Precision; Context Recall.

The lab uses nDCG@K with gain 2rel−1 and discount log₂(i+1): DCG@K=Σi=1…K(2relᵢ−1)/log₂(i+1), followed by division by the best attainable DCG for the same query and judgment universe. This combines graded relevance and rank sensitivity. The gain convention and cutoff must be stated. Burges, §3

A synthetic counterexample clarifies the distinction between faithfulness and truth. Suppose an invented passage incorrectly states “AX-17 supports mode Z,” and the answer repeats it accurately. A perfect context-support judge would accept the entailment while leaving the real-world claim wrong. A citation and a high faithfulness score can therefore coexist with misinformation. Conversely, an externally correct answer may lack support in the supplied context.

Use separate review questions: Did permitted retrieval find the evidence? Did assembly retain it? Did the answer accurately represent it? Is the underlying source suitable and current? For the proposed evaluation design, inspect disagreement cases manually, retain evaluator prompts and versions, and include abstentions and unanswerable queries. Automated scores help locate failures; they do not certify factual correctness or replace source assessment.

ReAct and versioned MCP boundaries

ReAct interleaves reasoning, actions, and observations so later decisions can incorporate environmental feedback. Its original demonstrations include task-specific actions, rather than a requirement for JSON Schema or MCP. The relevant architectural idea is an iterative interaction loop; published benchmark gains should not be generalized into guaranteed self-correction. Yao et al., §2

This guide pins MCP explanations to specification revision 2025-06-18, not an unspecified latest version. Its architecture assigns the host responsibility for client management, security policy, consent, and authorization decisions. Clients maintain server connections and negotiate capabilities. A server advertising a capability says what it supports; that declaration does not itself authorize a particular user’s operation. MCP Architecture

MCP 2025-06-18 server primitives and intended interaction patterns
PrimitiveIntended controlMeaning
ToolsModel-controlledNamed operations with input schemas.
ResourcesApplication-drivenURI-addressed context exposed by a server.
PromptsUser-controlledDiscoverable templates intended for explicit selection.

These are intended interaction patterns, not mandatory UI implementations. The tool specification separately requires input validation and access controls, and recommends human oversight and confirmation for sensitive operations. Schema conformity says that arguments have an acceptable form; it does not establish identity, permission, or a safe consequence. Tools, Resources, Prompts.

The model can finish or propose a call. Calls go through argument validation, then authorization and budget checks, before execution. Invalid arguments or denied and exhausted requests stop. Tool results return as untrusted observations for another bounded iteration.

Download editable tool-loop diagram

Diagram reading. The call arrow carries a proposed tool name and arguments. The valid arrow carries checked arguments; the allowed arrow additionally requires host permission and remaining budget. Execution returns an observation, which can inform another proposal but cannot rewrite policy. Invalid calls and denied or exhausted requests reach the failure endpoint. The finish branch produces an answer without another tool call. These are control-flow arrows in an original host design, not MCP message-order requirements.

Use trusted host identity rather than an identity field supplied by the model. The design consumes an attempt budget even for rejected calls and does not retry failures indefinitely. Real execution also needs deadlines and service-side permission enforcement. The local lab demonstrates only the distinction among parsing, shape checks, permission, and budget; it is not a sandbox or a complete security boundary.

Synthetic lab: RRF, nDCG, and tool-call gates

Illustrative Python, synthetic inputs. The complete lab.py uses only the standard library and in-memory data. It makes no shell, file, network, or model calls. The rankings below stand in for retriever outputs; neither ranking was measured from a real index. All documents in this fixture are assumed permitted for the example reader.

Invented rankings and graded judgments for one query
DocumentDense rankLexical rankGradeRRF, c=60
A2230.032258
B4120.032018
C1420.032018
D3Absent00.015873
EAbsent310.015873

A receives 1/62+1/62. B and C each receive 1/61+1/64, while D and E receive 1/63. The lab breaks score ties alphabetically, so the fused order is A, B, C, D, E. This tie rule differs from relying on dictionary insertion order and makes the intended result explicit. For these invented judgments, fused nDCG@3 is 1.0000; dense nDCG@3 is approximately 0.7136. These are arithmetic consequences, not evidence that fusion usually wins.

Python example
from fractions import Fraction


def rrf(rankings, constant=60):
    if type(constant) is not int or constant < 0:
        raise ValueError('constant must be a nonnegative integer')
    scores = {}
    for ranking in rankings:
        if len(ranking) != len(set(ranking)):
            raise ValueError('duplicate ID within a ranking')
        for position, doc_id in enumerate(ranking, 1):
            contribution = Fraction(1, constant + position)
            scores[doc_id] = scores.get(doc_id, Fraction(0)) + contribution
    return sorted(scores.items(), key=lambda item: (-item[1], item[0]))


dense = ['C', 'A', 'D', 'B']
lexical = ['B', 'A', 'E', 'C']
fused = rrf([dense, lexical])

The full lab computes ideal DCG from the complete supplied judgment mapping, not merely the grades of returned documents. With only D retrieved, sorting that returned subset would hide all missing relevant documents. Unknown IDs are rejected rather than silently labeled irrelevant. In real evaluation, incomplete judgments need a documented policy; this fixture assumes complete grades for its five-document universe.

The imported five-grade example [2,3,0,1,2] has nDCG@5≈0.8322 under the stated gain and discount. That number is retained as a separate arithmetic check. It is not the fused ranking’s nDCG. The lab also defines zero ideal gain as score zero, rejects duplicate returned IDs, and uses exact rational RRF accumulation to make symmetrical ties stable.

The second exercise accepts one invented tool, query_knowledge_base, with a nonempty query and integer top_k between 1 and 20. Its validator rejects JSON arrays, duplicate keys, extra fields, booleans masquerading as integers, and out-of-range counts. This is a hand-written validator for one narrow schema, not a general JSON Schema implementation. A structurally valid request from guest still fails permission; reader with no attempts left also fails. Successful execution only returns synthetic IDs from a local list.

Explore three changes independently: lower the fusion constant; remove A from both input rankings; deny the reader’s permission. Predict whether each changes ranking, attainable retrieval quality, or execution eligibility before inspecting the code. Avoid changing the relevance grades to make a preferred ranking look better. The included assertions capture expected mechanics, not production performance.

Explanatory questions

Q1 · FusionWhy use RRF instead of adding BM25 and dense scores directly?

RRF combines positions without requiring raw score comparability. It loses score margins and still needs choices about candidate depth and its constant. Sixty was a pilot choice in the original paper, not a universal best value. In the lab, A benefits from appearing second in both lists. RRF paper

Q2 · HNSW layersHow does the hierarchy accelerate approximate neighbor search?

Sparse upper layers guide the search toward a useful region, and lower layers refine it. The base includes all elements. This avoids an obligatory exhaustive scan but does not guarantee logarithmic worst-case behavior for every dataset. Approximation quality must be measured. HNSW, §4

Q3 · RerankingWhy apply a cross-encoder to a shortlist?

Joint query–passage encoding depends on the specific pair. A shortlist limits that work; batching changes execution efficiency without eliminating the need to score the pairs. Fifty is a possible configuration, not an architectural requirement. BERT reranking, §2

Q4 · ContextWhat does Lost in the Middle imply for context ordering?

The reported models often used beginning or ending evidence more effectively than middle evidence. Test positions and distractors on the actual task; the result does not establish one universally optimal ordering or guarantee that a large window will be used well. Liu et al.

Q5 · FaithfulnessWhat does a high faithfulness score establish?

It estimates support for answer statements in the provided context, subject to evaluator errors. It does not establish that the context itself is correct. The invented AX-17 example separates entailment from truth. Source quality and reference coverage require additional assessment. RAGAS, §§3 and 8

Q6 · ReActWhat changes when reasoning and acting are interleaved?

Observations can inform subsequent decisions instead of all decisions being fixed before interaction. The host still needs bounded attempts, permissions, and error handling. Neither the ReAct pattern nor a reasoning trace guarantees correct action selection. ReAct, §2

Q7 · MCPWho controls tools, resources, and prompts?

The pinned specification describes tools as model-controlled, resources as application-driven, and prompts as user-controlled, while allowing implementation flexibility. Host policy and server access controls remain separate from those interaction labels. A model-selected call is not automatically an authorized call. Architecture; Tools; Resources; Prompts.

Q8 · Search effortWhat changes when efSearch increases?

The retained search list grows, generally trading more query work for better approximate-neighbor recall. It changes neither embedding dimensionality nor lexical scoring. Measure recall against exact neighbors and measure relevance separately; improved ANN recall alone does not prove improved answers. hnswlib parameters

References

References and source links

  1. Lewis et al. (2020; arXiv v4, 2021). Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks.
    https://arxiv.org/html/2005.11401v4
  2. Malkov and Yashunin (2018; v4). Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs.
    https://arxiv.org/pdf/1603.09320
  3. hnswlib maintainers (undated; master). HNSW Algorithm Parameters.
    https://raw.githubusercontent.com/nmslib/hnswlib/master/ALGO_PARAMS.md
  4. Robertson and Zaragoza (2009). The Probabilistic Relevance Framework: BM25 and Beyond.
    https://www.staff.city.ac.uk/~sbrp622/papers/foundations_bm25_review.pdf
  5. Cormack, Clarke, and Buettcher (2009). Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods.
    https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf
  6. Nogueira and Cho (2019; v3). Passage Re-ranking with BERT.
    https://arxiv.org/html/1901.04085v3
  7. Khattab and Zaharia (2020; v2). ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction over BERT.
    https://arxiv.org/html/2004.12832v2
  8. Hugging Face / Sentence Transformers (2026). Multi-Vector (Late Interaction) Embedding Models with Sentence Transformers.
    https://huggingface.co/blog/multi-vector-encoder
  9. Liu et al. (2023; v3). Lost in the Middle: How Language Models Use Long Contexts.
    https://arxiv.org/html/2307.03172v3
  10. Es et al. (2024). RAGAS: Automated Evaluation of Retrieval Augmented Generation. EACL System Demonstrations.
    https://aclanthology.org/2024.eacl-demo.16.pdf
  11. Ragas maintainers (undated; stable documentation). Context Precision.
    https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/context_precision/
  12. Ragas maintainers (undated; stable documentation). Context Recall.
    https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/context_recall/
  13. Burges (2010; MSR-TR-2010-82). From RankNet to LambdaRank to LambdaMART: An Overview.
    https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/MSR-TR-2010-82.pdf
  14. Yao et al. (2023; v3). ReAct: Synergizing Reasoning and Acting in Language Models.
    https://arxiv.org/html/2210.03629v3
  15. MCP maintainers (revision 2025-06-18). Architecture.
    https://modelcontextprotocol.io/specification/2025-06-18/architecture
  16. MCP maintainers (revision 2025-06-18). Tools.
    https://modelcontextprotocol.io/specification/2025-06-18/server/tools
  17. MCP maintainers (revision 2025-06-18). Resources.
    https://modelcontextprotocol.io/specification/2025-06-18/server/resources
  18. MCP maintainers (revision 2025-06-18). Prompts.
    https://modelcontextprotocol.io/specification/2025-06-18/server/prompts

Source-check scope and limitations

The evidence method separates original papers, maintainer documentation, synthetic calculations, and proposed design choices. Source passages support particular claims rather than a blanket validation badge. Model-based evaluation is not independent expert verification.

Evidence versions and reading scope

Sources were accessed on 16 November 2026. Relevant full-text sections were read for equations, HNSW mechanics, fusion, reranking, context effects, evaluation, and protocol boundaries. MCP claims refer specifically to revision 2025-06-18. The hnswlib master and Ragas stable pages are mutable documentation, not pinned package releases. No library benchmark or installed-version compatibility is asserted.

The public saved Sentence Transformers original was read as document 4c879f7e590d798f7ba989555e6ce9ca, revision 77d567d00a3ce8e7620b4ad9ba01738a, and its live public page was opened. It supports the representation and storage discussion, not the synthetic results. The remaining cited evidence uses the linked public originals without saved-document identifiers.

The diagrams describe an original design. The Python is illustrative and its inputs are synthetic. Numerical values are derived from the stated formulas; they are not measured retrieval or generation results. The claim ledger records evidence locations and distinguishes these calculations from source-reported findings.