1、什么是 Mineru？
MinerU是一个将复杂文档（如PDF）转换为LLM就绪的markdown/JSON格式的工具，用于Agentic工作流。相比传统PDF解析工具，MinerU在文档结构解析、多媒体提取、公式识别等方面有着显著优势。
主要功能包括：
- 文档结构解析：移除页眉页脚、脚注、页码等，确保语义连贯性
- 内容提取：输出按人类可读顺序排列的文本，支持单列、多列和复杂布局
- 格式保持：保留原始文档结构（标题、段落、列表等）
- 多媒体提取：提取图像、图像描述、表格、表格标题和脚注
- 公式识别：自动将文档中的公式转换为LaTeX格式
- 表格识别：自动将表格转换为HTML格式
- OCR支持：自动检测扫描版PDF并启用OCR功能，支持84种语言
- 多平台支持：兼容Windows、Linux、Mac平台，支持CPU/GPU/NPU加速
2、环境准备与安装
2.1 硬件要求
- CPU推理：支持纯CPU环境
- GPU要求：Turing架构及以上，6GB+显存（pipeline后端）或8GB+显存（VLM后端）
- 内存要求：最低16GB+，推荐32GB+
- 磁盘空间：20GB+，建议SSD
- Python版本：3.10-3.13
2.2 安装方法
（1）使用pip或uv安装
|-------|---------------------------------------------------------------------------------|
| 1 2 3 | pip install --upgrade pip pip install uv uv pip install -U "mineru[core]" |
（2）基于源码安装
|-------|-----------------------------------------------------------------------------------------------|
| 1 2 3 | git clone https://github.com/opendatalab/MinerU.git cd MinerU uv pip install -e .[core] |
（3）Docker部署
项目提供Docker部署方式，可快速搭建环境解决兼容性问题。
3、配置文件详解
MinerU提供了灵活的配置选项，主要包括：
- 解析后端设置（pipeline和VLM两种）
- 输出格式选择（Markdown、JSON等）
- OCR语言设置
- 图像和表格处理参数
配置文件通常包括解析精度、资源使用限制等关键参数，可以根据需要进行调整。
3.1 解析后端pipeline和VLM对比
3.1.1 Pipeline 后端（传统流水线）
-
原理 ：基于计算机视觉（CV）规则和传统OCR引擎（如PaddleOCR）的组合管道。先分析页面布局（定位标题、段落、图片区域），再对文本区域进行OCR或直接提取。
-
核心模型 ：由多个专项轻量模型 + 规则组成 工具链，分工处理不同任务：
- 布局分析：DocLayoutYOLO（识别标题、段落、表格等元素位置）；
- OCR 识别：PaddleOCR（提取图片中的文字）；
- 表格解析：UnetTableModel（有线表格）、RapidTableModel（无线表格）；
- 公式处理：YOLOv8MFD（公式检测）+ Unimernet（公式识别为 LaTeX）。
-
辅助工具：需要坐标计算（如 IOU 重叠度）、规则匹配（如列表缩进判断）等工程化逻辑。
-
特点：
-
✅ 速度快，资源消耗低，适合批量和实时处理。
-
✅ 对标准电子版文档（如Word生成的PDF）提取准确率高。
-
✅ 技术成熟，稳定性好。
-
❌ 对极端复杂排版（如多栏混排、不规则表格）的还原能力有限。
-
❌ 对扫描质量差的文档容错率较低。
-
3.1.2 VLM 后端（视觉 - 语言模型）
-
原理 ：利用视觉语言大模型理解整个文档页面，像人一样"阅读"并结构化信息。能更好地理解上下文和语义关系。
-
核心模型：依赖视觉 - 语言大模型（如 Qwen2VL、LLaVA 等），具备 "看图理解内容 + 格式" 的能力，需配合 vllm 等推理引擎加速（支持批量 / 异步推理）。
-
辅助工具：仅需基础的 PDF 转图像工具（如 pdf2image），无需其他专项模型（布局分析、OCR、表格解析等均由大模型内部完成）。
-
特点：
-
✅ 理解能力极强，对复杂排版、图表关联、公式、手写体等有更好的还原度。
-
✅ 文档结构还原更精准，逻辑顺序更符合人类阅读习惯。
-
✅ 对低质量扫描件的鲁棒性更好。
-
❌ 速度慢，计算资源消耗大（尤其依赖GPU）。
-
❌ 通常需要本地部署或使用特定云端服务，配置更复杂。
-
3.1.3 性能指标对比
处理速度对比：
| 模式 | 单页处理时间 | 批处理效率 | 加速方案 |
|---|---|---|---|
| Pipeline | 2-5秒/页 | 支持批量并行 | GPU加速 |
| VLM-transformers | 10-20秒/页 | 单页串行 | 无原生加速 |
| VLM-sglang | 0.5-1秒/页 | 支持批量并行 | sglang加速20-30倍 |
资源消耗对比：
| 资源类型 | Pipeline模式 | VLM-transformers | VLM-sglang |
|---|---|---|---|
| GPU显存 | 6GB+ | 8GB+ | 8GB+ |
| CPU内存 | 中等 | 较低 | 较低 |
| 模型存储 | 多模型总计~5GB | 单模型~2GB | 单模型~2GB |
精度表现对比（基于标准测试集的评估结果）：
| 任务类型 | Pipeline模式 | VLM模式 | 优势方 |
|---|---|---|---|
| 常规文本 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Pipeline |
| 复杂布局 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | VLM |
| 手写文本 | ⭐⭐ | ⭐⭐⭐⭐ | VLM |
| 多语言混合 | ⭐⭐⭐⭐ | ⭐⭐⭐ | Pipeline |
| 公式解析 | ⭐⭐⭐⭐ | ⭐⭐⭐ | Pipeline |
| 表格识别 | ⭐⭐⭐ | ⭐⭐⭐⭐ | VLM |
部署方案对比：
| 部署方式 | Pipeline模式 | VLM模式 |
|---|---|---|
| 最低配置 | CPU + 8GB内存 | GPU 8GB + 16GB内存 |
| 推荐配置 | GPU 6GB + 16GB内存 | GPU 16GB + 32GB内存 |
| 模型下载 | 多模型~5GB | 单模型~2GB |
| 依赖项 | 较多专业库 | 相对简洁 |
3.2 配置场景推荐
| 您的场景 | 推荐配置 | 理由 |
|---|---|---|
| 批量处理标准电子版PDF/Word（如公文、报表） | 关闭OCR + Pipeline后端 | 直接提取文字层，速度最快，结果足够准确，成本最低。 |
| 处理扫描版PDF或图片文档 | 开启OCR + Pipeline后端 | 必须通过OCR获取文字。Pipeline方案在清晰度尚可的扫描件上性价比最高。 |
| 处理高度复杂的学术论文、古籍、杂志 | 开启OCR + VLM后端 | VLM能更好地理解多栏排版、图文混排、数学公式和参考文献的复杂结构。 |
| 对格式还原精度要求极高（如存档、出版） | 开启OCR + VLM后端 | VLM的语义理解能力可以最大程度保留原文档的视觉和逻辑结构。 |
| 在本地服务器处理敏感/涉密文档 | 本地部署VLM服务 ，并填写server地址 |
数据不出内网，安全可控，同时能利用大模型的高精度解析能力。 |
| 快速验证或处理简单文档 | 使用 MinerU云端服务 ，语言设auto |
无需部署，开箱即用，适合原型验证或轻量使用。 |
3.3 总结与建议
-
优先尝试默认Pipeline ：对于大多数清晰、结构规范的电子文档，默认的
pipeline模式在速度和准确度上是最平衡的选择。 -
复杂和扫描件用VLM ：当遇到复杂排版、或Pipeline解析结果不理想时，特别是处理学术论文、古籍、复杂报告 时，应转向
v2+VLM后端的方案。 -
OCR是开关，不是质量决定项 ：
开启OCR是处理图片类文档的必要条件，但最终解析质量由"OCR精度" + "后端结构理解能力"共同决定。VLM后端能弥补OCR的某些不足。 -
从云端到本地 ：建议先在 **MinerU官网（mineru.net）** 的在线体验区，用不同配置测试您的典型文档。确定最佳配置后，再考虑是否需要为性能、隐私或定制化需求而进行本地部署。
4、API调用
MinerU提供云端API服务，可以通过简单的HTTP请求调用文档解析功能：
|----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | import requests token ``= "官网申请的api token" url ``= "https://mineru.net/api/v4/extract/task" header ``= { ``"Content-Type"``: ``"application/json"``, ``"Authorization"``: f``"Bearer {token}" } data ``= { ``"url"``: ``"https://cdn-mineru.openxlab.org.cn/demo/example.pdf"``, ``"is_ocr"``: ``True``, ``"enable_formula"``: ``False``, } res ``= requests.post(url,headers``=``header,json``=``data) print``(res.status_code) print``(res.json()) print``(res.json()[``"data"``]) |
API参数说明：
- url: 要解析的PDF文档在线链接
- is_ocr: 是否启用OCR识别（默认True）
- enable_formula: 是否启用公式识别（默认False）
返回结果包含任务ID，可通过任务ID查询解析进度和结果
5、Dify配置私有化部署MinerU
（1）在插件市场搜索 MinerU，点击下载安装即可。
（2）如果使用MinerU官方API，授权地址是 https://mineru.net；如果是私有化部署的MinerU，授权地址是http://服务器Ip:MinerU监听端口；
（3）为了避免如下报错，需要设置 Dify 的配置文件
|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 2 3 | cd ``/``data``/``dify``/``dify``-``1.11``.``4``/``docker``/ vim docker``-``compose.yaml ``FILES_URL: ${FILES_URL:``-``http:``/``/``192.168``.``137.138``:``5001``} |
FILES_URL设置为 http://Dify宿主机IP:5001（如 http://192.168.137.138:5001，这里的 IP 通常是运行 Dify 的机器的 IP，即前文提到的"本地IP"端口。5001是 Dify API 服务的默认端口）。
确认 Dify API 服务的5001端口已对外暴露（可检查docker-compose.yaml文件的端口映射）。
重启 Dify 服务以使配置生效。
（4）之后就可以在工作流中使用MinerU工具进行文档解析。
6、总结
MinerU作为一款专注于文档解析的工具，为AI Agent提供了高质量的文档处理能力。通过其强大的结构化解析、公式表格识别等功能，可以将复杂的PDF文档转换为机器可理解的格式，为后续的AI处理提供了坚实基础。