opendatalab/MinerU · 上手攻略

仓库：opendatalab/MinerU
链接：https://github.com/opendatalab/MinerU
分类：ai
作者：Jay
更新：2026-08-17

是什么

MinerU 是由 OpenDataLab（上海人工智能实验室关联开源组织）开发的高精度文档解析引擎，于 2024 年开源。其核心能力是：将 PDF、DOCX、PPTX、XLSX、图片、网页等复杂文档，转换为 LLM 可直接消费的 Markdown 或 JSON 格式，同时保留阅读顺序、标题层级、表格结构、公式 LaTeX 等语义信息。

MinerU 最早服务于InternLM 大模型的预训练数据构建，专注于解决学术文献中符号转换（公式、表格、图表）的难题，后来逐步演化为通用文档解析工具。最新版本为 v3.4（2026年6月18日），支持 109 种语言的 OCR 识别。

解决什么问题

RAG 和 Agent 工作流依赖高质量的文档切片（chunk），但现实中大量文档是扫描件、多栏布局、含复杂公式表格的 PDF，直接用 PyMuPDF 或 pdfplumber 提取的文字乱序、公式变图片、表格无法结构化。MinerU 用 VLM（视觉语言模型）+ OCR 双引擎解决这个问题，让 LLM 真正"读懂"文档。

核心解析能力

全格式支持：PDF、DOCX、PPTX、XLSX、图片（PNG/JPG）、网页
阅读顺序还原：多栏布局、跨页表格合并、页眉页脚自动去除
公式识别：自动将公式转为 LaTeX，表格转为 HTML
VLM + OCR 双引擎：文本型 PDF 用 VLM，扫描件用 OCR，各取所长
109 语言 OCR：涵盖中英日韩及主要欧洲语言
结构保持：标题、段落、列表、图像说明、注脚均保留

快速安装

pip 安装（推荐）

pip install mineru[all]

mineru[all] 包含所有核心功能，兼容 Windows / Linux / macOS。

⚠️ 若安装后 CUDA 加速不可用，Windows 用户参考官方 Windows CUDA 加速 FAQ；macOS 用户需要通过 conda 或源码编译（不支持 Apple Silicon GPU 加速）。

Docker 部署（推荐生产环境）

# 拉取镜像（Linux only，不支持 macOS 原生 Docker）
docker pull mineru-sglang:latest

# 启动解析服务（暴露 30000 端口）
docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 \
  --ipc=host \
  mineru-sglang:latest \
  mineru-sglang-server --host 0.0.0.0 --port 30000

# 下载模型（可选，首次启动后会自动下载）
docker run --rm mineru-sglang:latest \
  mineru-models-download -s huggingface -m all

注意：Docker 部署仅支持 Linux 和 WSL2；macOS 用户请用 pip 安装。

在线体验（无需安装）

WebUI：https://mineru.net
Gradio 界面：仓库内置了 Gradio WebUI

核心用法

Python API（最常用）

from mineru import MinerU

# 初始化（自动选择最优后端）
u = MinerU()

# 解析单个 PDF
result = u.parse("path/to/document.pdf")

# 输出 Markdown
print(result.markdown)

# 输出结构化 JSON
print(result.json)

Pipeline 模式（稳定版）

适合大多数场景，OmniDocBench v1.5 得分 86.2：

from mineru.pipeline import Pipeline

pipeline = Pipeline()
result = pipeline("document.pdf", output_format="markdown")

VLM Engine 模式（高精度）

适合复杂布局文档（图表分析、图像内公式）：

from mineru.vlm_engine import VLMEngine

vlm = VLMEngine()
result = vlm.parse("complex_doc.pdf")

Hybrid Engine（v3.3+ 新增）

平衡速度与精度，支持 effort 参数：

# medium：速度快（Linux 下文本 PDF 提速约 80%，OCR PDF 提速约 35%），精度损失仅 0.13 分
# high：最高精度，支持图像分析，但速度较慢
result = pipeline("doc.pdf", effort="medium")  # v3.3 默认
result = pipeline("doc.pdf", effort="high")    # 最高精度

REST API（Docker 部署后）

# 上传 PDF 解析
curl -X POST "http://localhost:30000/file_parse" \
  -F "files=@/path/to/example.pdf"

# 访问 Swagger 文档
# http://localhost:30000/docs

CLI 命令

# 解析本地文件
mineru /path/to/document.pdf --output ./output/

# 批量处理
mineru /path/to/directory/ --recursive --output ./output/

三种推理后端

后端	特点	适合场景
pipeline	快速稳定，无幻觉，支持 CPU/GPU	大多数日常文档处理
vlm-engine	高精度，支持 vLLM/LMDeploy/mlx	复杂图表、图像内公式
hybrid-engine	高精度 + 低幻觉，medium/high 两档	兼顾速度与质量的平衡场景

典型适用场景

RAG 数据预处理：将论文、报告、合同等 PDF 转为干净 Markdown 供向量数据库检索
Agent 文档理解：给 Agent 提供结构化文档，让它真正理解表格/公式内容
训练数据构建：从 PDF 批量提取高质量文本用于 LLM 预训练或微调
企业知识库：合同、发票、报告等文档的自动化解析与索引
多语言文档处理：109 语言 OCR 支持，适合跨境文档处理

坑与注意

GPU 显存要求高：官方建议 16GB+ VRAM，16GB+ RAM（32GB 推荐）。没有 GPU 的用户只能用 pipeline CPU 模式，速度较慢。
Docker macOS 限制：官方明确不支持 macOS 原生 Docker，需要通过 pip 方式安装，但 GPU 加速可能受限。
模型下载依赖网络：首次安装会自动从 HuggingFace 下载模型（约数 GB），国内网络可能超时。v3.4 增加了自动源选择和本地缓存复用，可以配置镜像源。
复杂 PDF 仍可能出错：极度复杂的手写体、印章遮挡、多语言混合等场景，OCR 和 VLM 仍可能出错，建议对关键文档做人工抽检。
许可证：v3.1+ 改为 MinerU Open Source License（基于 Apache 2.0 的自定义许可），比 AGPLv3 更宽松，但商业使用前请仔细阅读 LICENSE.md。
Windows CUDA 加速：部分 Windows 用户反馈 pip 安装后 CUDA 不可用，需要参考官方 FAQ 或使用 Docker 方案。

与同类对比

维度	MinerU	MarkItDown	PyMuPDF+OCR	Mathpix
格式支持	PDF/DOCX/PPTX/XLSX/图片/网页	主流办公格式为主	主要 PDF	主要 PDF/图片
公式提取	✅ LaTeX	❌	❌	✅ LaTeX
表格结构	✅ HTML 还原	部分	❌	✅
多栏布局	✅	❌	❌	❌
OCR	✅ 109语言	❌	需额外接 OCR	✅
VLM 驱动	✅	❌	❌	❌
开源	✅	✅	✅	❌（商业）
本地部署	✅ Docker	✅ pip	✅	❌（云端）

一句话推荐结论

如果你需要将复杂 PDF（尤其是含公式、表格、多栏布局的学术文档或报告）转化为干净的 Markdown/JSON 供 LLM 使用，MinerU 是目前开源方案里精度最高、功能最全的选择，Docker 一键部署也足够简单；唯独对 GPU 显存要求较高，没有独显的用户体验会打折扣。

来源

https://github.com/opendatalab/MinerU（README、v3.4/3.3/3.1/3.0 release notes）
https://opendatalab.github.io/MinerU（官方文档）
https://github.com/opendatalab/MinerU/discussions/2961（Docker 部署与 API 使用）
https://doc.fastgpt.io/en/self-host/custom-models/mineru（FastGPT 集成教程）