企业官网建设流程全解析

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

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

本文基于 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 的说明）：

--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 模块）：

边缘设备侧则只需基础包或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 在不同算力条件下的完整部署。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU