{"record":{"id":"8aafaa68d4c17725","repo":"opendatalab/MinerU","slug":"please-install-lmdeploy-to-use-the-lmdeploy-engine","errorCode":null,"errorMessage":"Please install lmdeploy to use the lmdeploy-engine backend.","messagePattern":"Please install lmdeploy to use the lmdeploy-engine backend\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"mineru/backend/vlm/vlm_analyze.py","lineNumber":180,"sourceCode":"                                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()\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_async_llm = AsyncLLM.from_engine_args(AsyncEngineArgs(**kwargs))\n                    elif backend == \"lmdeploy-engine\":\n                        try:\n                            from lmdeploy import PytorchEngineConfig, TurbomindEngineConfig\n                            from lmdeploy.serve.vl_async_engine import VLAsyncEngine\n                        except ImportError:\n                            raise ImportError(\"Please install lmdeploy to use the lmdeploy-engine backend.\")\n                        if \"cache_max_entry_count\" not in kwargs:\n                            kwargs[\"cache_max_entry_count\"] = 0.5\n\n                        device_type = os.getenv(\"MINERU_LMDEPLOY_DEVICE\", \"\")\n                        if device_type == \"\":\n                            if \"lmdeploy_device\" in kwargs:\n                                device_type = kwargs.pop(\"lmdeploy_device\")\n                                if device_type not in [\"cuda\", \"ascend\", \"maca\", \"camb\"]:\n                                    raise ValueError(f\"Unsupported lmdeploy device type: {device_type}\")\n                            else:\n                                device_type = \"cuda\"\n                        lm_backend = os.getenv(\"MINERU_LMDEPLOY_BACKEND\", \"\")\n                        if lm_backend == \"\":\n                            if \"lmdeploy_backend\" in kwargs:\n                                lm_backend = kwargs.pop(\"lmdeploy_backend\")\n                                if lm_backend not in [\"pytorch\", \"turbomind\"]:\n                                    raise ValueError(f\"Unsupported lmdeploy backend: {lm_backend}\")\n                            else:","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/vlm/vlm_analyze.py#L162-L198","documentation":"Raised on the lmdeploy-engine branch (vlm_analyze.py) when `from lmdeploy import PytorchEngineConfig, TurbomindEngineConfig` plus the vl_async_engine import fails. The lmdeploy-engine backend needs the lmdeploy package (with VL async engine support) to serve the VLM model; its absence is converted into this actionable ImportError.","triggerScenarios":"backend='lmdeploy-engine' with lmdeploy not installed, an lmdeploy build without vision-language/async serving modules, or an lmdeploy version where serve.vl_async_engine moved.","commonSituations":"Choosing lmdeploy for Ascend/older GPUs without installing it; lmdeploy version drift after upgrades; minimal container images.","solutions":["pip install lmdeploy (a version with VLAsyncEngine; check MinerU docs for the pinned range).","Verify python -c \"from lmdeploy.serve.vl_async_engine import VLAsyncEngine\" and adjust the lmdeploy version if it fails.","Otherwise switch to vllm-engine, transformers, or a remote http-client backend."],"exampleFix":"# before\nrun(backend=\"lmdeploy-engine\", ...)  # ImportError\n\n# after\npip install lmdeploy\nrun(backend=\"lmdeploy-engine\", ...)","handlingStrategy":"validation","validationCode":"def lmdeploy_available() -> bool:\n    try:\n        from lmdeploy import PytorchEngineConfig, TurbomindEngineConfig  # noqa\n        from lmdeploy.serve.vl_async_engine import VLAsyncEngine  # noqa\n        return True\n    except ImportError:\n        return False\n\nif not lmdeploy_available():\n    backend = \"vllm-engine\" if vllm_available() else \"transformers\"","typeGuard":null,"tryCatchPattern":"try:\n    vlm_analyze(..., backend=\"lmdeploy-engine\")\nexcept ImportError as e:\n    if \"install lmdeploy\" in str(e):\n        raise RuntimeError(\"missing lmdeploy; install it or select another backend\") from e\n    raise","preventionTips":["Install lmdeploy in the target image and pin its version.","Verify the VLAsyncEngine import at deploy time, not at first request.","Document which backends each deployment profile ships (Ascend -> lmdeploy, NVIDIA -> vllm)."],"tags":["lmdeploy","dependency","import","vlm","engine"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}