MinerU 把复杂文档整理成大模型应用更容易消费的 Markdown 和 JSON——适合 RAG、知识库与 Agent 工作流的数据准备。
一句话概览
opendatalab/MinerU 是一个面向大模型数据准备的文档解析工具，可以把 PDF、图片、DOCX、PPTX、XLSX 等输入转换为 Markdown、JSON 和中间结构化结果，方便进入 RAG、信息抽取、知识库构建或 Agent 工作流。
项目与文档：
适合先解决什么问题
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；2026 年 6 月 4 日发布的 3.2.3 增加上下标检测与输出，并加入 post-OCR fallback 机制。
安装方式
本地试用时，官方推荐先安装 uv，再安装完整功能包：
pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"也可以从源码安装：
git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]mineru[all] 包含核心功能，官方说明兼容 Windows、Linux 和 macOS。文档解析对硬件和依赖比较敏感，尤其是 GPU、推理框架、Python 版本和系统环境。正式部署前建议先用小样本跑通。
第一次解析文档
最基础命令是指定输入路径和输出路径：
mineru -p <input_path> -o <output_path>如果设备不满足 GPU 加速条件，可以指定 pipeline 后端，用 CPU 路线运行：
mineru -p <input_path> -o <output_path> -b pipeline<input_path> 可以是单个文件，也可以是目录。建议先准备一个小目录，只放几份代表性文档：
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、表格文件，并且后续要进入大模型应用，MinerU 值得单独试一轮。
批量处理建议
正式批量处理前，可以按这个顺序验证：
- 选 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 或多服务部署。
