Retriever Methods

Short guide with pictures

What is a retriever?
It picks a few small text pieces (chunks) for a question.
The AI only reads those — not every file you have.

Practice texts A–F (every example uses these)
Six chunks: A–F. Main question: "cats sleep". Code question: "SKU-991".
Numbers beside each chunk stand for meaning. Last column = close score (1.0 = best match).

ID	Chunk text	Number list (vector)	How close to the question?
A	cats sleep about 18 hours every day	[0.95, 0.30, 0.00]	0.954
B	felines rest for most of the day and night	[0.93, 0.32, 0.00]	0.946
C	cats hunt small prey during darkness	[0.65, 0.05, 0.75]	0.654
D	dogs enjoy walks in the park	[0.02, 0.02, 1.00]	0.020
E	warranty code SKU-991 covers this unit	[0.12, 0.15, 0.20]	0.433
F	error 404 means the page was not found	[0.10, 0.12, 0.18]	0.420

Basics — What retrievers do, two search types, close scores
Part 4 — vector_similarity
Part 5 — mmr
Part 6 — similarity_threshold
Part 7 — bm25
Part 8 — hybrid
Part 9 — parent_child
Part 10 — All methods compared
Part 11 — Chooser + word list

Basics — Start here

Documents become chunks. Each chunk gets a number list for meaning. A retriever picks the best chunks for a question. The AI never sees your whole library.

Retriever = librarian for the AI.

Six methods exist because "best" can mean: same meaning, exact words, different facts, only strong matches, or small hit + big section.

Meaning search (left) vs word search (right).

Meaning search: vector_similarity, mmr, similarity_threshold, parent_child, half of hybrid.
Word search: bm25 and the other half of hybrid.
Start with vector_similarity. Use bm25 or hybrid for codes and IDs.

Meaning search uses a close score (cosine similarity once: do question and chunk "point" the same way?). Near 1.0 = related. Near 0 = not. After this, we just say close score.

Same direction = high close score.

Scores
Do not compare numbers across methods. Trust the order of the list.

Part 4 — vector_similarity

Pick the k chunks closest in meaning to the question.

Question → numbers → top k chunks.

Setting	Default	What it does
k	4	How many chunks to send to the AI.

Question: "cats sleep"

k = 3 → ['A', 'B', 'C']

A first, then near copy B, then C.

#1	A	0.9536	cats sleep about 18 hours every day
#2	B	0.9456	felines rest for most of the day and night
#3	C	0.6541	cats hunt small prey during darkness

Bigger k adds more chunks at the end.

Use for: normal questions, first method to try.
Try mmr if top hits repeat; bm25/hybrid for exact codes.

Part 5 — mmr

Like vector_similarity, but skip near copies — pick chunks that add new facts.

Want variety, not three same ideas.

Setting	Default	What it does
k	4	How many chunks to return.
lambda_mult	0.5	1 = best match only; 0 = most different only.

Question: "cats sleep"

k=3, lambda_mult=0.5 → ['A', 'C', 'B']

After A, it picks C instead of near copy B.

#1	A	0.9536	cats sleep about 18 hours every day
#2	C	0.6541	cats hunt small prey during darkness
#3	B	0.9456	felines rest for most of the day and night

Higher lambda_mult keeps B; lower drops it.

Note
Scores shown are close scores, not MMR pick scores. Trust list order.

Use when top hits look the same.

Part 6 — similarity_threshold

Only keep chunks above a minimum close score. Can return fewer than k or none.

Below the line = dropped.

Setting	Default	What it does
score_threshold	0.5	Minimum close score to keep a chunk.
k	None	Optional cap after filtering (None = no cap).

Question: "cats sleep"

score_threshold = 0.5 → 3 hit(s): ['A', 'B', 'C']

#1	A	0.9536	cats sleep about 18 hours every day
#2	B	0.9456	felines rest for most of the day and night
#3	C	0.6541	cats hunt small prey during darkness

Higher bar = fewer hits.

Empty is OK
No strong match is better than a weak guess. Tell the user clearly.

Use when wrong answers are costly.

Part 7 — bm25 (word search)

Like smart Ctrl+F — matches words in the question and chunk. No meaning numbers needed.

Word search vs meaning search.

Setting	Default	What it does
k	4	How many chunks to return.

Question: "cats sleep"

bm25 k=3 → ['A', 'C', 'E']

Finds "cats" and "sleep". Near copy B uses "felines" / "rest" — word search may miss it.

#1	A	—	cats sleep about 18 hours every day
#2	C	—	cats hunt small prey during darkness
#3	E	—	warranty code SKU-991 covers this unit

Code question "SKU-991": bm25 finds E; meaning search may not.

Warning
Capital letters matter: "cats" ≠ "Cats". Use the same case in questions and text. For reworded questions, use meaning search or hybrid.

Use for SKUs, error codes, names.

Part 8 — hybrid

Runs word search and meaning search, then merges the two lists.

Merge ranks, not scores.

Setting	Default	What it does
k	4	Final number of chunks.
fetch_k	2×k	How many each search brings before merge.

Question: "cats sleep"

hybrid k=3 → ['A', 'C', 'E']

Scores may look tiny (~0.03). That is normal — trust order.

#1	A	0.0328	cats sleep about 18 hours every day
#2	C	0.0320	cats hunt small prey during darkness
#3	E	0.0315	warranty code SKU-991 covers this unit

On "SKU-991", hybrid can save the code hit.

Note
Small hybrid scores can still be good hits.

Use for normal text plus codes/IDs.

Part 9 — parent_child

Search small child chunks; return the bigger parent section for the AI.

Hit small piece → get full section.

Setting	Default	What it does
k	4	Max parent sections to return.
child_k	2×k	How many small hits to find first.

Question: "cats sleep"

k=2, child_k=3 → 2 parent(s)

#1	c1	0.9536	cats sleep about 18 hours every day. felines rest for most of the day and night. this long sleep cycle is normal for domestic cats.
#2	c3	0.6541	cats hunt small prey during darkness. they use stealth and patience. night vision helps them track movement.

Two children can become one parent.

Warning
Needs parent_id / parent_content on chunks (from hierarchical chunking). Without that, you just get children.

Use for long docs where a small hit needs surrounding context.

Part 10 — All methods compared

Same practice texts A–F, question "cats sleep".

Same question — different order.

Method	Order	Short note
vector_similarity k=3	A → B → C	Best meaning matches; B near copy of A.
mmr k=3 λ=0.5	A → C → B	Skips B for more different C.
similarity_threshold 0.5	A → B → C	Only above score bar.
bm25 k=3	A → C → E	Word match on cats/sleep.
hybrid k=3	A → C → E	Mix of both.

Part 11 — Chooser + word list

Pick a method.

Quick picks

Situation	Method	Start settings
Normal questions	vector_similarity	k = 4
Same idea repeated	mmr	k = 4, lambda_mult = 0.5
Empty beats wrong	similarity_threshold	score_threshold = 0.6
Codes / IDs	bm25	k = 4
Text + codes	hybrid	k = 4, fetch_k = 8
Hierarchical chunks	parent_child	k = 3, child_k = 6

App settings (retriever_options)

retriever	Example
vector_similarity	{"k": 4}
mmr	{"k": 4, "fetch_k": 20, "lambda_mult": 0.5}
similarity_threshold	{"score_threshold": 0.5, "k": 4}
bm25	{"k": 4}
hybrid	{"k": 4, "fetch_k": 8, "rrf_k": 60}
parent_child	{"k": 3, "child_k": 6}

Word list

Word	Means
Retriever	Picks chunks for the AI to read.
Chunk	Small piece of a document.
Vector	Numbers that stand for meaning.
k	How many results.
Close score	How well question and chunk match (meaning search).
MMR	Avoid near copies; pick different facts.
lambda_mult	MMR: 1 = best match, 0 = most different.
fetch_k	Candidates to look at before final pick.
score_threshold	Lowest close score to keep a chunk.
BM25	Word search.
Hybrid	Meaning + word search combined.
RRF	Merges two ranked lists.
Parent / child	Big section built from small searchable pieces.

One line
vector_similarity: same meaning? bm25: same words? hybrid: both — trust order, not score size.

Contents

Basics — Start here

Part 4 — vector_similarity

Part 5 — mmr

Part 6 — similarity_threshold

Part 7 — bm25 (word search)

Part 8 — hybrid

Part 9 — parent_child

Part 10 — All methods compared

Part 11 — Chooser + word list

Quick picks

App settings (retriever_options)

Word list