jpmschweitzerandClaude Opus 4.5
f095de1162
Documents two-stage RRF, configuration options, and notes potential vector search noise improvements for future reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
# HybridRAG Architecture
|
|
|
|
## Overview
|
|
|
|
HybridRAG combines three search sources to provide comprehensive results:
|
|
- **Vector search** (Qdrant) - Semantic similarity via embeddings
|
|
- **Graph search** (Neo4j) - Entity relationships in knowledge graph
|
|
- **Web search** (SearXNG) - External web results via Trafilatura extraction
|
|
|
|
## Two-Stage RRF Fusion (v1.3.0+)
|
|
|
|
To ensure fair ranking between wiki and web results, we use a two-stage Reciprocal Rank Fusion:
|
|
|
|
```
|
|
Stage 1: Wiki Merge
|
|
vector results ─┬─→ Mini-RRF ─→ Unified wiki ranking
|
|
graph results ─┘
|
|
|
|
Stage 2: Final RRF
|
|
wiki (merged) ─┬─→ Final RRF ─→ Combined results
|
|
web results ─┘
|
|
```
|
|
|
|
**Why two stages?**
|
|
|
|
Previously, wiki pages found by BOTH vector and graph received double RRF contribution, giving them an unfair 2x advantage over web results. The two-stage approach:
|
|
1. Merges vector+graph into a single "wiki" source
|
|
2. Wiki's internal ranking still benefits from multi-source confirmation
|
|
3. Wiki and web compete as equals in final ranking
|
|
|
|
## Configuration
|
|
|
|
| Setting | Default | Description |
|
|
|---------|---------|-------------|
|
|
| `VECTOR_SIMILARITY_THRESHOLD` | 0.7 | Minimum similarity score for vector results |
|
|
| `HYBRID_RAG_VECTOR_LIMIT` | 10 | Max vector results |
|
|
| `HYBRID_RAG_GRAPH_LIMIT` | 10 | Max graph results |
|
|
| `HYBRID_RAG_WEB_LIMIT` | 5 | Max web results |
|
|
|
|
## Known Limitations & Future Improvements
|
|
|
|
### Vector Search Noise
|
|
|
|
**Status:** Open for improvement if needed after observation period.
|
|
|
|
Vector search may return generic category/index pages (e.g., "Reference", "Projects", "Places") with high similarity scores (~0.86). These pages often have similar boilerplate content leading to uniform scores.
|
|
|
|
**Potential solutions if this becomes problematic:**
|
|
1. **Raise threshold** - Increase `VECTOR_SIMILARITY_THRESHOLD` to 0.85+
|
|
2. **Page-type filtering** - Exclude pages tagged as category/index/stub
|
|
3. **Content length signal** - Penalize pages with minimal content
|
|
4. **Duplicate score detection** - Flag results with suspiciously identical scores
|
|
|
|
The LLM re-ranking phase typically demotes these low-quality results, so this may not require immediate action.
|
|
|
|
### Graph Search
|
|
|
|
Graph search uses only core keywords (no LLM-generated synonyms) to avoid false matches like "author" → "author2000". This is intentional - vector search handles semantic similarity via embeddings.
|