前言
在 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 -yconda 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 updatesudo apt-get install -y libgl1-mesa-glx libglib2.0-0
如果是在Autodl等平台上面，就不需要赋予权限，可以按以下命令：
apt-get updateapt-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 演示界面：
# 先安装 gradiopip install gradio # 从 GitHub 克隆源码以运行 demo (或者直接运行包内的 demo)git clone https://github.com/opendatalab/MinerU.gitcd MinerUpython 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相关模型。
7. 总结
MinerU 2.5-1.2B 是目前开源界处理 PDF 效果最出色的工具之一。通过合理的配置，它可以极大地提升我们处理非结构化文档的效率。
如果你觉得有用，请点个赞并关注吧！有任何部署问题欢迎在评论区留言讨论。
