# RAGAnything Configuration Options for Context-Aware Processing: context_window and context_mode Explained

> Master RAGAnything context-aware processing. Learn to control LLM context with context_window and switch extraction strategies using context_mode for optimal results.

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

---

**Use `context_window` to control how many surrounding pages or chunks feed into the LLM, and `context_mode` to switch between page-based and chunk-based extraction strategies.**

RAGAnything's multimodal RAG system uses `context_window` and `context_mode` as the primary levers for context-aware processing. These settings determine how much surrounding material accompanies images, tables, and equations when they're sent to the language model for analysis. The configuration lives in `RAGAnythingConfig` at [`raganything/config.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py), with the actual extraction logic implemented in [`raganything/modalprocessors.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py).

## Core Configuration: context_window and context_mode

The two primary options work together to define context scope and granularity.

### context_window: Defining the Breadth of Context

The `context_window` parameter sets how many items to include **before and after** the target content.

| Value | Behavior |
|-------|----------|
| `0` | Disables context entirely; only the target item is processed |
| `1` | Includes 1 page or chunk on each side (default) |
| `n` | Includes `n` pages or chunks on each side |

This is defined at [`raganything/config.py#L77`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py#L77):

```python
@dataclass
class RAGAnythingConfig:
    # ...

    context_window: int = 1  # pages/chunks before and after

```

### context_mode: Switching Between Page and Chunk Strategies

The `context_mode` parameter determines **how** the window is applied. It supports two extraction strategies at [`raganything/config.py#L80`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py#L80):

| Mode | Description | Best For |
|------|-------------|----------|
| `"page"` | Uses **page boundaries** (`page_idx`) to gather context. Items on the same physical page (or adjacent pages) are included. | Documents with strong page-level structure (PDFs, academic papers) |
| `"chunk"` | Uses **sequential index** in the content list. The `n` items before and after in processing order are included. | Linear content where page boundaries are meaningless or disruptive |

The internal implementation distinguishes these modes in `ContextExtractor._extract_page_context()` versus `_extract_chunk_context()` at [[`raganything/modalprocessors.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py)](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py#L73).

## Auxiliary Context Configuration Options

Beyond the two primary settings, several additional parameters fine-tune context extraction:

| Option | Default | Purpose | Source |
|--------|---------|---------|--------|
| `max_context_tokens` | `2000` | Hard token limit; context is truncated at sentence boundaries | [`L84`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py#L84) |
| `include_headers` | `True` | Inject document headers/titles as Markdown | [`L88`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py#L88) |
| `include_captions` | `True` | Append image/table captions | [`L91`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py#L91) |
| `context_filter_content_types` | `["text"]` | Whitelist of content types to include in context | [`L96`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py#L96) |
| `content_format` | `"minerU"` | Expected input format (e.g., `"minerU"`, `"text_chunks"`, `"text"`) | [`L103`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py#L103) |

## Practical Configuration Examples

### Example 1: Page-Based Context for PDF Documents

For academic papers where figures and tables appear on specific pages with surrounding explanatory text:

```python
from raganything import RAGAnything, RAGAnythingConfig

config = RAGAnythingConfig(
    context_window=2,           # 2 pages on each side

    context_mode="page",        # respect page boundaries

    max_context_tokens=2500,
    include_headers=True,       # section headers provide context

    include_captions=True,
    context_filter_content_types=["text", "image"],  # images may contain relevant diagrams

    content_format="minerU",    # MinerU-parsed PDF input

)

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

await rag.process_document_complete("research_paper.pdf")

```

The `RAGAnything` class builds this into a `ContextConfig` via `_create_context_config()` at [`raganything/raganything.py#L78`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py#L78).

### Example 2: Chunk-Based Context for Linear Content

For documents without meaningful page boundaries, such as concatenated text files or slide decks where order matters more than pagination:

```python
config = RAGAnythingConfig(
    context_window=5,           # 5 items before and after

    context_mode="chunk",       # sequential index, not page-based

    max_context_tokens=1500,
    include_headers=False,      # headers may be unreliable in this format

    include_captions=False,
    context_filter_content_types=["text"],  # text-only context

    content_format="text_chunks",
)

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

# Update configuration at runtime if needed

rag.update_config(context_window=3, context_mode="page")

```

Runtime updates are handled by `RAGAnything.update_config()` at [`raganything/raganything.py#L46`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py#L46). The chunk extraction logic resides in `_extract_chunk_context()` at [`modalprocessors.py#L73`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py#L73).

### Example 3: Direct ContextExtractor Usage

For advanced scenarios requiring custom integration:

```python
from raganything.modalprocessors import ContextConfig, ContextExtractor

ctx_cfg = ContextConfig(
    context_window=1,
    context_mode="page",
    max_context_tokens=2000,
    include_headers=True,
    include_captions=True,
    filter_content_types=["text", "image"],
)

extractor = ContextExtractor(config=ctx_cfg, tokenizer=my_tokenizer)

# content_list: MinerU JSON representation of document

item_info = {"page_idx": 4, "type": "image"}  # target image on page 4

context_text = extractor.extract_context(
    content_list, 
    item_info, 
    content_format="minerU"
)

```

`ContextConfig` and `ContextExtractor` are defined at [`modalprocessors.py#L33`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py#L33).

## Internal Implementation Flow

Understanding how `context_window` and `context_mode` flow through the codebase helps predict behavior and debug issues:

1. **Configuration Layer**: `RAGAnythingConfig` validates and stores user settings in [`raganything/config.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py)
2. **Bridge Layer**: `RAGAnything._create_context_config()` converts to internal `ContextConfig` in [`raganything/raganything.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py)
3. **Extraction Layer**: `ContextExtractor` selects `_extract_page_context()` or `_extract_chunk_context()` based on `context_mode` in [`raganything/modalprocessors.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/modalprocessors.py)
4. **Filtering Layer**: `filter_content_types` removes unwanted content types from the gathered window
5. **Truncation Layer**: `_truncate_context()` enforces `max_context_tokens` at sentence boundaries
6. **Formatting Layer**: Headers and captions are injected if their flags are enabled

## Summary

- **`context_window`** controls quantity: how many pages or chunks surround the target item (default: `1`, set to `0` to disable)
- **`context_mode`** controls method: `"page"` uses physical page boundaries, `"chunk"` uses sequential list indices
- **`max_context_tokens`** provides a hard ceiling on token count, with intelligent truncation
- **Auxiliary flags** (`include_headers`, `include_captions`, `context_filter_content_types`) fine-tune content selection and formatting
- **Configuration propagation**: `RAGAnythingConfig` → `ContextConfig` → `ContextExtractor` → modal processors

## Frequently Asked Questions

### What happens if I set context_window to 0?

Setting `context_window=0` disables context extraction entirely. The modal processor receives only the target item (image, table, equation, etc.) without any surrounding text. This minimizes token usage but may reduce understanding for items that depend on nearby explanatory content.

### Should I use page mode or chunk mode?

Use **`"page"` mode** for PDFs, scanned documents, and publications where physical layout carries semantic meaning—figures on page 3 are likely explained by text on pages 2-4. Use **`"chunk"` mode** for linear or streaming content where items are processed sequentially without meaningful page boundaries, such as concatenated text files or slide decks converted to item lists.

### How does max_context_tokens interact with context_window?

`context_window` determines the **candidate items** to include; `max_context_tokens` enforces the **actual token budget**. The extractor first gathers all items within the window, then applies `filter_content_types`, then truncates intelligently at sentence boundaries until the token count falls below `max_context_tokens`. A large window with a small token cap results in aggressive truncation; a small window with a large cap preserves more complete surrounding text.

### Can I change context settings after initializing RAGAnything?

Yes. Call `rag.update_config(context_window=3, context_mode="chunk")` to modify settings at runtime. This method updates the internal `ContextConfig` and propagates changes to active modal processors. However, documents already processed retain their original context extraction results; the new settings apply only to subsequent `process_document_complete()` calls.