wshobson/hybrid-search-implementation

Hybrid Search Implementation

Patterns for combining vector similarity and keyword-based search.

When to Use This Skill

• Building RAG systems with improved recall
• Combining semantic understanding with exact matching
• Handling queries with specific terms (names, codes)
• Improving search for domain-specific vocabulary
• When pure vector search misses keyword matches

Core Concepts

1. Hybrid Search Architecture

Query → ┬─► Vector Search ──► Candidates ─┐
        │                                  │
        └─► Keyword Search ─► Candidates ─┴─► Fusion ─► Results

2. Fusion Methods

| Method | Description | Best For | | ----------------- | ------------------------ | --------------- | | RRF | Reciprocal Rank Fusion | General purpose | | Linear | Weighted sum of scores | Tunable balance | | Cross-encoder | Rerank with neural model | Highest quality | | Cascade | Filter then rerank | Efficiency |

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

• Tune weights empirically - Test on your data
• Use RRF for simplicity - Works well without tuning
• Add reranking - Significant quality improvement
• Log both scores - Helps with debugging
• A/B test - Measure real user impact

Don'ts

• Don't assume one size fits all - Different queries need different weights
• Don't skip keyword search - Handles exact matches better
• Don't over-fetch - Balance recall vs latency
• Don't ignore edge cases - Empty results, single word queries