rag-playbook

name

rag-playbook

description

Use when building or debugging RAG / semantic search / retrieval systems — before choosing a vector store (pgvector, Qdrant, Milvus, Elasticsearch), designing chunking, embedding models, hybrid search (BM25 + vector), HNSW indexing, or a reranker; or when facing bad recall, "retrieved the wrong docs", LLM answers wrong despite good docs, stale index, post-filter emptying top-k, metadata filtering, or planning a semantic similarity / retrieval evaluation with recall@k / MRR / nDCG.

🌐 繁體中文（canonical） · English mirror

RAG and Semantic Search Judgment Handbook

Currency: criteria reflect the early-2026 ecosystem. Anywhere a specific model/product name appears is marked "verified 2026-07, re-verify before selecting" — leaderboards and pricing move fast; don't treat a two-year-old ranking as current.

Core Principles

1. Retrieval quality is the ceiling on generation quality: the LLM can only answer from the context you feed it. When the answer is wrong, first measure retrieval (is the correct answer even in the retrieved docs?) — don't first tune the prompt or swap in a bigger model; that's fixing the wrong layer.
2. Tuning without an eval set is superstition: changing chunk size, swapping embeddings, adding rerank — each can make some queries better and others worse. Without a golden set to run recall@k, you're just gambling. The eval set comes before all optimization.
3. Hybrid (BM25 + vector) is the default, not an advanced option: pure vector loses to keyword matching on proper nouns, model numbers, IDs, and codes. Unless you've already verified pure vector is enough, start from hybrid.
4. First ask "do you even need RAG": if the documents fit in the context window → hand the full text straight to the LLM; if what you need to change is behavior/tone rather than facts → fine-tune; only "large body of facts, needs citation, gets updated" is RAG's turf. Don't use RAG for RAG's sake.
5. Query side and index side must use the same embedding model: swapping models = re-embed everything. Computing similarity across two different models' vectors produces meaningless numbers, and it won't raise an error — the hardest silent failure to catch.

Where to Start

Situation	Which path	Read first
Just starting, not yet sure whether to use RAG	Run the "do you need RAG" triage first, then discuss the pipeline	references/architecture-design.md §1
Designing the whole pipeline / assigning each stage's responsibility	First draw ingest→chunk→embed→index→retrieve→rerank→generate, marking clearly what symptom each stage's error disguises itself as	references/architecture-design.md
Choosing vector store / embedding model / index / reranker	Use the decision tables; never introduce new infrastructure just because it "sounds professional"	references/tech-selection.md
Retrieval is inaccurate (finds nothing, finds wrong, bad ranking)	First locate whether it's chunk / language mismatch / should-be-hybrid, then act	references/retrieval-quality.md
Building an eval set / deciding whether a change can ship	golden set + recall@k baseline, run once before and once after the change	references/retrieval-quality.md §Evaluation
Fine in demo, blows up only in production	Run the release checklist line by line (latency p99, cost, injection, privilege escalation)	references/release-checklist.md

Red Lines (Absolutely Forbidden)

• Never claim "retrieval got better" without a golden set: any optimization without a before/after recall@k comparison is a gut feeling, and gut feelings lie — one query improving is often accompanied by a batch of others regressing.
• Never apply metadata as a post-filter (filtering after retrieval): taking top-k first and then filtering by tenant/date will empty out the top-k (retrieve 10, filter out 9, 1 left). The filter condition must go into the vector retrieval as a pre-filter.
• Never splice retrieved docs directly into the prompt as trusted input: document content may contain injections like "ignore previous instructions." Retrieved content is untrusted input — isolate it with markers and never execute instructions inside it.
• Never upgrade the embedding model without re-embedding the old data: new and old vectors live in different spaces, similarity breaks and raises no error. Swapping models = schedule a full re-embed plan; if there's no plan, don't swap.
• Never let the filter drop the tenant condition: in multi-tenant, a dropped filter = one tenant retrieving another tenant's data — that's a data-leak incident, not a bug.
• Never force pure vector to carry exact-match needs (model numbers, SKUs, error codes): this is BM25's home turf; pure vector treats "ERR-4021" and "ERR-4012" as near-synonyms.

Failure Signals (Turn Back, Don't Retry)

Symptom	Usually is	Fall back to
Keep tuning the prompt, keep swapping in a bigger LLM, answer still wrong	Retrieval never fetched the correct doc; you're fixing the wrong layer	Measure recall@k first, go back to the retrieval layer
Change chunk size, one batch of queries improves and another regresses	No eval set, you're gambling on feel	Build the golden set first, then tune
After adding a metadata filter, often "no results"	Post-filter emptied the top-k	Switch to pre-filter
Proper nouns/model numbers not found but semantically similar ones are	Pure vector's innate weakness	Add BM25, go hybrid
After swapping the embedding model everything got worse with no pattern	Old data not re-embedded, two vector sets mixed	Re-embed everything
Adding rerank blew up latency but accuracy barely rose	Top-k recall was bad to begin with; ranking can't save it	Fix recall first (chunk/hybrid); rerank is ordering, not recall

References Index

• references/architecture-design.md — the "do you need RAG" triage, each pipeline stage's responsibility and the "which error disguises as which symptom" map, index freshness, pre-filter, multi-tenancy, embedding version consistency. Read before designing.
• references/tech-selection.md — decision tables and criteria for vector store / embedding / similarity metric / ANN index / reranker. Read before selecting.
• references/retrieval-quality.md — chunking, hybrid + RRF, query-side techniques, evaluation methods (golden set, recall@k, MRR/nDCG), failure-mode troubleshooting table. Read before tuning retrieval.
• references/release-checklist.md — eval baseline, latency budget, cost, injection, PII, privilege escalation, zero-downtime rebuild, semantic-cache pitfalls. Tick off line by line before going live.
• references/test-scenarios.md — the criteria test set, to verify a handoff model actually follows this. Do not let the model under test read it.