MinerU 扩展模块安装实战：core、vllm、lmdeploy、s3 与轻量 HTTP Client 模式详解

本文基于 MinerU 官方《扩展模块安装指南》，系统讲解 MinerU 各扩展模块（core、s3、vllm、lmdeploy、pipeline 等）的安装命令、适用场景与显存/驱动要求，并结合 pyproject.toml 中的依赖声明和 mineru/cli/backend_options.py 等源码，说明每个扩展模块如何对应到具体的解析后端与服务端入口，帮助你在不同硬件条件下选择并落地最合适的安装方案。

一、为什么 MinerU 要拆分扩展模块

MinerU 将 PDF、图片、DOCX、PPTX、XLSX 解析为可供 LLM 使用的 Markdown/JSON。不同使用场景对依赖的诉求差异很大：

• 只做本地文档解析，需要 core（含 torch、transformers、onnxruntime、gradio 等重依赖）；
• 想用 vLLM 或 LMDeploy 加速 VLM 推理，需要对应的推理框架；
• 需要从 S3 读写文件，需要 boto3；
• 边缘设备只做"客户端"，只依赖基础包即可，无需任何 GPU 依赖。

因此 MinerU 在 pyproject.toml 中通过 [project.optional-dependencies] 定义了细粒度的扩展分组，按需安装可以避免在不必要的设备上引入庞大的推理框架依赖。

二、常见场景与安装命令

2.1 核心功能安装（core）

core 模块是 MinerU 的核心依赖，包含常用解析功能，不包含 vllm/lmdeploy/s3 等可选模块。安装此模块可以确保 MinerU 基本功能正常运行：

uv pip install "mineru[core]"

从 pyproject.toml 的声明看，core 是三个分组的组合：

core = [
    "mineru[vlm]",
    "mineru[pipeline]",
    "mineru[gradio]",
]

其中：

• vlm 组引入 torch>=2.6.0,<3、transformers>=4.57.3,<5.0.0、accelerate>=1.5.1，用于本地 VLM 推理；
• pipeline 组引入 PyYAML、shapely、pyclipper、torch、torchvision、onnxruntime>1.17.0 等，用于传统 OCR/版面分析管线；
• gradio 组引入 gradio 与 gradio-pdf，用于 WebUI。

这意味着安装 core 后即可覆盖本地 pipeline、vlm-engine、hybrid-engine 三种后端（见 mineru/cli/backend_options.py 中的 LOCAL_BACKEND_CHOICES）。

2.2 使用 S3 输入输出（s3）

如需通过 S3 读取或写入文件，请安装 s3 扩展模块：

uv pip install "mineru[s3]"

该分组在 pyproject.toml 中仅引入 boto3>=1.28.43，是一个非常轻量的可选依赖。MinerU 内部在 mineru/data/io/s3.py 中封装了 S3 的输入/输出访问逻辑，安装后即可在数据读写路径中使用 S3 地址。

2.3 使用 vllm 加速 VLM 模型推理

说明：vllm 和 lmdeploy 对 VLM 的推理加速效果和使用方式几乎相同，可根据实际情况选择其中之一安装使用，但不建议同时安装这两个模块，以避免潜在的依赖冲突。

vllm 模块提供了对 VLM 模型推理的加速支持，适用于具有 Volta 及以后架构的显卡（8G 显存及以上）。安装此模块可以显著提升模型推理速度：

uv pip install "mineru[core,vllm]"

在 pyproject.toml 中该分组的版本约束为 vllm>=0.10.1.1,<0.22.0。安装时需要注意以下几点（源自官方指南的提示）：

• 由于 vllm 扩展包已放开到 0.21 系列版本，默认安装通常会选择当前允许范围内更高的 vllm 版本。请确保物理机显卡驱动支持所安装 vllm 包对应的 CUDA 运行时，默认路径需要 CUDA 13.0 兼容驱动；
• 如需使用 CUDA 12.9 兼容环境，可参考 vLLM 官方安装文档选择对应的 CUDA 安装方式，或直接使用 Docker 部署 中的 vllm/vllm-openai:v0.21.0-cu129 基础镜像；
• 如在安装包含 vllm 的扩展包过程中发生异常，同样可参考 vLLM 官方文档尝试解决。

源码印证：vLLM 服务端如何被拉起

MinerU 在 pyproject.toml 的 [project.scripts] 中注册了 mineru-vllm-server 入口，指向 mineru/cli/vlm_server.py 的 vllm_server 函数；其实际实现位于 mineru/model/vlm/vllm_server.py。从源码可以看出几个关键默认行为：

• 默认监听端口为 30000（未显式传 --port 时自动追加 ["--port", "30000"]），这正是轻量客户端示例中 -u http://127.0.0.1:30000 的由来；
• 若未显式指定模型路径，会调用 auto_download_and_get_model_root_path("/", "vlm") 自动下载并定位 VLM 模型；
• 默认按设备类型设置 --gpu-memory-utilization，并可通过自定义 logits processor 追加 --logits-processors mineru_vl_utils:MinerULogitsProcessor；
• 启动前会将 OMP_NUM_THREADS 默认设为 1，然后以 serve <model_path> ... 方式调用 vLLM 自带的 main 入口。

2.4 使用 lmdeploy 加速 VLM 模型推理

说明：与 vllm 相同，二选一即可，不建议同时安装。

lmdeploy 模块同样提供对 VLM 模型推理的加速支持，适用于 Volta 及以后架构的显卡（8G 显存及以上）：

uv pip install "mineru[core,lmdeploy]"

pyproject.toml 中该分组声明为 lmdeploy>=0.10.2,<0.12 与 qwen-vl-utils>=0.0.14,<1。如在安装过程中发生异常，可参考 LMDeploy 官方安装文档尝试解决。

从 mineru/cli/vlm_server.py 的 openai_server 命令看，MinerU 还提供了统一的 mineru-openai-server 入口：当 --engine auto（默认）时，它优先尝试导入 vllm，失败则回退到 lmdeploy；两者都未安装时直接报错退出。因此在只安装了 lmdeploy 的机器上，mineru-openai-server 会自动选择 LMDeploy 引擎对外提供 OpenAI 兼容服务，与安装了 vllm 的机器使用体验一致。

2.5 安装轻量版 client 连接兼容 OpenAI 服务器（vlm-http-client 模式）

如果需要在边缘设备上安装轻量版 client 端，以连接兼容 OpenAI 接口的服务端来使用 VLM 模式，可以直接安装 mineru 基础包——它非常轻量，适合在只有 CPU 和网络连接的设备上使用：

uv pip install mineru
mineru -p <input_path> -o <output_path> -b vlm-http-client -u http://127.0.0.1:30000

这里的 -b vlm-http-client 对应源码 mineru/cli/backend_options.py 中的 BACKEND_VLM_HTTP_CLIENT，属于 HTTP_CLIENT_BACKEND_CHOICES；-u 参数在 mineru/cli/client.py 的定义中要求：当 backend 为 <vlm/hybrid>-http-client 时，必须指定 OpenAI 兼容服务的 server_url（例如 http://127.0.0.1:30000）。demo/demo.py 中的示例注释同样确认：vlm-http-client 用于连接远程 OpenAI 兼容 VLM 服务。根据 mineru/cli/api_request.py 中的说明，该模式"通过远程算力获得高精度，适合 OpenAI 兼容服务器，目前仅支持中文和英文文档"。

2.6 安装轻量版 client 连接兼容 OpenAI 服务器（hybrid-http-client 模式）

如果要在边缘设备上连接兼容 OpenAI 接口的服务端使用 hybrid 模式，可以安装 mineru 的 pipeline 扩展包。它相对较轻量，可以在只有 CPU 和网络连接的设备上使用；同时在支持 GPU 加速的设备上可以更快运行：

uv pip install "mineru[pipeline]"
mineru -p <input_path> -o <output_path> -b hybrid-http-client -u http://127.0.0.1:30000

hybrid-http-client 与 vlm-http-client 的核心差异（结合 mineru/cli/api_request.py 与 mineru/cli/client.py 的说明）：

模式	本地算力需求	特点	语言支持
vlm-http-client	几乎无（CPU+网络即可）	高精度，全部依赖远程算力	中文、英文
hybrid-http-client	少量本地算力	混合解析，远程算力为主，本地承担部分环节，可通过 --effort 切换 medium/high 行为	多语言

--effort 参数的取值与默认值在 mineru/cli/backend_options.py 中定义为 HYBRID_EFFORT_CHOICES = ("medium", "high")、DEFAULT_HYBRID_EFFORT = "medium"，仅对 hybrid-* 后端生效。

2.7 一站式安装（all，补充说明）

除官方指南列出的场景外，pyproject.toml 还定义了 all 分组，按操作系统平台自动裁剪可选依赖：

all = [
    "mineru[core]",
    "mineru[s3]",
    "mineru[mlx] ; sys_platform == 'darwin'",
    "mineru[vllm] ; sys_platform == 'linux'",
    "mineru[lmdeploy] ; sys_platform == 'win32'",
]

即：macOS 上追加 mlx（mlx-vlm>=0.3.3,<0.4），Linux 上追加 vllm，Windows 上追加 lmdeploy。这体现了官方"按平台选择推理引擎"的思路，与 vllm/lmdeploy 二选一的说明相互印证。需要说明的是，该分组不在扩展模块指南的正文场景中，属于源码中的补充能力，适合希望在单一平台上尽量装全的用户自行评估后使用。

三、扩展模块与解析后端的对应关系

MinerU 的 mineru 命令通过 -b/--backend 选择解析后端。mineru/cli/backend_options.py 定义了全部公开后端选项：

BACKEND_PIPELINE = "pipeline"
BACKEND_VLM_ENGINE = "vlm-engine"
BACKEND_HYBRID_ENGINE = "hybrid-engine"
BACKEND_VLM_HTTP_CLIENT = "vlm-http-client"
BACKEND_HYBRID_HTTP_CLIENT = "hybrid-http-client"
DEFAULT_BACKEND = BACKEND_HYBRID_ENGINE

• 本地后端 pipeline / vlm-engine / hybrid-engine 依赖 core（其中 vlm-engine 依赖 vlm 分组的 torch/transformers）；
• HTTP 客户端后端 vlm-http-client / hybrid-http-client 分别对应 2.5、2.6 节的轻量安装方案；
• 默认后端为 hybrid-engine（DEFAULT_BACKEND），即安装 core 后不带 -b 参数时直接走本地 hybrid 解析；
• 旧名称 vlm-auto-engine、hybrid-auto-engine 会被 normalize_backend 自动映射为新名称。

四、服务端命令速查

在 GPU 机器上提供 OpenAI 兼容服务时，pyproject.toml 注册了以下入口（均实现于 mineru/cli/vlm_server.py 及 mineru/model/vlm/ 下的各 server 模块）：

命令	作用	依赖扩展
mineru-vllm-server	以 vLLM 启动 VLM 服务（默认端口 30000，自动下载模型）	mineru[core,vllm]
mineru-lmdeploy-server	以 LMDeploy 启动 VLM 服务	mineru[core,lmdeploy]
mineru-openai-server	--engine auto 自动选择 vllm/lmdeploy 启动 OpenAI 兼容服务	二者装其一即可
mineru-api	启动 MinerU FastAPI Web API 服务	mineru[core]

边缘设备侧则只需基础包或 pipeline 分组，通过 -u 指定服务端地址即可接入，实现"重算力在服务器、轻客户端在边缘"的部署形态。

五、选型建议与注意事项

1. 本地 GPU 解析：显存 ≥8G 且显卡为 Volta 及以后架构时，安装 mineru[core,vllm] 或 mineru[core,lmdeploy]（二选一）以获得 VLM 推理加速；不满足硬件条件时，mineru[core] 使用本地 hybrid-engine/vlm-engine 后端。
2. 驱动/CUDA 匹配：默认安装的 vllm 高版本路径要求 CUDA 13.0 兼容驱动；CUDA 12.9 环境建议使用 Docker 部署 中的 v0.21.0-cu129 镜像（该 Dockerfile 默认集成 vllm 推理框架，适合规避环境兼容问题）。
3. 纯客户端场景：只有 CPU+网络的设备装基础包用 vlm-http-client（中英文文档）；需要多语言或愿意付出少量本地算力时，装 mineru[pipeline] 用 hybrid-http-client。
4. S3 对象存储读写：追加安装 mineru[s3]，底层基于 boto3。
5. 依赖冲突预防：vllm 与 lmdeploy 不建议共存；所有版本约束以当前仓库 pyproject.toml 的实际声明为准，跨大版本升级前请重新核对。

按上述选择安装扩展模块后，即可在 GPU 服务器或边缘设备上运行对应的解析/服务命令，完成 MinerU 在不同算力条件下的完整部署。