MinerU 文档解析全指南：从 magic-pdf 到 3.4.5，PDF→Markdown 开源利器深度实战
项目：MinerU（OpenDataLab / 上海 AI Lab）
GitHub：https://github.com/opendatalab/MinerU
官方文档：https://opendatalab.github.io/MinerU/
最新稳定版：mineru-3.4.5 （2026-08-14）
预览分支：v4.0.0a6 （2026-08-14）
核验日期：2026-09-10
许可证：MinerU 开源许可证（基于 Apache 2.0，3.1 起自 AGPLv3 变更）
官方 Logo 来自 OpenDataLab/MinerU 仓库；时间线、后端对比、工具矩阵图为笔者整理。
一句话读懂 MinerU
MinerU 是面向 RAG / Agent 场景的开源文档解析引擎，能把 PDF、图片及 Office 文档转成结构化 Markdown / JSON------在公式、表格、中文复杂版式上精度领先，同时提供 pipeline（CPU 友好）与 hybrid / VLM（GPU 高精度）双路线，已从科研工具演进为企业级解析基座。
前言：为什么 RAG 团队都在关注 MinerU？
如果你做过知识库，大概率踩过这些坑：
- PDF 直接切块，表格变成乱码、公式丢失、脚注错位；
- 扫描件 OCR 质量差，检索到的 chunk 和原文对不上；
- 开源工具很多，但许可证、GPU 要求、中文支持差异巨大；
- 同一套 pipeline，换一份财报或论文，效果断崖式下跌。
MinerU 诞生于 InternLM 预训练过程中的文档清洗需求，由 OpenDataLab 团队持续维护。截至 2026 年中，GitHub Stars 已突破 6 万+，成为 PDF→Markdown 赛道最活跃的开源项目之一。
本文按 演进史 → 后端选型 → 部署 → 使用 → 效果对比 → 竞品横评 组织，帮你系统判断 MinerU 是否适合你的场景。
1. MinerU 是什么？
MinerU 的核心任务：把非结构化文档变成机器可读格式。
| 维度 | 说明 |
|---|---|
| 输入 | PDF、图片、DOCX、PPTX、XLSX |
| 输出 | Markdown、JSON、content_list（按阅读顺序） |
| 特色能力 | 公式→LaTeX、表格→HTML、OCR 109 语言、阅读顺序还原 |
| 部署形态 | CLI、FastAPI、Gradio WebUI、mineru-router、Docker、在线版 mineru.net |
| 生态集成 | LangChain、LlamaIndex、RAGFlow、Dify、FastGPT、MCP Server 等 |
主要功能（官方 README）：
- 删除页眉、页脚、页码，保持语义连贯
- 支持单栏、多栏、复杂排版的人类阅读顺序
- 自动检测扫描版 / 乱码 PDF 并启用 OCR
- 提取图像、表格、脚注，并保留结构层级
- 支持纯 CPU（pipeline）与 GPU / NPU / MPS 加速
2. 演进时间线：从 magic-pdf 到 MinerU 3.4.5
MinerU 并非一夜成名，而是经历了 包名迁移、模型路线升级、工程化重构 三个阶段。以下只列大版本里程碑（细粒度 patch 见官方 Changelog）。
2.1 起源：magic-pdf 时代（2024 Q4 -- 2025 Q2）
| 时间 | 版本 | 关键变化 |
|---|---|---|
| 2024-11 ~ 12 | magic_pdf 0.10.x | 项目首次公开发布，聚焦 PDF 解析与 OCR |
| 2025-01 | magic_pdf 1.0.1 | 1.x 系列起步，CLI 与模型管线成型 |
| 2025-02 ~ 04 | magic_pdf 1.1 ~ 1.3 | 表格结构识别、公式检测、布局分析持续增强 |
| 2025-05 | magic_pdf 1.3.12 | 1.x 收官版本，为品牌统一做准备 |
这一阶段的特点：传统 OCR + 布局检测 pipeline，在中文科技文献场景快速积累用户，但尚无独立 VLM 品牌。
2.2 品牌统一：MinerU 2.x（2025 Q2 -- 2026 Q1）
| 时间 | 版本 | 关键变化 |
|---|---|---|
| 2025-06-13 | MinerU 2.0.0 | PyPI 包名由 magic-pdf 迁移为 mineru，项目正式品牌化 |
| 2025-07 | 2.1.x | VLM 推理后端引入，支持 vLLM / LMDeploy |
| 2025-09-19 | 2.5.0 | MinerU2.5 VLM 路线发布，OmniDocBench 精度大幅提升 |
| 2025-10 ~ 11 | 2.6.x | 表格合并、跨页处理、Gradio / API 体验优化 |
| 2025-12-30 | 2.7.0 | Hybrid 后端 上线；默认后端从 pipeline 切到 hybrid-auto-engine |
| 2026-01 ~ 02 | 2.7.x | 国产算力适配（昇腾、寒武纪、摩尔线程等）；跨页表格合并优化 |
2.x 的核心转折：
- 双后端架构：pipeline（稳定、CPU）+ VLM（高精度、GPU）
- Hybrid 后端（2.7）：在 VLM 基础上融合 pipeline 能力------文本 PDF 直提文字降低幻觉，扫描件走 OCR，兼顾精度与可控性
- 安装简化 ：
uv pip install -U "mineru[all]"一次装全可选依赖
许可证注记：2.x 时期项目仍为 AGPLv3，对闭源商用集成有约束；此问题在 3.1 解决（见下文）。
2.3 工程化跃迁：MinerU 3.x（2026 Q1 -- 至今）
| 时间 | 版本 | 关键变化 |
|---|---|---|
| 2026-03-28 | 3.0.0 | DOCX 原生解析；pipeline OmniDocBench v1.5 达 86.2；mineru-api 异步 /tasks；mineru-router 多 GPU 路由；长文档内存优化 |
| 2026-04-17 | 3.1.0 | 许可证切换为 MinerU License（基于 Apache 2.0）；VLM 升级 MinerU2.5-Pro-2604-1.2B；PPTX / XLSX 原生解析 |
| 2026-05 ~ 06 | 3.2 ~ 3.3 | VLM 升至 MinerU2.5-Pro-2605-1.2B；Hybrid 新增 effort=medium/high 档位 |
| 2026-06-18 | 3.4.0 | pipeline OCR 升级 PP-OCRv6 ，OmniDocBench v1.6 OCR 指标约 +11% ，OCR 速度约 2× |
| 2026-08-14 | 3.4.5 | 当前最新稳定版，修复 DOCX 表格等边界问题 |
| 2026-07 ~ 08 | v4.0.0a1 ~ a6 | Alpha 预览分支，PDF 处理能力进一步增强（非生产推荐） |
3.0 的官方定位变化值得单独强调：
从「数据生产工具」演进为「面向高并发、高吞吐的大规模文档解析基座」------支持滑动窗口降内存、流式落盘、线程安全并发、多卡 router。
2.4 模型论文脉络
| 论文 | 时间 | 要点 |
|---|---|---|
| MinerU Technical Report | 2024 | 初代系统与评测 |
| MinerU2.5 | 2025 | 解耦式 VLM，高效高分辨率解析 |
| MinerU2.5-Pro | 2026 | 纯数据工程将 1.2B 模型推到 OmniDocBench v1.6 95.69 |
3. 三大解析后端：如何选型？
MinerU 的竞争力很大程度来自 「精度 ↔ 资源」可切换 的设计。
3.1 官方 OmniDocBench v1.6 数据
| 后端 | E2E Overall | CPU | 最低显存 | 典型场景 |
|---|---|---|---|---|
| pipeline | 86.47 | ✅ | 4GB（可选 GPU） | 无 GPU、批量 OCR、稳定优先 |
| hybrid medium（默认） | 95.26 | ❌ | 8GB | 日常生产，速度/精度平衡 |
| hybrid high | 95.39 | ❌ | 8GB | 极致精度、图表分析 |
| vlm / vlm-http-client | 95.30 | client 端 ✅ | 8GB / client 2GB | 远程 OpenAI 兼容服务 |
补充说明：
- hybrid medium（3.3 默认）：相比 high 仅低 0.13 分，但速度快 35% ~ 220%（因平台与文档类型而异）；不支持 image analysis
- pipeline（3.4）：PP-OCRv6 后 OCR 精度显著提升，适合「没有 GPU 但必须跑」的场景
- *-http-client：把推理放到 vLLM / SGLang / LMDeploy 服务端，客户端轻量
3.2 硬件与系统要求（官方）
| 项目 | pipeline / hybrid-engine | *-http-client |
|---|---|---|
| 操作系统 | Linux（2019+）/ Windows / macOS 14+ | 同左 |
| Python | 3.10 -- 3.13（Windows 最高 3.12） | 同左 |
| 内存 | 最低 16GB，推荐 32GB+ | 最低 16GB |
| 磁盘 | 20GB+（推荐 SSD） | 2GB+（模型在远端） |
4. 部署指南
4.1 最快上手：pip / uv 安装
bash
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首次运行会自动从 HuggingFace 下载模型。若网络受限，切换国内源：
bash
# Linux / macOS
export MINERU_MODEL_SOURCE=modelscope
# Windows PowerShell
$env:MINERU_MODEL_SOURCE="modelscope"4.2 源码安装（开发者）
bash
git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all] -i https://mirrors.aliyun.com/pypi/simple4.3 Docker 部署
- 适用于 Linux 及 WSL2 Windows
- macOS 不建议 Docker，直接用 pip 安装
- 详见Docker 部署文档
Docker 的价值：隔离 torch / vLLM / CUDA 版本冲突，适合 CI 与多租户服务。
4.4 生产级：API + Router
单机 API：
bash
mineru-api --host 0.0.0.0 --port 8000 --enable-vlm-preload多 GPU Router（3.0+）：
bash
mineru-router --host 0.0.0.0 --port 8002 \
--local-gpus 0,1 --enable-vlm-preloadRouter 与 mineru-api 接口兼容，内置任务负载均衡，适合企业内统一接入。
4.5 不想自建？在线版
建议：先用在线版评估效果，再决定私有化部署规模。
5. 使用方法
5.1 CLI：最常用入口
GPU 环境（默认 hybrid）：
bash
mineru -p ./papers/ -o ./output/纯 CPU：
bash
mineru -p ./papers/ -o ./output/ -b pipeline指定解析强度（3.3+）：
bash
# 更快，适合日常文档
mineru -p doc.pdf -o out/ -b hybrid-auto-engine --effort medium
# 更高精度，支持 image analysis
mineru -p doc.pdf -o out/ -b hybrid-auto-engine --effort high常见参数：
| 参数 | 说明 |
|---|---|
-p |
输入文件或目录 |
-o |
输出目录 |
-b |
后端：pipeline / hybrid-auto-engine / vlm-auto-engine 等 |
--start / --end |
页码范围 |
--lang |
OCR 语言（扫描件） |
输出目录通常包含：
*.md：Markdown 正文images/：提取的图片content_list.json：结构化块列表（适合自定义分块）
5.2 FastAPI：服务化集成
同步解析：
bash
curl -X POST http://localhost:8000/file_parse \
-F "file=@document.pdf" \
-F "method=auto" \
-F "backend=hybrid-auto-engine"异步任务（3.0+，适合长文档）：
bash
# 1. 提交
TASK_ID=$(curl -s -X POST http://localhost:8000/submit_parse_task \
-F "file=@document.pdf" | jq -r '.task_id')
# 2. 轮询状态
curl -s "http://localhost:8000/get_async_task_status?task_id=$TASK_ID"
# 3. 获取结果
curl -s "http://localhost:8000/get_async_task_result?task_id=$TASK_ID"5.3 Gradio WebUI
bash
mineru-gradio适合非技术用户试解析、对比不同后端效果。2.7+ 支持中英文界面切换。
5.4 Python SDK 集成 RAG
典型流程：
mineru解析 PDF → Markdown + JSON- 按标题 / content_list 分块
- Embedding → 向量库
- RAG 检索问答
MinerU 输出的 HTML 表格 和 LaTeX 公式 对下游 LLM 友好，但若你的分块器只认纯文本，需要预处理（例如表格转 Markdown 或保留 HTML 块）。
6. 效果对比：MinerU 到底有多准？
6.1 OmniDocBench 官方榜单视角
OmniDocBench 是文档解析领域的主流基准，评测维度包括文本、公式、表格、阅读顺序等。MinerU2.5-Pro 论文（2026）在 v1.6 协议 下报告 95.69 分，同架构 baseline 提升 2.71 分。
各后端在 README 中公布的 v1.6 E2E Overall：
| 工具/后端 | Overall |
|---|---|
| MinerU hybrid high | 95.39 |
| MinerU vlm | 95.30 |
| MinerU hybrid medium | 95.26 |
| MinerU pipeline | 86.47 |
| MinerU2.5-Pro（论文） | 95.69 |
6.2 第三方「硬文档」实测（pdf-to-markdown-benchmark）
pdf-to-markdown-benchmark 用 5 类故意刁难的文档（论文、财报、法律、纯表格、扫描件）评测 9 款工具，平均分如下：
| 工具 | 论文 | 财报 | 法律 | 表格 | 扫描 | 平均 |
|---|---|---|---|---|---|---|
| MinerU | 99 | 95 | 67 | 100 | 71 | 86 |
| Marker | 95 | 87 | 82 | 96 | 71 | 86 |
| Docling | 63 | 80 | 90 | 92 | 61 | 77 |
| PyMuPDF4LLM | 61 | 90 | 90 | 82 | 58 | 76 |
| MarkItDown | 51 | 65 | 70 | 66 | 33 | 57 |
要点：
- MinerU 与 Marker 平均分并列第一，但强项不同（MinerU 表格/公式极强；Marker 法律文档略好）
- MinerU 在法律文档上弱项明显：评测指出会丢失脚注正文、把目录行误标为 H1
- 无静默错误（silent errors = 0），比部分商业 OCR 更「诚实」
6.3 速度维度（勿只看精度）
| 工具 | 速度特征 |
|---|---|
| MarkItDown / PyMuPDF4LLM | 原生 PDF 极快（秒级），但无 OCR |
| Marker | H100 批量模式可达 ~120 页/秒（官方 README 估算） |
| MinerU VLM | 约 2~4.5 页/秒（视 GPU 而定），精度优先 |
| MinerU pipeline | 3.4 OCR 速度约 2× 提升，适合 CPU 批量 |
结论：高精度 VLM / Hybrid 路线不可能与 MarkItDown 比速度；选型要看文档类型与硬件预算。
7. 与主流 PDF→Markdown 工具横评
7.1 总览对比表
| 工具 | 机构 | 许可证 | OCR | 公式 | 表格 | CJK | GPU 需求 | 适合场景 |
|---|---|---|---|---|---|---|---|---|
| MinerU | OpenDataLab | MinerU License | ✅ 109 语 | ✅✅ | ✅✅✅ | 极强 | 高精度需 GPU | 学术/中文/复杂版式 RAG |
| Marker | Datalab | GPL + RAIL-M | ✅ | ✅✅ | ✅✅ | 良好 | 可选 | 大批量、版式结构 |
| Docling | IBM | MIT | ✅ | ✅ | ✅✅ | 良好 | 可选 | 企业多格式、LlamaIndex |
| PyMuPDF4LLM | Artifex | AGPL | ❌ | ❌ | ✅ | 基础 | 否 | 原生 PDF 快速抽取 |
| MarkItDown | Microsoft | MIT | ❌ | ❌ | 弱 | 弱 | 否 | 简单文档、极速 |
| Nougat | Meta | 非商用 | ✅ | ✅✅ | 弱 | 弱 | 是 | arXiv 论文（已停维护） |
7.2 分场景推荐
| 你的需求 | 推荐 | 原因 |
|---|---|---|
| 中文论文 / 教材 / 研报 | MinerU hybrid | 公式+表格+CJK 综合最强 |
| 只有 CPU、批量扫描件 | MinerU pipeline 或 Docling | 不依赖大显存 |
| 百万页批量、有 H100 | Marker | 吞吐极高（注意许可证） |
| 企业内网、MIT 许可 | Docling | 许可最宽松，集成成熟 |
| 原生 PDF、追求极速 | PyMuPDF4LLM | 毫秒级，但无 OCR |
| 临时转 Word/PPT | MarkItDown | 安装最简单 |
| 数学 arXiv 旧论文 | Nougat（维护风险） | 仅英文、非商用 |
7.3 MinerU 相对竞品的真实短板
客观说，MinerU 并非万能：
- 资源占用：完整安装 + 模型缓存约 20GB 级，高于 MarkItDown / PyMuPDF4LLM
- 表格输出格式：常输出 HTML 而非 GitHub 风格 pipe table，部分 RAG 框架需适配
- 法律/脚注类文档：第三方评测暴露脚注丢失、目录误标标题等问题
- 许可证 ：虽比 AGPL 友好，但仍基于 Apache 2.0 附带额外条款，商用前需读 LICENSE.md
- v4 仍在 Alpha ：生产环境请锁定 3.4.5 稳定版
8. RAG 实战建议
8.1 推荐工作流
text
原始文档 → MinerU 解析 → content_list.json 分块 → Embedding → 向量库 → RAG8.2 参数建议
| 文档类型 | 后端 | effort | 备注 |
|---|---|---|---|
| 数字版 PDF 论文 | hybrid-auto-engine | medium | 默认即可 |
| 扫描版书籍 | hybrid 或 pipeline | high / 默认 | 注意 --lang |
| 纯 Office | office 后端（自动） | - | 3.1+ 原生 DOCX/PPTX/XLSX |
| 超长文档（>500 页） | API 异步 + router | medium | 3.0 流式落盘 |
| 边缘设备 | pipeline 或 http-client | - | 2GB 显存 client |
8.3 分块注意事项
- 保留 标题层级（hybrid 效果远好于 MarkItDown）
- 表格块单独处理：HTML 表格可整段入库，或转描述文本
- 公式块：LaTeX 对数学 RAG 友好，但 token 较长，考虑摘要
- 解析后 人工抽检 5% 样本，尤其脚注、跨页表格、双栏目录
9. 版本升级速查
| 你现在的版本 | 建议 | 理由 |
|---|---|---|
| magic-pdf 1.x | 升级到 3.4.5 | 包名已废弃，API 不兼容 |
| MinerU 2.5 ~ 2.6 | 升级到 3.4.5 | Hybrid 默认、Office 原生、许可证变更 |
| MinerU 3.0 ~ 3.3 | 升级到 3.4.5 | PP-OCRv6、OCR 速度翻倍 |
| MinerU 3.4.x | 保持或 patch | 当前稳定主线 |
| v4.0.0a* | 仅测试 | Alpha 预览，勿上生产 |
10. 总结
MinerU 的演进路线清晰：
- magic-pdf 阶段：把中文科技文献 PDF 解析做好
- 2.x 阶段：引入 VLM + Hybrid，精度追上 SOTA
- 3.x 阶段：Office 全格式、API/Router 工程化、许可证开放、OCR 大幅提速
如果你在做 中文 RAG、学术知识库、复杂版式文档摄入，MinerU 是目前开源方案中综合性价比最高的选择之一；若只有原生 PDF、追求极致速度，PyMuPDF4LLM / MarkItDown 更合适；若看重 MIT 许可与企业集成，Docling 是稳健备选。
落地三步走：
- 用 mineru.net 或 Gradio 在线版验证你的文档集
- 按硬件选 backend（无 GPU → pipeline；有 8GB+ → hybrid medium）
- 对接 RAG 前，用 5 份代表性文档做人工质检 + 检索评测
参考资料
- MinerU GitHub：https://github.com/opendatalab/MinerU
- 官方文档：https://opendatalab.github.io/MinerU/
- 更新日志：https://opendatalab.github.io/MinerU/zh/reference/changelog/
- MinerU 在线版：https://mineru.net/
- MinerU 技术报告：https://arxiv.org/abs/2409.18839
- MinerU2.5 论文：https://arxiv.org/abs/2509.22186
- MinerU2.5-Pro 论文：https://arxiv.org/abs/2604.04771
- OmniDocBench：https://github.com/opendatalab/OmniDocBench
- PDF→MD 横向评测：https://github.com/pdfmarkdownapp/pdf-to-markdown-benchmark
- Marker：https://github.com/VikParuchuri/marker
- Docling：https://github.com/docling-project/docling
- MarkItDown：https://github.com/microsoft/markitdown
- PyMuPDF4LLM：https://github.com/pymupdf/RAG