MinerU：让 PDF「开口说话」的文档解析利器

你是否有过这样的经历：费尽九牛二虎之力从 PDF 里复制出一段文字，结果排版全乱了——表格歪七扭八、公式面目全非、图片和正文老死不相往来？这种情况在处理学术论文、财务报表、产品手册时尤为常见。传统的 PDF 解析工具只能"傻瓜式"地提取文字，无法理解版面的逻辑结构。

MinerU（Magic PDF）正是为解决这一痛点而生。它由 OpenDataLab 团队开源，能够将 PDF、Word、PPT、Excel 等复杂文档精准转换为 Markdown 或 JSON 格式，同时完整保留原始版面结构——段落顺序、表格内容、数学公式、图片标题，全部一丝不苟地保留下来，输出结果直接喂给大语言模型即可使用，是 RAG（检索增强生成）流水线的关键一环。

图1：MinerU 官方 Logo

一、项目背景与行业意义

MinerU 诞生于 2022 年，由上海人工智能实验室旗下的 OpenDataLab 团队开发和维护。项目名称「MinerU」取自「Mining Your Documents」——挖掘文档中的宝藏。从最初的 PDF 解析脚本到如今功能完整的文档智能解析平台，MinerU 已走过多次重大版本迭代。

当前稳定版本为 3.1.15（2026年5月19日发布），主分支为 master，仓库累积获得 64,593 颗 GitHub Stars，fork 数超过 5,400，PyPI 月下载量突破 6 万次，是文档解析与 AI 文档处理领域的绝对标杆项目。

该项目被广泛应用于以下场景：

• RAG 知识库构建：将企业内部文档、合同、政策文件解析为结构化文本，供大模型检索
• AI 训练语料生产：从学术论文、技术报告中提取高质量文本，用于模型微调
• 法律/金融文档处理：精确提取表格数据、签名区域、页眉页脚
• 多语言文档国际化：保留原文格式的同时转换为目标语言

MinerU 的核心价值在于：它解决了 AI 时代文档数据的「最后一公里」问题——无论你的文档库多么庞大，MinerU 都能将其高效转化为大模型可理解的结构化数据，让「喂给 AI 看」这件事变得轻而易举。

二、技术架构：传统解析 + 视觉大模型的强强联合

MinerU 采用流水线架构，将文档解析拆解为多个专业模块，依次执行，最终输出高质量的结构化结果。

后端流水线（Pipeline）：协调整个解析流程，包含文件预处理、内容路由和质量控制。

多格式支持（Office）：内置 python-docx、mammoth、openpyxl 处理器，无缝支持 Word、Excel、PowerPoint 文档的解析。

模型层（Model）：包含多个专用子模块——版面分析（Layout）检测文档中的文本块、表格、图片、公式等元素；OCR 引擎集成 pdftext 等库对扫描版 PDF 进行文字识别；表格识别（Table）将表格还原为结构化 JSON/HTML；VLM 视觉大模型（MinerU 3.0 核心创新）调用 Qwen-VL 等多模态模型对复杂版面的图片、图表、公式进行理解式提取，解决传统 OCR 无法处理的「图文混排」难题。

前端交互（CLI）：提供命令行工具支持批量处理；提供 FastAPI 服务接口（OpenAI 兼容 API）供外部系统调用；内置 Gradio 可视化界面，非技术用户也能通过浏览器直接使用。

图2：MinerU 工作流程示意图

图3：版面分析效果图，精准识别文本、表格、图片等元素

图4：MinerU 技术架构全景图

三、核心功能与使用场景

1. 全格式文档支持

MinerU 支持的输入格式覆盖了日常办公中最常见的文档类型：

格式	支持情况	备注
PDF（原生文本）	完整支持	版面分析 + 文字提取
PDF（扫描件/图片型）	完整支持	OCR + VLM 联合处理
Word (.docx)	完整支持	保留样式和结构
PowerPoint (.pptx)	完整支持	提取文本和图片
Excel (.xlsx)	完整支持	还原表格结构
图片 (.png/.jpg)	完整支持	视同 PDF 图片页

2. 三种使用模式

命令行模式（CLI）：适合技术人员批量处理文件，一行命令搞定整个目录的文档转换。

API 服务模式：部署为 OpenAI 兼容 API 服务器，其他系统都可以通过 HTTP 请求调用 MinerU 的解析能力，支持高并发路由分发。

Gradio 可视化界面：零配置打开浏览器就能用，上传文件后实时预览解析结果，非技术用户友好。

3. 版面保留的黑科技

MinerU 在提取文字的同时，会自动记录每个内容块在原文档中的位置、大小、类型，并将其编码到输出的 Markdown/JSON 中。表格不会乱跳，图片不会错位，版式与原文档高度一致。

4. VLM 赋能复杂内容理解

对于学术论文中的数学公式、商业报告里的图表、PPT 中的信息图——这些「图文混合内容」是传统 OCR 的噩梦。MinerU 3.0 引入视觉大模型（VLM），能够像人类一样「看懂」这些复杂元素，输出准确的 LaTeX 公式描述或图表标题说明。

四、部署与上手

Docker 一键部署（推荐）

项目提供了完整的 Dockerfile 和 docker-compose.yaml，推荐有 GPU 环境的用户直接使用 Docker 部署：

cd docker
docker compose --profile api up -d   # 启动 API 服务（端口 8000）
docker compose --profile openai-server up -d  # 启动 OpenAI 兼容接口（端口 30000）

容器内置 vLLM 推理引擎和 MinerU 模型，开箱即用。

pip 安装（轻量级）

pip install 'mineru[core]'    # 纯 Python 依赖，适合无 GPU 环境
pip install 'mineru[vlm]'     # 额外安装 PyTorch + Transformers

无 GPU 时，MinerU 会自动回退到传统 PDF 解析模式（pdfminer + pypdfium2）。

硬件需求

资源	需求
GPU	必须（VLM 模式）；可选（纯文本 PDF）
显存	16GB+（VLM 推理）
内存	32GB+
磁盘	50GB+（模型文件）
Python	3.10 ~ 3.13

如果你没有 GPU 又想体验完整功能，建议直接使用 mineru.net 的在线 API，无需本地部署。

五、局限性与挑战

尽管 MinerU 已经是目前最完善的文档解析开源方案，但仍有一些局限性值得关注：

GPU 依赖：VLM 模式的文档解析必须在有 NVIDIA GPU 的环境下运行，显存需求 16GB+。对于没有 GPU 的用户，只能使用纯文本解析模式，功能大幅缩水。

模型体积：完整部署（含 vLLM 推理引擎）需要 50GB+ 磁盘空间，镜像拉取和初始化时间较长。

多语言支持：中文和英文文档的识别效果最佳，其他语言（尤其是从右向左书写的阿拉伯文、希伯来文）支持较弱。

嵌套 PDF：部分由多张图片拼接而成的 PDF（如手机拍照后拼接的长图），解析效果不稳定。

性能瓶颈：单个大文件（>100页）的解析时间较长，vLLM 推理是主要瓶颈，文档量大时建议使用路由分发模式做并行处理。

六、行业意义与未来趋势

MinerU 的出现填补了 AI 文档处理领域的一个重要空白。在 RAG 流水线中，文档解析是整个系统的「上游」，解析质量直接决定了下游检索和生成的最终效果。在此之前，开发者需要在十几种工具中反复对比、组合使用，而 MinerU 用一套方案解决了几乎所有常见文档格式的解析问题。

从开源社区的反应来看，MinerU 的 6.4 万 Stars 背后，是大量 AI 应用开发者、RAG 系统构建者和企业知识库工程师的认可。Hugging Face Spaces 和 ModelScope 均提供了在线体验版本，进一步降低了使用门槛。

展望未来，文档解析正在从「批处理」向「智能体化」演进：未来的文档解析不再是简单的文字提取，而是由 AI Agent 主导的主动理解——Agent 会根据文档内容动态决定解析策略，必要时调用外部工具补充信息，最终输出真正「可用」的结构化知识。这一趋势，MinerU 已经在架构层面做好了准备。