opendatalab/MinerU · critical · RuntimeError

NPU is selected as device, but torch_npu is not available. P

Error message

NPU is selected as device, but torch_npu is not available. Please ensure that the torch_npu package is installed correctly.

What it means

Identical NPU guard to model_init.py:354, but on the batch-analysis path in pipeline_analyze.py:348. After get_device() resolves the device, an 'npu' prefix triggers a torch_npu import/availability probe; failure raises this RuntimeError with the original exception chained.

Source

Thrown at mineru/backend/pipeline/pipeline_analyze.py:348

def batch_image_analyze(
        images_with_extra_info: List[Tuple[Image.Image, bool, str]],
        formula_enable=True,
        table_enable=True):

    from .batch_analyze import BatchAnalyze

    model_manager = ModelSingleton()

    device = get_device()

    if str(device).startswith('npu'):
        try:
            import torch_npu
            if torch_npu.npu.is_available():
                torch_npu.npu.set_compile_mode(jit_compile=False)
        except Exception as e:
            raise RuntimeError(
                "NPU is selected as device, but torch_npu is not available. "
                "Please ensure that the torch_npu package is installed correctly."
            ) from e

    gpu_memory = get_vram(device)
    if gpu_memory >= 32:
        batch_ratio = 16
    elif gpu_memory >= 16:
        batch_ratio = 8
    elif gpu_memory >= 8:
        batch_ratio = 4
    elif gpu_memory >= 6:
        batch_ratio = 2
    else:
        batch_ratio = 1
    logger.info(
            f'GPU Memory: {gpu_memory} GB, Batch Ratio: {batch_ratio}. '
    )

View on GitHub (pinned to 4fe4bde114)

Solutions

Install the torch_npu build matching your torch version.
Ensure the service/batch process inherits Ascend env (source set_env.sh) and npu-smi info works as the same user.
Smoke-test: python -c "import torch_npu; assert torch_npu.npu.is_available()".
Force a different device if NPU was auto-detected unintentionally.

Example fix

# before
python batch_analyze.py  # RuntimeError: torch_npu not available

# after
source /usr/local/Ascend/ascend-toolkit/set_env.sh
pip install torch-npu==<version-matching-torch>
python batch_analyze.py

Defensive patterns

Strategy: validation

Validate before calling

def npu_ready() -> bool:
    try:
        import torch_npu
        return torch_npu.npu.is_available()
    except Exception:
        return False

if not npu_ready():
    os.environ["MINERU_DEVICE_MODEL"] = "cpu"  # explicit device for batch run

Try / catch

try:
    analyzer = BatchAnalyze(...)
except RuntimeError as e:
    if "torch_npu" in str(e):
        abort_with_runbook("npu-setup", e)
    raise

Prevention

Containerize the Ascend env: driver + CANN + pinned torch/torch_npu layers.
Run an npu readiness check as the first job step on NPU runners.
Never let device auto-detect surprise you — set the device explicitly per machine.

When it happens

Trigger: Running batch analysis with device resolved to npu while torch_npu is missing, mismatched with torch, or CANN runtime is unavailable.

Common situations: Works in single-doc mode after manual torch_npu setup in one shell, fails in batch service started without sourcing CANN env; fresh Ascend container without the pip package; torch upgraded without reinstalling torch_npu.

Related errors

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/dd287a3770424ce6. Report an issue: GitHub.