How to Intermediate · 3 min read

How to use hybrid search in LlamaIndex

Q: How to use hybrid search in LlamaIndex

Use LlamaIndex's HybridSearch by combining vector embeddings and keyword search indexes. Initialize both vector and keyword indices, then create a HybridSearch instance to query both simultaneously for more accurate results.

Quick answer

Use LlamaIndex's HybridSearch by combining vector embeddings and keyword search indexes. Initialize both vector and keyword indices, then create a HybridSearch instance to query both simultaneously for more accurate results.

PREREQUISITES

Python 3.8+
pip install llama-index>=0.6.0
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install llama-index and openai Python packages, and set your OpenAI API key as an environment variable.

bash

pip install llama-index openai

Step by step

This example shows how to create a vector index and a keyword index, then combine them with HybridSearch to perform hybrid search queries.

python

import os
from llama_index import (
    SimpleDirectoryReader,
    GPTVectorStoreIndex,
    KeywordTableIndex,
    HybridSearch
)

# Load documents from a directory
documents = SimpleDirectoryReader('data').load_data()

# Create a vector index
vector_index = GPTVectorStoreIndex.from_documents(documents)

# Create a keyword index
keyword_index = KeywordTableIndex.from_documents(documents)

# Create a hybrid search instance combining both indexes
hybrid_search = HybridSearch(vector_index=vector_index, keyword_index=keyword_index)

# Query the hybrid search
query = "Explain hybrid search in LlamaIndex"
response = hybrid_search.query(query)
print(response.response)

output

Hybrid search results combining vector similarity and keyword matches.

Common variations

Use different embedding models by passing embed_model to GPTVectorStoreIndex.
Use asynchronous calls if supported by your environment.
Adjust keyword index parameters for more precise keyword matching.

Troubleshooting

If queries return no results, verify documents are loaded correctly.
Ensure your OpenAI API key is set in os.environ["OPENAI_API_KEY"].
Check that llama-index version supports HybridSearch.

✅

Key Takeaways

Hybrid search in LlamaIndex combines vector and keyword indexes for improved retrieval accuracy.
Initialize both GPTVectorStoreIndex and KeywordTableIndex before combining with HybridSearch.
Always set your OpenAI API key in environment variables to authenticate embedding generation.
Adjust embedding models and keyword index parameters to optimize search results for your data.
Verify document loading and package versions if hybrid search queries fail or return empty results.

Verified 2026-04 · gpt-4o, llama-3.2

Verify ↗