LlamaIndex Basics

8 examples to get you started with LlamaIndex - 5 basic and 3 intermediate.

You will load a folder of files, build a vector index, ask questions with a query engine, inspect source nodes, and wrap retrieval as an agent tool.

Prerequisites

Python 3.11+ recommended
An LLM API key (OpenAI is the common default; other providers work via integrations)
A small data/ folder with a few .txt or .md files you own

python -m venv .venv && source .venv/bin/activate
pip install llama-index
export OPENAI_API_KEY="sk-..."
mkdir -p data
echo "Refunds are available within 30 days of purchase with a receipt." > data/refunds.txt
echo "Support hours are Monday to Friday, 9am to 5pm Eastern." > data/support.txt

Pin integration packages you need at build time (for example OpenAI LLM/embed packages) when the monorepo split requires them.

Basic Examples

1. Five-Line Query Engine

Load a directory, index it, and ask one question.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
 
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("What is the refund window?")
print(response)

This is the canonical LlamaIndex starter path.
SimpleDirectoryReader picks readers by file extension.
Default models come from environment/settings unless you override them.

Related: The LlamaIndex Mental Model: Documents, Indexes, and Query Engines

2. Inspect Documents Before Indexing

Confirm loaders produced the text you expect.

from llama_index.core import SimpleDirectoryReader
 
documents = SimpleDirectoryReader("data").load_data()
for doc in documents:
    print(doc.metadata)
    print(doc.text[:200])
    print("---")

Bad loads produce confident wrong answers later.
Metadata such as file_path becomes citation material.
Fix encoding and empty files before embedding.

3. Build an Index from In-Memory Documents

Skip the filesystem when text already lives in your app.

from llama_index.core import Document, VectorStoreIndex
 
docs = [
    Document(text="Tier A customers get priority routing.", metadata={"tier": "A"}),
    Document(text="Tier B customers use standard support.", metadata={"tier": "B"}),
]
index = VectorStoreIndex.from_documents(docs)
print(index.as_query_engine().query("Who gets priority routing?"))

Useful for tests and synthetic fixtures.
Attach metadata early for filters and debugging.
Same index/query APIs as directory-loaded data.

4. Tune Retrieval with `similarity_top_k`

Control how many chunks enter the prompt.

query_engine = index.as_query_engine(similarity_top_k=3)
response = query_engine.query("When is support available?")
print(response)

Higher k can improve recall and raise token cost.
Lower k is cheaper but may miss multi-hop facts.
Pair top-k changes with a small eval set, not vibes.

5. Read Source Nodes from the Response

Grounding starts with knowing which chunks were used.

response = query_engine.query("What is the refund window?")
print(response)
for node in response.source_nodes:
    print(node.score, node.node.metadata)
    print(node.node.get_content()[:240])

Source nodes power citations and UI “evidence” panels.
Low scores can signal chunking or embedding mismatch.
Log node ids in agent traces for later debugging.

Related: Evaluating Retrieval Quality in a LlamaIndex Pipeline

Intermediate Examples

6. Persist and Reload an Index

Avoid re-embedding the corpus on every process start.

from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    StorageContext,
    load_index_from_storage,
)
 
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
index.storage_context.persist(persist_dir="./storage")
 
storage_context = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage_context)
print(index.as_query_engine().query("Summarize support hours."))

Local persist dirs work for demos; production usually uses an external vector DB.
Rebuild when chunking rules or embedding models change.
Version storage paths with model and splitter configs.

7. Use a Retriever Without Full Synthesis

Fetch context only when you synthesize elsewhere (or for debugging).

retriever = index.as_retriever(similarity_top_k=2)
nodes = retriever.retrieve("refund policy")
for n in nodes:
    print(n.score, n.get_content()[:200])

Separates retrieval quality from generation quality.
Agents can pack retrieved text into custom tool results.
Ideal input for ranking metrics in eval harnesses.

Related: Ingesting and Chunking Documents for an Agent's Knowledge Base

8. Wrap the Query Engine as an Agent Tool

Let an agent decide when to consult your docs.

import asyncio
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.tools import QueryEngineTool
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI  # verify package path at build
 
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
qe = index.as_query_engine(similarity_top_k=3)
 
tool = QueryEngineTool.from_defaults(
    qe,
    name="policy_docs",
    description="Answer questions using internal refund and support policy documents.",
)
 
agent = FunctionAgent(
    tools=[tool],
    llm=OpenAI(model="gpt-4o-mini"),  # verify model at build
    system_prompt="Use policy_docs for company policy questions. Be concise.",
)
 
async def main():
    response = await agent.run("Can a customer get a refund after 10 days?")
    print(str(response))
 
asyncio.run(main())

Tool name and description drive tool selection quality.
Prefer dedicated tools per corpus over one mega-description.
Class names and import paths for agents evolve - verify at build.

Related: Building a Query Engine Agent Over Your Own Data

The LlamaIndex Mental Model: Documents, Indexes, and Query Engines - object model
Ingesting and Chunking Documents for an Agent's Knowledge Base - production ingestion
Building a Query Engine Agent Over Your Own Data - agent recipe depth
LlamaIndex.TS for RAG-First TypeScript Applications - JS/TS path
LlamaIndex Best Practices - section checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

You will load a folder of files, build a vector index, ask questions with a query engine, inspect source nodes, and wrap retrieval as an agent tool.

Prerequisites

Python 3.11+ recommended
An LLM API key (OpenAI is the common default; other providers work via integrations)
A small data/ folder with a few .txt or .md files you own

python -m venv .venv && source .venv/bin/activate
pip install llama-index
export OPENAI_API_KEY="sk-..."
mkdir -p data
echo "Refunds are available within 30 days of purchase with a receipt." > data/refunds.txt
echo "Support hours are Monday to Friday, 9am to 5pm Eastern." > data/support.txt

Pin integration packages you need at build time (for example OpenAI LLM/embed packages) when the monorepo split requires them.

Basic Examples

1. Five-Line Query Engine

Load a directory, index it, and ask one question.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
 
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("What is the refund window?")
print(response)

This is the canonical LlamaIndex starter path.
SimpleDirectoryReader picks readers by file extension.
Default models come from environment/settings unless you override them.

Related: The LlamaIndex Mental Model: Documents, Indexes, and Query Engines

2. Inspect Documents Before Indexing

Confirm loaders produced the text you expect.

from llama_index.core import SimpleDirectoryReader
 
documents = SimpleDirectoryReader("data").load_data()
for doc in documents:
    print(doc.metadata)
    print(doc.text[:200])
    print("---")

Bad loads produce confident wrong answers later.
Metadata such as file_path becomes citation material.
Fix encoding and empty files before embedding.

3. Build an Index from In-Memory Documents

Skip the filesystem when text already lives in your app.

from llama_index.core import Document, VectorStoreIndex
 
docs = [
    Document(text="Tier A customers get priority routing.", metadata={"tier": "A"}),
    Document(text="Tier B customers use standard support.", metadata={"tier": "B"}),
]
index = VectorStoreIndex.from_documents(docs)
print(index.as_query_engine().query("Who gets priority routing?"))

Useful for tests and synthetic fixtures.
Attach metadata early for filters and debugging.
Same index/query APIs as directory-loaded data.

4. Tune Retrieval with `similarity_top_k`

Control how many chunks enter the prompt.

query_engine = index.as_query_engine(similarity_top_k=3)
response = query_engine.query("When is support available?")
print(response)

Higher k can improve recall and raise token cost.
Lower k is cheaper but may miss multi-hop facts.
Pair top-k changes with a small eval set, not vibes.

5. Read Source Nodes from the Response

Grounding starts with knowing which chunks were used.

response = query_engine.query("What is the refund window?")
print(response)
for node in response.source_nodes:
    print(node.score, node.node.metadata)
    print(node.node.get_content()[:240])

Source nodes power citations and UI “evidence” panels.
Low scores can signal chunking or embedding mismatch.
Log node ids in agent traces for later debugging.

Related: Evaluating Retrieval Quality in a LlamaIndex Pipeline

Intermediate Examples

6. Persist and Reload an Index

Avoid re-embedding the corpus on every process start.

from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    StorageContext,
    load_index_from_storage,
)
 
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
index.storage_context.persist(persist_dir="./storage")
 
storage_context = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage_context)
print(index.as_query_engine().query("Summarize support hours."))

Local persist dirs work for demos; production usually uses an external vector DB.
Rebuild when chunking rules or embedding models change.
Version storage paths with model and splitter configs.

7. Use a Retriever Without Full Synthesis

Fetch context only when you synthesize elsewhere (or for debugging).

retriever = index.as_retriever(similarity_top_k=2)
nodes = retriever.retrieve("refund policy")
for n in nodes:
    print(n.score, n.get_content()[:200])

Separates retrieval quality from generation quality.
Agents can pack retrieved text into custom tool results.
Ideal input for ranking metrics in eval harnesses.

Related: Ingesting and Chunking Documents for an Agent's Knowledge Base

8. Wrap the Query Engine as an Agent Tool

Let an agent decide when to consult your docs.

import asyncio
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.tools import QueryEngineTool
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI  # verify package path at build
 
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
qe = index.as_query_engine(similarity_top_k=3)
 
tool = QueryEngineTool.from_defaults(
    qe,
    name="policy_docs",
    description="Answer questions using internal refund and support policy documents.",
)
 
agent = FunctionAgent(
    tools=[tool],
    llm=OpenAI(model="gpt-4o-mini"),  # verify model at build
    system_prompt="Use policy_docs for company policy questions. Be concise.",
)
 
async def main():
    response = await agent.run("Can a customer get a refund after 10 days?")
    print(str(response))
 
asyncio.run(main())

Tool name and description drive tool selection quality.
Prefer dedicated tools per corpus over one mega-description.
Class names and import paths for agents evolve - verify at build.

Related: Building a Query Engine Agent Over Your Own Data

The LlamaIndex Mental Model: Documents, Indexes, and Query Engines - object model
Ingesting and Chunking Documents for an Agent's Knowledge Base - production ingestion
Building a Query Engine Agent Over Your Own Data - agent recipe depth
LlamaIndex.TS for RAG-First TypeScript Applications - JS/TS path
LlamaIndex Best Practices - section checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

LlamaIndex Basics

Buscar en la documentación

LlamaIndex Basics