MinerU 使用指南：把 PDF、Office 和图片解析成适合 RAG 的 Markdown/JSON

Sun, 07 Jun 2026 23:41:50 +0800

opendatalab/MinerU 是一个面向大模型数据准备的文档解析工具。它可以把 PDF、图片、DOCX、PPTX、XLSX 等输入转换为 Markdown、JSON 和中间结构化结果，方便后续进入 RAG、信息抽取、知识库构建或 Agent 工作流。

它要解决的问题很具体：真实文档往往包含多栏排版、表格、公式、页眉页脚、扫描页、手写内容和图片说明。直接把这些内容丢给大模型，容易出现顺序错乱、表格丢结构、公式不可读、OCR 噪声过多等问题。MinerU 的思路是先做版面、文本、表格、公式和 OCR 解析，再输出更接近“机器可读”和“人类阅读顺序”的结果。

适合先解决什么问题

MinerU 更适合下面几类场景：

把论文、报告、合同、手册解析成 Markdown；
给 RAG 知识库准备更干净的文档切分输入；
从扫描版 PDF 或图片里提取文本、表格和公式；
把 DOCX、PPTX、XLSX 统一转成后续流程能消费的结构化数据；
在本地或私有环境里批量处理文档；
为 LangChain、LlamaIndex、Dify、RAGFlow、FastGPT 等框架准备数据。

如果你的任务只是读取一份排版简单的纯文本 PDF，直接用常规 PDF 提取工具可能已经够用。MinerU 的价值主要体现在复杂版式、表格公式、多格式输入和批量生产文档数据上。

核心能力

根据项目 README，MinerU 支持 PDF、图片、DOCX、PPTX 和 XLSX 输入，并能输出 Markdown、按阅读顺序排列的 JSON，以及用于检查解析质量的可视化结果。

比较关键的能力包括：

自动移除页眉、页脚、脚注、页码等干扰内容；
按人类阅读顺序输出文本，适配单栏、多栏和复杂排版；
保留标题、段落、列表等文档结构；
提取图片、图片说明、表格、表格标题和脚注；
将公式识别并转换为 LaTeX；
将表格识别并转换为 HTML；
自动检测扫描 PDF 和乱码 PDF，并启用 OCR；
OCR 支持 109 种语言；
提供 CLI、FastAPI、Gradio WebUI 和 mineru-router。

2026 年 4 月的 3.1.0 版本还引入了 PPTX 和 XLSX 原生解析，并将主 VLM 模型升级到 MinerU2.5-Pro-2604-1.2B。GitHub release 页面显示，2026 年 6 月 4 日发布的 3.2.3 增加了上下标检测与输出，并加入了 post-OCR fallback 机制，用于处理私有区字符场景。

安装方式

如果只是本地试用，官方推荐先安装 uv，再安装完整功能包：

1
2
3

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

也可以从源码安装：

1
2
3

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

mineru[all] 包含核心功能，官方说明兼容 Windows、Linux 和 macOS。需要注意的是，文档解析对硬件和依赖比较敏感，尤其是 GPU、推理框架、Python 版本和系统环境。正式部署前建议先用小样本跑通，再决定是否进入批量处理。

第一次解析文档

最基础的命令是指定输入路径和输出路径：

`1`	`mineru -p <input_path> -o <output_path>`

如果设备不满足 GPU 加速条件，可以指定 pipeline 后端，用纯 CPU 路线运行：

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

<input_path> 可以是单个文件，也可以是目录。实际使用时，可以先准备一个小目录，只放几份代表性文档：

`1`	`mineru -p ./samples -o ./output -b pipeline`

这样可以先观察输出质量、耗时、内存占用和文件结构，再决定是否扩大到完整文档库。

输出结果怎么用

MinerU 的输出可以进入几类下游流程。

第一类是 RAG。你可以把 Markdown 作为切分和向量化的输入，让标题、段落、列表、表格和公式尽量保持原始语义。相比直接 OCR 成一大段文本，结构化 Markdown 更容易做分块、引用和结果回溯。

第二类是信息抽取。JSON 和中间结果适合给后续脚本读取，例如抽取表格、公式、图片说明或特定章节。对于需要自动整理报告、论文或合同字段的场景，这比只拿纯文本更稳定。

第三类是人工复核。MinerU 提供版面、span 等可视化结果，可以帮助你检查解析是否漏掉内容、顺序是否合理、表格是否变形。做批量处理前，最好先抽样看这些可视化结果。

后端选择

MinerU 文档里主要提到几类后端路线：

pipeline：兼容性好，可以在 CPU 或 GPU 上运行，适合先试用和常规批处理；
vlm-engine：准确率更高，但硬件要求也更高，适合复杂文档和高质量解析；
hybrid-engine：结合原生文本提取与高准确率解析，适合希望降低幻觉并提升复杂版式质量的场景；
*-http-client：连接 OpenAI API 兼容服务，可对接本地或远程推理服务。

如果你只是想验证效果，先用 pipeline 更稳。等确认文档类型、质量要求和处理量之后，再考虑 VLM 或混合路线。对于企业内部文档，后端选择还要结合数据是否允许离开本地环境。

部署方式

MinerU 支持 CLI、本地 API、Gradio WebUI、Docker 和 mineru-router。不同入口适合不同团队：

个人试用：CLI 最直接；
非技术同事体验：Gradio WebUI 更友好；
接入现有系统：FastAPI 或 REST API 更合适；
多服务、多 GPU、高并发：考虑 mineru-router；
想降低环境配置成本：Linux 或 WSL2 环境下可以看 Docker 部署。

Docker 部署目前更适合 Linux 和带 WSL2 的 Windows。macOS 用户通常优先走 pip / uv 安装路线。

和普通 OCR 工具有何不同

普通 OCR 工具主要关注“把图像里的字识别出来”。这当然重要，但对 RAG 来说还不够。RAG 更关心的是段落顺序、标题层级、表格结构、公式表达、图片上下文和可追溯性。

MinerU 更像文档理解前处理工具。它不只是 OCR，还会处理版面分析、阅读顺序、表格 HTML、公式 LaTeX、多格式输入和结构化输出。它更适合把复杂文档整理成下游模型能稳定消费的数据。

这也意味着它不是越重越好。对于简单发票、单页图片或纯文本 PDF，轻量 OCR 或 PDF 文本提取工具可能更快。MinerU 更适合文档复杂度已经明显影响后续效果的场景。

和 PaddleOCR、Marker、Unstructured 怎么选

这些工具有重叠，但入口不同。

PaddleOCR 更偏 OCR 基础能力和文字识别组件，适合你需要自己搭建更细粒度的 OCR 流程。Marker 更偏 PDF 到 Markdown，适合快速把文档变成可读 Markdown。Unstructured 更偏文档数据抽取与企业数据管道，适合多类型文档进入检索或 ETL 流程。

MinerU 的特点是面向 LLM、RAG 和 Agent 数据准备，强调复杂版式、表格、公式、多格式输入、VLM + OCR 双引擎和私有部署。若你的文档主要是论文、报告、教材、PPT、表格文件，并且后续要进入大模型应用，它值得单独试一轮。

批量处理建议

正式批量处理前，可以按下面顺序做一次小规模验证：

选 10 到 20 份代表性文档，覆盖扫描件、复杂表格、多栏论文、PPT 和 Excel。
先用 pipeline 后端解析，记录耗时、内存、输出大小和失败样例。
抽查 Markdown、JSON 和可视化结果，重点看阅读顺序、表格、公式和图片说明。
对质量不够的样本，再尝试 VLM 或 hybrid 后端。
确认输出结构后，再接入 RAG 切分、向量化和引用回溯。

不要一开始就把整库文档丢进去。文档解析的失败往往很具体：某类扫描件、某种表格、某个字体、某个语言方向或某些跨页内容。先找出边界，再放大规模，会省很多时间。

隐私与合规注意事项

如果处理的是企业内部文档、客户资料、合同、财务报表或未公开研究资料，先确认部署方式和数据流向。

需要重点检查：

文件内容是否会发送到外部模型服务；
是否使用本地推理、远程推理或 OpenAI API 兼容服务；
中间文件里是否包含完整文本、图片、表格和业务敏感信息；
输出 Markdown / JSON 是否会进入日志、对象存储或共享目录；
批处理失败样本是否会被上传到 issue、社区或第三方调试平台。

MinerU 支持私有和离线部署，但这不等于所有配置都天然离线。真实部署前，最好画清楚从输入文件、临时目录、模型推理、输出目录到日志系统的完整数据路径。

什么时候不适合用

下面几种情况可以先不引入 MinerU：

文档很简单，普通 PDF 文本提取已经足够；
你只需要一次性读几页内容，不需要结构化输出；
当前机器资源不足，解析成本高于收益；
文档质量太差，OCR 结果需要大量人工校对；
私有文档不能进入当前推理链路；
团队还没有明确的 RAG、抽取或知识库下游需求。

文档解析工具最好服务于后续流程，而不是为了“解析而解析”。如果没有明确的消费方，先把输出样例和下游需求对齐，再决定是否批量投入。

小结

MinerU 适合把复杂文档转换成大模型应用更容易使用的 Markdown 和 JSON。它覆盖 PDF、图片、Office 文档、表格、公式、OCR、多语言识别和本地部署，尤其适合 RAG、知识库和 Agent 工作流的数据准备。

比较稳妥的使用路线是：先用在线体验或小样本本地解析评估质量，再用 pipeline 后端跑通流程，最后根据准确率和吞吐要求决定是否切换到 VLM、hybrid、API 或多服务部署。对于复杂文档，它能明显减少前处理成本；对于简单文档，也要注意别把流程做重。

MinerU on KnightLi的博客