Hybrid Retrieval
Product: v0.23.0 · Contract: OpenAPI · Spec ops: Ingestion cancel & fairness
Hybrid Retrieval
Section titled “Hybrid Retrieval”Hybrid retrieval combines vector similarity search with knowledge graph traversal to provide comprehensive context for LLM responses.
What is Hybrid Retrieval?
Section titled “What is Hybrid Retrieval?”Hybrid retrieval uses both approaches together:
- Vector Search: Find semantically similar content
- Graph Traversal: Follow entity relationships
┌─────────────────────────────────────────────────────────────────┐│ HYBRID RETRIEVAL │├─────────────────────────────────────────────────────────────────┤│ ││ USER QUERY ││ │ ││ ┌────────────┴────────────┐ ││ │ │ ││ v v ││ ┌─────────────────┐ ┌─────────────────┐ ││ │ VECTOR SEARCH │ │ GRAPH TRAVERSAL │ ││ │ │ │ │ ││ │ • Embeddings │ │ • Entity match │ ││ │ • Cosine sim │ │ • 1-hop neighbors│ ││ │ • Top-K chunks │ │ • Relationship │ ││ └────────┬────────┘ └────────┬────────┘ ││ │ │ ││ └────────────┬────────────┘ ││ │ ││ v ││ ┌─────────────────────────┐ ││ │ CONTEXT FUSION │ ││ │ • Deduplicate │ ││ │ • Rank by relevance │ ││ │ • Truncate to limit │ ││ └────────────┬────────────┘ ││ │ ││ v ││ ┌─────────────────────────┐ ││ │ LLM GENERATION │ ││ └─────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘Vector Search vs Graph Traversal
Section titled “Vector Search vs Graph Traversal”Each approach has strengths:
| Aspect | Vector Search | Graph Traversal |
|---|---|---|
| Best for | Semantic similarity | Entity relationships |
| Finds | Similar text chunks | Connected entities |
| Misses | Indirect connections | Semantic nuance |
| Speed | Fast (HNSW index) | Medium (path queries) |
Example:
Query: “What did Sarah Chen work on?”
- Vector search finds: Chunks mentioning “Sarah Chen”
- Graph traversal finds:
SARAH_CHEN --[researches]--> NEURAL_NETWORKS
Combined: More complete context than either alone.
Dual-Level Approach
Section titled “Dual-Level Approach”EdgeQuake implements LightRAG’s dual-level retrieval:
Low-Level Retrieval
Section titled “Low-Level Retrieval”Focuses on specific entities and their immediate neighbors:
Query: "Who is Sarah Chen?"
Low-Level Results:┌─────────────────────────────────────────────┐│ SARAH_CHEN (direct match) ││ ├── Description: "Lead researcher at..." ││ │ ││ ├── QUANTUM_LAB (1-hop neighbor) ││ │ └── via: WORKS_AT ││ │ ││ ├── NEURAL_NETWORKS (1-hop neighbor) ││ │ └── via: RESEARCHES ││ │ ││ └── BOB_SMITH (1-hop neighbor) ││ └── via: COLLABORATES_WITH │└─────────────────────────────────────────────┘High-Level Retrieval
Section titled “High-Level Retrieval”Focuses on broad topics and theme summaries:
Query: "What are the main AI research themes?"
High-Level Results:┌─────────────────────────────────────────────┐│ Topic Cluster: "AI RESEARCH" ││ ├── Key themes: ││ │ • Neural network architectures ││ │ • Deep learning optimization ││ │ • Computer vision applications ││ │ ││ └── Related entities: 45 │└─────────────────────────────────────────────┘Query Modes
Section titled “Query Modes”EdgeQuake offers 6 query modes for different use cases:
┌─────────────────────────────────────────────────────────────────┐│ QUERY MODE SPECTRUM │├─────────────────────────────────────────────────────────────────┤│ ││ Speed ────────────────────────────────────────▶ Comprehensiveness││ ││ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ││ │ Naive │ │ Local │ │ Global│ │ Hybrid│ │ Mix │ ││ │ │ │ │ │ │ │ │ │ │ ││ │ Vector│ │Entity │ │Topics │ │ Both │ │Weighted│ ││ │ only │ │+1-hop │ │only │ │ │ │ blend │ ││ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ ││ ││ FASTEST ◄─────────────────────────────────► MOST COMPLETE ││ │└─────────────────────────────────────────────────────────────────┘| Mode | Vector | Graph | Best For |
|---|---|---|---|
| Naive | ✅ | ❌ | Simple factual queries |
| Local | ✅ | ✅ Entities | “Who/What is X?” |
| Global | ❌ | ✅ Topics | “What are the themes?” |
| Hybrid | ✅ | ✅ Both | Complex multi-faceted |
| Mix | Weighted | Weighted | Custom blend (API default) |
| Bypass | ❌ | ❌ | Testing/debugging |
Context Fusion
Section titled “Context Fusion”After retrieval, results are fused into a coherent context:
┌─────────────────────────────────────────────────────────────────┐│ CONTEXT FUSION │├─────────────────────────────────────────────────────────────────┤│ ││ Step 1: COLLECT ││ ├── Chunks from vector search (10) ││ ├── Entities from graph (20) ││ └── Relationships from graph (15) ││ ││ Step 2: DEDUPLICATE ││ └── Remove overlapping content ││ ││ Step 3: RANK ││ └── Score by relevance to query ││ ││ Step 4: TRUNCATE ││ └── Fit within context window (30000 tokens default) ││ ││ Step 5: FORMAT ││ └── Structure for LLM consumption ││ │└─────────────────────────────────────────────────────────────────┘Balanced Truncation
Section titled “Balanced Truncation”EdgeQuake uses intelligent truncation to preserve diversity:
// From truncation.rs (LightRAG constants, LR_*)pub struct TruncationConfig { pub max_entity_tokens: usize, // 6000 pub max_relation_tokens: usize, // 8000 pub max_total_tokens: usize, // 30000 pub buffer_tokens: usize, // 200 pub min_chunk_budget_ratio: f32, // 0.40 (EDGEQUAKE_MIN_CHUNK_BUDGET_RATIO, clamp [0.0, 0.9])}Rather than just taking “top N” of each, it balances across categories: the chunk budget is max_total_tokens − entity_tokens − relation_tokens − buffer, with a floor that reserves at least 40% of the budget for document chunks.
Choosing a Mode
Section titled “Choosing a Mode”Decision guide:
Is this a test/debug? ───▶ Use BYPASS │ No │ vIs it about specific entities? ───▶ Use LOCAL("Who is X?", "What is Y?") │ No │ vIs it about broad themes? ───▶ Use GLOBAL("What are the main topics?") │ No │ vIs it complex/multi-faceted? ───▶ Use HYBRID("How does X relate to Y?") │ │ vNeed weighted control? ───▶ Use MIX (production default, RRF fusion)API Usage
Section titled “API Usage”# Query with specific modecurl -X POST http://localhost:8080/api/v1/query \ -H "Content-Type: application/json" \ -d '{ "query": "Who is Sarah Chen?", "mode": "local" }'
# Query with default mode (mix when mode is unset)curl -X POST http://localhost:8080/api/v1/query \ -d '{"query": "Tell me about the research"}'Learn More
Section titled “Learn More”- Foundation concept: Graph-RAG
- How entities are extracted: Entity Extraction
- Storage details: Knowledge Graph
- Deep dive: LightRAG Algorithm
Source Code
Section titled “Source Code”- Query engine:
edgequake-query/src/engine_impl/ - Query modes:
modes.rs - Context building:
context.rs