Hardware Accelerator Support#

Device Detection & Priority#

MinerU auto-selects the compute device at startup via get_device() in mineru/utils/config_reader.py. The selection order is:

CUDA → MPS → NPU → GCU → MUSA → MLU → SDAA → CPU

Each backend is probed with a try/except chain — if the import or availability check throws, the next backend is tried. Set MINERU_DEVICE_MODE=<device> to bypass auto-detection and force a specific backend .

Supported Backends#

Device	Identifier	Hardware	Notes
CUDA	`cuda`	NVIDIA GPUs	Highest priority; supports FlashAttention, pinned memory, non-blocking transfers
MPS	`mps`	Apple Silicon (M1/M2/M3)	2nd priority; requires `PYTORCH_ENABLE_MPS_FALLBACK=1`; no FlashAttention
NPU	`npu`	Huawei Ascend (910B)	Via `torch_npu`; `attn_implementation="eager"` for MFR model
GCU	`gcu`	Enflame / 燧原 (S60)	Via `torch.gcu`; device selection via `TOPS_VISIBLE_DEVICES`
MUSA	`musa`	Moore Threads (MTT S4000)	Via `torch.musa`
MLU	`mlu`	Cambricon (MLU590-M9D)	Via `torch.mlu`; supports vLLM and LMDeploy backends
SDAA	`sdaa`	Hygon DCU / SDAA	Via `torch.sdaa`
CPU	`cpu`	Fallback	Used when no accelerator is found

Per-Device Memory Utilities#

mineru/utils/model_utils.py provides three key functions that all backends share:

get_vram(device) — returns total device memory in GB. Reads MINERU_VIRTUAL_VRAM_SIZE first; falls back to device-specific APIs (torch.cuda, torch_npu.npu, torch.gcu, torch.musa, torch.mlu, torch.sdaa). Unrecognized devices (e.g., MPS) default to 1 GB.
clean_memory(device) — calls the device-specific empty_cache() for CUDA, NPU, MPS, GCU, MUSA, MLU, and SDAA, then runs gc.collect().
clean_vram(device, vram_threshold=8) — fires clean_memory() only when get_vram() ≤ threshold (default 8 GB). On high-VRAM devices (≥ 32 GB), cleanup is skipped unless MINERU_VIRTUAL_VRAM_SIZE overrides the reported size.

Batch Ratio Auto-Scaling#

pipeline_analyze.py scales inference batch sizes based on detected VRAM:

VRAM	`batch_ratio`
≥ 32 GB	16
≥ 16 GB	8
≥ 8 GB	4
≥ 6 GB	2
< 6 GB	1

Override with MINERU_VIRTUAL_VRAM_SIZE=<GB> (changes reported VRAM) to tune batch sizing on any device.

Platform-Specific Notes#

GCU (Enflame / 燧原)#

Tested on Enflame S60, Ubuntu 22.04, driver 1.7.0.9
Deploy via docker/china/gcu.Dockerfile
All MinerU modes (pipeline, vlm/hybrid-engine, HTTP client, FastAPI, Gradio, OpenAI-server) are supported and stable
Device selection: use TOPS_VISIBLE_DEVICES (analogous to CUDA_VISIBLE_DEVICES)
Monitor card utilization: efsmi

MUSA (Moore Threads)#

Tested on MTT S4000
Deploy via docker/china/musa.Dockerfile

MLU (Cambricon)#

Tested on MLU590-M9D
Deploy via docker/china/ Dockerfiles; supports both vLLM and LMDeploy backends

NPU (Ascend)#

Tested on 910B2
Deploy via docker/china/npu.Dockerfile
Memory fragmentation is the primary failure mode on high-VRAM 910B devices — see Ascend NPU Support

Environment Variables Reference#

Variable	Scope	Effect
`MINERU_DEVICE_MODE`	All	Force device selection; bypasses auto-detection
`MINERU_VIRTUAL_VRAM_SIZE`	All	Override reported VRAM (GB); affects batch ratio and `clean_vram` trigger
`MINERU_VLLM_DEVICE`	VLM backend	Injects device-specific vLLM kwargs; `corex` → CUDA-graph config, `kxpu` → custom splitting ops + `block_size=128` + prefix caching disabled
`MINERU_LMDEPLOY_DEVICE`	Pipeline backend	`corex` disables OCR-det batching; other values enable it
`TOPS_VISIBLE_DEVICES`	GCU only	Select specific Enflame GCU card(s), analogous to `CUDA_VISIBLE_DEVICES`
`PYTORCH_NPU_ALLOC_CONF`	NPU only	E.g. `max_split_size_mb:128` to reduce memory fragmentation on Ascend
`PYTORCH_ENABLE_MPS_FALLBACK`	MPS only	Set to `1` to allow unsupported ops to fall back to CPU

Key Source Files#

File	Purpose
`mineru/utils/config_reader.py`	`get_device()` — device auto-selection logic
`mineru/utils/model_utils.py`	`clean_memory()`, `clean_vram()`, `get_vram()`
`mineru/backend/pipeline/pipeline_analyze.py`	Batch ratio scaling; `MINERU_LMDEPLOY_DEVICE` handling
`mineru/backend/vlm/utils.py`	`_get_device_config()`, `mod_kwargs_by_device_type()` for `MINERU_VLLM_DEVICE`
`docs/zh/usage/acceleration_cards/`	Per-platform deployment guides (Enflame, Cambricon, Moore Threads, Ascend, etc.)