{"record":{"id":"7ae07224266d4555","repo":"opendatalab/MinerU","slug":"please-install-vllm-to-use-the-vllm-async-engine-b","errorCode":null,"errorMessage":"Please install vllm to use the vllm-async-engine backend.","messagePattern":"Please install vllm to use the vllm-async-engine backend\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"mineru/backend/vlm/utils.py","lineNumber":223,"sourceCode":"            _add_server_arg_if_missing(\n                args, \"compilation-config\",\n                json.dumps(value, separators=(',', ':'))\n            )\n        else:\n            # 转换 key 格式: block_size -> block-size\n            arg_name = key.replace(\"_\", \"-\")\n            if arg_name in {\"enable-chunked-prefill\", \"enable-prefix-caching\"} and value is False:\n                _add_server_flag_if_missing(args, f\"no-{arg_name}\")\n                continue\n            _add_server_arg_if_missing(args, arg_name, str(value))\n\n\ndef _apply_engine_config(kwargs: dict, config: dict, vllm_mode: str) -> None:\n    \"\"\"应用 engine 模式的配置\"\"\"\n    try:\n        from vllm.config import CompilationConfig\n    except ImportError:\n        raise ImportError(\"Please install vllm to use the vllm-async-engine backend.\")\n\n    for key, value in config.items():\n        if key == \"compilation_config_dict\":\n            if vllm_mode == \"sync_engine\":\n                compilation_config = value\n            elif vllm_mode == \"async_engine\":\n                compilation_config = CompilationConfig(**value)\n            else:\n                continue\n            _add_engine_kwarg_if_missing(kwargs, \"compilation_config\", compilation_config)\n        else:\n            _add_engine_kwarg_if_missing(kwargs, key, value)\n","sourceCodeStart":205,"sourceCodeEnd":236,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/vlm/utils.py#L205-L236","documentation":"Raised by _apply_engine_config() (mineru/backend/vlm/utils.py) when applying engine-mode config for the vllm-async-engine backend: `from vllm.config import CompilationConfig` raised ImportError, meaning vllm is not installed (or too old to expose vllm.config.CompilationConfig). The message tells the user the async-engine backend has vllm as a hard dependency.","triggerScenarios":"Selecting backend='vllm-async-engine' in a base install that lacks the [vllm] extra; vllm version predating vllm.config.CompilationConfig; broken vllm install whose top-level package fails to import submodules.","commonSituations":"pip install mineru without extras then choosing a vlm engine backend; GPU environments where vllm was skipped to save space; upgrading vllm to a refactor that moved CompilationConfig.","solutions":["Install vllm in the environment (e.g. pip install vllm, ideally the version MinerU's docs pin).","If vllm IS installed, verify `python -c \"from vllm.config import CompilationConfig\"` and upgrade/downgrade vllm to a compatible release if it fails.","Alternatively use a backend whose dependencies you have (transformers, mlx-engine, or http-client)."],"exampleFix":"# before\nrun(backend=\"vllm-async-engine\", ...)  # ImportError\n\n# after\npip install vllm\nrun(backend=\"vllm-async-engine\", ...)","handlingStrategy":"validation","validationCode":"def vllm_async_available() -> bool:\n    try:\n        from vllm.config import CompilationConfig  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not vllm_async_available():\n    backend = \"vllm-engine\" if sync_ok() else \"transformers\"","typeGuard":null,"tryCatchPattern":"try:\n    vlm_analyze(..., backend=\"vllm-async-engine\")\nexcept ImportError as e:\n    if \"install vllm\" in str(e):\n        log.error(\"vllm missing; falling back to transformers backend\")\n        vlm_analyze(..., backend=\"transformers\")\n    else:\n        raise","preventionTips":["Install via MinerU's documented extras so engine deps come along.","Add an import probe for vllm.config in service startup checks.","Pin vllm to a version compatible with the async engine path."],"tags":["vllm","dependency","import","vlm","async-engine"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}