# How to Load and Integrate RAGAnything with an Existing LightRAG Instance

> Integrate RAGAnything with an existing LightRAG instance by passing the LightRAG object to the RAGAnything constructor. Effortlessly inherit storages, LLM callbacks, and embeddings without duplication.

- Repository: [✨Data Intelligence Lab@HKU✨/RAG-Anything](https://github.com/HKUDS/RAG-Anything)
- Tags: how-to-guide
- Published: 2026-04-22

---

**You can integrate RAGAnything with an existing LightRAG instance by passing the LightRAG object to the `RAGAnything` constructor via the `lightrag` parameter, which automatically inherits all storages, LLM callbacks, and embeddings without duplication.**

RAGAnything extends LightRAG with multimodal document processing capabilities—handling images, tables, equations, and context-aware caption generation—while reusing LightRAG's core vector stores, knowledge graphs, and retrieval infrastructure. When you already have a LightRAG instance with indexed knowledge, you can inject it directly into RAGAnything rather than rebuilding your knowledge base from scratch.

## Prerequisites for RAGAnything Integration

Before integrating, ensure your existing LightRAG instance is properly initialized. The `RAGAnything` class in [`raganything/raganything.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py) (lines 55-69) accepts an optional `lightrag` parameter:

```python
@dataclass
class RAGAnything:
    lightrag: Optional[LightRAG] = None
    # ... other configuration fields

```

If you pass `lightrag`, RAGAnything skips creating a new LightRAG instance and instead adopts the existing one.

## Step-by-Step Integration Process

### Step 1: Initialize Your Existing LightRAG Instance

Load your existing LightRAG workspace and ensure its storages are initialized:

```python
import asyncio
from lightrag import LightRAG
from lightrag.llm.openai import openai_complete_if_cache, openai_embed
from lightrag.utils import EmbeddingFunc

api_key = "YOUR_OPENAI_API_KEY"
base_url = "https://api.openai.com/v1"

lightrag = LightRAG(
    working_dir="./existing_lightrag_storage",
    llm_model_func=lambda p, sp=None, hm=[], **kw: openai_complete_if_cache(
        "gpt-4o-mini", p, system_prompt=sp, history_messages=hm,
        api_key=api_key, base_url=base_url, **kw
    ),
    embedding_func=EmbeddingFunc(
        embedding_dim=3072,
        max_token_size=8192,
        func=lambda texts: openai_embed.func(
            texts,
            model="text-embedding-3-large",
            api_key=api_key,
            base_url=base_url,
        ),
    ),
)

# Critical: Initialize storages before passing to RAGAnything

await lightrag.initialize_storages()

```

This initialization step is essential—RAGAnything's `_ensure_lightrag_initialized` method (lines 72-106 in [`raganything/raganything.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py)) expects the storages to be ready.

### Step 2: Inject LightRAG into RAGAnything

Create your `RAGAnything` instance by passing the initialized LightRAG object:

```python
from raganything import RAGAnything

rag = RAGAnything(
    lightrag=lightrag,          # Reuse existing LightRAG instance

    vision_model_func=None,      # Optional: custom VLM for image analysis

    # llm_model_func and embedding_func are inherited automatically

)

```

The `RAGAnything` constructor detects the `lightrag` parameter and invokes `_ensure_lightrag_initialized`, which:

1. **Inherits model callbacks** (lines 72-84): If `llm_model_func` or `embedding_func` are not explicitly provided, RAGAnything copies them from the supplied LightRAG instance.
2. **Initializes shared storages** (lines 86-106): Calls `await self.lightrag.initialize_storages()` and sets up the pipeline status and parse-cache KV store within the same workspace.
3. **Builds multimodal processors** (lines 201-242 in `_initialize_processors`): Creates image, table, equation, and fallback processors that share LightRAG's tokenizer for context extraction.

### Step 3: Query Your Combined Knowledge Base

Your existing LightRAG data and any new multimodal content share the same storage:

```python

# Query across all indexed content (existing + new)

result = await rag.aquery(
    "What topics were covered in the documents already indexed?",
    mode="hybrid"               # Combines vector and graph retrieval

)
print(result)

```

The `aquery` method is implemented in [`raganything/query.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py) as part of `QueryMixin`. It delegates to the underlying LightRAG retrieval while enriching results with multimodal context when available.

### Step 4: Add New Multimodal Documents

Process new documents through RAGAnything's multimodal pipeline—they'll be stored in your existing LightRAG indexes:

```python
await rag.process_document_complete(
    file_path="path/to/new_multimodal.pdf",
    output_dir="./output",        # Temporary parsing files

    parse_method="auto",          # MinerU selects OCR or text mode

)

```

The `process_document_complete` method, defined in [`raganything/processor.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/processor.py) within `ProcessorMixin`, orchestrates document parsing, multimodal element extraction, caption generation, and final insertion into LightRAG's vector and graph stores.

### Alternative: Direct Content List Insertion

If you've already parsed documents externally, bypass RAGAnything's parsing stage:

```python
await rag.insert_content_list(
    content_list=my_content_list,  # Pre-parsed content from any source

    file_path="external_source.pdf",
    doc_id="external-001",         # Optional custom document ID

)

```

This method is also part of `ProcessorMixin` in [`raganything/processor.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/processor.py), allowing flexible integration with custom parsing pipelines.

## Key Integration Points in the Source Code

| File | Purpose | Critical Lines |
|------|---------|----------------|
| [`raganything/raganything.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py) | Core wrapper class; handles LightRAG injection and lazy initialization | [55-69](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py#L55-L69) (constructor), [72-84](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py#L72-L84) (callback inheritance), [86-106](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py#L86-L106) (storage initialization), [201-242](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py#L201-L242) (processor building) |
| [`raganything/config.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py) | All configurable options for parsing, multimodal processing, and context extraction | [config.py](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py) |
| [`raganything/processor.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/processor.py) | `ProcessorMixin` implementing document ingestion, multimodal caption generation, and `insert_content_list` | [processor.py](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/processor.py) |
| [`raganything/query.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py) | `QueryMixin` providing `aquery`, `aquery_with_multimodal`, and retrieval helpers | [query.py](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py) |
| [`examples/raganything_example.py`](https://github.com/HKUDS/RAG-Anything/blob/main/examples/raganything_example.py) | Complete working example showing LightRAG creation, RAGAnything wrapping, and querying | [raganything_example.py](https://github.com/HKUDS/RAG-Anything/blob/main/examples/raganything_example.py) |
| [`README.md`](https://github.com/HKUDS/RAG-Anything/blob/main/README.md) (Loading Existing LightRAG section) | Human-readable walkthrough with exact code snippets | [README lines 690-795](https://github.com/HKUDS/RAG-Anything/blob/main/README.md#L690-L795) |

## Summary

Loading and integrating RAGAnything with an existing LightRAG instance requires four key steps:

- **Initialize your LightRAG storages** with `await lightrag.initialize_storages()` before passing the object to RAGAnything
- **Pass the LightRAG instance** to the `RAGAnything` constructor via the `lightrag` parameter to trigger automatic callback inheritance and shared storage setup
- **Query seamlessly** across existing and new content using `aquery` with `mode="hybrid"` for combined vector and graph retrieval
- **Add multimodal documents** via `process_document_complete` or `insert_content_list`—all content persists to the same LightRAG indexes

The integration avoids index duplication, preserves your existing embeddings and knowledge graph, and immediately extends LightRAG with multimodal parsing capabilities.

## Frequently Asked Questions

### What happens if I don't call `initialize_storages()` on my LightRAG instance before passing it to RAGAnything?

RAGAnything's `_ensure_lightrag_initialized` method will attempt to initialize storages, but you may encounter race conditions or incomplete initialization if the LightRAG object wasn't properly prepared. Always explicitly call `await lightrag.initialize_storages()` first to ensure all vector, KV, and graph stores are ready.

### Can I use different LLM or embedding models for RAGAnything than my existing LightRAG instance?

Yes, though it requires explicit configuration. If you pass `llm_model_func` or `embedding_func` parameters to the `RAGAnything` constructor, these will override the callbacks inherited from LightRAG. However, this creates model inconsistency—your existing embeddings won't match new ones. For best results, inherit the same models from your LightRAG instance.

### Does RAGAnything duplicate my existing LightRAG data when I integrate it?

No duplication occurs. RAGAnything is a thin wrapper that reuses LightRAG's existing storages. The `lightrag` parameter injection ensures RAGAnything operates on the same vector database, knowledge graph, and KV stores. Only new documents processed through RAGAnything's multimodal pipeline are added—existing data remains untouched and immediately searchable.

### How do I verify that my integration worked correctly?

Query for content that existed in your original LightRAG instance using `await rag.aquery()` with `mode="hybrid"`. If results include your previously indexed documents, the integration succeeded. You can also check that `rag.lightrag` references the same object you passed, and that new multimodal documents processed via `process_document_complete` appear in subsequent queries alongside existing content.