MinerU 快速入门：从环境选型、安装部署到命令行解析的完整上手指南

文档解析是困难且复杂的任务，尤其是复杂版面、扫描件、手写体等场景，解析结果可能不尽如人意。本文以 MinerU 仓库的官方快速入门文档为骨架，覆盖“在线体验评估 → 软硬件环境选型 → pip/uv/源码/Docker 四种安装方式 → mineru 命令行首次解析”的完整路径，并结合 mineru/cli/ 与 pyproject.toml 的源码实现，讲清每个部署选项背后的默认值与执行链路，帮助你在正确配置上以最低成本跑通第一篇 PDF/DOCX 的 Markdown 解析。

先在线体验，再决定部署方式

MinerU 官方给出的第一条建议是：先在线评估解析效果与适用性，再根据实际需求选择部署方式。官方提供了两类免费入口：

• 官网在线应用：功能与客户端一致，界面美观、功能丰富，需要登录使用；
• 基于 Gradio 的在线 demo：界面简洁，仅包含核心解析功能，免登录（部署在 ModelScope / HuggingFace Spaces 上）。

如果你手头有解析效果不佳的文档样例，可以将其提交到项目 issue，官方会据此持续优化解析能力；如果安装过程中遇到问题，则应先查阅仓库内置的 FAQ，其中已收录了 Windows CUDA 加速、WSL2 缺 libgl、Linux 缺 CJK 字体等高频问题的解决方案。

本地部署前的软硬件环境选型

为了在推荐配置上获得最佳性能与最少兼容性问题，MinerU 只对特定软硬件环境做优化和测试。非主线环境下，由于硬件、软件配置多样性和第三方依赖兼容性问题，官方不保证 100% 可用——因此安装前务必先按下表对照你的设备。

各解析后端的环境要求

维度	pipeline	hybrid-engine / vlm-engine	hybrid-http-client / vlm-http-client
后端特性	兼容性好	硬件配置要求较高	适用于 OpenAI 兼容服务器
精度指标（OmniDocBench v1.6 Overall）	86.47	95.39（high）/ 95.26（medium）	95.30
操作系统	Linux / Windows / macOS	Linux / Windows / macOS	Linux / Windows / macOS
纯 CPU 平台支持	支持	不支持	支持
GPU 加速支持	Volta 及以后架构 GPU 或 Apple Silicon	Volta 及以后架构 GPU 或 Apple Silicon	不需要
显存最低要求	4GB	8GB	2GB
内存要求	最低 16GB 以上，推荐 32GB 以上	最低 16GB 以上，推荐 32GB 以上	16GB
磁盘空间要求	20GB 以上，推荐 SSD	20GB 以上，推荐 SSD	2GB
Python 版本	3.10 ~ 3.13	3.10 ~ 3.13	3.10 ~ 3.13

需要留意的平台细节：

1. 精度指标为 OmniDocBench (v1.6) 的 End-to-End Evaluation Overall 分数，基于 MinerU 最新版本测试；
2. “OpenAI 兼容服务器”指通过 vLLM / SGLang / LMDeploy 等推理框架部署的本地模型服务器或远程模型服务；
3. Linux 仅支持 2019 年及以后发行版；
4. Windows 上由于关键依赖 ray 尚未支持 Python 3.13，故仅支持 3.10 ~ 3.12；
5. macOS 需使用 14.0 以上版本。

Python 版本约束与 pyproject.toml 中 requires-python = ">=3.10,<3.14" 的声明一致。此外，除以上主流平台外，仓库还收录了社区反馈的其他加速卡适配情况，详见 其他加速卡适配文档（含 AMD、Ascend、Biren、Cambricon、Enflame、Hygon、IluvatarCorex、Kunlunxin、METAX、MooreThreads、THead、Tecorigin、VastAI 等厂商页面）。

安装 MinerU

使用 pip 或 uv 安装

pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple
pip install uv -i https://mirrors.aliyun.com/pypi/simple
uv pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple

通过源码安装

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all] -i https://mirrors.aliyun.com/pypi/simple

从 pyproject.toml 的 [project.optional-dependencies] 可以看到，mineru[all] 是“核心功能 + 平台相关加速模块”的组合：

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 加速
]
core = [
    "mineru[vlm]",        # torch / transformers / accelerate
    "mineru[pipeline]",  # torch / torchvision / onnxruntime / ftfy 等
    "mineru[gradio]",    # WebUI
]

也就是说 mineru[all] 包含全部核心解析功能，兼容 Windows / Linux / macOS，适合绝大多数用户；且会按操作系统自动选择对应的 VLM 推理加速框架（macOS → MLX、Linux → vLLM、Windows → LMDeploy）。

几个官方提示，对应仓库中的扩展模块安装指南 extension_modules.md：

• mineru[all] 适合绝大多数用户；在 Windows 上安装后无法使用 CUDA 加速时，参考 FAQ 的 Windows CUDA 加速章节（Volta/Turing/Ampere/Ada 架构直接装支持 CUDA 的 torch 即可，Blackwell 架构需安装 lmdeploy 0.11.1 + cu128 的 Windows wheel）；
• 需要指定 VLM 推理框架（mineru[core,vllm] / mineru[core,lmdeploy]）或在边缘设备只装轻量 client（uv pip install mineru 或 mineru[pipeline]）时，参考上述扩展模块安装指南；
• 如需 S3 输入输出，安装 mineru[s3]。

使用 Docker 部署 MinerU

Docker 部署有助于快速搭建环境并解决一些棘手的环境兼容问题，但仅适用于 Linux，以及支持 WSL2 的 Windows 环境。macOS 用户请直接使用 pip/uv 或源码方式安装——因为 Docker 环境下无法调用 macOS 上的 MPS 和 MLX 加速能力，Apple Silicon 设备通过该方案无法获得预期加速效果。

使用 Dockerfile 构建镜像

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

MinerU 的 Docker 镜像使用 vllm/vllm-openai 作为基础镜像，因此默认集成了 vllm 推理加速框架和必需依赖。国内 Dockerfile（docker/china/Dockerfile）默认使用 vllm/vllm-openai:v0.21.0，适用于 CUDA 13.0 兼容环境；如需 CUDA 12.9 兼容镜像，可将 Dockerfile 顶部默认 FROM 注释掉，启用注释中的 vllm/vllm-openai:v0.21.0-cu129 基础镜像。在满足条件的设备上即可直接使用 vllm 加速 VLM 模型推理。使用 vllm 加速需满足：

• 设备包含 Volta 及以后架构的显卡，且可用显存 >= 8GB；
• 物理机显卡驱动支持所选基础镜像对应的 CUDA 运行时版本（v0.21.0 需 CUDA 13.0 兼容驱动，v0.21.0-cu129 需 CUDA 12.9 兼容驱动），可通过 nvidia-smi 检查驱动版本；
• Docker 中能够访问物理机的显卡设备。

完整说明见 Docker 部署文档。

启动 Docker 容器

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

执行后进入容器交互式终端，映射的端口分别对应 OpenAI 兼容接口（30000）、Gradio WebUI（7860）、Web API（8000）和 MinerU Router（8002）。你也可以把 /bin/bash 直接替换为服务启动命令来启动对应服务。

通过 Docker Compose 直接启动服务

仓库提供了 compose.yaml，其中包含 MinerU 的多个服务配置，可按需选择启动：

# 启动 openai 兼容接口服务（配合 vlm-http-client 后端连接使用）
docker compose -f compose.yaml --profile openai-server up -d

# 启动 Web API 服务（浏览器访问 http://<server_ip>:8000/docs 查看 API 文档）
docker compose -f compose.yaml --profile api up -d

# 启动 MinerU Router 服务（默认 --local-gpus auto 自动拉起本地 worker，
# 通过 http://<server_ip>:8002/docs 暴露统一入口；也可改用 --upstream-url 聚合已有 mineru-api 服务）
docker compose -f compose.yaml --profile router up -d

# 启动 Gradio WebUI 服务（浏览器访问 http://<server_ip>:7860）
docker compose -f compose.yaml --profile gradio up -d

注意：由于 vllm 预分配显存的特性，同一台机器上可能无法同时运行多个 vllm 服务。启动 vlm-openai-server 服务或使用 vlm-vllm-engine 后端时，请确保其他可能占用显存的服务已停止。

首次使用 MinerU 命令行

模型来源切换

默认使用托管在 Hugging Face 的模型进行解析，首次使用时会自动下载所需模型文件，后续使用直接加载本地缓存。如果无法访问 Hugging Face，可以通过环境变量切换至国内镜像源：

export MINERU_MODEL_SOURCE=modelscope

该环境变量在源码中的定义见 models_download.py 与 models_download_utils.py，两处均以 MODEL_SOURCE_ENV_VAR = 'MINERU_MODEL_SOURCE' 作为统一入口。

基础解析命令

如果设备满足上表 GPU 加速条件，可以直接执行：

mineru -p <input_path> -o <output_path>

如果设备不满足 GPU 加速条件，指定后端为 pipeline 以在纯 CPU 环境运行：

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

当前 mineru 支持本地 PDF / 图片 / DOCX / PPTX / XLSX 文件或目录输入。仓库自带示例输入可用于验证安装是否成功，例如 demo/pdfs 目录下的 demo1.pdf、small_ocr.pdf，以及 demo/office_docs 目录下的 docx/pptx/xlsx 样例。

完整命令行参数

从 CLI 入口 client.py 的 click 选项定义可以确认全部参数、默认值与适用条件：

参数	默认值	说明
-p, --path（必填）	—	本地文件或目录，支持 pdf、图片、docx、pptx、xlsx
-o, --output（必填）	—	输出本地目录
-b, --backend	hybrid-engine	解析后端，取值：pipeline / vlm-engine / vlm-http-client / hybrid-engine / hybrid-http-client
--effort	medium	hybrid 后端解析强度：medium 更快、关闭图像/图表分析；high 精度更高、支持 image analysis。仅对 hybrid-* 生效
-m, --method	auto	PDF 解析方法：auto / txt（文本抽取）/ ocr。仅对 pipeline 与 hybrid-* 后端生效
-l, --lang	ch	输入文档语言，提升 OCR 准确性（pipeline 后端生效）
-u, --url	无	使用 vlm-http-client / hybrid-http-client 后端时必填，OpenAI 兼容服务器地址，如 http://127.0.0.1:30000
-s, --start	0	PDF 起始页，从 0 开始
-e, --end	无	PDF 结束页，从 0 开始
-f, --formula	True	启用公式解析
-t, --table	True	启用表格解析
--image-analysis	True	VLM 与 hybrid 后端的图像/图表分析；hybrid medium 档会自动关闭
--client-side-output-generation	False	由服务端返回 middle json、图片与原文件后，在本地重建 markdown 与 content list
--api-url	无	指定 MinerU FastAPI 基础地址；省略时 mineru 会自动拉起一个本地临时的 mineru-api 服务
-v, --version	—	显示版本并退出

后端选项的合法取值与默认值由 backend_options.py 集中定义：DEFAULT_BACKEND = "hybrid-engine"，DEFAULT_HYBRID_EFFORT = "medium"，并保留了旧别名 vlm-auto-engine / hybrid-auto-engine 到当前公开名称的兼容映射（normalize_backend 负责校验与归一）。CLI 传入非法 backend 时会抛出 BadParameter 并列出全部允许值。

源码视角：一条命令的执行链路

从 client.py 的 run_orchestrated_cli 可以看到，mineru 命令行本质上是一个“编排客户端”：

1. 先经 ensure_backend_dependencies(backend) 校验所选后端的依赖是否安装（cli/common.py）；
2. 通过 collect_input_documents 收集输入：目录会被排序遍历，按扩展名过滤出受支持的文档，PDF 还会用 pypdfium2 探测有效页数；
3. 若未提供 --api-url，则启动本地临时 mineru-api 服务并等待健康检查通过；若提供则直接向远端服务拉取 server_health；
4. 按后端策略规划任务：pipeline 后端按处理窗口大小（processing window）把多个文档装箱成批，其他后端每个文档一个任务（plan_tasks，见 client.py）；
5. 并发提交异步任务、轮询状态（终端会渲染实时进度条），完成后下载结果 zip 并解压到 -o 指定目录，同时在独立进程池中生成可视化产物。

安装完成后，pyproject.toml 的 [project.scripts] 会注册整套命令行入口，除了主入口 mineru，还包括 mineru-api（FastAPI 服务）、mineru-router（多服务/多 GPU 统一路由）、mineru-gradio（WebUI）、mineru-vllm-server / mineru-lmdeploy-server / mineru-openai-server（VLM 推理服务）和 mineru-models-download（模型预下载）。这意味着 CLI、API、WebUI、HTTP client、server 等多种使用形态共享同一套代码，进阶用法可继续阅读 使用指南。

常见安装问题速查

• Windows 直接安装后推理很慢：通常是 CUDA 加速依赖未正确安装，按显卡架构选择方案（Volta/Turing/Ampere/Ada 装 CUDA 版 torch；Blackwell/RTX 50xx 装 lmdeploy 0.11.1 + cu128 wheel），详见 FAQ；
• WSL2 Ubuntu 22.04 报 ImportError: libGL.so.1：执行 sudo apt-get install libgl1-mesa-glx 解决；
• Linux 解析结果缺失部分文字：pypdfium2 渲染 PDF 时因系统缺少 CJK 字体丢字，安装 fonts-noto-core 与 fonts-noto-cjk 后执行 fc-cache -fv，或直接使用 Docker 镜像（镜像默认包含字体包）。

按本文路径完成“选型 → 安装 → 首条命令”后，即可用仓库内 demo/pdfs 样例验证整条链路，并沿着 Docker 部署、扩展模块安装指南 与 使用指南 继续深入服务化部署与 API 编排。