MinerU 文档解析实战指南：从安装部署、后端选型到 CLI 完整参数的深度解析

MinerU 是一款面向 LLM、RAG、Agent 场景的高精度文档解析工具，可将 PDF、图片以及 DOCX、PPTX、XLSX 文档统一转换为 Markdown、JSON 等机器可读格式。本文以 MinerU 中文 README 为骨架，结合仓库源码逐层展开：你将掌握五种解析后端（pipeline / vlm-engine / hybrid-engine / vlm-http-client / hybrid-http-client）的精度与资源差异、pip/uv/源码/Docker 四种安装方式、模型源（HuggingFace/ModelScope/本地）的切换机制，以及 mineru 命令行全部参数在源码中的真实定义与默认值，并了解 3.0 版本后 "CLI 作为 mineru-api 编排客户端" 的异步任务架构。

一、项目定位：把复杂文档变成 LLM 可用的结构化数据

MinerU 的核心目标是将 PDF、图片以及 DOCX、PPTX、XLSX 转化为机器可读格式（Markdown、JSON），便于后续检索、抽取与二次处理。README 指出，MinerU 诞生于书生-浦语（InternLM）的预训练过程中，最初聚焦于科技文献中的符号转化问题，现已发展为覆盖全格式文档的解析基座。

其核心解析能力包括：

• 原生支持 DOCX、PPTX、XLSX 解析（无需先转 PDF）；
• 公式自动转为 LaTeX、表格自动转为 HTML，精准还原复杂版面；
• 支持扫描件、手写体、多栏布局、跨页表格合并；
• 输出符合人类阅读顺序，自动去除页眉、页脚、脚注、页码；
• VLM + OCR 双引擎，OCR 支持 109 种语言的检测与识别；
• 支持多种输出格式：面向多模态与 NLP 的 Markdown、按阅读顺序排序的 JSON、信息丰富的中间格式（middle json）等；
• 提供 layout 可视化、span 可视化等质检手段；
• 内置命令行、FastAPI、Gradio WebUI，支持本地编排和多服务部署；
• 支持纯 CPU 运行、GPU/MPS 加速，以及十余款国产算力平台（昇腾、寒武纪、燧原、沐曦、摩尔线程、昆仑芯、天数智芯、瀚博、太初元碁、海光、平头哥等）。

从仓库目录结构看，解析能力被组织为三个后端实现：mineru/backend/pipeline/（传统 OCR 流水线）、mineru/backend/vlm/（VLM 视觉语言模型后端）、mineru/backend/hybrid/（VLM + 原生文本提取混合后端），以及 mineru/backend/office/（DOCX/PPTX/XLSX 原生解析），另有 mineru/model/ 下内置的布局检测（PP-DocLayoutV2）、公式识别（PP-FormulaNet、UniMERNet）、表格结构识别（SLANet+、UNet Table）与 OCR 模型代码，印证了 README 中 "公式 → LaTeX、表格 → HTML" 等能力的实现来源。

二、近期版本演进：3.0 架构升级之后的持续迭代

当前仓库代码版本为 3.4.x（见 mineru/version.py），README 记录了四个关键版本节点，理解它们有助于把握各后端的定位：

3.4：pipeline OCR 升级与模型下载优化（2026/06/18）

• pipeline 后端 OCR 模型升级至 PP-OCRv6，在 OmniDocBench v1.6 评测中 OCR 相关指标提升约 11%；
• 移除 OCR 语言选择中的日语、繁体中文、英语、拉丁文选项，相关场景统一路由到 ch OCR 模型，简化配置；
• OCR 推理与处理链路优化，处理速度提升约 100%；
• 模型下载新增自动源选择能力：首次安装时根据网络环境自动选择更合适的模型源，并优先复用本地已下载模型缓存。

3.3：Hybrid effort 参数与 VLM 模型升级（2026/06/11）

• Hybrid 后端新增 effort 解析强度参数（medium / high）。medium 相比 high 综合精度仅降低 0.13（OmniDocBench v1.6），但在不同平台可获得 35%～220% 的解析速度提升（Linux：文本 PDF +80%/OCR +35%；Windows：+90%/+45%；macOS：+220%/+50%）；
• 默认使用 effort=medium；注意 medium 档不支持 image analysis（图片/图表分析），需要时切回 high；
• VLM 主模型升级至 MinerU2.5-Pro-2605-1.2B，原生支持多语言 OCR。

3.1.0：许可证开放与全格式支持（2026/04/18）

• 许可协议从 AGPLv3 切换为基于 Apache 2.0 的 MinerU 开源许可证（见 LICENSE.md）；
• VLM 主模型切换为 MinerU2.5-Pro-2604-1.2B，新增子图切分合并、图像与图表解析、截断段落合并、跨页面表格合并、表格内图像识别；
• 新增 PPTX 与 XLSX 原生解析，至此完整支持图片、PDF、DOCX、PPTX、XLSX 全格式。

3.0.0：架构级升级（2026/03/29）

• DOCX 原生解析上线，端到端速度相比"先转 PDF 再解析"提升数十倍；
• pipeline 后端在 OmniDocBench (v1.5) 上取得 86.2 分，超过上一代主流 VLM；
• API / CLI / Router 编排体系重构：mineru 命令行改为基于 mineru-api 的编排客户端运行，未传入 --api-url 时自动拉起本地临时服务；mineru-api 新增异步任务接口 POST /tasks（任务提交、状态查询、结果获取），同时保留同步接口 POST /file_parse；新增 mineru-router 用于多服务、多 GPU 的统一入口与负载均衡；
• 长文档链路优化：滑动窗口降低内存峰值、pipeline batch 推理流式落盘、线程安全优化支持多线程并发推理；
• 移除两个 AGPLv3 模型（doclayoutyolo、mfd_yolov8）与一个 CC-BY-NC-SA 4.0 模型（layoutreader）。

更完整的历史版本信息可参考 docs/zh/reference/changelog.md。

三、使用方式总览：先在线体验，再选部署形态

文档解析是困难且复杂的任务，尤其是复杂版面、扫描件、手写体等场景。官方建议先用在线体验评估 MinerU 的解析效果与适用性，再决定本地部署方式：

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

接入方式按场景划分如下：

场景	方案
AI 编程工具	MCP Server（Cursor、Claude Desktop、Windsurf）
RAG 框架	LangChain、LlamaIndex、RAGFlow、RAG-Anything、Flowise、Dify、FastGPT
开发集成	Python / Go / TypeScript SDK、CLI、REST API、Docker
零代码	mineru.net 在线版、Gradio WebUI、桌面客户端

四、本地部署：后端选型与硬件环境要求

安装前必读（官方环境支持说明）：MinerU 仅对特定软硬件环境进行优化和测试。在推荐系统配置上部署可获得最佳性能与最少的兼容性问题；在非主线环境中，由于硬件、软件配置的多样性及第三方依赖的兼容性问题，官方无法 100% 保证完全可用——建议先阅读文档与 FAQ，多数问题已有对应解决方案，也欢迎社区反馈以扩大支持范围。

各解析后端的能力矩阵

README 给出的后端对比表（精度指标为 OmniDocBench v1.6 的 End-to-End Evaluation Overall 分数）：

维度	pipeline	hybrid-engine	vlm-engine	hybrid-http-client	vlm-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 支持	✅	❌	❌	✅	✅
GPU 加速	Volta 及以后架构 GPU 或 Apple Silicon	同左	同左	不需要	不需要
显存最低要求	4GB	8GB	8GB	2GB	2GB
内存要求	最低 16GB 以上，推荐 32GB 以上	同左	同左	最低 16GB	最低 16GB
磁盘空间	20GB 以上，推荐 SSD	同左	同左	至少 2GB	至少 2GB
Python 版本	3.10–3.13	同左	同左	同左	同左

平台限制说明：

1. Linux 仅支持 2019 年及以后发行版；
2. Windows 由于关键依赖 ray 未支持 Python 3.13，仅支持 3.10~3.12；
3. macOS 需 14.0 以上版本；
4. *-http-client 后端适用于兼容 OpenAI API 的服务器，例如通过 vLLM/SGLang/LMDeploy 等推理框架部署的本地模型服务器或远程模型服务。

在源码层面，这五个后端是集中定义并统一校验的。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_HYBRID_EFFORT = "medium"
HYBRID_EFFORT_CHOICES = ("medium", "high")
DEFAULT_BACKEND = BACKEND_HYBRID_ENGINE

可以看到默认后端为 hybrid-engine、默认 effort 为 medium，并且 vlm-auto-engine / hybrid-auto-engine 两个旧名称会经由 normalize_backend() 自动映射为当前公开名称，非法取值会抛出明确的 Invalid backend 错误。

五、安装 MinerU

5.1 使用 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

mineru[all] 包含所有核心功能，兼容 Windows / Linux / macOS，适合绝大多数用户。

5.2 通过源码安装

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

5.3 可选扩展模块（来自 pyproject.toml 的 extras 定义）

从 pyproject.toml 的 [project.optional-dependencies] 可看到完整的模块划分：

扩展	内容	安装命令
core	vlm + pipeline + gradio 三大核心依赖组合	uv pip install "mineru[core]"
s3	通过 S3 读取/写入文件（boto3）	uv pip install "mineru[s3]"
vllm	用 vLLM 加速 VLM 推理（Volta 及以后显卡、8G 显存以上）	uv pip install "mineru[core,vllm]"
lmdeploy	用 LMDeploy 加速 VLM 推理（同上硬件要求）	uv pip install "mineru[core,lmdeploy]"
mlx	macOS Apple Silicon 的 MLX 推理	随 mineru[all] 在 darwin 平台自动安装
基础包 mineru	轻量 client，仅 CPU + 网络，适合边缘设备连接 OpenAI 兼容服务器	uv pip install mineru

注意事项（详见 docs/zh/quick_start/extension_modules.md）：

• vllm 与 lmdeploy 对 VLM 的推理加速效果和使用方式几乎相同，二选一安装，不建议同时安装以避免依赖冲突；
• 安装 mineru[all] 时，vllm 仅在 linux 平台、lmdeploy 仅在 win32 平台、mlx 仅在 darwin 平台安装（见 pyproject.toml 中的 all 依赖声明）；
• 轻量 client 用法示例：

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

5.4 Docker 部署

MinerU 提供便捷的 Docker 部署方式，有助于快速搭建环境并解决环境兼容问题。限制：

• Docker 部署仅适用于 Linux，以及支持 WSL2 的 Windows 环境；
• macOS 用户请使用 pip/源码安装方式，不要使用 Docker 部署。

仓库中 docker/compose.yaml 定义了 mineru-api 与 mineru-gradio 两个服务的编排，docker/china/ 与 docker/global/ 分别提供面向中国大陆网络（ModelScope 模型源）与全球网络的镜像构建文件（含 corex.Dockerfile、npu.Dockerfile、musa.Dockerfile 等针对国产加速卡的变体）。完整部署说明见 docs/zh/quick_start/docker_deployment.md。

5.5 控制台入口一览

pyproject.toml 声明了安装后可用的全部命令行入口：

命令	入口函数	用途
mineru	mineru.cli.client:main	文档解析 CLI（编排客户端）
mineru-api	mineru.cli.fast_api:main	启动解析 API 服务（含异步任务接口）
mineru-router	mineru.cli.router:main	多服务统一入口与任务路由
mineru-gradio	mineru.cli.gradio_app:main	启动本地 WebUI
mineru-vllm-server / mineru-lmdeploy-server / mineru-openai-server	mineru.cli.vlm_server	拉起 VLM 推理服务器（OpenAI 兼容接口）
mineru-models-download	mineru.cli.models_download:download_models	交互式下载/更新模型到本地

六、模型源配置：HuggingFace / ModelScope / 本地模型

默认使用托管在 HuggingFace 的模型进行解析，首次使用时自动下载所需模型文件，后续直接加载本地缓存。无法访问 HuggingFace 时可切换国内镜像源：

export MINERU_MODEL_SOURCE=modelscope
mineru -p <input_path> -o <output_path>

完整的模型源机制（详见 docs/zh/usage/model_source.md）：

• MINERU_MODEL_SOURCE 环境变量支持 huggingface、modelscope、local 三个取值，优先级高于 mineru.json 中的 model-source 字段；不要将其设置为 auto，如需自动选择应直接删除该环境变量（3.4 版本新增的自动选择能力发生在首次探测阶段）；
• 未设置环境变量时，MinerU 读取用户目录下 mineru.json（可用仓库根目录的 mineru.template.json 复制改名创建）中的 model-source 字段；值为 auto 或缺失时，首次运行自动探测实际来源，并将探测结果写回 mineru.json，避免网络波动导致来源反复切换；
• 本地模型工作流：运行 mineru-models-download 交互式下载模型（路径自动写入 mineru.json），然后 export MINERU_MODEL_SOURCE=local 启用本地模型；模型文件夹可自由移动，但需同步更新 mineru.json 中的路径。注意 mineru-models-download 必须使用远端模型源执行真实下载——若当前终端已设 MINERU_MODEL_SOURCE=local，该命令会仅在本次执行中临时忽略该值。

七、命令行使用：mineru 的全部参数与默认值

README 给出的两条最常用命令：

# 满足 GPU 加速条件时（默认 hybrid-engine 后端）
mineru -p <input_path> -o <output_path>

# 纯 CPU 环境指定 pipeline 后端
mineru -p <input_path> -o <output_path> -b pipeline

mineru 支持本地 PDF / 图片 / DOCX / PPTX / XLSX 文件或目录输入。完整的命令行参数定义在 mineru/cli/client.py（click 框架），汇总如下：

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

另外，该命令以 ignore_unknown_options=True, allow_extra_args=True 注册（mineru/utils/cli_parser.py 提供 --key value / --key=value 形式未知参数的解析），透传给底层 API 服务，用于覆盖服务侧的运行时配置。

一个贴近实际的完整命令示例：

# 解析目录，指定 hybrid 高强度 + 图表分析，仅解析前 20 页
mineru -p ./docs_dir -o ./output -b hybrid-engine --effort high --image-analysis -s 0 -e 19

# 连接远程 OpenAI 兼容的 VLM 服务
mineru -p ./input.pdf -o ./output -b vlm-http-client -u http://127.0.0.1:30000

八、源码级理解：3.0 之后 CLI 的异步编排架构

从 mineru/cli/client.py 的 run_orchestrated_cli() 可以看到 3.0 版本重构后的核心调用链：

1. 服务启动：api_url is None 时创建 LocalAPIServer 并 start()，日志输出 Started local mineru-api at ...，随后 wait_for_local_api_ready() 等待健康检查通过；若传入了 --api-url，则直接 fetch_server_health() 探测远端服务（含并发上限与处理窗口信息），并创建实时任务状态渲染器（终端中的进度条）；
2. 任务规划：collect_input_documents() 收集输入（目录会按支持的后缀过滤，见 demo/demo.py 的 collect_input_files() 同款逻辑），plan_tasks() 按 processing_window_size 把文档切分成多个处理窗口任务；
3. 异步提交与并发控制：execute_planned_tasks() 使用 asyncio.Queue 工作池，并发度由服务端健康检查返回的 max_concurrent_requests 与任务数共同决定（resolve_submit_concurrency() 取最小值），每个任务经 submit_parse_task() 走 POST /tasks 异步接口提交，再轮询状态直至完成；
4. 结果落盘：download_result_zip() 下载结果压缩包并 safe_extract_zip() 解压到输出目录；按需执行客户端侧输出再生成（--client-side-output-generation）与 layout/span 可视化任务（进程池执行）；
5. 临时服务回收：finally 块中 local_server.stop() 确保本地临时 mineru-api 服务被可靠停止。

仓库自带的 demo/demo.py 是同一架构的 Python 直调示例：通过 mineru.cli.api_client 的 build_parse_request_form_data() 构造表单、LocalAPIServer 拉起本地服务、提交任务并轮询状态，其中对 backend、effort、parse_method、language 等参数的注释（demo/demo.py）与 README 的参数说明完全一致，可作为 API 编程调用的参考实现。端到端测试见 tests/unittest/test_e2e.py。

九、输出与质检

• 输出包括面向多模态与 NLP 的 Markdown、按阅读顺序排序的 JSON、含丰富信息的中间格式（middle json）等，支持 layout 可视化、span 可视化，便于高效确认输出效果与质检（对应 mineru/cli/visualization.py 的可视化任务实现）；
• 自动化脚本可结合 --client-side-output-generation 在服务端返回 middle json 后于本地重建最终产物，降低服务端与客户端版本耦合。

十、常见问题与支持渠道

• 安装或使用中遇到问题，先查 docs/zh/faq/index.md（Windows CUDA 加速问题、Linux 发行版限制等高频问题均有覆盖）；
• 也可使用 DeepWiki 与 AI 助手交流解决常见问题；
• 仍无法解决时可通过 Discord 或微信群加入社区交流；解析效果不佳的文档样例欢迎提交 issue 并附上相关文件；
• 国产加速卡适配进展见 docs/zh/usage/acceleration_cards/ 目录下的各平台文档，社区适配经验欢迎以 show-and-tell 讨论或 PR 形式贡献。

十一、许可与引用

本仓库采用 MinerU 开源许可证（基于 Apache 2.0 并附带额外条款）。项目致谢 UniMERNet、TableStructureRec、PaddleOCR、PaddleOCR2Pytorch、fast-langdetect、pypdfium2、pdftext、pypdf、magika、vLLM、LMDeploy 等开源工作。引用可参考 README 中给出的 BibTeX（MinerU 原始论文 arXiv:2409.18839、MinerU2.5 arXiv:2509.22186、MinerU2.5-Pro arXiv:2604.04771 等），完整列表见 README_zh-CN.md。

适用前提提示：本文所有精度分数（86.47 / 95.39 / 95.30 等）来自 README 基于 OmniDocBench v1.6 的评测声明，硬件与 Python 版本要求以当前仓库 README 为准；实际选型前建议先按第三节的建议做在线体验验证，再结合自身 GPU 型号、显存与网络环境确定后端组合。