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

> Learn how to configure MinerU with GPU acceleration (CUDA, NPU, MPS) in RAGAnything. Streamline your RAG setup by setting the device parameter in RAGAnything's parsing methods.

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

---

**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`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/parser.py), the `MinerUParser._run_mineru_command` method builds the subprocess command that invokes MinerU. This is where the `-d` flag is appended:

```python

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

```python

# 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`:

```python

# 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`:

```python

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

```bash
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:

```python
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:

```python
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:

```python

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

```python
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.