# LlamaIndex

LlamaIndex connects language models to your data: ingestion, parsing, indexing, retrieval, query engines, agents and event-driven workflows. Learn how it works.

## Overview

LlamaIndex is an open-source framework for connecting language models to your own data. It handles the full path from raw files to answers: loading documents, parsing them, splitting them into chunks, creating embeddings, storing them in an index, retrieving the right pieces for a question and asking a model to answer with them. On top of that it offers agents and event-driven workflows, so a model can decide which data to search and how to combine results.

The framework is best known for retrieval-augmented generation, or RAG. Many teams use it to build question-answering systems over company documents, assistants that read contracts or reports, and agents that combine document search with database queries. It has Python and TypeScript versions, a large catalogue of integrations, and a company behind it that offers commercial document parsing and hosted retrieval services.

An everyday comparison is a library with a good catalogue system. Books arrive in many formats, so someone unpacks them, labels them and files them by subject (ingestion and indexing). When you ask a question, the librarian looks up the catalogue, pulls the right pages and hands them to an expert who writes the answer (retrieval and synthesis). For harder questions, the librarian plans a search across several sections (agents and workflows).

## What it is

LlamaIndex is published under the MIT licence. In Python, the core lives in `llama-index-core`, and each integration, such as a model provider or vector database, is a separate package.

| Part | What it does |
|---|---|
| Readers and connectors | Load data from files, databases, APIs and SaaS tools |
| Documents and nodes | A document is a source; nodes are the chunks made from it, with metadata |
| Node parsers | Split documents into chunks by size, sentence, structure or meaning |
| Ingestion pipeline | A repeatable chain of parsing, transformations and embedding, with caching |
| Indexes | Data structures for retrieval, most commonly a vector index |
| Retrievers | Components that fetch relevant nodes for a query |
| Postprocessors | Rerank, filter or trim retrieved nodes before the model sees them |
| Query engines | Retrieval plus answer synthesis behind one `query` call |
| Chat engines | Query engines with conversation history |
| Agents | Models that choose and call tools, including query engines as tools |
| Workflows | Event-driven, step-based orchestration for agents and pipelines |
| LlamaParse and LlamaCloud | Commercial services for document parsing, extraction and hosted indexing |

## Where it came from

Jerry Liu started the project in November 2022 under the name GPT Index, while experimenting with ways to give GPT-3 access to more text than fit in its prompt. It was renamed LlamaIndex in early 2023. LlamaHub, a shared collection of data loaders, launched in February 2023. Liu and Simon Suo founded a company around the project in 2023, and it raised a seed round that June.

Version 0.10, released in early 2024, split the code into a small core package and many separate integration packages. In February 2024 the company launched LlamaParse, a parser for complex PDFs with tables and charts. Later in 2024 it introduced Workflows, an event-driven way to build agents and multi-step pipelines. LlamaCloud, the hosted platform for parsing, extraction and retrieval, became generally available in March 2025. More recently the company has focused heavily on document parsing and extraction for agents.

## How it works

### Step 1: Load

Readers turn sources into documents. A directory reader handles common file types. Connectors on LlamaHub cover sources such as cloud drives, wikis and databases. Each document carries metadata such as file name, date and author.

### Step 2: Parse and chunk

Node parsers split documents into nodes. Chunk size, overlap and structure matter a great deal. A contract is better split by clause; a manual by heading. Complex PDFs with tables often need a specialised parser, which is where LlamaParse is used.

### Step 3: Embed and index

An embedding model turns each node into a vector; see [embeddings](/tools/embeddings). The vector index stores these, either in memory or in a vector database such as [Qdrant](/tools/qdrant) or pgvector. An ingestion pipeline makes this repeatable and caches results so unchanged documents are not processed again.

### Step 4: Retrieve and refine

For each question, a retriever fetches the most similar nodes. You can filter by metadata, combine keyword and vector search, and rerank results; see [hybrid search](/tools/hybrid-search) and [cross-encoder reranking](/tools/cross-encoder-reranking).

### Step 5: Synthesise

A query engine passes the question and retrieved nodes to the model with instructions to answer from them. Different response modes handle cases where the retrieved text is too long for one prompt.

```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

documents = SimpleDirectoryReader("policies").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
print(query_engine.query("How many days of parental leave do employees get?"))
```

### Step 6: Add agents and workflows

An agent can use several query engines as tools, for example one per document collection, plus a SQL tool. It decides which to call, reads results and continues; see [agentic RAG](/tools/agentic-rag). Workflows define steps that react to events. Each step receives an event, does work and emits a new event, which triggers the next step. This supports branching, loops, parallel steps and pauses for human input. Ready-made agent classes and multi-agent workflows are built on this layer.

## Key concepts and terms

| Term | Meaning |
|---|---|
| Document | A unit of source data with text and metadata |
| Node | A chunk of a document, the basic unit of retrieval |
| Node parser | The component that splits documents into nodes |
| Ingestion pipeline | A repeatable chain of transformations with caching |
| Vector index | An index that retrieves nodes by embedding similarity |
| Retriever | The component that fetches relevant nodes |
| Postprocessor | A step that reranks or filters retrieved nodes |
| Query engine | Retrieval plus answer synthesis behind one call |
| Chat engine | A query engine with memory of the conversation |
| Agent | A model that chooses and calls tools |
| Workflow | Event-driven orchestration of steps |
| LlamaHub | The catalogue of community connectors and tools |

## A worked example

This scenario is illustrative. A mid-sized manufacturer builds an assistant for its maintenance engineers.

1. It loads 1,800 equipment manuals (PDF) and 12,000 past work orders (from a database).
2. The manuals go through a parser that keeps tables of torque values and part numbers intact. Nodes are split by section heading and tagged with machine model.
3. The work orders are indexed separately, with metadata for machine, date and fault code.
4. An agent gets three tools: a manuals query engine, a work-orders query engine with metadata filters, and a SQL tool for spare-parts stock.
5. An engineer asks: "Press 7 shows fault E42 again. What fixed it before, and do we have the part?" The agent searches work orders filtered to Press 7 and E42, finds two past repairs that replaced a pressure sensor, looks up the part number in the manual, and queries stock: 3 in the store.
6. The team tests on 150 real questions with known answers. The first version answers 112 correctly. Adding a reranker and metadata filters raises that to 131.

## Strengths and limitations

**Strengths:**

- Deep, mature tooling for loading, parsing, chunking, indexing and retrieval.
- Hundreds of integrations for data sources, models and vector stores.
- Query engines make standard RAG very quick to build.
- Agents and event-driven workflows for more complex, multi-step systems.
- Python and TypeScript versions.
- Optional commercial parsing for difficult documents.

**Limitations:**

- Many abstractions and options, which can be confusing at first.
- Defaults are a starting point; good results usually need tuning of chunking and retrieval.
- The API has changed significantly over time, so older tutorials may not work.
- The best parsing of complex documents may require the paid service.
- Like any RAG system, answers are only as good as the retrieved evidence.

## How it compares with alternatives

| Option | Strength | Trade-off |
|---|---|---|
| LlamaIndex | Deep data ingestion, indexing and retrieval | Many abstractions to learn |
| [LangGraph](/tools/langgraph) | Explicit agent graphs and durable state | Less built-in data tooling |
| [DSPy](/tools/dspy) | Optimises retrieval and answer prompts against a metric | Not a data-ingestion framework |
| [Mastra](/tools/mastra) | TypeScript agents, workflows and RAG in one package | Smaller data ecosystem |
| Plain vector database plus code | Full control, few dependencies | You build every step yourself |

## Practical guidance and best practices

1. Start with a small, representative set of documents and real questions.
2. Inspect the nodes your parser produces before tuning anything else.
3. Choose chunking by document structure, not a single fixed size.
4. Store useful metadata and filter on it during retrieval.
5. Add a reranker before increasing the number of retrieved chunks.
6. Use an ingestion pipeline with caching for documents that change.
7. Measure retrieval and answers separately; see [RAGAS](/tools/ragas) and [evals](/tools/evals).
8. Move to agents and workflows only when a single query engine is not enough.

## Common mistakes

- Indexing everything with default settings and blaming the model for poor answers.
- Ignoring tables and images in PDFs, which plain text extraction often mangles.
- Retrieving many chunks and flooding the prompt with noise.
- Mixing documents with different access rights in one index without filters.
- Following tutorials written for older versions without checking the current API.

## Frequently asked questions

### What is LlamaIndex?

LlamaIndex is an open-source framework for connecting language models to your data. It covers loading, parsing, indexing, retrieval and answer synthesis, plus agents and workflows for multi-step tasks.

### Was LlamaIndex called GPT Index?

Yes. Jerry Liu started it in November 2022 as GPT Index and renamed it LlamaIndex in early 2023.

### Is LlamaIndex only for RAG?

RAG is its core strength, but it also provides agents, multi-agent workflows, structured data extraction and tools for chat assistants.

### What is LlamaParse?

LlamaParse is the company's commercial document parsing service, designed for complex files such as PDFs with tables, charts and unusual layouts.

### How do LlamaIndex workflows work?

A workflow is a set of steps that react to events. Each step receives an event, does some work and emits another event, which triggers the next step. This supports branching, loops, parallel work and pauses for human input.

### Does LlamaIndex lock me into one model or database?

No. Models, embedding providers and vector stores are separate integration packages, so you can switch between them.

## Glossary

- RAG: answering with retrieved evidence in the prompt.
- Document: a loaded source with metadata.
- Node: a chunk of a document.
- Embedding: a vector that represents meaning.
- Index: a structure for finding nodes.
- Retriever: the component that fetches nodes.
- Reranker: a model that reorders retrieved results.
- Query engine: retrieval plus synthesis.
- Workflow: event-driven orchestration.
- LlamaHub: the integration catalogue.

## Summary

LlamaIndex is a data framework for language model applications. It began as GPT Index in November 2022 and grew into a full toolkit for ingestion, parsing, indexing, retrieval, query engines, agents and event-driven workflows, with commercial parsing and hosting alongside. It makes basic RAG quick, but quality comes from careful parsing, chunking, metadata, reranking and measurement. Start simple, inspect your nodes, evaluate retrieval and answers separately, and add agents only when needed.