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

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, with the actual extraction logic implemented in 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:

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

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#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
include_headers	True	Inject document headers/titles as Markdown	L88
include_captions	True	Append image/table captions	L91
context_filter_content_types	["text"]	Whitelist of content types to include in context	L96
content_format	"minerU"	Expected input format (e.g., "minerU", "text_chunks", "text")	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:

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.

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:

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. The chunk extraction logic resides in _extract_chunk_context() at modalprocessors.py#L73.

Example 3: Direct ContextExtractor Usage

For advanced scenarios requiring custom integration:

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.

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
2. Bridge Layer: RAGAnything._create_context_config() converts to internal ContextConfig in raganything/raganything.py
3. Extraction Layer: ContextExtractor selects _extract_page_context() or _extract_chunk_context() based on context_mode in 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.

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