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安装

pip install --upgrade pip
pip install uv
uv pip install -U "mineru[core]"

（2）基于源码安装

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 性能指标对比

处理速度对比：

资源消耗对比：

精度表现对比（基于标准测试集的评估结果）：

部署方案对比：

3.2 配置场景推荐

 4、API调用

MinerU提供云端API服务，可以通过简单的HTTP请求调用文档解析功能：

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 的配置文件

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处理提供了坚实基础。 

官方文档：https://mineru.net/apiManage/docs

参考：https://blog.csdn.net/Vantastic999/article/details/153752920

参考：https://blog.csdn.net/gitblog_00804/article/details/151124271

参考：https://blog.csdn.net/star_nwe/article/details/151418668