opendatalab/MinerU · error · ImportError

Please install lmdeploy to use the lmdeploy-engine backend.

Error message

Please install lmdeploy to use the lmdeploy-engine backend.

What it means

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.

Source

Thrown at mineru/backend/vlm/vlm_analyze.py:180

                                except (json.JSONDecodeError, TypeError) as e:
                                    logger.warning(
                                        f"Failed to parse compilation_config: {kwargs['compilation_config']}, error: {e}")
                                    del kwargs["compilation_config"]
                        if "gpu_memory_utilization" not in kwargs:
                            kwargs["gpu_memory_utilization"] = set_default_gpu_memory_utilization()
                        if "model" not in kwargs:
                            kwargs["model"] = model_path
                        if enable_custom_logits_processors() and ("logits_processors" not in kwargs):
                            from mineru_vl_utils import MinerULogitsProcessor
                            kwargs["logits_processors"] = [MinerULogitsProcessor]
                        # 使用kwargs为 vllm初始化参数
                        vllm_async_llm = AsyncLLM.from_engine_args(AsyncEngineArgs(**kwargs))
                    elif backend == "lmdeploy-engine":
                        try:
                            from lmdeploy import PytorchEngineConfig, TurbomindEngineConfig
                            from lmdeploy.serve.vl_async_engine import VLAsyncEngine
                        except ImportError:
                            raise ImportError("Please install lmdeploy to use the lmdeploy-engine backend.")
                        if "cache_max_entry_count" not in kwargs:
                            kwargs["cache_max_entry_count"] = 0.5

                        device_type = os.getenv("MINERU_LMDEPLOY_DEVICE", "")
                        if device_type == "":
                            if "lmdeploy_device" in kwargs:
                                device_type = kwargs.pop("lmdeploy_device")
                                if device_type not in ["cuda", "ascend", "maca", "camb"]:
                                    raise ValueError(f"Unsupported lmdeploy device type: {device_type}")
                            else:
                                device_type = "cuda"
                        lm_backend = os.getenv("MINERU_LMDEPLOY_BACKEND", "")
                        if lm_backend == "":
                            if "lmdeploy_backend" in kwargs:
                                lm_backend = kwargs.pop("lmdeploy_backend")
                                if lm_backend not in ["pytorch", "turbomind"]:
                                    raise ValueError(f"Unsupported lmdeploy backend: {lm_backend}")
                            else:

View on GitHub (pinned to 4fe4bde114)

Solutions

1. pip install lmdeploy (a version with VLAsyncEngine; check MinerU docs for the pinned range).
2. Verify python -c "from lmdeploy.serve.vl_async_engine import VLAsyncEngine" and adjust the lmdeploy version if it fails.
3. Otherwise switch to vllm-engine, transformers, or a remote http-client backend.

Example fix

# before
run(backend="lmdeploy-engine", ...)  # ImportError

# after
pip install lmdeploy
run(backend="lmdeploy-engine", ...)

def lmdeploy_available() -> bool:
    try:
        from lmdeploy import PytorchEngineConfig, TurbomindEngineConfig  # noqa
        from lmdeploy.serve.vl_async_engine import VLAsyncEngine  # noqa
        return True
    except ImportError:
        return False

if not lmdeploy_available():
    backend = "vllm-engine" if vllm_available() else "transformers"

try:
    vlm_analyze(..., backend="lmdeploy-engine")
except ImportError as e:
    if "install lmdeploy" in str(e):
        raise RuntimeError("missing lmdeploy; install it or select another backend") from e
    raise

When it happens

Trigger: 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.

Common situations: Choosing lmdeploy for Ascend/older GPUs without installing it; lmdeploy version drift after upgrades; minimal container images.

Related errors

• Please install vllm to use the vllm-engine backend.
• Please install vllm to use the vllm-async-engine backend.
• Please install transformers to use the transformers backend.
• Please install vllm to use the vllm-async-engine backend.
• CUDA is not available.

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/8aafaa68d4c17725. Report an issue: GitHub.