MinerU 文档解析工具深度解析：从 PDF/Office 到 LLM-ready Markdown 与 JSON 的完整实现

MinerU 是一款开源文档解析工具，可将 PDF、图片以及 DOCX、PPTX、XLSX 转化为 Markdown、JSON 等机器可读格式，服务于 RAG 检索、知识抽取与 Agent 工作流。本文以仓库中文文档首页 docs/zh/index.md 为核心脉络，结合 pyproject.toml 的包定义、mineru/cli/backend_options.py 的后端选择逻辑以及 docs/zh/reference/output_files.md 的输出规范，讲清 MinerU 的核心能力、解析后端体系、安装部署方式与输出文件结构，帮助你在 30 分钟内理解并跑通这套文档解析管线。

项目定位：面向大模型时代的文档解析器

MinerU 的官方定位是：将复杂文档（PDF、图片、Office 办公文件）解析为机器可读格式（Markdown、JSON），便于后续检索、抽取与二次处理。据 docs/zh/index.md 介绍，MinerU 诞生于书生·浦语（InternLM）的预训练过程中，团队专注于解决科技文献中的符号（公式、表格、代码）转化问题。这一背景也解释了它在论文类 PDF 上对行间公式、图表、参考文献等细粒度结构的重视程度。

从 pyproject.toml 可以看到项目的工程定位：

• 包名 mineru，当前版本为 3.4.4（见 mineru/version.py），要求 Python >=3.10,<3.14，classifier 覆盖 3.10~3.13；
• 关键词覆盖 pdf、markdown、ocr、vlm、docx、pptx、xlsx、multimodal 等方向，与文档首页声明的能力一一对应；
• 依赖面较宽：pypdfium2/pypdf 用于 PDF 读取，python-docx/pypptx-with-oxml/openpyxl/mammoth 用于 Office 解析，fast-langdetect 用于语言检测，fastapi/uvicorn 用于 API 服务，modelscope/huggingface-hub 用于模型下载。

核心功能全景

docs/zh/index.md 的“主要功能”一节列出了 MinerU 的完整能力清单，可归纳为五个层面：

1. 输入侧：支持 PDF、图片与 DOCX、PPTX、XLSX 输入；
2. 版面理解：删除页眉、页脚、脚注、页码等干扰元素以保证语义连贯；输出符合人类阅读顺序的文本，适配单栏、多栏及复杂排版；保留标题、段落、列表等原始结构；
3. 符号提取：提取图像、图片描述、表格、表格标题及脚注；自动将公式转换为 LaTeX；自动将表格转换为 HTML；
4. OCR 与自动路由：自动检测扫描版 PDF 和乱码 PDF 并启用 OCR，OCR 支持 109 种语言的检测与识别；
5. 输出与部署：支持多模态/NLP Markdown、按阅读顺序排序的 JSON、信息丰富的中间格式等多种输出；提供 layout 可视化、span 可视化等质检手段；内置命令行、FastAPI、Gradio WebUI，支持本地编排和多服务部署；支持纯 CPU 运行及 GPU(CUDA)/NPU(CANN)/MPS 加速，兼容 Windows、Linux 和 Mac。

仓库源码结构与这些能力一一对应：mineru/backend/pipeline 承载传统检测-识别管线，mineru/backend/vlm 承载视觉语言模型解析，mineru/backend/hybrid 提供混合后端，mineru/backend/office 承载 DOCX/PPTX/XLSX 解析，mineru/model/ 下则包含 layout、ocr、table、mfr（公式识别）等模型模块。

解析后端体系：pipeline、vlm 与 hybrid

自 3.0 起，MinerU 的 mineru 命令默认作为基于 mineru-api 的编排客户端运行（见 docs/zh/usage/index.md）。后端选择在 mineru/cli/backend_options.py 中集中定义：

后端	常量	类型	特点
pipeline	BACKEND_PIPELINE	本地引擎	传统模型管线，兼容性好，支持纯 CPU
vlm-engine	BACKEND_VLM_ENGINE	本地引擎	VLM 推理精度更高，硬件要求较高
hybrid-engine	BACKEND_HYBRID_ENGINE	本地引擎	混合后端，默认后端（DEFAULT_BACKEND）
vlm-http-client	BACKEND_VLM_HTTP_CLIENT	HTTP 客户端	对接 OpenAI 兼容的远程模型服务
hybrid-http-client	BACKEND_HYBRID_HTTP_CLIENT	HTTP 客户端	同上，hybrid 变体

源码中还有两个值得注意的细节：

• 旧版别名 vlm-auto-engine、hybrid-auto-engine 会经由 normalize_backend 归一化到新名称，保证旧命令的向后兼容；
• hybrid 后端支持 effort 参数，取值为 medium / high（HYBRID_EFFORT_CHOICES，默认 medium），用于调节精度档位。

按 docs/zh/quick_start/index.md 的软硬件支持矩阵：pipeline 后端可纯 CPU 运行、显存最低 4GB；*-engine 后端要求 Volta 及以后架构 GPU 或 Apple Silicon、显存最低 8GB，内存推荐 32GB 以上、磁盘 20GB 以上并推荐 SSD；*-http-client 后端只需 2GB 显存（实际推理在服务端），内存 16GB 即可。精度指标（OmniDocBench v1.6 端到端 Overall 分）方面，文档给出的参考值为 pipeline 86.47，vlm/hybrid 在 95.3 左右（medium/high 档分别为 95.26 / 95.39 或 95.30）。

安装与快速使用

安装

pyproject.toml 定义了可选依赖分组，按需安装：

• mineru[core]：包含 vlm + pipeline + gradio，是完整本地能力组合；
• mineru[all]：在 core 基础上追加 s3（boto3）、按平台追加 mlx（macOS）/vllm（Linux）/lmdeploy（Windows），适合绝大多数用户；
• mineru[vlm]、mineru[pipeline]、mineru[gradio]、mineru[s3] 等可单独安装，用于轻量边缘部署。

标准安装命令（来自 docs/zh/quick_start/index.md）：

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

此外，docker/compose.yaml 与 docker/global/Dockerfile、docker/china/ 提供了 Docker 部署方案（仅适用于 Linux 与 WSL2，macOS 用户建议用 pip/源码方式）。

解析命令

安装后获得一组可执行入口（由 pyproject.toml 的 [project.scripts] 声明）：

命令	入口	用途
mineru	mineru.cli.client:main	命令行解析客户端（编排 mineru-api）
mineru-api	mineru.cli.fast_api:main	本地 FastAPI 解析服务
mineru-router	mineru.cli.router:main	多服务/多 GPU 路由编排
mineru-gradio	mineru.cli.gradio_app:main	Gradio WebUI
mineru-vllm-server / mineru-lmdeploy-server / mineru-openai-server	mineru.cli.vlm_server	启动 VLM 推理服务器
mineru-models-download	mineru.cli.models_download:download_models	预下载模型

基础用法：

# 满足 GPU 加速条件时，使用默认后端
mineru -p <input_path> -o <output_path>

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

-p 支持本地 PDF / 图片 / DOCX / PPTX / XLSX 文件或目录。默认从 huggingface 拉取模型并缓存到本地，无法访问时可切换国内镜像源：

export MINERU_MODEL_SOURCE=modelscope

仓库还附带了演示脚本 demo/demo.py，输入样例位于 demo/pdfs/ 与 demo/office_docs/，可直接对照体验解析效果；端到端测试见 tests/unittest/test_e2e.py。更多参数（页码范围、语言、公式/表格开关、effort 等）请参阅 docs/zh/usage/cli_tools.md 与 docs/zh/usage/advanced_cli_parameters.md。

输出文件体系：Markdown、JSON 与可视化

MinerU 执行后除主 Markdown 外，还会生成用于调试、质检和二次开发的辅助文件（详见 docs/zh/reference/output_files.md）。生成哪些文件取决于后端类型和输入文档类型，整体分为三类：

1. 可视化调试文件

• {原文件名}_layout.pdf：每页布局分析结果可视化，检测框右上角数字表示阅读顺序，不同背景色区分内容块类型，适合检查布局与阅读顺序是否正确；
• {原文件名}_span.pdf（仅 pipeline 后端）：按 span 类型用不同颜色线框标注页面，用于排查文本丢失、行内公式识别与文本分割问题。

2. 结构化数据文件

• {原文件名}_model.json：模型原始推理结果。pipeline 后端为带 cls_id/label/score/bbox 的检测框列表；VLM 后端为两层嵌套 list（页→内容块），每块含 type、bbox（0-1 相对坐标）、angle、content 字段；
• {原文件名}_middle.json：中间处理结果，顶层为 pdf_info（逐页解析）、_backend（pipeline/vlm/office）、_version_name 三部分，块层级为「一级块（table/image/chart）→ 二级块 → 行（line）→ 片段（span）」；
• {原文件名}_content_list.json：简化版 middle.json，按阅读顺序平铺所有可读内容块，含 text_level 标题层级、page_idx、0-1000 归一化 bbox 等字段，类型覆盖 image/table/chart/text/equation/code/list 及页面辅助块；
• {原文件名}_content_list_v2.json：3.0 起所有后端额外输出的按页分组结构，统一 type + content 设计，title 带 level、paragraph 带 paragraph_content、equation_interline 带 math_content 等，更适合程序化处理（文档标注该格式仍在演进中）。

3. 主 Markdown 输出

多模态 Markdown 中，image/chart 默认以截图为主；若块内存在 content，会在图片后追加一个默认折叠的 HTML <details> 内容块。

选择建议（与 output_files.md 总结一致）：直接用模型原始输出选 model.json；调试质检看 layout.pdf/span.pdf；内容提取用 *.md + content_list.json（或 v2）；二次开发用 middle.json。需注意 2.5 版本 vlm 后端的结构化输出与 pipeline 版本存在不兼容变更，跨后端消费结构化结果时应以当前版本文档为准。

部署形态与平台支持

围绕 docs/zh/index.md 声明的“命令行、FastAPI、Gradio WebUI，本地编排与多服务部署”，仓库提供的落地方式为：

• 命令行：mineru 客户端 + mineru-api 本地服务，3.0 起默认以编排客户端模式运行；
• 多服务部署：mineru-router 负责多实例/多 GPU 路由，配合 mineru-vllm-server 等 VLM 服务实现 *-http-client 后端模式；
• WebUI：mineru-gradio 提供免登录的核心解析界面；
• Docker：docker/compose.yaml 一键拉起，docker/china/ 目录还包含针对昇腾、寒武纪、摩尔线程、壁仞、瀚博、沐曦、昆仑芯、算能等国产加速卡的专用 Dockerfile；
• 加速卡适配：昇腾 Ascend、平头哥 T-Head、沐曦 METAX、海光 Hygon、燧原 Enflame、摩尔线程等官方/社区适配文档见 docs/zh/usage/。

平台限制（来自快速入门文档脚注）：Linux 仅支持 2019 年及以后发行版；Windows 因 ray 依赖暂不支持 Python 3.13（仅 3.10~3.12）；macOS 需 14.0 以上。

许可证

本仓库采用 MinerU 开源许可证（基于 Apache 2.0 并附带额外条款）进行许可，pyproject.toml 中声明为 LicenseRef-MinerU-Open-Source-License。

小结

MinerU 以「文档 → Markdown/JSON」为主线，用 pipeline / vlm-engine / hybrid-engine 三类本地后端与 *-http-client 远程后端覆盖从纯 CPU 到多 GPU 集群的部署光谱；输出侧同时提供人类可读 Markdown、程序友好的 content_list（含 3.0 新增的 v2 格式）、可二次开发的 middle.json 以及 layout/span 可视化质检文件。如果你要在 RAG 或 Agent 管线中接入文档解析，建议按 docs/zh/quick_start/index.md 完成安装、用 mineru -p ... -o ... 跑通一次解析，再对照 docs/zh/reference/output_files.md 选取适合你下游任务的结构化文件。