| 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
- 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.
- 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.
- 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.
- 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.
- 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.
