{"record":{"id":"ba6af94fc3505160","repo":"opendatalab/MinerU","slug":"please-install-vllm-to-use-the-vllm-async-engine-b-ba6af9","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/vlm_analyze.py","lineNumber":149,"sourceCode":"                                    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]\n                        # 使用kwargs为 vllm初始化参数\n                        vllm_llm = vllm.LLM(**kwargs)\n                    elif backend == \"vllm-async-engine\":\n                        try:\n                            from vllm.engine.arg_utils import AsyncEngineArgs\n                            from vllm.v1.engine.async_llm import AsyncLLM\n                            from vllm.config import CompilationConfig\n                        except ImportError:\n                            raise ImportError(\"Please install vllm to use the vllm-async-engine backend.\")\n\n                        kwargs = mod_kwargs_by_device_type(kwargs, vllm_mode=\"async_engine\")\n\n                        if \"compilation_config\" in kwargs:\n                            if isinstance(kwargs[\"compilation_config\"], dict):\n                                # 如果是字典，转换为 CompilationConfig 对象\n                                kwargs[\"compilation_config\"] = CompilationConfig(**kwargs[\"compilation_config\"])\n                            elif isinstance(kwargs[\"compilation_config\"], str):\n                                # 如果是 JSON 字符串，先解析再转换\n                                try:\n                                    config_dict = json.loads(kwargs[\"compilation_config\"])\n                                    kwargs[\"compilation_config\"] = CompilationConfig(**config_dict)\n                                except (json.JSONDecodeError, TypeError) as e:\n                                    logger.warning(\n                                        f\"Failed to parse compilation_config: {kwargs['compilation_config']}, error: {e}\")\n                                    del kwargs[\"compilation_config\"]\n                        if \"gpu_memory_utilization\" not in kwargs:\n                            kwargs[\"gpu_memory_utilization\"] = set_default_gpu_memory_utilization()","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/vlm/vlm_analyze.py#L131-L167","documentation":"Raised on the vllm-async-engine branch (vlm_analyze.py) when importing AsyncEngineArgs/AsyncLLM/CompilationConfig from vllm fails. The async engine drives vLLM via AsyncLLM.from_engine_args, so these vllm internals are required; absence (or a vllm version that moved them) raises this ImportError.","triggerScenarios":"backend='vllm-async-engine' with vllm missing; vllm present but old enough that vllm.v1.engine.async_llm does not exist; partially upgraded vllm.","commonSituations":"Async service integrations (FastAPI workers) choosing async-engine on an env built for the sync engine; vllm major-version upgrades relocating v1 engine modules.","solutions":["Install a vllm version compatible with MinerU (docs list the supported range) and verify python -c \"from vllm.v1.engine.async_llm import AsyncLLM\".","If you only have sync vllm working, use backend='vllm-engine' instead.","Pin vllm in your requirements to avoid surprise upgrades moving internal modules."],"exampleFix":"# before\nrun(backend=\"vllm-async-engine\", ...)  # ImportError\n\n# after\npip install \"vllm>=0.10\"\npython -c \"from vllm.v1.engine.async_llm import AsyncLLM\"  # sanity check\nrun(backend=\"vllm-async-engine\", ...)","handlingStrategy":"validation","validationCode":"def vllm_async_available() -> bool:\n    try:\n        from vllm.engine.arg_utils import AsyncEngineArgs\n        from vllm.v1.engine.async_llm import AsyncLLM\n        from vllm.config import CompilationConfig\n        return True\n    except ImportError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    vlm_analyze(..., backend=\"vllm-async-engine\")\nexcept ImportError as e:\n    if \"install vllm\" in str(e):\n        vlm_analyze(..., backend=\"vllm-engine\")  # sync fallback if vllm present\n    else:\n        raise","preventionTips":["Pin vllm to a version whose v1 async engine exists and matches MinerU's tested range.","Probe the three internal imports in readiness checks for async services.","Have a sync-engine code path ready as fallback in async integrations."],"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"}