MinerU 快速上手：从环境选型到 CLI、Docker 部署与解析命令实操

本文基于 MinerU 官方 Quick Start 文档（docs/en/quick_start/index.md）及其配套源码编写，覆盖文档解析前的体验入口、本地部署的硬件/软件环境选型（pipeline / *-engine / *-http-client 三大类后端）、pip/uv 与源码安装、Docker 部署，以及 mineru 命令行参数与底层执行链路。读完后，你可以按自身设备条件选对安装方式与解析后端，并用一条命令把 PDF/Office 文档转成 LLM 可用的 Markdown/JSON。

文档解析是一项困难且复杂的任务：在复杂版式、扫描页、手写内容等场景下，解析结果可能不如预期。官方建议先用在线 Demo 评估 MinerU 的解析质量与适配性，再根据实际需求选择合适的部署方式；如果你的文档样本解析效果不佳，欢迎在项目 issue 中分享以便持续改进，安装过程中遇到问题则建议先查阅 FAQ。

一、在线体验：先评估解析质量，再决定是否本地部署

官方提供两类在线入口，便于在投入本地部署前先验证效果：

• 官方在线 Web 应用（mineru.net 开源版工具）：功能与桌面客户端一致，界面与功能更完整，需要登录后使用；
• 基于 Gradio 的在线 Demo（ModelScope / HuggingFace Space）：接口简单，只保留核心解析功能，无需登录，适合快速试解析一份文档。

仓库内同时附带了可直接运行的本地样例，方便安装完成后立即验证解析链路：demo/demo.py 会解析 demo/pdfs 目录下的示例 PDF（另含 demo/office_docs 中的 DOCX/PPTX/XLSX 样例），把结果解压到 demo/api_output，并支持切换 backend、effort、parse_method、server_url 等参数——它的实现与 CLI 走同一套 API 客户端逻辑，可作为"以脚本方式调用 MinerU"的参考。

二、本地部署前的环境选型

2.1 硬件与软件环境支持说明

官方提示（Prerequisites）：为了保证项目的稳定性与可靠性，MinerU 在开发阶段只对特定硬件和软件环境做了优化与测试，以确保用户在推荐系统配置上获得最佳性能并遇到最少的兼容性问题。团队将资源集中在主流环境上，可以更高效地修复潜在 bug 并及时开发新功能。在非主流环境下，由于硬件与软件配置的多样性及第三方依赖的兼容性问题，无法保证 100% 可用；官方建议此类用户先仔细阅读文档与 FAQ（大多数问题已有解决方案），并鼓励社区反馈问题以逐步扩大支持范围。

2.2 解析后端与硬件要求对照表

不同解析后端在精度、硬件要求与适用场景上的差异，是部署选型的核心依据：

维度	pipeline	vlm-engine	hybrid-engine	vlm-http-client	hybrid-http-client
后端特性	兼容性良好	硬件要求高（本地算力）	硬件要求高（本地算力）	面向 OpenAI 兼容服务¹	面向 OpenAI 兼容服务¹
精度²	86.47	95.39（high）/ 95.26（medium）	95.30	95.39（high）/ 95.26（medium）	95.30
操作系统	Linux³ / Windows⁴ / macOS⁵（各后端一致）
纯 CPU 支持	支持	不支持（vlm/hybrid-engine 均不支持）	不支持	支持	支持
GPU 加速	Volta 及以后架构的 GPU 或 Apple Silicon（本地四类后端一致）			无需 GPU	无需 GPU
最低显存	4GB	8GB	8GB	2GB	—
内存	最低 16GB+，推荐 32GB+（本地三类后端一致）			16GB（http-client 两类）	16GB
磁盘空间	20GB+，推荐 SSD（本地三类后端一致）			2GB（http-client 两类）	2GB
Python 版本	3.10–3.13（所有后端一致）

脚注（与原文档保持一致）：

1. ¹ 指与 OpenAI API 兼容的服务，例如本地模型服务，或通过 vLLM/SGLang/LMDeploy 等推理框架部署的远程模型服务；
2. ² 精度指标为 OmniDocBench（v1.6）端到端评测（End-to-End Evaluation）的 Overall 分数，基于最新版本的 MinerU；
3. ³ Linux 仅支持 2019 年及之后的发行版；
4. ⁴ Windows 上由于关键依赖 ray 不支持 Python 3.13，仅支持 3.10~3.12；
5. ⁵ macOS 要求 14.0 及以上版本。

选型结论很直接：有本地 GPU（Volta+ 架构、8GB 显存）且追求精度，用 *-engine 本地后端；设备是纯 CPU 或边缘设备，用 pipeline（本地通用 OCR/文本链路）或 *-http-client（连接远程 OpenAI 兼容推理服务，客户端本身只需 CPU 与网络）；pipeline 是唯一的纯 CPU 本地后端，也是兼容性最好、显存要求最低（4GB 即可 GPU 加速）的方案。Python 版本要求与 pyproject.toml 中的 requires-python = ">=3.10,<3.14" 一致。

三、安装 MinerU

3.1 使用 pip 或 uv 安装

pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

• mineru[all] 包含全部核心功能，兼容 Windows / Linux / macOS，适合大多数用户；
• Windows 上若安装后 CUDA 加速不可用，参见 Windows CUDA 加速 FAQ；
• 如需为 VLM 模型指定推理框架，或只在边缘设备上安装轻量客户端，请参考 扩展模块安装指南。

从 pyproject.toml 的 extras 定义可以看到 mineru[all] 的实际构成：

core = ["mineru[vlm]", "mineru[pipeline]", "mineru[gradio]"]
all = [
    "mineru[core]",
    "mineru[s3]",
    "mineru[mlx] ; sys_platform == 'darwin'",   # macOS 走 MLX 加速
    "mineru[vllm] ; sys_platform == 'linux'",   # Linux 附带 vLLM
    "mineru[lmdeploy] ; sys_platform == 'win32'",  # Windows 附带 LMDeploy
]

即 all = core（vlm + pipeline + gradio 全量能力）+ s3（S3 输入输出），并按平台条件追加推理加速框架：macOS 配 mlx、Linux 配 vllm、Windows 配 lmdeploy。扩展模块安装指南 中还给出了更轻量的组合：例如边缘设备只装基础包 mineru 走 vlm-http-client，或装 mineru[pipeline] 走 hybrid-http-client（相对轻量，纯 CPU+网络可用，有 GPU 则更快）。

3.2 从源码安装

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

源码安装适合需要跟随最新提交或参与开发的场景；当前仓库版本号为 3.4.4（见 mineru/version.py）。

3.3 使用 Docker 部署

Docker 部署可以快速搭建环境并绕开一些棘手的环境兼容问题：

• 仅支持 Linux 与 Windows（WSL2） 环境；
• macOS 用户不建议使用 Docker 部署——macOS 上的 Docker 无法访问 MPS 或 MLX 加速，Apple Silicon 设备无法获得预期加速，应改用上面的 pip/源码安装方式。

详见 Docker 部署说明，核心步骤如下：

1）构建镜像（Dockerfile 位于 docker/global/Dockerfile）：

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/global/Dockerfile
docker build -t mineru:latest -f Dockerfile .

MinerU 的 Docker 以 vllm/vllm-openai 为基底镜像（默认 v0.21.0，面向 CUDA 13.0 兼容环境；需要 CUDA 12.9 兼容时可改用注释中的 v0.21.0-cu129 基础镜像），因此默认自带 vllm 推理加速框架。用 vllm 加速 VLM 推理要求：Volta 架构或更新显卡且 8GB+ 可用显存、宿主机驱动匹配所选镜像的 CUDA 运行时（可用 nvidia-smi 查看）、容器能访问宿主机显卡设备。

2）启动容器：

docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 -p 7860:7860 -p 8000:8000 -p 8002:8002 \
  --ipc=host \
  -it mineru:latest \
  /bin/bash

执行后进入容器交互终端，可直接在容器内运行 MinerU 命令；也可以把 /bin/bash 替换为服务启动命令直接拉起服务。

3）用 Docker Compose 直接启动服务。仓库提供 docker/compose.yaml，预置四个按 profile 划分的常驻服务（均设置了 MINERU_MODEL_SOURCE: local 使用本地模型）：

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml

服务（profile）	端口	说明
openai-server（mineru-openai-server）	30000	OpenAI 兼容服务，供 vlm-http-client 等后端连接
api（mineru-api）	8000	Web API 服务，http://<server_ip>:8000/docs 查看接口文档
router（mineru-router）	8002	路由/聚合服务，默认 --local-gpus auto 在容器内自动拉起本地 worker
gradio（mineru-gradio）	7860	Gradio WebUI，浏览器访问 http://<server_ip>:7860

启动示例（按需选择服务）：

docker compose -f compose.yaml --profile openai-server up -d
docker compose -f compose.yaml --profile api up -d
docker compose -f compose.yaml --profile router up -d
docker compose -f compose.yaml --profile gradio up -d

注意事项（来自 compose.yaml 注释与文档）：

• 启动 openai-server 后，可在另一个终端用纯 CPU 的 http-client 连接它： mineru -p <input_path> -o <output_path> -b vlm-http-client -u http://<server_ip>:30000；
• vllm 会预占显存，同一台机器上通常不能同时跑多个 vllm 服务：在启动 vlm-openai-server 服务或使用 vlm-engine 后端前，请先停掉其他占用显存的服务；
• router 若不想在容器内拉起本地 worker、而是聚合已有的 mineru-api 服务，可按 compose.yaml 中的注释示例切换为 --local-gpus none + --upstream-url http://mineru-api:8000；
• 遇到显存不足时，可启用注释中的 --gpu-memory-utilization 0.5（甚至更低）压缩 KV cache。

四、使用 MinerU 命令行

4.1 最小可用命令

设备满足上表 GPU 加速要求时，一条命令即可完成文档解析（默认后端为 hybrid-engine）：

mineru -p <input_path> -o <output_path>

设备不满足 GPU 加速要求时，指定 -b pipeline 在纯 CPU 环境运行：

mineru -p <input_path> -o <output_path> -b pipeline

mineru 目前支持本地 PDF、图片、DOCX、PPTX、XLSX 文件或目录作为输入。除 CLI 外，MinerU 也提供 API 与 WebUI 使用方式，详细用法见 Usage 指南。

4.2 CLI 参数全解（源码视角）

mineru 命令由 pyproject.toml 中的入口点 mineru.cli.client:main 注册，参数定义见 mineru/cli/client.py：

参数	取值 / 默认值	说明
-p, --path	必填	本地文件或目录路径；支持 pdf、image、docx、pptx、xlsx
-o, --output	必填	输出本地目录
--api-url	默认 None	指定已有的 MinerU FastAPI 地址；省略时 CLI 会自动拉起一个临时的本地 mineru-api 服务，用完即停
-m, --method	auto / txt / ocr，默认 auto	PDF 解析方法；txt 走文本抽取、ocr 走 OCR；仅对 pipeline 与 hybrid-* 后端生效
-b, --backend	pipeline / vlm-engine / hybrid-engine / vlm-http-client / hybrid-http-client，默认 hybrid-engine	解析后端，见下文 2.2 节选型表
--effort	medium / high，默认 medium	hybrid 后端的解析强度；medium 更快但自动关闭图像/图表分析，high 精度更高且支持图像/图表分析；仅 hybrid-* 生效
-l, --lang	默认 ch	OCR 语言提示，仅 pipeline 后端使用（hybrid/VLM 后端忽略该值）
-u, --url	默认 None	*-http-client 后端必填，如 http://127.0.0.1:30000
-s, --start / -e, --end	默认 0 / None	PDF 解析页范围，页码从 0 开始；end 省略表示解析到最后一页
-f, --formula	默认 True	是否启用公式解析（LaTeX 化）
-t, --table	默认 True	是否启用表格解析（HTML 化）
--image-analysis	默认 True	对 VLM 与 hybrid 后端启用图像/图表分析；hybrid medium 会自动禁用
--client-side-output-generation	默认 False	由客户端基于服务端返回的 middle json、图片与原文件在本地重建 Markdown 与 content list
-v, --version	—	显示版本并退出

几个值得注意的实现细节（均可在 mineru/cli/backend_options.py 与 mineru/cli/client.py 中验证）：

• 默认后端与旧名兼容：backend_options.py 中 DEFAULT_BACKEND = "hybrid-engine"，且 normalize_backend 会把旧别名 vlm-auto-engine、hybrid-auto-engine 自动映射为新名称，因此升级后旧命令不会直接报错；
• effort 只约束 hybrid 后端：HYBRID_EFFORT_CHOICES = ("medium", "high")，默认 medium（与 3.3 版本起"默认 hybrid 走 medium 以提升整体效率"的发布说明一致）；
• 未知参数会被透传给内嵌服务：CLI 以 ignore_unknown_options=True, allow_extra_args=True 注册（见 client.py），parse_unknown_args（mineru/utils/cli_parser.py）会把 --xxx value 形式的额外参数解析成 kwargs，随 LocalAPIServer(extra_cli_args=...) 传给自动拉起的本地 mineru-api——这也是 compose.yaml 里 --gpu-memory-utilization 等 vLLM 参数能透传生效的机制；
• 日志级别由环境变量 MINERU_LOG_LEVEL 控制，默认 INFO（见 client.py）；
• 目录输入的去重：同一批次内出现同名文件时，uniquify_task_stems 会自动重命名文档 stem 并给出警告（见 client.py），避免输出互相覆盖。

4.3 一条命令背后的执行链路

mineru -p ... -o ... 并不是本地进程直接跑模型，而是一个"客户端编排"流程，核心在 run_orchestrated_cli：

1. 参数校验与依赖检查：页范围校验（--start/--end 非负）、按后端检查依赖（ensure_backend_dependencies，hybrid 缺依赖会抛出 HybridDependencyError）；
2. 收集输入：collect_input_documents 扫描文件/目录，按扩展名过滤出支持的文档，并用 pypdfium2 探测 PDF 有效页数（页范围越界会直接报错）；
3. 规划任务：plan_tasks 中，pipeline 后端会把多个文档按 processing_window_size 做装箱合并成一个批次（plan_pipeline_tasks 按页数降序装箱），而 hybrid-*/vlm-* 后端每个文档单独一个任务；
4. 连接服务：未提供 --api-url 时自动启动临时本地 mineru-api 并等待健康检查通过；提供则拉取远端健康状态（含并发上限与窗口大小），并渲染任务进度；
5. 并发提交与结果落盘：execute_planned_tasks 以"并发度 = min(本地/服务端 max_concurrent_requests, 任务数)"的 worker 池并发提交，逐任务完成"提交 → 等待状态 → 下载结果 zip → 解压到输出目录"，最后统一汇总失败任务并报错。

demo/demo.py 复现了同一条链路（收集文件 → 构建表单 → 提交 → 轮询状态 → 下载解压），可作为理解 CLI 行为的脚本化对照；tests/unittest/test_e2e.py 则用 tests/unittest/pdfs/test.pdf 作为端到端回归用例，验证默认解析链路。

4.4 组合示例

# 默认：hybrid-engine + medium effort（GPU 设备）
mineru -p ./docs.pdf -o ./out

# 纯 CPU 设备
mineru -p ./docs.pdf -o ./out -b pipeline

# 高分辨率文档：hybrid high 精度 + 图像/图表分析
mineru -p ./scan.pdf -o ./out -b hybrid-engine --effort high --image-analysis true

# 连接远端 OpenAI 兼容推理服务（客户端仅需 CPU + 网络）
mineru -p ./docs.pdf -o ./out -b vlm-http-client -u http://127.0.0.1:30000

# 只解析指定页范围（页码从 0 开始）
mineru -p ./book.pdf -o ./out -s 0 -e 9

# 指定解析方法与 OCR 语言（pipeline 后端）
mineru -p ./book.pdf -o ./out -b pipeline -m ocr -l ch

# 显式对接一个已运行的 mineru-api 服务，而不是自动拉起本地服务
mineru -p ./book.pdf -o ./out --api-url http://127.0.0.1:8000

五、小结与延伸阅读

• 先在线后本地：用 mineru.net 在线版或 Gradio Demo 验证解析效果，再按 2.2 节选型表确定后端；
• 安装按平台选 extras：mineru[all] 覆盖全功能且按平台自动带上 vllm/mlx/lmdeploy；边缘设备可只装基础包或 mineru[pipeline]，详见 扩展模块安装指南；
• macOS 不要用 Docker：改用 pip/源码安装以保住 MPS/MLX 加速；Linux/Windows(WSL2) 可优先 Docker + compose 一键起服务，见 Docker 部署说明；
• CLI 的默认路径：mineru -p <input> -o <output> 自动使用 hybrid-engine（默认 medium effort）并自动拉起临时本地 API；纯 CPU 场景加 -b pipeline；对接远端推理服务用 *-http-client + -u <url>；
• 更完整的 CLI 参数、API/WebUI/HTTP client-server 用法见 Usage 指南，模型下载与模型源配置见 model_source 文档，常见问题见 FAQ。

（文中准确率、硬件要求等数据均引自 docs/en/quick_start/index.md 及官方 README 的 OmniDocBench v1.6 口径，具体行为请以当前仓库 pyproject.toml、mineru/cli/ 下的源码为准。）