opendatalab/MinerU · error · ImportError

Please install vllm to use the vllm-async-engine backend.

Error message

Please install vllm to use the vllm-async-engine backend.

What it means

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.

Source

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

                                    logger.warning(
                                        f"Failed to parse compilation_config as JSON: {kwargs['compilation_config']}")
                                    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_llm = vllm.LLM(**kwargs)
                    elif backend == "vllm-async-engine":
                        try:
                            from vllm.engine.arg_utils import AsyncEngineArgs
                            from vllm.v1.engine.async_llm import AsyncLLM
                            from vllm.config import CompilationConfig
                        except ImportError:
                            raise ImportError("Please install vllm to use the vllm-async-engine backend.")

                        kwargs = mod_kwargs_by_device_type(kwargs, vllm_mode="async_engine")

                        if "compilation_config" in kwargs:
                            if isinstance(kwargs["compilation_config"], dict):
                                # 如果是字典，转换为 CompilationConfig 对象
                                kwargs["compilation_config"] = CompilationConfig(**kwargs["compilation_config"])
                            elif isinstance(kwargs["compilation_config"], str):
                                # 如果是 JSON 字符串，先解析再转换
                                try:
                                    config_dict = json.loads(kwargs["compilation_config"])
                                    kwargs["compilation_config"] = CompilationConfig(**config_dict)
                                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()

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Install a vllm version compatible with MinerU (docs list the supported range) and verify python -c "from vllm.v1.engine.async_llm import AsyncLLM".
2. If you only have sync vllm working, use backend='vllm-engine' instead.
3. Pin vllm in your requirements to avoid surprise upgrades moving internal modules.

Example fix

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

# after
pip install "vllm>=0.10"
python -c "from vllm.v1.engine.async_llm import AsyncLLM"  # sanity check
run(backend="vllm-async-engine", ...)

def vllm_async_available() -> bool:
    try:
        from vllm.engine.arg_utils import AsyncEngineArgs
        from vllm.v1.engine.async_llm import AsyncLLM
        from vllm.config import CompilationConfig
        return True
    except ImportError:
        return False

try:
    vlm_analyze(..., backend="vllm-async-engine")
except ImportError as e:
    if "install vllm" in str(e):
        vlm_analyze(..., backend="vllm-engine")  # sync fallback if vllm present
    else:
        raise

When it happens

Trigger: backend='vllm-async-engine' with vllm missing; vllm present but old enough that vllm.v1.engine.async_llm does not exist; partially upgraded vllm.

Common situations: Async service integrations (FastAPI workers) choosing async-engine on an env built for the sync engine; vllm major-version upgrades relocating v1 engine modules.

Related errors

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

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