{"record":{"id":"8e17c12a309b5c14","repo":"opendatalab/MinerU","slug":"please-install-vllm-to-use-the-vllm-engine-backend","errorCode":null,"errorMessage":"Please install vllm to use the vllm-engine backend.","messagePattern":"Please install vllm to use the vllm-engine backend\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"mineru/backend/vlm/vlm_analyze.py","lineNumber":122,"sourceCode":"                        use_fast=True,\n                    )\n                    if batch_size == 0:\n                        batch_size = set_default_batch_size()\n                elif backend == \"mlx-engine\":\n                    mlx_supported = is_mac_os_version_supported()\n                    if not mlx_supported:\n                        raise EnvironmentError(\"mlx-engine backend is only supported on macOS 13.5+ with Apple Silicon.\")\n                    from mineru_vl_utils.mlx_compat import load_mlx_model\n                    model, processor = load_mlx_model(model_path)\n                else:\n                    if os.getenv('OMP_NUM_THREADS') is None:\n                        os.environ[\"OMP_NUM_THREADS\"] = \"1\"\n\n                    if backend == \"vllm-engine\":\n                        try:\n                            import vllm\n                        except ImportError:\n                            raise ImportError(\"Please install vllm to use the vllm-engine backend.\")\n\n                        kwargs = mod_kwargs_by_device_type(kwargs, vllm_mode=\"sync_engine\")\n\n                        if \"compilation_config\" in kwargs:\n                            if isinstance(kwargs[\"compilation_config\"], str):\n                                try:\n                                    kwargs[\"compilation_config\"] = json.loads(kwargs[\"compilation_config\"])\n                                except json.JSONDecodeError:\n                                    logger.warning(\n                                        f\"Failed to parse compilation_config as JSON: {kwargs['compilation_config']}\")\n                                    del kwargs[\"compilation_config\"]\n                        if \"gpu_memory_utilization\" not in kwargs:\n                            kwargs[\"gpu_memory_utilization\"] = set_default_gpu_memory_utilization()\n                        if \"model\" not in kwargs:\n                            kwargs[\"model\"] = model_path\n                        if enable_custom_logits_processors() and (\"logits_processors\" not in kwargs):\n                            from mineru_vl_utils import MinerULogitsProcessor\n                            kwargs[\"logits_processors\"] = [MinerULogitsProcessor]","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/vlm/vlm_analyze.py#L104-L140","documentation":"Raised on the vllm-engine branch (vlm_analyze.py) when `import vllm` fails. The synchronous vllm-engine backend constructs vllm.LLM(**kwargs), so vllm must be importable; the try/except converts the raw ImportError into guidance to install vllm.","triggerScenarios":"backend='vllm-engine' without vllm installed; vllm installed but failing to import due to CUDA/torch version mismatch; vllm built for a different Python version.","commonSituations":"Default lightweight install plus GPU backend selected; torch upgraded independently breaking vllm's compiled extensions; wrong-architecture wheels (e.g. CPU wheel of vllm).","solutions":["pip install vllm (matching your torch/CUDA and Python version).","If installed, run python -c \"import vllm\" to see the true error and align torch/vllm versions.","Without a GPU stack, use transformers backend or a remote http-client backend."],"exampleFix":"# before\nrun(backend=\"vllm-engine\", ...)  # ImportError\n\n# after\npip install vllm  # or: pip install -e \"mineru[vllm]\" per docs\nrun(backend=\"vllm-engine\", ...)","handlingStrategy":"validation","validationCode":"def vllm_available() -> bool:\n    try:\n        import vllm  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not vllm_available():\n    backend = \"transformers\"  # or \"http-client\" to remote GPU server","typeGuard":null,"tryCatchPattern":"try:\n    vlm_analyze(..., backend=\"vllm-engine\")\nexcept ImportError as e:\n    if \"install vllm\" in str(e):\n        raise RuntimeError(\"environment missing vllm; deploy GPU image or switch backend\") from e\n    raise","preventionTips":["Build a GPU image that pre-installs torch+cuda and vllm together.","Probe `import vllm` during deployment smoke tests.","Keep torch and vllm versions locked as a pair."],"tags":["vllm","dependency","import","vlm","engine"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}