MinerU 架构拆解：高精度文档解析引擎的 pipeline / vlm-engine / hybrid 三路后端与多模态输出

opendatalab/MinerU 想做的事情并不只是一份 PDF 转 Markdown 工具——它要替代的是 PDF-Extract-Kit、marker、unstructured 这类在 InternLM 预训练数据生产线上被反复重写的"半成品"工作流。截至 2026-06-25，这个 69,156 Stars、5,843 Forks、MinerU Open Source License（基于 Apache 2.0 加附加条款）的项目（创建于 2024-02-29）已经把"PDF / DOCX / PPTX / XLSX / 图片"五大输入格式、109 种语言 OCR、scan / handwriting / multi-column / 跨页表格合并等复杂版面都跑通了，并在 OmniDocBench v1.6 上做到 pipeline 86.47、hybrid 95.39 (high) / 95.26 (medium) 的端到端精度。本文是一篇架构分析，文章会拆 MinerU 的三路后端（pipeline / vlm-engine / hybrid-engine / *-http-client）、MCP Server 与 LangChain/Dify/FastGPT 的多端集成、以及从 CPU 到 10+ 国产 AI 芯片的部署策略，并讨论为什么 LLM 训练数据生产线上需要一个"全格式原生 + 严格保序"的解析层。

一、核心判断：MinerU 是"为下游 Agent / RAG / 训练数据生产线而设计"的解析层

MinerU 的 README 第一句话划定了产品边界：

MinerU is a document parsing tool that converts PDF, image, DOCX, PPTX, and XLSX inputs into machine-readable formats such as Markdown and JSON for downstream retrieval, extraction, and processing.

三个关键词决定了它和 marker / unstructured / PyMuPDF 的根本差异：

• machine-readable：输出必须能让 RAG（检索增强生成）召回、能被 LLM 微调数据流水线消费、能用 JSON schema 校验，而不是"看起来像 Markdown"
• downstream retrieval, extraction, and processing：定位是"解析层"，不是"转换器"——下游客服 Agent、文档问答、表格抽取、训练数据 ETL 才是真正的消费方
• DOCX / PPTX / XLSX 是和 PDF 一等公民：2026-04 之前 MinerU 只能从 PDF / 图片出发，把 Office 文件先转 PDF 再走解析；2026-04 之后 3.1.0 起原生支持 PPTX / XLSX，2026-03 之前 3.0.0 起原生支持 DOCX——这是"为全文档流水线设计"和"为 PDF 设计"的根本分水岭

这意味着 MinerU 的目标是"全格式原生 + 严格保序 + 多端可消费"，而不是"最快的 PDF 解析"或"最便宜的 OCR"。

二、系统地图：CLI / API / Router 编排 + 三路后端 + 多 AI 芯片

MinerU 3.0+ 的代码组织是清晰的分层架构：

┌────────────────────────────────────────────────────────────────┐
│  L3 入口层（CLI / Python / Go / TypeScript SDK / REST API）    │
│    mineru CLI   mineru-api (FastAPI)   mineru-router           │
│    POST /file_parse (同步)   POST /tasks (异步)                │
├────────────────────────────────────────────────────────────────┤
│  L2 推理后端（三路可选）                                        │
│    pipeline       vlm-engine       hybrid-engine               │
│    (CPU/GPU, OCR) (VLM, vLLM)      (原生文本 + VLM)            │
│    86.47 (v1.6)   95.30 (v1.6)     95.39 high / 95.26 medium   │
│                                                                 │
│  *-http-client：把 vlm-engine / hybrid-engine 替换为           │
│  兼容 OpenAI API 的远端推理服务                                │
├────────────────────────────────────────────────────────────────┤
│  L1 模型与解析库                                                │
│    MinerU2.5-Pro-2605-1.2B（VLM 主模型，2026-06 升级）        │
│    PP-OCRv6（2026-06 OCR 模型升级，精度 +11%）                 │
│    layoutreader（已被 3.0 移除以彻底清除 AGPL/CC-BY-NC-SA）  │
│    PDF/DOCX/PPTX/XLSX 各格式原生解析器                          │
├────────────────────────────────────────────────────────────────┤
│  L0 基础设施                                                     │
│    Python 3.10-3.13   PyTorch ≥ 2.8   vLLM 0.11.2              │
│    10+ 国产 AI 芯片：昇腾 / 寒武纪 / 燧原 / 沐曦 / Moore      │
│                       Threads / 昆仑芯 / 壁仞 / 海光 / 平头哥  │
│    Docker / WSL2（Linux / Windows，macOS 不走 Docker）         │
└────────────────────────────────────────────────────────────────┘

下面逐层看每一层的关键判断。

三、L2 后端：pipeline / vlm-engine / hybrid-engine 三路分立

MinerU 真正的工程取舍在"三路后端"的设计上。README 的版本支持矩阵（基于 OmniDocBench v1.6 端到端精度）：

三路后端不是"性能梯度"，而是"工程取舍的三条正交轴"：

3.1 pipeline 后端：CPU 友好、零幻觉的 OCR 路线

pipeline 后端是经典的"版面分析 + OCR + 公式识别 + 表格识别"流水线：

• 不依赖大模型，所有步骤都是专用模型（PP-OCRv6、UniMERNet、TableStructureRec）
• 可在纯 CPU 上跑，显存 4GB 起
• 不会"幻觉"——所有内容都来自版面检测和 OCR 识别，没有 VLM 自由生成的可能
• 精度 86.47——比上一代 VLM 模型 MinerU2.0-2505-0.9B 还高

适用场景：科研论文批量解析（幻觉对科学公式是致命的）、CPU 集群、显存受限的边缘设备。

3.2 vlm-engine 后端：VLM 一体化的精度路线

vlm-engine 把"版面理解 + 文字识别 + 公式识别"全部交给一个 VLM（视觉-语言模型）：

• 主模型 MinerU2.5-Pro-2605-1.2B（2026-06 升级，1.2B 参数）
• 通过 vLLM / LMDeploy / mlx 推理生态运行
• 不支持 CPU，显存 8GB 起
• 精度 95.30，端到端最强

适用场景：版面极其复杂（杂志排版、混合图表 + 文字 + 公式）、对精度要求 > 95% 的金融 / 法律文档。

3.3 hybrid-engine 后端：原生文本 + VLM 的折中路线

hybrid-engine 是 3.0 之后的默认后端（2026-06 之后 medium 模式进一步默认）：

• 优先抽原生文本（PDF 文本层、Office XML 文本）——不经过 VLM
• VLM 只补版面理解、表格、图表、扫描页——VLM 只在该上场时上场
• 3.3 新增 effort=medium | high 参数：
  • high 模式：精度 95.39，支持 image analysis
  • medium 模式：精度 95.26（仅 -0.13），速度提升 35%~220%（Linux/Windows/macOS 三平台不同）

effort=medium 的关键是"用 0.13 个百分点的精度换 80%~220% 的速度"。对一个 100 万页的批量数据生产任务来说，速度的提升远比 0.13 精度重要。

3.4 *-http-client：把推理推到远端

*-http-client 后端是 3.0 引入的"无 GPU 本地 + 远端推理服务"模式：

• 本地 mineru 客户端 + 远端 OpenAI 兼容推理服务（vLLM / SGLang / LMDeploy）
• 本地显存需求 0
• 适合"边缘设备 + 数据中心推理"的网络拓扑

四、3.x 关键版本演进：从"PDF 解析器"到"全格式原生"

MinerU 2026 上半年的三次重要发布（3.0 / 3.1 / 3.3 / 3.4）把工程能力往前推了一截。

4.1 3.0.0（2026-03-29）：原生 DOCX + pipeline 精度跃升 + API 编排

• 原生 DOCX 解析：不再走"先转 PDF 再解析"的中间步骤，端到端速度提升"几十倍"（README 原话）
• pipeline 精度：OmniDocBench v1.5 评分 86.2，超过上一代 VLM MinerU2.0-2505-0.9B
• API 编排：mineru 变成基于 mineru-api 的编排客户端，未传 --api-url 时自动启动本地临时服务
• 异步任务端点：POST /tasks 提交任务 + 状态查询 + 结果拉取；POST /file_parse 同步端点保留兼容
• mineru-router：多服务、多 GPU 统一入口 + 自动任务负载均衡
• 滑动窗口 + 流式写盘：超长文档峰值内存下降，万页级文档不再需要手动拆分
• 彻底清除 AGPL / CC-BY-NC-SA 模型：doclayoutyolo / mfd_yolov8（AGPLv3）、layoutreader（CC-BY-NC-SA 4.0）全部移除，许可证路线图解锁

4.2 3.1.0（2026-04-18）：许可证升级 + VLM 升级 + 全格式原生

• 许可证：AGPLv3 → MinerU Open Source License（基于 Apache 2.0 + 附加条款）
• VLM 主模型：MinerU2.5-Pro-2604-1.2B——图像 / 图表解析、跨段合并、跨页表格合并、表格内图片识别
• PPTX / XLSX 原生支持：与 PDF / DOCX / 图片并列一等公民

4.3 3.3（2026-06-11）：hybrid effort 参数 + VLM 多语言 OCR

• effort=medium | high 解析强度参数（仅 hybrid）
• VLM 升级到 MinerU2.5-Pro-2605-1.2B，原生多语言 OCR（无需额外语言配置）

4.4 3.4（2026-06-18）：OCR 升级 + 模型下载体验优化

• OCR 模型升级到 PP-OCRv6：OmniDocBench v1.6 精度提升约 11%
• OCR 处理流水线优化：批量文档 / OCR 密集型文档解析速度提升约 100%
• 自动模型源选择：首次安装根据网络环境选最优源
• 本地模型缓存优先：避免重复下载

3.x 的演进路径很清晰：每一次大版本都解掉一组"非 MinerU 自己能解决的外部依赖"——AGPL 模型、Office 文件非原生、CPU 不可用、远端推理不支持。这种"把工程代价外部化"的节奏是健康的，因为 MinerU 自己的核心（版面理解 + 公式识别 + 表格识别 + VLM）一直是稳定内功。

五、L3 入口层：MCP Server + SDK + Dify / FastGPT / LangChain

MinerU 3.x 的另一个工程取舍是"在所有 AI Coding / Agent 框架里都能直接用"。

5.1 MCP Server

MCP（Model Context Protocol，模型上下文协议）是 2025-2026 年 Agent 工具接入的事实标准。MinerU 提供官方 MCP Server：

支持客户端：Cursor / Claude Desktop / Windsurf
输入：本地文件路径 / PDF / 图片 / Office 文件
输出：Markdown / JSON

MCP 的好处是"AI 编码助手可以直接调用 MinerU 解析 PDF"——比如 Cursor 里直接说"把 docs/contract.pdf 解析成 Markdown"。

5.2 RAG 框架原生集成

注意：这些集成是"数据源集成"——MinerU 负责把文档变成 Markdown / JSON，RAG 框架负责后续切块、向量化、检索。MinerU 不抢 RAG 的活。

5.3 SDK + CLI + REST API

• Python SDK：from mineru import parse 风格的程序化调用
• Go / TypeScript SDK：跨语言消费
• CLI：mineru -p <input> -o <output> [-b backend] 一行命令
• REST API：mineru-api FastAPI 服务（同步 + 异步端点）
• Gradio WebUI：本地可视化界面

六、L0 基础设施：10+ 国产 AI 芯片 + 跨平台部署

6.1 国产 AI 芯片支持

MinerU 明确列出 10+ 国产 AI 芯片支持：

• 昇腾（华为）
• 寒武纪
• 燧原
• 沐曦
• Moore Threads（摩尔线程）
• 昆仑芯（百度）
• Iluvatar（天数智芯）
• 海光（Hygon）
• 壁仞
• 平头哥（T-Head，阿里）

这是一个工程化投入巨大的信号——单是为一个开源项目做 10+ 芯片的适配测试，就要数月工作量。这意味着 MinerU 在中国市场的 B 端 / G 端部署上几乎没有"必须用英伟达"的硬约束。

6.2 跨平台部署

• Linux：2019+ 发行版（ray 限制）
• Windows：3.10-3.12（ray 不支持 3.13）
• macOS：14.0+，MPS 加速
• Docker / WSL2：Linux / Windows，macOS 不走 Docker

七、OmniDocBench 评测定位：精度的客观对照

MinerU 把 OmniDocBench（同一团队开源的文档解析评测基准）作为客观对照表：

注意：hybrid 95.26 / 95.39 的差距是 0.13——而 medium 模式速度比 high 快 35%~220%。这是非常划算的"速度/精度"取舍。

benchmark 解释：

• “端到端评分” 反映"整个 pipeline（版面分析 + 文字识别 + 公式识别 + 表格识别）从 PDF 到 Markdown 的整体质量"
• 不能推出：“对某个特定类型文档的精度”——benchmark 是综合评分，不是细分场景对照
• 不能推出：“与商业产品（Adobe、AFFiNE）的对照”——必须用同一版本 OmniDocBench 跑对照实验

八、一个 PDF 从 CLI 到 Markdown 的完整路径

以一个 200 页的混合排版 PDF（多列 + 跨页表格 + 公式 + 扫描页）为例，走默认的 hybrid-engine + effort=medium 路径：

# 1. 安装
pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

# 2. 解析（CLI 一行）
mineru -p ./paper.pdf -o ./output

# 3. 等价于编程方式
# from mineru import parse
# md = parse("./paper.pdf", backend="hybrid-engine", effort="medium")

内部流程：

1. CLI 解析参数
   ↓
2. mineru-api 编排：本地客户端拉起 / 检测远端服务
   ↓
3. hybrid-engine 后端
   ├─ 先抽 PDF 原生文本（文本层 / Office XML）
   ├─ 用 VLM 补版面理解（多列识别 / 跨页表格）
   ├─ OCR 兜底扫描页（PP-OCRv6）
   └─ 公式 / 表格后处理（UniMERNet / TableStructureRec）
   ↓
4. 按人类阅读顺序拼接
   ├─ 自动去除页眉 / 页脚 / 脚注 / 页码
   ├─ 公式 → LaTeX
   ├─ 表格 → HTML
   └─ 图片 / 图表 / 描述 / 表格标题 / 脚注全部保留
   ↓
5. 输出 multimodal-markdown / nlp-markdown / JSON（按阅读顺序）

九、与 marker / unstructured / PyMuPDF 的取舍对比

关键差异：

• marker 走 VLM 一体化路线（强项：版面复杂；弱项：CPU 不友好、精度依赖 VLM）
• unstructured 走通用路线（强项：格式多；弱项：精度一般，公式支持弱）
• PyMuPDF 走轻量原生路线（强项：速度；弱项：仅 PDF、公式支持弱、AGPL 商用问题）
• MinerU 是"三路后端 + 全格式 + 国产芯片"的工程化方案

十、当前版本的硬约束

截至 2026-06-25 的版本（3.4），硬约束包括：

• Python 3.10-3.13：Windows 下 ray 不支持 3.13，只支持 3.10-3.12
• macOS 14.0+：MPS 加速仅 Apple Silicon
• Docker 仅 Linux / WSL2：macOS 不支持 Docker 部署
• Linux 2019+ 发行版：更老的发行版未测试
• VLM 显存 8GB+：hybrid / vlm-engine 在显存 < 8GB 时无法运行（可走 -http-client 把推理推到远端）
• OCR 模型自动源选择：首次安装会根据网络环境选源，企业内网需要手动配置模型源
• 3.0 起才原生支持 Office：3.0 之前的版本，DOCX / PPTX / XLSX 会被先转 PDF 再解析，速度损失巨大
• 活跃开发期：README 明确写出"may include breaking changes before 1.0"

十一、快速上手路径

11.1 第一次接触

1. 打开 mineru.net 在线 demo（需要登录）—— 评估解析质量是否满足需求
2. 再用 HuggingFace / ModelScope 上的 Gradio demo 试免登录版本
3. 选一个自己的 PDF 上传，看输出 Markdown / JSON 的质量

11.2 第一次本地部署

1. 硬件检查：Mac 14+ / 任意 Linux / Windows + WSL2
2. 显存 ≥ 4GB（pipeline）或 ≥ 8GB（hybrid/vlm）或 ≥ 2GB（hybrid medium）
3. pip install uv + uv pip install -U "mineru[all]"
4. mineru -p test.pdf -o output 跑通最小例子
5. 评估输出质量，再决定是否切换后端 / 切换 effort

11.3 第一次接 RAG

1. Python SDK：from mineru import parse
2. 切块：用 LangChain / LlamaIndex 的 MarkdownHeaderTextSplitter 或 MarkdownTextSplitter
3. 向量化：任选 embedding（bge / m3e / OpenAI text-embedding-3）
4. 落地：FAISS / Milvus / pgvector

十二、这篇文章没覆盖什么

• MinerU-Diffusion（opendatalab/MinerU-Diffusion）：一个独立项目，把 OCR 重新定义为"逆渲染 + 扩散解码"，是 arXiv 2603.22458 论文的代码实现
• PDF-Extract-Kit / magic-doc：早期项目，已被 MinerU 取代
• OmniDocBench 评测细节：评测集构造、评分算法、对照实验
• DataFlow（OpenDCAI/DataFlow）：上游 LLM 数据 ETL 流水线
• LabelU / LabelLLM：配套的数据标注工具
• Paper 复现：4 篇 arXiv 论文的具体复现实验

十三、适用人群与采用建议

十四、总结

MinerU 的真正价值不是"又一个 PDF 解析器"，而是它把"全格式原生 + 多路后端 + 多芯片 + 多端可消费"这四件事同时做完了。下游消费者（训练数据流水线、RAG 引擎、AI 编码助手）只需要挑后端、写解析、拿 Markdown / JSON，剩下的工程代价 MinerU 已经替它付了。

挑后端的核心问题只有一个：你的速度预算和精度预算分别是多少？ 答案是：

• 速度优先：hybrid + medium
• 精度优先：hybrid + high 或 vlm
• 显存 / CPU 受限：pipeline 或 *-http-client
• 全自动：什么都不传，让 MinerU 选 hybrid + medium