What causes "Please install vllm to use the vllm-async-engine backend." in opendatalab/MinerU?

Install vllm in the environment (e.g. pip install vllm, ideally the version MinerU's docs pin).

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

Source

Thrown at mineru/backend/vlm/utils.py:223

            _add_server_arg_if_missing(
                args, "compilation-config",
                json.dumps(value, separators=(',', ':'))
            )
        else:
            # 转换 key 格式: block_size -> block-size
            arg_name = key.replace("_", "-")
            if arg_name in {"enable-chunked-prefill", "enable-prefix-caching"} and value is False:
                _add_server_flag_if_missing(args, f"no-{arg_name}")
                continue
            _add_server_arg_if_missing(args, arg_name, str(value))


def _apply_engine_config(kwargs: dict, config: dict, vllm_mode: str) -> None:
    """应用 engine 模式的配置"""
    try:
        from vllm.config import CompilationConfig
    except ImportError:
        raise ImportError("Please install vllm to use the vllm-async-engine backend.")

    for key, value in config.items():
        if key == "compilation_config_dict":
            if vllm_mode == "sync_engine":
                compilation_config = value
            elif vllm_mode == "async_engine":
                compilation_config = CompilationConfig(**value)
            else:
                continue
            _add_engine_kwarg_if_missing(kwargs, "compilation_config", compilation_config)
        else:
            _add_engine_kwarg_if_missing(kwargs, key, value)

View on GitHub (pinned to 4fe4bde114)

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).

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

def vllm_async_available() -> bool:
    try:
        from vllm.config import CompilationConfig  # noqa: F401
        return True
    except ImportError:
        return False

if not vllm_async_available():
    backend = "vllm-engine" if sync_ok() else "transformers"

Try / catch

try:
    vlm_analyze(..., backend="vllm-async-engine")
except ImportError as e:
    if "install vllm" in str(e):
        log.error("vllm missing; falling back to transformers backend")
        vlm_analyze(..., backend="transformers")
    else:
        raise

Prevention

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.

When it happens

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

Common situations: 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.

Related errors

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