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 环境，避免依赖冲突。

/* by 01130.hk - online tools website : 01130.hk/zh/caiji.html */ # 创建 Python 3.10 环境 conda create -n mineru python=3.10 -y conda activate mineru

2.2 安装 magic-pdf

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

/* by 01130.hk - online tools website : 01130.hk/zh/caiji.html */ # 安装 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 需要一个配置文件来指定模型路径。

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

{ "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. 常见坑点与解决

显存溢出 (OOM):
- 如果显存小于 8G，建议在配置文件中将device-mode设置为cpu（速度会变慢）。
- 或者处理 PDF 时减少并发。
PaddlePaddle 报错:
- MinerU 的 OCR 默认依赖 Paddle。如果报错libpaddle.so相关问题，请检查 CUDA 版本是否与 Paddle 匹配。
- 尝试重新安装：pip install paddlepaddle-gpu -i https://pypi.tuna.tsinghua.edu.cn/simple
公式识别乱码:
- 确保magic-pdf.json中的路径正确，且完整下载了LaTeX_OCR相关模型。