PDF 转 Markdown 神器：MinerU 2.5 (1.2B) 部署全攻略

---

前言

在 AI 时代，高质量的数据是模型训练的基石。而 PDF 文档由于其排版复杂（多栏、表格、公式、图片交叉），一直是数据清洗中的"硬骨头"。

MinerU 是由 OpenDataLab 推出的开源 PDF 提取工具，支持精准的布局分析、公式识别和表格提取。最近更新的 2.5-2509-1.2B 版本在性能和准确率上又有了显著提升。今天，我们就来手把手拆解如何在 Linux 环境下部署这套强大的系统。

---

1. 硬件要求

MinerU 2.5-1.2B 包含多个深度学习模型（Layout, OCR, Formula），建议配置如下：

• 操作系统: Ubuntu 22.04 或更高版本
• CPU: 8 核以上
• GPU : NVIDIA GPU (显存建议 8GB 以上，12GB/16GB 最佳)
• 存储: 至少 20GB 剩余空间（用于存放模型权重）

---

2. 环境搭建

2.1 创建虚拟环境

建议使用 Conda 来管理 Python 环境，避免依赖冲突。

# 创建 Python 3.10 环境
conda create -n mineru python=3.10 -y
conda activate mineru

2.2 安装 magic-pdf

magic-pdf 是 MinerU 的核心包。我们选择带 GPU 加速的全量安装包。

# 安装 magic-pdf [full]
pip install -U magic-pdf[full] --extra-index-url https://wheels.myhloli.com

这个过程稍微耗时会有一点久，中间可能会有警告弹出（黄色字体）不用管让他下载就好了

2.3 安装系统依赖

PDF 解析涉及到图像处理，需要安装相关的系统动态库：

sudo apt-get update
sudo apt-get install -y libgl1-mesa-glx libglib2.0-0

如果是在Autodl等平台上面，就不需要赋予权限，可以按以下命令：

apt-get update
apt-get install -y libgl1 libglx-mesa0 libglib2.0-0

这个也需要下载

pip install -U mineru

---

3. 模型权重下载

MinerU 2.5 需要加载预训练权重。国内用户推荐使用 ModelScope（魔搭），速度极快。

3.1 使用脚本下载

创建一个 download_models.py 文件：

from modelscope import snapshot_download

# 注意：仓库名需包含版本号和参数量
model_dir = snapshot_download('OpenDataLab/MinerU2.5-2509-1.2B', local_dir='models')

print(f"模型下载成功，存放路径为: {model_dir}")

运行下载：

python download.py

3.2其他权重下载

这个是补充部分缺失的权重，主要用于OCR，如果不是很模糊的扫描件的话可以跳过这一步

运行命令

python -c "from modelscope import snapshot_download; snapshot_download('OpenDataLab/PDF-Extract-Kit-1.0', local_dir='/root/workspace/MinerU2.5', max_workers=16)"

这个过程可能会有点久，稍微等待等待

---

4. 核心配置（关键步骤）

MinerU 需要一个配置文件来指定模型路径。

1. 获取模板 ：在你的家目录下创建一个名为 magic-pdf.json 的文件。（注意一定要家目录）
2. 填写路径：

{
  "models-dir": "/root/workspace/MinerU2.5/models",
  "device-mode": "cuda",
  "layout-config": {
    "model": "doclayout_yolo"
  },
  "ocr-config": {
    "model": "native",
    "enable": false
  }
}

注意 ：models-dir 必须是绝对路径，且指向你刚才下载模型所在的那个文件夹。

---

5. 开始实战

5.1 命令行模式（CLI）

这是最快捷的测试方式，直接将一个 PDF 转换为 Markdown。

mineru -p test.pdf -o ./output --task doc

转换完成后，你会在 output 文件夹中看到：

5.2 启动 Web UI 界面

如果你更喜欢可视化操作，可以启动内置的 Gradio 演示界面：

# 先安装 gradio
pip install gradio

# 从 GitHub 克隆源码以运行 demo (或者直接运行包内的 demo)
git clone https://github.com/opendatalab/MinerU.git
cd MinerU
python web_demo.py

---

6. 常见坑点与解决

1. 显存溢出 (OOM):

   • 如果显存小于 8G，建议在配置文件中将 device-mode 设置为 cpu（速度会变慢）。
   • 或者处理 PDF 时减少并发。

2. PaddlePaddle 报错:

   • MinerU 的 OCR 默认依赖 Paddle。如果报错 libpaddle.so 相关问题，请检查 CUDA 版本是否与 Paddle 匹配。
   • 尝试重新安装：pip install paddlepaddle-gpu -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 公式识别乱码:

   • 确保 magic-pdf.json 中的路径正确，且完整下载了 LaTeX_OCR 相关模型。

---

7. 总结

MinerU 2.5-1.2B 是目前开源界处理 PDF 效果最出色的工具之一。通过合理的配置，它可以极大地提升我们处理非结构化文档的效率。

如果你觉得有用，请点个赞并关注吧！有任何部署问题欢迎在评论区留言讨论。

---