夜雨聆风MinerU 3.1 实战指南：从安装到生产，一篇搞定
做 RAG 或者大模型训练，你一定遇到过这个痛点：怎么把 PDF、Word、PPT 高质量地转成 Markdown 喂给大模型？
MinerU 就是干这个的。GitHub 6.2 万星，上海 AI 实验室 OpenDataLab 出品，文档解析领域最火的项目。
这篇文章不讲虚的，带你从安装到生产环境，把 MinerU 3.1 用明白。
一、安装：两条命令的事，但坑不少
1.1 环境准备
MinerU 要求 Python 3.10-3.13，先检查：
python --version版本不对？用 conda 隔离：
conda create -n mineru python=3.11
conda activate mineru1.2 安装
# 装 uv（比 pip 快很多）
pip install uv
# 安装 MinerU 全量依赖
uv pip install -U "mineru[all]">
如果下载超时，换清华源：
```bash
uv pip install -U "mineru[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple
```
有代理的话设一下环境变量：
```bash
$env:HTTPS_PROXY="http://127.0.0.1:18789"
$env:HTTP_PROXY="http://127.0.0.1:18789"
```
1.3 GPU 加速（可选）
有 NVIDIA GPU 的话，装对应版本的 PyTorch：
# 先查 CUDA 版本
nvidia-smi
# CUDA 12.1
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# CUDA 11.8
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118nvidia-smi 显示的是驱动支持的最高 CUDA 版本，不是实际安装的。
安装命令：pip install nvidia-smi
用 nvcc --version 看实际版本。如果报"命令不存在"，说明只装了驱动没装 CUDA Toolkit，需要单独装。
1.4 验证
mineru -h看到帮助信息就装好了。
二、三种引擎怎么选？
MinerU 提供三种解析引擎，选错了直接影响精度和速度。
2.1 选型对比
| 引擎 | 精度 | 速度 | 显存 | CPU 可用 | 适合场景 |
|---|---|---|---|---|---|
| \*-engine | 95+ 分 | 🐢 慢 | 8GB+ | ❌ | 学术论文、复杂排版 |
| hybrid | 90+ 分 | ⚡⚡ 中等 | 8GB | ❌ | 大多数场景的首选 |
2.2 Pipeline 模式（默认）
# 解析单个 PDF
mineru -p report.pdf -o ./output
# 解析整个文件夹
mineru -p ./pdfs/ -o ./output适合： 合同、报告、扫描版 PDF、日常文档。
优点： 纯 CPU 也能跑，4GB 显存就行，速度快。
缺点： 极端复杂排版（比如跨页多栏表格）精度不如 VLM。
2.3 \*-engine 模式（最高精度）
# vlm 引擎
mineru -p paper.pdf -o ./output -b vlm
# hybrid 引擎（推荐）
mineru -p paper.pdf -o ./output -b hybrid适合： 学术论文、出版级文档、公式表格密集的内容。
*-engine 需要下载模型权重，大约 20GB。确保磁盘够用再装。
2.4 实战建议
日常文档用 pipeline，够用且快。学术论文用 hybrid，精度和速度平衡。出版级要求用 vlm，精度拉满。没 GPU 就用 pipeline，纯 CPU 也能跑。
三、支持的格式
MinerU 3.1 原生支持五种格式，不需要先转 PDF：
mineru -p report.pdf -o ./output # PDF
mineru -p scan.png -o ./output # 图片
mineru -p doc.docx -o ./output # Word
mineru -p slides.pptx -o ./output # PPT
mineru -p data.xlsx -o ./output # Excel3.0 之前只能处理 PDF 和图片，3.0 加了 DOCX，3.1 补了 PPTX 和 XLSX。现在五种主流格式全覆盖。
四、输出结果长什么样？
解析完成后，输出目录结构：
output/
├── report/
│ ├── report.md # 最终 Markdown 文件
│ ├── report.json # 结构化 JSON（含版面信息）
│ └── images/ # 提取的图片
│ ├── img_1.png
│ └── img_2.pngMarkdown 里有什么？标题层级自动识别 h1/h2/h3，表格转成 HTML 格式保留行列结构，公式转成 LaTeX，图片提取到 images 目录正文里留引用，正文按人类阅读顺序排列，自动去页眉页脚页码。
一份含公式和表格的论文，解析后大概长这样：
# Attention Is All You Need
## 3.1 Model Architecture
本模型基于简单的注意力机制，完全通过注意力机制实现序列转换。
$$\text{Attention}(Q,K,V) = \text{softmax}\Big(\frac{QK^T}{\sqrt{d_k}}\Big)V$$
| 模型 | 参数量 | BLEU |
|------|--------|------|
| Transformer-base | 65M | 27.3 |
| Transformer-big | 213M | 28.4 |
图 1 展示了模型的整体架构...五、批量处理：一次搞定一个文件夹
# 批量解析整个目录
mineru -p ./docs/ -o ./output
# 指定引擎
mineru -p ./docs/ -o ./output -b pipeline如果文件特别大（几千页），MinerU 3.0 引入了滑动窗口机制，峰值内存大幅降低，不需要手动拆分。但首次跑的时候建议先拿几页测试一下，确认效果再全量跑。
六、Docker 部署：生产环境推荐
# 拉取镜像
docker pull opendatalab/mineru:latest
# 运行（GPU 版）
docker run --gpus all -p 8000:8000 opendatalab/mineru:latest
# 运行（CPU 版）
docker run -p 8000:8000 opendatalab/mineru:latest --cpu企业部署建议用 Docker，环境隔离，方便管理。多 GPU 场景可以用 mineru-router 做负载均衡。
七、集成到 AI 工作流
7.1 RAG 框架集成
MinerU 原生支持 LangChain、LlamaIndex、RAGFlow、Dify、FastGPT、Flowise 等主流 RAG 框架。在平台的文档解析模块选择 MinerU 作为解析引擎即可，不需要额外配置。
7.2 MCP Server（AI 编程工具）
MinerU 提供了 MCP Server，可以直接在 Cursor、Claude Desktop、Windsurf 中使用。配置好后，在 AI 编程工具里直接说"帮我解析这个 PDF"就行。具体配置请参考官方文档。
7.3 开发 SDK
MinerU 提供 Python、Go、TypeScript 三种语言的 SDK，以及 CLI、REST API 和 Docker 部署方式。开发者可以根据项目需求选择最合适的集成方式。
八、常见问题排错
Q1：安装报错 "Could not find a version that satisfies the requirement"
原因： Python 版本不对。MinerU 要求 3.10-3.13。
解决：
conda create -n mineru python=3.11
conda activate mineru
uv pip install -U "mineru[all]"Q2：运行时报 "CUDA out of memory"
原因： 显存不够。
解决： 换 pipeline 模式（只需 4GB 显存），或者用 CPU 模式：
mineru -p report.pdf -o ./output -b pipeline --cpuQ3：公式识别不准
原因： pipeline 模式对复杂公式精度有限。
解决： 换 vlm 或 hybrid 引擎：
mineru -p paper.pdf -o ./output -b vlmQ4：表格解析出来是乱的
原因： 跨页表格或复杂边框。
解决： hybrid 或 vlm 引擎对跨页表格支持更好：
mineru -p table.pdf -o ./output -b hybridQ5：磁盘空间不够
原因： *-engine 模型权重约 20GB。
解决： 只用 pipeline 模式，不需要下载大模型：
uv pip install -U "mineru[core]" # 最小安装九、开源协议变更：商业友好
3.1.0 最重要的改动之一：从 AGPLv3 换成了基于 Apache 2.0 的 MinerU 开源协议。
AGPLv3 的传染性很强，商业使用门槛高。新协议大幅降低了企业和社区的采用门槛，集成到业务中不再需要担心法律风险。
总结
MinerU 3.1 已经从一个 PDF 解析工具，长成了一个完整的文档解析平台：
全格式支持，PDF、图片、Word、PPT、Excel 全覆盖。三档引擎，pipeline 快、hybrid 平衡、vlm 精。工程化完善，API、Docker、异步任务、多 GPU 负载均衡。协议友好，Apache 2.0 基础，商业使用无忧。生态丰富，LangChain、Dify、MCP Server 直接集成。
如果你在做 RAG、大模型训练或者文档数字化，MinerU 值得试试。
*本文基于 MinerU 官方文档和实际使用经验整理，技术细节以官方文档为准。*
