hybrid-retrieval
Implement hybrid search combining vector and keyword retrieval for RAG systems. Use this skill when building RAG retrieval, combining semantic search with BM25, implementing reciprocal rank fusion (RRF), or optimizing retrieval accuracy. Activate when: vector search, keyword search, BM25, semantic search, hybrid RAG, retrieval optimization, search relevance, reranking.
How do I install this agent skill?
npx skills add https://github.com/latestaiagents/agent-skills --skill hybrid-retrievalIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard patterns and code implementations for hybrid retrieval in RAG systems. It correctly follows security best practices by using environment variables for API keys and referencing official, well-known libraries and services.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
Hybrid Retrieval for RAG
Combine vector similarity with keyword matching so exact terms and paraphrases both get found.
When to Use
- Vector search misses exact keyword matches (IDs, error codes, product names)
- Domain terminology needs exact matching
- Users mix natural-language questions with specific terms
Why Hybrid Retrieval
Vector search alone misses:
- Exact matches (product codes, IDs, names)
- Rare terms not well-represented in embeddings
- Keyword-specific queries ("error code E-5012")
Keyword search alone misses:
- Semantic similarity ("car" vs "automobile")
- Context and meaning
- Paraphrased content
A typical failure of vector-only search:
Query: "Error code E-4521 troubleshooting"
Vector search returns:
- "Common error handling patterns" (semantically similar)
- "Debugging techniques for applications" (related topic)
Missing:
- "E-4521: Database connection timeout" (needs an exact match)
Hybrid search combines both, so each covers the other's misses (exact terms vs. paraphrases). Measure recall on your own queries to confirm the gain.
Architecture
User Query
/ \
Dense search Sparse search
(embeddings) (BM25 / sparse vectors)
\ /
Fusion (RRF or weighted)
|
Reranker (optional)
|
Final results
Core Patterns
Pattern 1: Reciprocal Rank Fusion (RRF)
The standard for combining ranked results from multiple retrievers:
def reciprocal_rank_fusion(
results_lists: list[list[dict]],
k: int = 60
) -> list[dict]:
"""
Combine multiple ranked result lists using RRF.
Args:
results_lists: List of ranked results from different retrievers
k: Ranking constant. 60 is the value used in the original RRF paper
(Cormack et al., 2009); a higher k flattens the gap between ranks.
Returns:
Fused and re-ranked results
"""
fused_scores = {}
for results in results_lists:
for rank, doc in enumerate(results):
doc_id = doc["id"]
if doc_id not in fused_scores:
fused_scores[doc_id] = {"doc": doc, "score": 0}
# RRF formula: 1 / (k + rank)
fused_scores[doc_id]["score"] += 1 / (k + rank + 1)
# Sort by fused score
sorted_results = sorted(
fused_scores.values(),
key=lambda x: x["score"],
reverse=True
)
return [item["doc"] for item in sorted_results]
# Usage with LangChain retrievers (documents need a stable id in metadata)
dense = vector_retriever.invoke(query)
sparse = bm25_retriever.invoke(query)
fused = reciprocal_rank_fusion([
[{"id": d.metadata["id"], "doc": d} for d in dense],
[{"id": d.metadata["id"], "doc": d} for d in sparse],
])
RRF uses only ranks, so it needs no score normalization between BM25 and cosine similarity. That is why it is a common default.
Pattern 2: LangChain Ensemble Retriever
from langchain_classic.retrievers import EnsembleRetriever # pip install langchain-classic (LangChain 1.x)
from langchain_community.retrievers import BM25Retriever
from langchain_chroma import Chroma # pip install langchain-chroma
# Create vector retriever
vectorstore = Chroma.from_documents(documents, embeddings)
vector_retriever = vectorstore.as_retriever(search_kwargs={"k": 10})
# Create BM25 retriever
bm25_retriever = BM25Retriever.from_documents(documents)
bm25_retriever.k = 10
# Combine with weights
ensemble_retriever = EnsembleRetriever(
retrievers=[bm25_retriever, vector_retriever],
weights=[0.4, 0.6] # Tune based on your data
)
# Use in RAG chain
results = ensemble_retriever.invoke("your query here")
Pattern 3: LlamaIndex Hybrid Search
from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.core.retrievers import QueryFusionRetriever
from llama_index.retrievers.bm25 import BM25Retriever
# Build index
index = VectorStoreIndex.from_documents(documents)
# Create retrievers
vector_retriever = index.as_retriever(similarity_top_k=10)
bm25_retriever = BM25Retriever.from_defaults(
nodes=index.docstore.docs.values(),
similarity_top_k=10
)
# Fusion retriever with query expansion
retriever = QueryFusionRetriever(
retrievers=[vector_retriever, bm25_retriever],
similarity_top_k=10,
num_queries=4, # Generate 4 query variations
mode="reciprocal_rerank",
use_async=True,
)
Pattern 4: Direct Implementation with Qdrant
from qdrant_client import QdrantClient, models
client = QdrantClient(url="http://localhost:6333")
# Hybrid search with both dense and sparse vectors
results = client.query_points(
collection_name="documents",
prefetch=[
# Dense vector search
models.Prefetch(
query=dense_embedding, # [0.1, 0.2, ...]
using="dense",
limit=20
),
# Sparse vector search (BM25-style)
models.Prefetch(
query=models.SparseVector(
indices=[1, 42, 123], # Token IDs
values=[0.5, 0.8, 0.3] # Token weights
),
using="sparse",
limit=20
),
],
query=models.RrfQuery(rrf=models.Rrf()),
limit=10
)
Pattern 5: Weaviate (Native Hybrid)
Weaviate's Python client v4 (the v3 weaviate.Client is deprecated):
import weaviate
with weaviate.connect_to_local() as client:
docs = client.collections.use("Document")
response = docs.query.hybrid(
query="Error code E-4521",
alpha=0.5, # 1 = pure vector, 0 = pure keyword
limit=10,
)
for obj in response.objects:
print(obj.properties["content"])
Other Vector Stores
Many stores support hybrid search natively; prefer that over running two systems. APIs differ: for example, Pinecone's documentation describes weighting dense and sparse query vectors client-side (an alpha you apply before sending the query) or querying separate dense and sparse indexes and merging the results yourself. Check your store's current hybrid search guide.
Reranking for Better Precision
After hybrid retrieval, rerank for final ordering:
Cross-Encoder Reranking
from sentence_transformers import CrossEncoder
# Load reranker model
reranker = CrossEncoder("cross-encoder/ms-marco-MiniLM-L-6-v2")
def rerank_results(query: str, documents: list[str], top_k: int = 5):
"""Rerank documents using cross-encoder."""
# Create query-document pairs
pairs = [[query, doc] for doc in documents]
# Score all pairs
scores = reranker.predict(pairs)
# Sort by score
scored_docs = list(zip(documents, scores))
scored_docs.sort(key=lambda x: x[1], reverse=True)
return [doc for doc, score in scored_docs[:top_k]]
Cohere Rerank API
import os
import cohere
co = cohere.ClientV2() # reads CO_API_KEY from the environment
RERANK_MODEL = os.environ["RERANK_MODEL"] # pick a current model from Cohere's docs
def cohere_rerank(query: str, documents: list[str], top_k: int = 5):
"""Rerank using Cohere's rerank endpoint."""
response = co.rerank(
model=RERANK_MODEL,
query=query,
documents=documents,
top_n=top_k,
)
# Each result has the original list position and a relevance_score
return [documents[r.index] for r in response.results]
Retrieve more candidates than you need (for example 20) and let the reranker pick the final few.
Evaluating Hybrid vs Single-Path Retrieval
Run the same labeled queries through vector-only, keyword-only, and hybrid retrievers and compare:
def evaluate_retrieval(queries: list[str], ground_truth: dict, retriever, k: int = 5) -> dict:
"""ground_truth: {query: [relevant doc ids]}"""
mrr = recall = 0.0
for query in queries:
ids = [doc.metadata["id"] for doc in retriever.invoke(query)[:k]]
relevant = set(ground_truth[query])
mrr += next((1 / (i + 1) for i, d in enumerate(ids) if d in relevant), 0)
recall += len(set(ids) & relevant) / len(relevant)
n = len(queries)
return {"mrr": mrr / n, f"recall@{k}": recall / n}
See rag-evaluation for precision@k, NDCG, and generation metrics.
Weight Tuning Guidelines
Starting points to tune against your evaluation set, not measured optima:
| Data Type | Vector Weight | Keyword Weight |
|---|---|---|
| Technical docs | 0.5 | 0.5 |
| Legal/compliance | 0.4 | 0.6 |
| Creative content | 0.7 | 0.3 |
| Product catalogs | 0.3 | 0.7 |
| Code repositories | 0.4 | 0.6 |
Best Practices
- Always benchmark - Test vector-only, keyword-only, and hybrid on your data
- Tune weights empirically - Start at 0.5/0.5, adjust based on evaluation
- Try reranking - A cross-encoder or rerank API over the fused candidates often improves precision; confirm on your data
- Consider query type - Route exact-match queries to keyword, semantic to vector
- Use native hybrid - When your vector store supports it, avoid running a separate keyword engine
- Monitor both paths - Log which retriever contributed each final result; a path that never contributes is wasted latency
- Monitor latency - Hybrid adds overhead; cache where possible
Quick Decision Tree
Is the query an exact match (ID, code, name)?
├─ Yes → Keyword-heavy (0.3 vector / 0.7 keyword)
└─ No → Is it conceptual/semantic?
├─ Yes → Vector-heavy (0.7 vector / 0.3 keyword)
└─ Mixed → Balanced (0.5 / 0.5) + reranking
References
- Reciprocal Rank Fusion (Cormack, Clarke, Büttcher, 2009): https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf
- LangChain
EnsembleRetrieverand BM25 (langchain-classic,langchain-community): https://docs.langchain.com/oss/python/migrate/langchain-v1 - LlamaIndex
QueryFusionRetriever: https://developers.llamaindex.ai/python/examples/retrievers/reciprocal_rerank_fusion/ - Qdrant hybrid queries: https://qdrant.tech/documentation/concepts/hybrid-queries/
- Weaviate hybrid search: https://docs.weaviate.io/weaviate/search/hybrid
- Pinecone hybrid search: https://docs.pinecone.io/guides/search/hybrid-search
- Cohere Rerank: https://docs.cohere.com/reference/rerank
- Sentence Transformers cross-encoders: https://sbert.net/docs/cross_encoder/usage/usage.html
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/latestaiagents/agent-skills/hybrid-retrieval">View hybrid-retrieval on skillZs</a>