# How to Integrate LightRAG with LlamaIndex for Advanced Indexing

> Integrate LightRAG with LlamaIndex for advanced indexing using LightRAG's adapter. Learn how to leverage LLM and embedding backends for enhanced document retrieval and analysis.

- Repository: [✨Data Intelligence Lab@HKU✨/LightRAG](https://github.com/HKUDS/LightRAG)
- Tags: how-to-guide
- Published: 2026-03-23

---

**LightRAG provides a thin-layer adapter that turns LlamaIndex into a first-class LLM and embedding backend through three core components: a settings bridge (`configure_llama_index`), a completion wrapper (`llama_index_complete`), and an embedding wrapper (`llama_index_embed`) located in [`lightrag/llm/llama_index_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/llama_index_impl.py).**

LightRAG supports advanced indexing workflows by treating LlamaIndex (formerly GPT-Index) as a native backend provider. By leveraging the integration adapter in the HKUDS/LightRAG repository, you can route all language model completions and embedding operations through LlamaIndex's sophisticated model management, caching, and routing capabilities while retaining LightRAG's graph-based retrieval architecture.


## Understanding the Adapter Architecture

The integration is implemented as a compatibility layer in [`lightrag/llm/llama_index_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/llama_index_impl.py) that normalizes LlamaIndex's API to match LightRAG's internal expectations. The architecture consists of three logical pieces that work together to provide seamless interoperability.

### Settings Bridge: `configure_llama_index`

The `configure_llama_index` function (lines 33–53) serves as the entry point for global configuration. It accepts a `LlamaIndexSettings` object or plain keyword arguments and registers them in LightRAG's singleton configuration store. This mirrors LightRAG's pattern used for OpenAI and Ollama backends, allowing downstream components to automatically discover and use the LlamaIndex instance without explicit passing.

### Completion Wrapper: `llama_index_complete`

The `llama_index_complete` function (lines 42–74) handles text generation by converting LightRAG's generic message format into LlamaIndex's `ChatMessage` objects through `format_chat_messages` (lines 56–80). It invokes `model.achat` asynchronously and returns the raw response string, preserving the full conversation history and system prompt capabilities.

### Embedding Wrapper: `llama_index_embed`

The `llama_index_embed` function (lines 77–89) wraps any LlamaIndex `BaseEmbedding` instance to produce NumPy arrays compatible with LightRAG's vector stores. It automatically applies dimension validation and retry logic, ensuring the output shape matches expected dimensions before returning the embedding vectors.


## Step-by-Step Integration Guide

Follow these steps to wire LlamaIndex into your LightRAG pipeline.

1. **Install the optional dependency** – While LightRAG can install `llama-index` on-the-fly, explicit installation is recommended for version control:

   ```bash
   pip install "llama-index[all]"
   ```

2. **Create a `LlamaIndexSettings` object** – Instantiate your preferred LLM and embedding models using LlamaIndex's standard classes.

3. **Register the configuration globally** – Call `configure_llama_index` to store the settings in LightRAG's global state, enabling automatic discovery by downstream components.

4. **Invoke the wrapper functions** – Use `llama_index_complete` for generation and `llama_index_embed` for vectorization. These accept the same arguments as LightRAG's native OpenAI helpers (`prompt`, `system_prompt`, `history_messages`, etc.).

5. **Integrate with LightRAG pipelines** – Pass the string or NumPy array outputs directly into LightRAG's graph builders, RAG pipelines, and document chunkers without additional transformation.


## Complete Implementation Examples

These runnable examples demonstrate the integration patterns from basic setup to full pipeline deployment.

### Basic Configuration Setup

Register a LlamaIndex LLM and embedding model for global use within LightRAG:

```python

# example_setup.py

from lightrag.llm.llama_index_impl import configure_llama_index
from llama_index.core.settings import Settings as LlamaIndexSettings
from llama_index.llms.openai import OpenAI

# Create settings with your preferred models

my_settings = LlamaIndexSettings()
my_settings.llm = OpenAI(model="gpt-4o-mini")
my_settings.embed_model = "local:BAAI/bge-m3"

# Register globally – LightRAG will use these defaults automatically

configure_llama_index(my_settings)

```

### Text Completion with LlamaIndex

Generate responses using the configured LlamaIndex LLM through LightRAG's interface:

```python

# example_completion.py

import asyncio
from lightrag.llm.llama_index_impl import llama_index_complete

async def main():
    answer = await llama_index_complete(
        prompt="Summarise the key challenges of RAG systems.",
        system_prompt="You are a helpful AI assistant.",
        history_messages=[
            {"role": "user", "content": "What is Retrieval‑Augmented Generation?"},
            {"role": "assistant", "content": "RAG combines LLMs with external knowledge..."}
        ],
        llm_instance=None,  # Uses global setting configured earlier

    )
    print("Answer:", answer)

asyncio.run(main())

```

### Batch Embedding via LlamaIndex

Process multiple texts through LlamaIndex's embedding models with automatic dimension validation:

```python

# example_embed.py

import asyncio
import numpy as np
from lightrag.llm.llama_index_impl import llama_index_embed
from llama_index.embeddings.openai import OpenAIEmbedding

async def main():
    embedder = OpenAIEmbedding(model="text-embedding-3-large")
    
    texts = [
        "LightRAG enables graph‑based retrieval.",
        "LlamaIndex provides a unified data‑connector layer."
    ]
    
    vectors: np.ndarray = await llama_index_embed(
        texts=texts,
        embed_model=embedder,
    )
    print("Shape:", vectors.shape)  # → (2, 1536)

asyncio.run(main())

```

### Full LightRAG Pipeline Integration

Deploy LlamaIndex as the backend for a complete LightRAG workflow:

```python

# rag_pipeline.py

import asyncio
from lightrag.lightrag import LightRAG
from lightrag.llm.llama_index_impl import configure_llama_index
from llama_index.core.settings import Settings as LlamaIndexSettings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

async def run():
    # Configure LlamaIndex once

    cfg = LlamaIndexSettings()
    cfg.llm = OpenAI(model="gpt-4o-mini")
    cfg.embed_model = OpenAIEmbedding(model="text-embedding-3-large")
    configure_llama_index(cfg)
    
    # Initialize LightRAG with LlamaIndex backends

    rag = LightRAG(
        llm="llama_index",
        embed="llama_index",
    )
    
    # Ingest documents

    await rag.ingest_documents(["docs/intro.md", "docs/architecture.md"])
    
    # Query the knowledge graph

    response = await rag.query("How does LightRAG handle concurrency?")
    print(response)

asyncio.run(run())

```


## Reliability and Safety Mechanisms

According to the source code in [`lightrag/llm/llama_index_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/llama_index_impl.py) and [`lightrag/utils.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/utils.py), the adapter inherits LightRAG's production-grade robustness features:

- **Unified retry logic** – Both completion and embedding functions use the `@retry` decorator from `tenacity` to handle `RateLimitError`, `APIConnectionError`, and `APITimeoutError` (lines 85–90).

- **Dimension safety** – The `wrap_embedding_func_with_attrs` decorator (from [`lightrag/utils.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/utils.py)) injects the expected `embedding_dim` attribute and validates output shapes, preventing downstream matrix mismatches (lines 77–84).

- **Message normalization** – The `format_chat_messages` utility converts LightRAG's dictionary-based messages (with `role` and `content` keys) into LlamaIndex's native `ChatMessage` objects while preserving system, assistant, and user distinctions (lines 56–80).


## Summary

- The integration lives in [`lightrag/llm/llama_index_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/llama_index_impl.py) and exposes `configure_llama_index`, `llama_index_complete`, and `llama_index_embed`.
- **Global configuration** via `configure_llama_index` allows LightRAG to automatically discover LlamaIndex instances without per-call injection.
- **Retry and dimension validation** are handled automatically through decorators shared with LightRAG's native backends.
- **Return types** are plain strings (completion) and NumPy arrays (embeddings), ensuring compatibility with existing LightRAG pipelines.
- You can instantiate LightRAG with `llm="llama_index"` and `embed="llama_index"` after configuring the global settings.


## Frequently Asked Questions

### What file contains the LightRAG LlamaIndex integration?

The core adapter is located at [`lightrag/llm/llama_index_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/llama_index_impl.py) in the HKUDS/LightRAG repository. This file contains the `configure_llama_index`, `llama_index_complete`, and `llama_index_embed` functions that bridge the two frameworks.

### How does LightRAG handle embedding dimension validation with LlamaIndex?

LightRAG applies the `wrap_embedding_func_with_attrs` decorator (defined in [`lightrag/utils.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/utils.py)) to the embedding wrapper. This injects the expected `embedding_dim` attribute and validates that the output NumPy array matches the declared dimensions before returning it to the pipeline.

### Can I use different LlamaIndex models for different LightRAG operations?

Yes. While you can set global defaults via `configure_llama_index`, both `llama_index_complete` and `llama_index_embed` accept optional parameters (`llm_instance` and `embed_model` respectively) that allow per-call overrides with specific LlamaIndex model instances.

### What network errors does the retry decorator handle?

The integration uses `tenacity` to automatically retry on `RateLimitError`, `APIConnectionError`, and `APITimeoutError` (as implemented in lines 85–90 of [`llama_index_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/llama_index_impl.py)). This ensures robust operation against transient failures without manual exception handling in your application code.