skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
latestaiagents/agent-skills58 installs

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-retrieval
view source ↗

Is 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 TypeVector WeightKeyword Weight
Technical docs0.50.5
Legal/compliance0.40.6
Creative content0.70.3
Product catalogs0.30.7
Code repositories0.40.6

Best Practices

  1. Always benchmark - Test vector-only, keyword-only, and hybrid on your data
  2. Tune weights empirically - Start at 0.5/0.5, adjust based on evaluation
  3. Try reranking - A cross-encoder or rerank API over the fused candidates often improves precision; confirm on your data
  4. Consider query type - Route exact-match queries to keyword, semantic to vector
  5. Use native hybrid - When your vector store supports it, avoid running a separate keyword engine
  6. Monitor both paths - Log which retriever contributed each final result; a path that never contributes is wasted latency
  7. 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

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>