claude-dev-suite RAG Architecture
Three Architectural Tiers
| Tier | Components | Best For | Complexity |
|---|---|---|---|
| Naive RAG | Chunk + embed + top-K + stuff | Prototype, < 10k docs, homogeneous content | Low |
| Advanced RAG | + query rewriting, hybrid search, reranking, metadata filters | Production, heterogeneous content, > 10k docs | Medium |
| Agentic RAG | + self-reflection, retrieval-as-tool, multi-hop, corrective fallback | Complex research, multi-source synthesis, high-stakes answers | High |
Naive RAG Pipeline
[Docs] -> [Splitter] -> [Embedder] -> [Vector DB]
|
[Query] -> [Embedder] -> [Top-K Search] --+-> [Prompt Stuffer] -> [LLM] -> [Answer]
Single failure mode: bad retrieval = bad answer. No recovery path. Works for well-scoped FAQ bots on small corpora.
Advanced RAG Pipeline
pre-retrieval retrieval post-retrieval
[Query] -> [Router] -> [Rewrite/HyDE/Multi-Q] -> [Hybrid Search] -> [Rerank] -> [Compress] -> [LLM]
|
[BM25] + [Dense Vector] + [Metadata Filter]
Each stage is independently replaceable and measurable. See query-transformations, hybrid-search, reranking.
Agentic RAG Pipeline
[Query] -> [Planner Agent]
|
v
+-----+-----+-------------------+
| | |
[Retrieve] [Web Search] [Code Tool]
| | |
+-----+-----+-------------------+
|
[Critic / Self-reflection]
|
+-----+-----+
| |
[Answer] [Replan / More retrieval]
Dynamic step count, dynamic tool selection, self-correction. See agentic-rag.
Decision Tree: RAG vs Fine-Tuning vs Long Context
Is the knowledge dynamic (changes > monthly)?
Yes -> RAG
No -> Continue
|
Is it style/format/persona (not facts)?
Yes -> Fine-tuning (SFT or DPO)
No -> Continue
|
Does total corpus fit in 200k-1M tokens?
Yes -> Long context with prompt caching (cheaper than RAG at small scale)
No -> RAG
|
Need factual grounding with citations?
Yes -> RAG (mandatory for auditability)
No -> Hybrid: long context for recent + RAG for archive
Rules of thumb:
- Under 500 KB of content: long context with prompt caching beats RAG on latency and quality.
- Over 10 MB or changes weekly: RAG wins on cost and freshness.
- Between: measure both.
Latency Budget (Production Target: < 3s P95)
| Stage | Budget | Optimization |
|---|---|---|
| Query embedding | 50-150ms | Batch + local model for simple queries |
| Query rewriting (optional) | 300-800ms | Skip for short factual queries |
| Vector search (top-50) | 20-100ms | HNSW with ef_search tuned |
| BM25 search | 10-50ms | Parallel with vector search |
| Fusion (RRF) | < 5ms | In-memory |
| Reranking (top-50 -> top-5) | 100-400ms | Cohere/Voyage API or local BGE |
| LLM generation | 1000-2000ms | Streaming, prompt caching |
| Total | 1500-3500ms |
Parallelize embedding + BM25. Skip rewriting for short queries. Cache query embeddings for hot terms.
Production Component Diagram
+------------------+
| Ingestion API |
+--------+---------+
|
+-----------v------------+
| Chunker + Embedder |
| (batch worker, queue) |
+-----------+------------+
|
+-------------------+---------------------+
| |
+------v------+ +-------v-------+
| Vector DB | | Document Store|
| (HNSW) | | (Postgres/S3) |
+------+------+ +-------+-------+
| |
| +------------------+ |
+----> Retrieval Service <----------------+
| (hybrid + rerank)|
+--------+---------+
|
+--------v---------+
| LLM Gateway |
| (Claude/GPT) |
+--------+---------+
|
+--------v---------+
| API / UI |
+------------------+
Separate the ingestion path from the query path. Never block queries on indexing.
Minimal Python Scaffold (Advanced RAG)
from dataclasses import dataclass
from langchain_anthropic import ChatAnthropic
from langchain_openai import OpenAIEmbeddings
from langchain_qdrant import QdrantVectorStore
from langchain_community.retrievers import BM25Retriever
from langchain.retrievers import EnsembleRetriever, ContextualCompressionRetriever
from langchain_cohere import CohereRerank
@dataclass
class RAGConfig:
top_k_retrieve: int = 50
top_n_rerank: int = 5
alpha: float = 0.5 # dense weight in hybrid
rerank_model: str = "rerank-english-v3.0"
llm_model: str = "claude-sonnet-4-5-20250929"
def build_pipeline(docs, cfg: RAGConfig):
emb = OpenAIEmbeddings(model="text-embedding-3-small")
vstore = QdrantVectorStore.from_documents(docs, emb, collection_name="kb")
dense = vstore.as_retriever(search_kwargs={"k": cfg.top_k_retrieve})
sparse = BM25Retriever.from_documents(docs); sparse.k = cfg.top_k_retrieve
hybrid = EnsembleRetriever(retrievers=[sparse, dense], weights=[1 - cfg.alpha, cfg.alpha])
reranker = CohereRerank(model=cfg.rerank_model, top_n=cfg.top_n_rerank)
retriever = ContextualCompressionRetriever(base_compressor=reranker, base_retriever=hybrid)
llm = ChatAnthropic(model=cfg.llm_model, max_tokens=1024)
return retriever, llm
Scaling Patterns
| Regime | Index | Strategy |
|---|---|---|
| < 100k chunks | HNSW in-memory (FAISS, Chroma) | Single node |
| 100k-10M chunks | Managed HNSW (Qdrant, Pinecone, Weaviate) | Replicate reads |
| 10M-1B chunks | Sharded HNSW + IVF coarse filter | Partition by tenant/namespace |
| > 1B chunks | Disk-ANN / SPTAG / hierarchical | Custom; hire infra |
Namespace per tenant avoids noisy-neighbor retrieval in multi-tenant SaaS.
Anti-Patterns
| Anti-Pattern | Fix |
|---|---|
| Starting with agentic RAG | Start naive, measure, add complexity only when recall < 70% |
| Treating RAG as a solved box | Every stage needs its own eval; see rag-evaluation |
| Single index for heterogeneous content | Separate indexes per content type with a router |
| Synchronous indexing in query path | Queue ingestion; queries never block on embedding |
| No reranking above 10k docs | Reranking recovers 10-30% recall@5 vs raw vector search |
Hardcoded top_k everywhere |
Parametrize; tune with eval set |
| Storing chunks only in vector DB | Keep source of truth in document DB; vector DB holds refs |
Production Checklist
- Ingestion and query paths are separate services
- Document store is source of truth; vector DB holds IDs + embeddings only
- Latency budget allocated per stage and measured in traces
- Query router distinguishes factual, analytical, and conversational intents
- Hybrid search baseline before any advanced technique
- Reranker in place for corpora > 10k chunks
- Fallback path when retrieval returns nothing (admit ignorance, offer web search)
- Namespace isolation for multi-tenant deployments
- Graceful degradation: naive path if advanced stage fails
- Tracing across ingestion -> retrieval -> generation (LangSmith / OpenTelemetry)