MinerU 系列教程 | 第一课：走进 MinerU -- 核心功能与整体架构概览

MinerU 系列教程第一课：走进 MinerU -- 核心功能与整体架构概览

MinerU 系列教程第一篇

本篇教程作为 模块一：基础入门与架构概览 的第一课，全面介绍 MinerU 的核心功能与整体架构。无论你是刚接触文档解析领域的新手，还是正在寻找高质量 PDF 解析方案的工程师，本文都将帮助你建立对 MinerU 的全局认知，为后续的实战操作打下坚实基础。

学习目标

完成本课学习后，你将能够：

理解 MinerU 的基本定位与核心价值
了解 MinerU 的三大推理后端（Pipeline / VLM / Hybrid）及其适用场景
掌握 MinerU 支持的输入格式、输出格式与主要特性
熟悉 MinerU 的部署方式和交互入口
了解 MinerU 的项目背景与应用场景

一、MinerU 是什么

1.1 基本定位

MinerU 是一款面向 LLM / RAG / Agent 场景构建的 高精度文档解析引擎，能够将 PDF、图片、DOCX 等非结构化文档转化为机器可读的结构化格式（如 Markdown、JSON），便于后续的检索、抽取与二次处理。

用一句话来概括：

MinerU 将"人能看懂的文档"变为"机器能理解的数据"。

1.2 解决什么问题

在大模型（LLM）时代，高质量的训练数据和知识库构建都依赖于对海量文档的精准解析。然而，现实中的文档面临诸多挑战：

挑战	具体表现
格式多样	PDF、扫描件、Word、PPT、图片、网页等多种来源
版面复杂	多栏布局、跨页表格、嵌套公式、混排图文
内容异构	公式、表格、图片、代码块、手写体混合出现
语言多样	需覆盖中文、英文、日文、阿拉伯文等多种语言

MinerU 正是为解决这些问题而生。它通过 VLM + OCR 双引擎架构，在保持高精度的同时，支持 109 种语言的识别与解析。

二、核心技术栈：三大推理后端

MinerU 的解析能力建立在三套推理后端之上，用户可以根据硬件条件和精度需求灵活选择。

2.1 Pipeline 后端

复制代码

特点：快速稳定，无幻觉，CPU / GPU 均可运行

Pipeline 后端采用传统的 模块化流水线 架构，将文档解析拆解为版面分析、OCR 识别、公式识别、表格解析等独立阶段，逐步完成文档的结构化还原。

核心特点：

CPU 友好：无需 GPU 即可运行，适合资源受限的环境
无幻觉：基于规则与传统模型的组合，不会产生大模型的"编造"问题
高性价比：在 OmniDocBench (v1.5) 上取得 86.2 分，精度超过上一代主流 VLM
低资源占用：最低 4GB 显存（使用 GPU 加速时），纯 CPU 环境同样可用

技术组件包括：

版面分析模型（Layout Detection）
OCR 引擎（支持 109 种语言）
公式识别（输出 LaTeX）
表格结构识别（输出 HTML）
阅读顺序排序
文档分类器

2.2 VLM 后端（vlm-engine）

复制代码

特点：高精度，支持 vLLM / LMDeploy / mlx 推理生态

VLM（Vision-Language Model）后端直接利用视觉语言大模型对文档页面进行端到端的理解与转化，在复杂版面上具有更强的语义理解能力。

核心特点：

高精度：在 OmniDocBench (v1.5) 上得分 90+
端到端：无需拆解为多个子任务，直接从图像到结构化输出
多推理框架：支持 vLLM、LMDeploy、mlx-vlm 等主流推理引擎
硬件要求较高：需要 8GB 以上显存的 GPU 或 Apple Silicon

2.3 Hybrid 后端（hybrid-engine）

复制代码

特点：高精度 + 原生文本提取，低幻觉

Hybrid 后端是 Pipeline 与 VLM 的融合方案，结合了两者的优势：

原生文本提取：对于文本型 PDF，直接提取原生文字，避免 OCR 或 VLM 的识别误差
VLM 辅助：对于图片、扫描件等非文本内容，调用 VLM 进行高精度解析
低幻觉：通过原生文本兜底，显著降低大模型可能产生的幻觉问题

2.4 三大后端对比

维度	Pipeline	VLM	Hybrid
精度（OmniDocBench v1.5）	86+	90+	90+
是否支持纯 CPU	是	否	否
GPU 显存最低要求	4GB	8GB	8GB
幻觉风险	无	较高	低
适用场景	通用文档、资源受限环境	复杂版面、高精度需求	兼顾精度与可靠性

2.5 Office 后端

除上述三大核心后端外，MinerU 还提供了 Office 后端，支持 DOCX 和 PPTX 的原生解析。相较于"先将 DOCX 转为 PDF 再解析"的传统流程，原生解析在无幻觉的前提下实现高精度，且端到端速度提升数十倍以上。

三、主要特性

3.1 输入格式支持

MinerU 支持多种文档格式作为输入：

PDF：文本型 PDF、扫描型 PDF、混合型 PDF
图片：JPG、PNG 等常见图片格式
DOCX：Word 文档原生解析（3.0 新增）
PPTX：PowerPoint 文档原生解析

3.2 输出格式支持

输出格式	说明
Markdown	适合 NLP 和多模态场景，保留标题、段落、列表等结构
JSON	按阅读顺序排序的结构化数据，含丰富的元信息
中间格式	包含版面坐标、span 信息等详细数据，便于二次开发

3.3 解析能力亮点

公式还原：自动识别文档中的数学公式并转换为 LaTeX 格式
表格还原：自动识别表格结构并转换为 HTML 格式，支持跨页表格合并
版面理解：支持单栏、多栏、复杂排版，输出符合人类阅读顺序
元素过滤：自动去除页眉、页脚、脚注、页码等干扰元素，确保语义连贯
扫描件支持：自动检测扫描版 PDF 和乱码 PDF，并启用 OCR
多语言支持：OCR 引擎支持 109 种语言的检测与识别
可视化质检：提供 layout 可视化、span 可视化等多种检查工具

3.4 部署方式

MinerU 提供了从本地到云端的多层次部署方案：

复制代码

部署方式
├── 本地部署
│   ├── pip / uv 安装
│   └── 源码安装
├── 容器化部署
│   └── Docker
├── 服务化部署
│   ├── mineru-api（FastAPI 服务核心，支持同步 / 异步接口）
│   └── mineru-router（多 GPU 负载均衡路由）
└── 在线体验
    ├── mineru.net 官网在线版
    ├── ModelScope / HuggingFace Demo
    └── Google Colab

3.5 交互入口

入口	说明
`mineru` CLI	命令行工具，支持本地文件/目录输入，可指定后端与输出格式
`mineru-api`	基于 FastAPI 的 REST API 服务，支持同步（`POST /file_parse`）与异步（`POST /tasks`）接口
`mineru-gradio`	基于 Gradio 的 Web UI，提供可视化的文档解析体验
`mineru-router`	多服务、多 GPU 的统一入口，接口与 `mineru-api` 兼容，支持自动负载均衡
MCP Server	支持 Cursor、Claude Desktop、Windsurf 等 AI 编程工具接入
SDK 集成	Python / Go / TypeScript SDK，可嵌入自有系统

四、应用场景

MinerU 的输出结果天然适配下游的知识处理流程，以下是几个典型应用场景：

4.1 RAG（检索增强生成）

这是 MinerU 最核心的应用场景。通过将文档转为结构化 Markdown/JSON，可以直接接入 RAG 框架进行知识检索与问答：

RAGFlow：深度集成，作为文档解析前端
LangChain / LlamaIndex：通过 SDK 或 API 接入解析结果
Dify / FastGPT：原生集成 MinerU 解析能力

4.2 LLM 预训练数据

MinerU 诞生于书生-浦语（InternLM）的预训练过程中，专注于解决科技文献中的符号转化问题，可将海量 PDF 文献高质量地转化为模型可用的训练数据。

4.3 知识库构建

企业可利用 MinerU 将内部文档（技术手册、合同、报告等）批量转化为结构化数据，构建可检索的知识库。

4.4 科技文献处理

针对学术论文中常见的数学公式、化学式、复杂表格等特殊内容，MinerU 提供了专门的识别与转化能力，特别适合科研场景。

五、项目背景与发展

5.1 诞生背景

MinerU 诞生于上海人工智能实验室 OpenDataLab 团队，在书生-浦语（InternLM）大模型的预训练过程中孕育而生。

团队在处理海量科技文献时发现，传统的 PDF 解析工具在面对公式、表格、复杂版面时表现不佳，大量有价值的知识无法被准确提取。为了解决这一瓶颈，MinerU 应运而生，最初专注于 科技文献中的符号转化问题（如数学公式转 LaTeX），随后逐步发展为功能完备的通用文档解析引擎。

5.2 架构演进

MinerU 的架构经历了重要的演进过程：

复制代码

早期版本
  └── 单一 magic-pdf 解析库

2.x 版本
  └── Pipeline + VLM 双引擎

3.0 版本（当前）
  ├── mineru-api    ← 服务核心
  ├── mineru        ← CLI 编排客户端
  └── mineru-router ← 多 GPU 负载均衡

3.0 版本是一次关键跃迁，不仅提升了解析能力，更在系统架构层面实现了从"单机工具"到"可规模化部署的解析基座"的转变。主要突破包括：

滑动窗口 + 流式落盘：解决长文档（上万页）的内存峰值问题
线程安全优化：全面支持多线程并发推理
多卡部署 ：通过 mineru-router 一键实现多 GPU 负载均衡
DOCX 原生解析：端到端速度提升数十倍

5.3 技术栈概览

MinerU 基于 Python 3.10 ~ 3.13 开发，核心技术栈包括：

层级	主要技术
Web 服务	FastAPI、Uvicorn、HTTPX
文档解析	pdfminer.six、pypdfium2、python-docx
图像/OCR/VLM	Pillow、OpenCV、PyTorch、Transformers
推理引擎	vLLM、LMDeploy、mlx-vlm、ONNXRuntime
输出处理	ReportLab、Pandas、BeautifulSoup、pylatexenc

5.4 硬件与平台支持

操作系统：Windows / Linux / macOS
硬件加速：CPU（纯 CPU 可运行）、GPU（CUDA）、NPU（CANN）、Apple MPS
国产算力适配：昇腾、寒武纪、燧原、沐曦、摩尔线程、昆仑芯、天数智芯、瀚博、太初元碁、海光、平头哥
部署模式：支持私有化部署和完全离线运行

小结

本课我们全面了解了 MinerU 的核心全貌：

定位明确：MinerU 是面向 LLM/RAG/Agent 场景的高精度文档解析引擎，将非结构化文档转为结构化的 Markdown/JSON
三大后端：Pipeline（CPU 友好、无幻觉）、VLM（高精度）、Hybrid（兼顾精度与可靠性），用户可按需选择
能力全面：支持 PDF/图片/DOCX/PPTX 输入，覆盖公式、表格、多语言、复杂版面等场景
部署灵活：从 CLI 到 API、从本地到 Docker、从单机到多 GPU 集群，提供完整的部署链路
背景扎实：诞生于书生-浦语预训练实践，经过大规模科技文献解析的实战验证

MinerU 不仅是一个工具，更是连接非结构化文档与大模型生态的关键桥梁。理解了这些基础概念，你就为后续的安装部署和实战操作做好了准备。

下一课预告

第二课：环境搭建与快速上手

我们将动手实践，完成 MinerU 的安装部署（pip/Docker），运行第一个文档解析任务，并深入了解 CLI 的各项参数与输出结构。准备好一份 PDF 文档，下一课见！

MinerU 系列教程 | 第一课：走进 MinerU -- 核心功能与整体架构概览