How to beginner · 3 min read

How to use VectorIndexRetriever in LlamaIndex

Q: How to use VectorIndexRetriever in LlamaIndex

Use VectorIndexRetriever in LlamaIndex to perform semantic search by retrieving documents based on vector similarity. First, build a vector index from your documents, then create a VectorIndexRetriever with that index to query semantically relevant content efficiently.

Quick answer

Use VectorIndexRetriever in LlamaIndex to perform semantic search by retrieving documents based on vector similarity. First, build a vector index from your documents, then create a VectorIndexRetriever with that index to query semantically relevant content efficiently.

PREREQUISITES

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

Setup

Install the llama-index package and set your OpenAI API key as an environment variable.

Install with pip install llama-index openai
Set environment variable in your shell: export OPENAI_API_KEY='your_api_key'

bash

pip install llama-index openai

Step by step

This example shows how to create a vector index from documents and use VectorIndexRetriever to query it.

python

import os
from llama_index import SimpleDirectoryReader, GPTVectorStoreIndex, VectorIndexRetriever

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

# Build a vector index from documents
index = GPTVectorStoreIndex.from_documents(documents)

# Create a VectorIndexRetriever using the vector index
retriever = VectorIndexRetriever(index=index)

# Query the retriever
query = "What is the main topic of the documents?"
results = retriever.retrieve(query)

# Print retrieved documents content
for doc in results:
    print(doc.get_text())

output

The main topic of the documents is ... (depends on your data)

Common variations

You can customize VectorIndexRetriever with parameters like similarity_top_k to control how many top documents to retrieve. Also, you can use different embedding models or async calls if supported.

python

retriever = VectorIndexRetriever(index=index, similarity_top_k=5)

# For async usage (if supported by your environment):
# import asyncio
# results = await retriever.aretrieve(query)

Troubleshooting

If you get empty results, ensure your documents are loaded correctly and embeddings are generated.
Check your OpenAI API key is set in os.environ['OPENAI_API_KEY'].
For large datasets, consider increasing similarity_top_k or using more powerful embedding models.

✅

Key Takeaways

Use VectorIndexRetriever to perform semantic search over vector embeddings in LlamaIndex.
Build a GPTVectorStoreIndex from your documents before creating the retriever.
Customize retrieval with parameters like similarity_top_k for better results.
Always set your OpenAI API key in the environment for embedding generation.
Troubleshoot by verifying document loading and embedding creation.

Verified 2026-04 · gpt-4o, GPTVectorStoreIndex

Verify ↗