How to Configure MinerU with GPU Acceleration (CUDA, NPU, MPS) in RAGAnything

Set the device parameter to "cuda", "npu", or "mps" when calling RAGAnything's parsing methods, and the value flows directly to MinerU's -d/--device flag.

Configuring GPU acceleration for MinerU in RAGAnything requires understanding how the framework delegates document parsing to the underlying MinerU tool. The device parameter is the single configuration point that controls whether inference runs on CPU, NVIDIA GPU, Huawei NPU, or Apple Silicon. This guide walks through all three ways to set this parameter based on the RAGAnything source code in HKUDS/RAG-Anything.

Where the Device Configuration Lives in RAGAnything

RAGAnything does not implement its own OCR or vision models. Instead, it wraps MinerU as an external subprocess and passes configuration through command-line arguments. The device parameter originates in three possible entry points and converges at a single location in the codebase.

The Command Construction Point

In raganything/parser.py, the MinerUParser._run_mineru_command method builds the subprocess command that invokes MinerU. This is where the -d flag is appended:

# From raganything/parser.py, lines 683-685

cmd = [
    "magic-pdf",
    "-p", pdf_path,
    "-o", output_dir,
    "-d", self.device,  # <--- device flag added here

]

The self.device value comes from the device parameter passed during parser initialization or the parse_document call.

Entry Point 1: CLI Argument

The built-in parser CLI accepts --device directly:

# From raganything/parser.py, lines 2353-2356

parser.add_argument(
    "-d", "--device",
    default="cpu",
    help="Device to run MinerU on (cpu, cuda, npu, mps)"
)

Entry Point 2: High-Level API via process_document_complete

The RAGProcessor class forwards device through **kwargs:

# From raganything/processor.py, lines 96-98

async def parse_document(self, file_path: str, **kwargs):
    """Parse a document using the configured parser."""
    # kwargs including 'device' are forwarded to the parser

Entry Point 3: Direct Parser Instantiation

You can also pass device directly to MinerUParser.parse_document:

# From raganything/parser.py, lines 636-642

def parse_document(
    self,
    file_path: str,
    output_dir: str = None,
    method: str = "auto",
    device: str = "cpu",  # <--- direct parameter

    ...
) -> Tuple[str, str]:

Supported Device Values

The device string must match what MinerU (and underlying PyTorch) accepts. Based on the RAGAnything implementation and MinerU's capabilities:

Device String	Hardware Target	Common Use Case
cpu	CPU only	Fallback, no GPU available
cuda	First available NVIDIA GPU	Default GPU inference
cuda:0, cuda:1, etc.	Specific NVIDIA GPU	Multi-GPU systems
npu	Huawei Ascend NPU	Huawei Atlas hardware
mps	Apple Silicon Metal	M1/M2/M3 Macs

RAGAnything passes this value unmodified to MinerU. If the specified device is unavailable, MinerU handles the fallback and emits warnings independently.

Practical Configuration Examples

CLI Usage with CUDA

Run document parsing from the command line with GPU acceleration:

python -m raganything.parser \
    /path/to/document.pdf \
    --device cuda:0 \
    --method auto \
    --output ./parsed_output

The --device cuda:0 flag is passed through to MinerU's -d parameter.

Async API with NPU

Configure the high-level RAGAnything processor for Huawei Ascend hardware:

import asyncio
from raganything.raganything import RAGAnything
from raganything.config import RAGAnythingConfig

async def main():
    config = RAGAnythingConfig()
    rag = RAGAnything(config=config)
    
    result = await rag.process_document_complete(
        file_path="documents/contract.pdf",
        output_dir="./output",
        parse_method="auto",
        device="npu",  # Huawei Ascend NPU

        backend="pipeline",
    )
    print(f"Processed document: {result}")

asyncio.run(main())

The device="npu" parameter flows through process_document_complete → parse_document → MinerUParser._run_mineru_command.

Apple Silicon with MPS

For M1/M2/M3 Macs, use Metal Performance Shaders:

from raganything.parser import MinerUParser

parser = MinerUParser()

content, doc_id = parser.parse_document(
    file_path="scanned_report.pdf",
    output_dir="./parsed",
    method="auto",
    device="mps",  # Apple Silicon GPU

    backend="pipeline",
)

Multi-GPU Selection

Specify exact GPU indices for systems with multiple NVIDIA cards:

# Use second GPU (index 1)

device="cuda:1"

# Use third GPU (index 2)

device="cuda:2"

This maps directly to PyTorch's device specification that MinerU uses internally.

Verifying GPU Utilization

To confirm your device configuration is active, check MinerU's output logs. RAGAnything captures subprocess output, so you can enable verbose logging:

import logging
logging.basicConfig(level=logging.DEBUG)

When device="cuda" is specified, MinerU typically logs device binding messages like:

[INFO] Using device: cuda:0
[INFO] CUDA available: True

If the device is unavailable, MinerU falls back to CPU with a warning—RAGAnything does not intercept or modify this behavior.

Summary

• Single configuration point: The device parameter is the only setting needed for GPU acceleration in RAGAnything.
• Three entry points: CLI --device flag, process_document_complete(device=...) kwarg, or direct MinerUParser.parse_document(device=...) call.
• Direct pass-through: RAGAnything appends ["-d", device] to the MinerU subprocess command without transformation.
• Supported values: cpu, cuda, cuda:N, npu, mps—matching PyTorch/MinerU conventions.
• No additional setup: Ensure CUDA/NPU/MPS drivers and PyTorch are installed on the host; RAGAnything requires no internal configuration changes.

Frequently Asked Questions

What happens if I specify a GPU device that doesn't exist?

RAGAnything passes the device string directly to MinerU, which attempts to initialize PyTorch with that device. If unavailable, MinerU automatically falls back to CPU and emits a warning. RAGAnything does not validate devices beforehand or override this fallback behavior.

Can I use multiple different devices for different documents in the same RAGAnything instance?

Yes. Since device is passed per-call rather than set at initialization, you can process one document with device="cuda:0" and another with device="cpu" using the same RAGAnything or MinerUParser instance. The parameter is forwarded fresh for each parse_document invocation.

Does RAGAnything support distributed multi-GPU processing for a single document?

No. RAGAnything invokes MinerU as a single subprocess per document. MinerU itself does not implement model-parallel or data-parallel distribution across multiple GPUs for single-document processing. For multi-GPU throughput, run multiple RAGAnything instances or async tasks with different cuda:N assignments.

How do I verify that my NPU or MPS device is actually being used?

Enable debug logging to see MinerU's initialization messages, or monitor system-specific tools: npu-smi for Huawei Ascend, or Activity Monitor/GPU tab on macOS for MPS utilization. RAGAnything does not currently expose device utilization metrics directly.

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