MinerU 安装使用教程

🚀 项目介绍

MinerU 是由 OpenDataLab 开发的开源文档解析工具，专门用于将 PDF、Word、PPT 等复杂文档转换为大模型可用的 Markdown/JSON 格式。支持表格、公式、化学分子结构的精准识别！

✨

核心优势：52K+ Star 顶流项目、全格式兼容、表格公式化学分子精准识别、支持 RAG/大模型语料生产！

项目信息	详情
GitHub 地址	github.com/opendatalab/mineru
官网	mineru.net
开源协议	AGPL-3.0 License
支持平台	Windows / macOS / Linux

支持的格式

📄 PDF 📝 Word 📊 PPT 🖼️ 图片

📋 Markdown 🔧 JSON 📐 LaTeX 🌐 HTML

⚡ 核心功能

📊

表格智能还原

旋转表格、跨页表格、合并单元格完美还原

🔢

公式精准识别

长公式、多行公式，输出 LaTeX/MathML

🧪

化学分子识别

精确检测分子结构，转成 SMILES 格式

🚀

多场景输出

适配 RAG、大模型语料、知识库构建

💡

MinerU 2.5 版本使用解耦视觉-语言模型架构，在 OmniDocBench 基准测试中达到 SOTA 性能！

📋 环境要求

要求	GPU 加速模式	纯 CPU 模式
操作系统	Windows/Linux 2019+/macOS 14.0+	同左
Python	3.10 - 3.13	3.10 - 3.13
VRAM	≥ 8GB（推荐 16GB+）	不需要
内存	≥ 16GB	≥ 8GB
磁盘空间	≥ 20GB（SSD 推荐）	≥ 2GB

⚠️

注意：Windows + Python 3.13 暂不支持（依赖 ray 不兼容），建议使用 Python 3.10-3.12。

⚙️ 安装步骤

方式一：pip 安装（推荐）

创建虚拟环境

bash

# 创建 Python 虚拟环境
python -m venv mineru_env

# 激活环境（Windows）
mineru_env\Scripts\activate

# 激活环境（macOS/Linux）
source mineru_env/bin/activate

安装 MinerU

bash

# 更新 pip
pip install --upgrade pip

# 安装 uv（更快的包管理器）
pip install uv

# 安装 MinerU（包含所有功能）
uv pip install -U "mineru[all]"

方式二：从源码安装

克隆并安装

bash

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

方式三：Docker 部署

MinerU 提供 Docker 镜像，适合快速部署和解决环境兼容问题：

bash

# 拉取官方镜像
docker pull opendatalab/mineru:latest

# 运行容器
docker run -it --gpus all opendatalab/mineru:latest

✅

安装完成！运行 mineru --help 验证是否安装成功。

💻 使用方法

命令行使用

最简单的使用方式：

bash

# GPU 加速模式（默认）
mineru -p input.pdf -o output_dir

# 纯 CPU 模式
mineru -p input.pdf -o output_dir -b pipeline

# 批量处理
mineru -p ./docs_folder -o ./output_folder

常用参数

参数	说明
`-p, --path`	输入文件或目录路径
`-o, --output`	输出目录
`-b, --backend`	后端模式：auto（默认）/ pipeline（纯CPU）
`--format`	输出格式：markdown / json / html

Python API

python

from mineru import MinerU

# 初始化
miner = MinerU()

# 解析 PDF
result = miner.parse("input.pdf")

# 获取 Markdown 输出
markdown_content = result.to_markdown()

# 保存结果
result.save("output_dir")

🔧 高级用法

导出到 Notion

MinerU 支持直接导出解析结果到 Notion：

在 Notion 创建 Integration 并获取 API Token
配置环境变量 NOTION_TOKEN
使用 --export notion 参数导出

对接 Dify 工作流

将 MinerU 作为 Dify 的文档预处理工具：

在 Dify 知识库中启用"外部数据源"
配置 MinerU API 端点
上传 PDF 自动解析并入库

VLM 模型配置

MinerU 支持使用 VLM（视觉语言模型）提升解析精度：

bash

# 使用本地 VLM 模型（如通过 vLLM/SGLang 部署）
mineru -p input.pdf -o output --vlm-endpoint http://localhost:8000

# 使用在线 VLM 服务
mineru -p input.pdf -o output --vlm-provider openai

💡

提示：使用 VLM 模型可将解析精度提升到 81.9%（OmniDocBench v1.5 评测得分）！

❓ 常见问题

Q1: 安装时报 CUDA 错误怎么办？

确保已安装正确版本的 CUDA 驱动。或者使用纯 CPU 模式：

bash

mineru -p input.pdf -o output -b pipeline

Q2: 解析速度慢怎么优化？

使用 GPU 加速模式（需 8GB+ 显存）
启用 SSD 存储提升 I/O 速度
批量处理时使用多进程

Q3: 表格识别不准确？

尝试以下方法：

确保 PDF 是矢量格式（非扫描件）
使用 VLM 模型提升识别精度
调整 --table-mode 参数

Q4: 支持哪些语言？

MinerU 支持多语言识别，包括中文、英文、日文、韩文等主流语言。对于拉丁语系的变音符号和阿拉伯语可能有轻微误差。

Q5: 如何处理扫描版 PDF？

MinerU 内置 OCR 功能，可自动识别扫描版 PDF：

bash

mineru -p scanned.pdf -o output --ocr-enabled