{"record":{"id":"dd287a3770424ce6","repo":"opendatalab/MinerU","slug":"npu-is-selected-as-device-but-torch-npu-is-not-av-dd287a","errorCode":null,"errorMessage":"NPU is selected as device, but torch_npu is not available. Please ensure that the torch_npu package is installed correctly.","messagePattern":"NPU is selected as device, but torch_npu is not available\\. Please ensure that the torch_npu package is installed correctly\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"mineru/backend/pipeline/pipeline_analyze.py","lineNumber":348,"sourceCode":"\ndef batch_image_analyze(\n        images_with_extra_info: List[Tuple[Image.Image, bool, str]],\n        formula_enable=True,\n        table_enable=True):\n\n    from .batch_analyze import BatchAnalyze\n\n    model_manager = ModelSingleton()\n\n    device = get_device()\n\n    if str(device).startswith('npu'):\n        try:\n            import torch_npu\n            if torch_npu.npu.is_available():\n                torch_npu.npu.set_compile_mode(jit_compile=False)\n        except Exception as e:\n            raise RuntimeError(\n                \"NPU is selected as device, but torch_npu is not available. \"\n                \"Please ensure that the torch_npu package is installed correctly.\"\n            ) from e\n\n    gpu_memory = get_vram(device)\n    if gpu_memory >= 32:\n        batch_ratio = 16\n    elif gpu_memory >= 16:\n        batch_ratio = 8\n    elif gpu_memory >= 8:\n        batch_ratio = 4\n    elif gpu_memory >= 6:\n        batch_ratio = 2\n    else:\n        batch_ratio = 1\n    logger.info(\n            f'GPU Memory: {gpu_memory} GB, Batch Ratio: {batch_ratio}. '\n    )","sourceCodeStart":330,"sourceCodeEnd":366,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/pipeline/pipeline_analyze.py#L330-L366","documentation":"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.","triggerScenarios":"Running batch analysis with device resolved to npu while torch_npu is missing, mismatched with torch, or CANN runtime is unavailable.","commonSituations":"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.","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."],"exampleFix":"# before\npython batch_analyze.py  # RuntimeError: torch_npu not available\n\n# after\nsource /usr/local/Ascend/ascend-toolkit/set_env.sh\npip install torch-npu==<version-matching-torch>\npython batch_analyze.py","handlingStrategy":"validation","validationCode":"def npu_ready() -> bool:\n    try:\n        import torch_npu\n        return torch_npu.npu.is_available()\n    except Exception:\n        return False\n\nif not npu_ready():\n    os.environ[\"MINERU_DEVICE_MODEL\"] = \"cpu\"  # explicit device for batch run","typeGuard":null,"tryCatchPattern":"try:\n    analyzer = BatchAnalyze(...)\nexcept RuntimeError as e:\n    if \"torch_npu\" in str(e):\n        abort_with_runbook(\"npu-setup\", e)\n    raise","preventionTips":["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."],"tags":["npu","ascend","environment","torch-npu","batch","device"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}