How to Integrate LightRAG with LlamaIndex for Advanced Indexing

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.

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 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:

   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:

# 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:

# 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:

# 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:

# 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 and 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) 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 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 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) 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). This ensures robust operation against transient failures without manual exception handling in your application code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}