夜雨聆风
MinerU:一款能＂读懂＂文档的开源神器
在这个信息爆炸的时代，我们每天都要处理大量的PDF文档——科研论文、技术报告、电子书、合同文件……但你有没有想过，如果能让计算机像人类一样”理解”这些文档，会是什么样子？
今天要给大家介绍的项目叫MinerU，这是一个由OpenDataLab团队开源的文档解析工具，它能够将PDF和图片转换为机器可读的格式（Markdown和JSON），让文档内容变得可以被程序轻松提取和处理。
为什么要做MinerU？
说起来，MinerU的诞生还挺有意思。它最早其实是InternLM预训练工作的副产品——团队在处理科学文献时发现，符号转换是一个让人头疼的问题。你想啊，一篇满是公式、表格、多栏排版的学术论文，想要准确提取其中的结构化内容，难度有多大？
于是，MinerU就这样诞生了。经过几轮迭代，如今已经发展成为一个功能相当完善的文档解析解决方案。
MinerU能做什么？
先来看看MinerU的核心能力：
1. 文档清洗
自动识别并移除页眉、页脚、脚注、页码这些”噪音”，让文档内容保持语义连贯。
2. 阅读顺序重组
这个功能特别实用。很多PDF文档尤其是学术论文，排版复杂得很——双栏、三栏、图文混排……MinerU能智能识别内容的真实阅读顺序，无论是单栏、多栏还是复杂布局都能搞定。
3. 结构保留
标题、段落、列表这些文档结构都会被完整保留，不会变成一堆杂乱的文字。
4. 多模态内容提取
-
图片和图注 -
表格及其内容 -
各级标题 -
脚注和参考文献
5. 公式和表格识别
这是MinerU的强项之一。数学公式会自动转换为LaTeX格式，表格则转换为HTML格式，方便后续处理。
6. 强大的OCR支持
支持109种语言的文字识别，能自动检测扫描版PDF和模糊文档。
技术架构：三种后端模式
MinerU的一个设计亮点是采用了多后端架构，针对不同场景提供三种解析模式：
Pipeline后端
这是传统的解析方案，兼容性好，精度能达到82分以上（基于OmniDocBench v1.5评测）。适合在CPU环境下运行，对硬件要求较低。
Hybrid/VLM后端
基于视觉语言模型的解析方式，精度超过90分。它会根据运行环境自动选择最优的推理引擎——vLLM、LMDeploy或MLX。这是默认选项，开箱即用效果最好。
HTTP客户端后端
这个模式比较有意思，可以连接到远程的OpenAI兼容服务器进行解析，适合有私有部署需求的用户。
系统架构图
┌─────────────────────────────────────────────────────────────────────────────┐│ MinerU 系统架构 │└─────────────────────────────────────────────────────────────────────────────┘┌──────────────┐│ 用户接口层 │├──────────────┤│ • CLI 命令行 │ mineru -p xxx.pdf -o output│ • Web UI │ mineru-gradio / mineru.net│ • Python API │ mineru_core.parse()│ • FastAPI │ mineru-api└──────┬───────┘│▼┌────────────────────────────────────────────────────────────────┐│ 后端路由层 │├────────────────────────────────────────────────────────────────┤│ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ ││ │ Pipeline │ │ Hybrid │ │ HTTP Client │ ││ │ Backend │ │ Backend │ │ Backend │ ││ │ (CPU模式) │ │ (GPU模式) │ │ (远程服务器) │ ││ └─────┬──────┘ └─────┬──────┘ └──────────┬─────────┘ │└────────┼────────────────┼────────────────────┼────────────────┘│ │ ││ ┌───────────▼────────────────────▼─────────┐│ │ 核心处理引擎 ││ │ ┌─────────────────────────────────┐ ││ │ │ • DocLayout-YOLO (布局检测) │ ││ │ │ • PaddleOCR (文字识别) │ ││ │ │ • YOLOv8-MFD (公式检测) │ ││ │ │ • Unimernet (公式识别) │ ││ │ │ • RapidTable (表格识别) │ ││ │ │ • MinerU2.5 VLM (视觉理解) │ ││ │ └─────────────────────────────────┘ ││ └─────────────────┬───────────────────────┘│ │▼ ▼┌────────────────────────────────────────────────────────────────┐│ 处理流程 │├────────────────────────────────────────────────────────────────┤│ ││ PDF/图片 ─► 预处理 ─► 布局分析 ─► 内容识别 ─► 结构化输出 ││ │ │ │ │ ││ ▼ ▼ ▼ ▼ ││ 格式转换 区域检测 OCR/公式 Markdown/JSON ││ 页面分割 类型分类 表格识别 阅读顺序排序 ││ 噪声去除 位置定位 多语言 跨页合并 ││ │└────────────────────────────────────────────────────────────────┘│▼┌────────────────────────────────────────────────────────────────┐│ 输出格式 │├────────────────────────────────────────────────────────────────┤│ • Markdown (.md) ──► 易读的文档格式 ││ • JSON (.json) ──► 结构化数据 ││ • content_list.json ───► 完整内容列表 ││ • middle.json ───► 中间处理结果 ││ • images/ ───► 提取的图片 │└────────────────────────────────────────────────────────────────┘┌────────────────────────────────────────────────────────────────┐│ 硬件加速支持 │├────────────────────────────────────────────────────────────────┤│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ││ │ NVIDIA │ │ 华为昇腾 │ │ Apple │ │ 寒武纪 │ │ CPU │ ││ │ CUDA │ │ CANN │ │ MPS │ │ MLU │ │ Mode │ ││ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │└────────────────────────────────────────────────────────────────┘
核心技术揭秘
DocLayout-YOLO：布局识别的”火眼金睛”
DocLayout-YOLO是MinerU自研的布局识别模型，在0.9.0版本中引入。它的特点是什么？比之前的方案速度快了10倍以上，而且解析效果相当。这个模型负责识别文档中的不同区域——文本区、标题区、图片区、表格区等等。
公式识别：两阶段处理
数学公式的识别是个技术活，MinerU采用了两阶段方案：
检测阶段（MFD）：先用YOLOv8模型找到公式在哪里
识别阶段（MFR）：再用Unimernet等模型把公式转换成LaTeX代码
这个管道式的设计使得公式识别既准确又高效。
表格识别：有线无线都能搞定
表格识别的复杂度在于表格的样式千差万别。MinerU的处理方式是：
-
方向检测：先检测表格有没有旋转（0/90/180/270度） -
类型分类：判断是有线表格（带边框）还是无线表格（无边框） -
结构识别：有线表格用UnetTableModel，无线表格用RapidTableModel（SLANet+） -
结果优选：两个模型的结果会进行比较，选择更好的HTML输出
特别值得一提的是，MinerU还支持跨页表格的合并，这对于处理大型表格来说简直是救星。
VLM后端：MinerU2.5模型
在VLM后端中，MinerU使用了一个叫MinerU2.5的模型，参数量只有1.2B，但效果相当惊人——在OmniDocBench基准测试中，它竟然超过了Gemini 2.5 Pro、GPT-4o、Qwen2.5-VL-72B这些大型多模态模型。这说明在小模型精细调优这个方向上，国内团队确实走出了自己的路。
性能表现
用数据说话可能更直观：
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
应用场景
MinerU的应用场景其实挺广泛的：
学术研究：科研论文的批量处理，方便文献管理和知识图谱构建
企业文档：技术文档、合同、报告的结构化提取
数据采集：从PDF中提取表格数据进行分析
数字化工程：纸质文档扫描件的数字化处理
多语言处理：支持109种语言，国际化场景友好
如何安装？
在开始使用之前，先来看看系统要求和安装方法。
系统要求
MinerU对硬件的要求取决于你选择的后端模式：
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
注意：Windows用户只能使用pipeline后端，因为hybrid和vlm后端的ray依赖不支持Windows。
安装方法
方法一：使用uv安装（推荐）
这是最简单的安装方式，适合大多数用户：
# 先更新pippip install --upgrade pip# 安装uvpip install uv# 安装MinerU完整版uv pip install -U "mineru[all]"
方法二：从源码安装
如果你想体验最新功能或者参与开发，可以从GitHub克隆源码：
git clone https://github.com/opendatalab/MinerU.gitcd MinerUuv pip install -e .[all]
方法三：Docker部署
Docker是最省心的部署方式，所有依赖都预配置好了，不用担心环境冲突。
国内用户（使用DaoCloud镜像和ModelScope模型源）：
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/Dockerfiledocker build -t mineru:latest -f Dockerfile .
海外用户（使用官方镜像源和HuggingFace）：
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/global/Dockerfiledocker build -t mineru:latest -f Dockerfile .
启动容器：
docker run --gpus all \--shm-size 32g \-p 30000:30000 -p 7860:7860 -p 8000:8000 \--ipc=host \-it mineru:latest \/bin/bash
或者用Docker Compose一键启动服务：
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yamldocker compose -f compose.yaml --profile openai-server up -d
配置模型源
MinerU会在首次运行时自动下载模型，默认从HuggingFace下载。如果你在国内访问较慢，可以设置环境变量使用ModelScope：
export MINERU_MODEL_SOURCE=modelscope如何使用？
安装完成后，就可以开始解析文档了。
基本用法
GPU加速解析（默认使用hybrid-auto-engine后端）：
mineru -p document.pdf -o ./outputCPU模式解析（使用pipeline后端）：
mineru -p document.pdf -o ./output -b pipeline批量解析：
mineru -p /path/to/pdfs -o ./output客户端-服务器模式
如果你有多台机器，可以把GPU机器作为服务器，轻量机器作为客户端：
# 服务器端（GPU机器）mineru-openai-server --port 30000# 客户端（普通机器）mineru -p document.pdf -o ./output -b hybrid-http-client -u http://服务器IP:30000
Web界面使用
启动Gradio界面（无需登录）：
mineru-gradio启动FastAPI服务：
mineru-api浏览器访问对应端口就能通过Web界面上传文档进行解析了。
输出结果
解析完成后，输出目录会包含以下文件：
-
*.md：Markdown格式的文档内容 -
content_list.json：结构化的JSON数据 -
middle.json：中间处理结果（用于调试） -
images/：提取的图片文件
硬件支持
MinerU在硬件兼容性方面做得不错：
-
NVIDIA GPU（CUDA） -
华为昇腾NPU（CANN） -
苹果M系列芯片（MPS/MLX） -
寒武纪、燧原等国产算力平台 -
纯CPU模式
这意味着无论你是用MacBook Pro做轻量处理，还是用服务器集群做大规模文档解析，都能找到合适的部署方案。
写在最后
文档解析这个领域，说起来基础，但实际做起来坑不少。MinerU作为开源方案，能在OmniDocBench上拿到90+的分数，确实不容易。对于有文档处理需求的技术团队来说，这提供了一个可定制、可扩展的起点。
当然，工具再好也只是工具，关键还是要结合具体场景来用。如果你正好有文档解析的需求，不妨试试MinerU，看看它能不能解决你的问题。
项目地址：https://github.com/opendatalab/MinerU
官方文档：mineru.net
