# How to Use Hybrid Retrieval Mode in RAGAnything: Combining Vector Similarity and Graph Traversal

> Discover how to use hybrid retrieval mode in RAGAnything. Combine vector similarity and graph traversal with LightRAG for enhanced search results. Activate hybrid mode in aquery() for powerful AI applications.

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

---

**Use `mode="hybrid"` in `RAGAnything.aquery()` or `aquery_with_multimodal()` to activate hybrid retrieval, which merges dense vector similarity search with graph-based chunk expansion through LightRAG.**

RAGAnything provides multiple retrieval strategies through its integration with **LightRAG**, and the **hybrid retrieval mode** stands out for combining the semantic precision of vector embeddings with the structural context of document graphs. This article explains how hybrid retrieval works internally, how to configure it, and how to use it in both text-only and multimodal scenarios.

## Understanding RAGAnything Retrieval Modes

RAGAnything delegates all retrieval operations to LightRAG, exposing them through a unified `mode` parameter. The available modes offer different trade-offs between speed, coverage, and context richness:

| Mode | Behavior |
|------|----------|
| `local` | Pure vector similarity on the local LightRAG store |
| `global` | Vector similarity on a remote vector database |
| `mix` | Runs both local and global vector searches, merging results |
| **`hybrid`** | **Combines vector similarity with graph traversal** — the focus of this guide |
| `naive`, `bypass` | Specialized fallback behaviors |

The **hybrid retrieval mode** is unique because it performs two distinct operations: first, a standard vector similarity search to find semantically relevant chunks; second, a graph traversal that expands the context by following relationships between chunks in the document structure.

## How Hybrid Retrieval Works Internally

Hybrid retrieval in RAGAnything follows a clear pipeline defined in the source code. Understanding this flow helps you optimize configuration and debug issues.

### Entry Point: Query Methods

The public API exposes hybrid retrieval through two methods in [`raganything/raganything.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py):

- `RAGAnything.aquery()` — asynchronous text query
- `RAGAnything.query()` — synchronous wrapper
- `RAGAnything.aquery_with_multimodal()` — hybrid retrieval with multimodal enrichment

All methods forward to `QueryMixin` in [`raganything/query.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py) (lines 102-110), which handles the `mode` parameter and builds a `QueryParam` object for LightRAG (lines 209-214).

### LightRAG Processing Pipeline

When `mode="hybrid"` reaches LightRAG, the pipeline executes:

1. **Vector similarity phase** — Retrieves `top_k` nearest neighbors using the configured embedding function
2. **Graph traversal phase** — Expands each retrieved chunk by following edges in the document graph, pulling in `related_chunk_number` adjacent chunks with their own `chunk_top_k` vector limits
3. **Merge and deduplicate** — Combines both result streams, removing duplicates while preserving structural relevance

This dual-phase approach ensures you capture both semantic similarity and document structure — critical for queries that depend on context spanning multiple sections or pages.

## Configuring Hybrid Retrieval Parameters

All hybrid retrieval tuning happens through `RAGAnythingConfig` in [`raganything/config.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py) (lines 45-63). The relevant fields are:

| Parameter | Default | Purpose |
|-----------|---------|---------|
| `top_k` | 10 | Primary vector similarity limit |
| `related_chunk_number` | 3 | Graph expansion depth — how many adjacent chunks to traverse |
| `chunk_top_k` | 5 | Secondary vector limit for graph-expanded chunks |

Adjust these based on your documents:

- **Increase `related_chunk_number`** for highly structured documents where context flows across sections (contracts, research papers)
- **Reduce `top_k` and increase `chunk_top_k`** when you want fewer initial matches but deeper exploration of each match's neighborhood

## Code Examples: Using Hybrid Retrieval Mode

### Basic Hybrid Text Query

```python
from raganything import RAGAnything, RAGAnythingConfig

# Configure hybrid retrieval parameters

config = RAGAnythingConfig(
    top_k=10,                # vector similarity limit

    related_chunk_number=3,  # graph traversal depth

)
rag = RAGAnything(
    config=config,
    llm_model_func=my_llm,
    embedding_func=my_embed
)

# Index documents (builds vector store and graph)

await rag.process_document_complete("reports/annual_report.pdf")

# Execute hybrid retrieval query

answer = await rag.aquery(
    "What were the main revenue drivers in Q3?",
    mode="hybrid",  # activates vector + graph retrieval

)
print(answer)

```

This example follows the pattern shown in [`examples/raganything_example.py`](https://github.com/HKUDS/RAG-Anything/blob/main/examples/raganything_example.py) (lines 224-226), where `mode="hybrid"` triggers the dual-phase retrieval pipeline.

### Hybrid Retrieval with Multimodal Content

```python

# Prepare multimodal content to enrich the final answer

multimodal_items = [
    {
        "type": "image",
        "img_path": "figures/architecture.png",
        "image_caption": "System architecture diagram"
    },
    {
        "type": "table",
        "table_data": "Metric,Value\nLatency,120ms\nThroughput,3.2k req/s",
        "table_caption": "Performance benchmarks"
    }
]

# Hybrid retrieval still applies to text context

answer = await rag.aquery_with_multimodal(
    "Compare the architecture diagram with the performance numbers.",
    multimodal_content=multimodal_items,
    mode="hybrid",  # vector similarity + graph traversal for text context

)
print(answer)

```

The multimodal example in [`examples/raganything_example.py`](https://github.com/HKUDS/RAG-Anything/blob/main/examples/raganything_example.py) (lines 300-322) demonstrates this combined approach. The hybrid retrieval operates on the text corpus; the multimodal processor in [`raganything/modalprocessors.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py) then enriches the response with vision-LLM processed images and tables.

### Fine-Tuning Hybrid Parameters

```python

# Deeper graph exploration for highly structured documents

config = RAGAnythingConfig(
    top_k=15,
    related_chunk_number=5,   # more graph neighbors

    chunk_top_k=8,            # richer context per neighbor

)
rag = RAGAnything(config=config, llm_model_func=my_llm, embedding_func=my_embed)

# Process documents...

answer = await rag.aquery(
    "Explain the relationship between section 4 and the appendix.",
    mode="hybrid",
)

```

These configuration fields are defined in [`raganything/config.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py) (lines 45-63), with inline comments noting their specific role in hybrid mode operation.

## Key Files for Hybrid Retrieval

| File | Purpose | Key Lines |
|------|---------|-----------|
| [`raganything/query.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py) | `QueryMixin` implementation, `mode` parameter handling, `QueryParam` construction | 102-110, 209-214 |
| [`raganything/raganything.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py) | `RAGAnything` class, public `aquery`/`aquery_with_multimodal` methods | orchestration layer |
| [`raganything/config.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py) | `RAGAnythingConfig`, hybrid-specific parameters (`top_k`, `related_chunk_number`, `chunk_top_k`) | 45-63 |
| [`examples/raganything_example.py`](https://github.com/HKUDS/RAG-Anything/blob/main/examples/raganything_example.py) | Working examples of hybrid and multimodal hybrid queries | 224-226, 300-322 |
| [`raganything/modalprocessors.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py) | Multimodal enrichment layer that receives hybrid-retrieved context | processing pipeline |

## Summary

- **Hybrid retrieval mode** combines **vector similarity search** with **graph-based chunk traversal** to deliver context that is both semantically relevant and structurally grounded.
- Activate it by passing `mode="hybrid"` to `RAGAnything.aquery()` or `aquery_with_multimodal()`.
- Tune the balance between vector and graph contributions through `RAGAnythingConfig` parameters: `top_k`, `related_chunk_number`, and `chunk_top_k`.
- The pipeline is delegated to LightRAG, with RAGAnything providing configuration, multimodal enrichment, and a simplified API surface.

## Frequently Asked Questions

### What is the difference between `mode="mix"` and `mode="hybrid"` in RAGAnything?

`mode="mix"` runs **local and global vector searches** separately and merges their results — it is purely vector-based. `mode="hybrid"` first performs vector similarity, then **traverses the document graph** to expand context with related chunks. Use `hybrid` when you need structural relationships between document sections, not just semantic similarity.

### How do I configure the graph traversal depth in hybrid mode?

Set the `related_chunk_number` parameter in `RAGAnythingConfig`. This controls how many graph-adjacent chunks are pulled in for each vector match. Increase it for highly interlinked documents (research papers, legal contracts); decrease it for linear documents where excessive traversal dilutes relevance.

### Can I use hybrid retrieval with images and tables?

Yes. Call `aquery_with_multimodal()` with `mode="hybrid"`. The method performs standard hybrid retrieval on your text corpus, then enriches the LLM prompt with base64-encoded images, table data, or equations. The graph traversal operates on the underlying text chunks; multimodal content is added downstream in [`raganything/modalprocessors.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py).

### Does hybrid mode slow down queries compared to pure vector search?

Hybrid mode adds **graph traversal overhead** proportional to `related_chunk_number` and `chunk_top_k`. Each vector match triggers additional chunk lookups and secondary vector searches. For latency-sensitive applications, reduce `related_chunk_number` to 1-2, or fall back to `mode="local"` for pure vector retrieval.