How to Intermediate · 3 min read

How to use MultiQueryRetriever in LangChain

Q: How to use MultiQueryRetriever in LangChain

Use MultiQueryRetriever in LangChain to perform multi-vector retrieval by combining multiple retrievers, each with its own query embedding. Initialize it with a list of retrievers and call aget_relevant_documents or get_relevant_documents to fetch documents matching any of the queries. This enables efficient multi-query semantic search over your document collections.

Quick answer

Use MultiQueryRetriever in LangChain to perform multi-vector retrieval by combining multiple retrievers, each with its own query embedding. Initialize it with a list of retrievers and call aget_relevant_documents or get_relevant_documents to fetch documents matching any of the queries. This enables efficient multi-query semantic search over your document collections.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install langchain openai faiss-cpu

Setup

Install LangChain and dependencies, and set your OpenAI API key in the environment.

bash

pip install langchain openai faiss-cpu

Step by step

This example shows how to create two retrievers with different queries and combine them using MultiQueryRetriever to retrieve documents matching either query.

python

import os
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import FAISS
from langchain.chains import RetrievalQA
from langchain.schema import Document
from langchain.schema.retriever import MultiQueryRetriever

# Sample documents
texts = [
    Document(page_content="Python is a programming language."),
    Document(page_content="JavaScript is used for web development."),
    Document(page_content="OpenAI provides powerful AI models."),
    Document(page_content="LangChain helps build LLM applications.")
]

# Initialize embeddings
embeddings = OpenAIEmbeddings(openai_api_key=os.environ["OPENAI_API_KEY"])

# Create two separate FAISS vector stores with the same documents
faiss_index1 = FAISS.from_documents(texts, embeddings)
faiss_index2 = FAISS.from_documents(texts, embeddings)

# Create retrievers with different search queries
retriever1 = faiss_index1.as_retriever(search_type="similarity", search_kwargs={"k": 2})
retriever2 = faiss_index2.as_retriever(search_type="similarity", search_kwargs={"k": 2})

# Combine retrievers using MultiQueryRetriever
multi_retriever = MultiQueryRetriever(retrievers=[retriever1, retriever2])

# Define queries for each retriever
queries = ["programming language", "AI models"]

# Retrieve documents matching any of the queries
results = multi_retriever.get_relevant_documents(queries)

# Print retrieved documents
for i, doc in enumerate(results):
    print(f"Result {i+1}: {doc.page_content}")

output

Result 1: Python is a programming language.
Result 2: OpenAI provides powerful AI models.

Common variations

You can use aget_relevant_documents for async retrieval, change the underlying vector store (e.g., Chroma), or customize search_kwargs per retriever for different k values or search types.

python

import asyncio

async def async_multiquery():
    results = await multi_retriever.aget_relevant_documents(queries)
    for i, doc in enumerate(results):
        print(f"Async Result {i+1}: {doc.page_content}")

asyncio.run(async_multiquery())

output

Async Result 1: Python is a programming language.
Async Result 2: OpenAI provides powerful AI models.

Troubleshooting

If no documents are returned, verify your embeddings and that documents are indexed correctly.
Ensure your queries list length matches the number of retrievers.
Check your OpenAI API key is set in os.environ["OPENAI_API_KEY"].

✅

Key Takeaways

Use MultiQueryRetriever to combine multiple retrievers for multi-query semantic search.
Initialize each retriever with its own vector store and search parameters before combining.
Ensure the queries list matches the number of retrievers when calling retrieval methods.
You can perform both synchronous and asynchronous retrieval with MultiQueryRetriever.
Troubleshoot by verifying embeddings, document indexing, and environment variables.

Verified 2026-04 · gpt-4o, OpenAIEmbeddings

Verify ↗