解锁高难度PDF！MinerU部署保姆教程 + Dify联合解析《少年百科》

写在前面

复杂排版 PDF 的解析能力，已成为衡量企业文档自动化处理水平的重要指标之一。

然而，在实际操作中，大多数企业并不具备自主研发 PDF 解析系统的能力，更多依赖于开源工具来完成这一任务。因此，选择一款功能强大、适配性强的 PDF 解析工具，显得尤为关键。

在本文中，笔者实测了七款主流的 PDF 解析工具（包括 MinerU、Doc2X、maker、Nanonets-OCR-s、olmOCR、surya 等），综合对比其在复杂排版文档中的表现后发现，MinerU 在多个维度上最贴合笔者的真实工作场景的需求 ，最终决定选用该工具进行部署和应用。

由于篇幅限制，具体的评测结果和截图暂不在此展示。

MinerU是适合的，但不是最强的。

如果你也在寻找合适的 PDF 解析方案，建议根据自身需求对各工具进行测试与评估，不要被工具的推文标题所迷惑。

---

本文主要两个内容：

• 原生提取器 vs MinerU
• MinerU本地部署教程（全）

原生 vs MinerU

Dify 一遇到复杂PDF就掉链子，使得调用第三方工具成为必然。

LLM 节点的SYSTEM 提示词（仅供参考）：

根据知识库回答问题，如果没有请回答“知识库中未找到相关内容”！知识库如下：/上下文

Difyp配置Miner，步骤如下

1. 安装：工具–搜索“MinerU”–安装
2. 给MinerU工具授权：
   1. 本地安装：Base URL填本机MinerU的URL，令牌为空，服务类型：本地部署
   2. 官网API：Base URL填https://mineru.net/api/v4/extract/task，令牌填申请的API-KEY，服务类型：官方API
3. 使用：工作流中添加MinerU的 PARSE PDF节点

Dify挂上Miner工具，一下就给出正确答案

笔者用如下的PDF测试，各位可以先在MinerU在线体验 上测试下自己文档是否适用，再考虑购置API/本地部署。

MinerU本地部署

如果你也需要在本地环境中部署 MinerU，下文将提供详细的保姆级部署教程，包括【Pip】和【Docker】两种方式，供你参考实践。

• pip安装，有可视化UI界面，可以在本地/代码中使用
• Docker安装，给第三方提供服务/代码中使用

2.1 Pip安装

先看看带ui界面的MinerU

pip 或 uv 安装

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[core] -i https://mirrors.aliyun.com/pypi/simple

使用 MinerU
最简单的命令行调用方式如下：

mineru -p <input_path> -o <output_path>

• <input_path>：本地 PDF 文件或目录（支持 pdf/png/jpg/jpeg）
• <output_path>：输出目录

启动Gradio界面

cd Projects/gradio_apppip install gradio gradio-pdfpython app.py

网页中打开

http://127.0.0.1:7860/

上传文档，类似官方界面的解析效果就出来了

技巧1：突破20页限制

if __name__ == '__main__':with gr.Blocks() as demo:# ... existing code ...max_pages = gr.Slider(1, 100, 10, step=1, label='Max convert pages')    # 原第2个参数是20,现修改为100# ... existing code ...

技巧2：修改端口
将 demo.launch() 改为 demo.launch(server_name="0.0.0.0", server_port=8800)

2.2 Docker安装

Docker可以通过 docker run 和 docker compose 安装，两种docker方式的关键区别

​操作​	​单镜像/多容器​	​自动启动容器​	​依赖管理​	​适用场景​
docker run	适合单镜像	否	无	仅需下载镜像
docker-compose	适合多容器	是	有	完整环境部署（推荐生产使用）
建议

• 如果 quincyqiang/mineru:0.3-models 是独立服务，直接 docker run 即可。
• 如果它需要与其他服务（如数据库、消息队列）协作，务必使用 docker-compose.yaml 统一管理。

方式1. docker compose 一键启动（推荐）

第三方mineru镜像

• 优点：快
• 缺点：不是最新的

创建MinerU文件夹，在MinerU文件夹下，创建 一个docker-compose.yaml 文件，粘贴如下内容

# 指定 docker-compose 文件版本
version: "3.8"services:# 定义服务名称为 mineru_servermineru_server:# 指定使用的 Docker 镜像image: quincyqiang/mineru:0.3-models# 指定容器名称container_name: mineru_server# 端口映射，将主机的 8000 端口映射到容器的 8000 端口ports:- "3211:8000"# 挂载卷，将主机的 /mineru_files 目录映射到容器的 /root/output 目录volumes:- ./mineru_files:/root/output# GPU 相关配置deploy:resources:reservations:devices:# 配置 NVIDIA GPU 设备- driver: nvidiacount: 0capabilities: [gpu]# 使用 NVIDIA 运行时runtime: nvidia# 环境变量设置environment:# 允许容器访问所有 GPU 设备- NVIDIA_VISIBLE_DEVICES=all# 保持 STDIN 开启，允许交互式会话stdin_open: true# 分配一个伪终端tty: true

启动

docker compose up -d

问题1：是否可以删除挂载卷？
在Windows运行上述文件，是否可以删除挂载卷的问题？

可以删除，但需注意：

• 如果容器内应用不需要持久化存储数据​（如临时文件、仅内存计算），直接移除 volumes 配置是安全的。
• 如果应用依赖 /root/output 目录写入数据，删除后会导致：
  • 数据仅存在容器内，容器销毁后丢失。
  • 无法从宿主机（Windows）访问生成的文件。

问题2：Windows 下的路径问题（若需保留挂载卷）​​:
如果仍需挂载卷，Windows 路径需调整为以下格式之一：

volumes:# 方式1：使用绝对路径（需替换为你的实际路径）- D:/mineru_output:/root/output- # 方式2：Docker 共享驱动器的路径（需先在 Docker Desktop 中配置共享）- /D/mineru_output:/root/output

注意​：

• 确保路径存在且权限正确（可在 Docker Desktop 的 Settings > Resources > File Sharing 中添加共享目录）。
• 避免使用 \ 反斜杠（Linux 容器不兼容），统一用 / 正斜杠。

方式2. docker run

第三方镜像（推荐）

docker pull quincyqiang/mineru:0.3-modelssudo docker run -d \-p 8000:8000 \-v ./mineru_files:/root/output \--name mineru \--gpus '"device=0,1,2,3"' \
quincyqiang/mineru:0.3-models

测试本地访问

curl http://YOUR_IP:3002/docs

你会看到这样的界面，Try it out 就可以上传文件解析了，也可以在Apifox中请求尝试

官方镜像

构建 MinerU 的 Docker 镜像，MinerU官网

git clone https://github.com/opendatalab/MinerU.git
cd projects/web_api
docker build -t mineru-api .

启动 mineru-api 容器

sudo docker run -d \-p 8000:8000 \--name mineru-api \--network dify_ssrf_proxy_network \-v minerupaddleocr:/root/.paddleocr \mineru-api

测试本地访问

curl http://YOUR_IP:3002/docs

---

以上就是所有的安装教程了，启动成功后，就可以在Dify的MinerU工具中测试啦~

以下是踩坑实录，希望你不会遇到~

可能遇到的问题

若官方的源码安装失败，可尝试以下两种方式

方法1.设置 HuggingFace 的国内镜像站点

• Linux

export HF_ENDPOINT=https://hf-mirror.com

• Windows Powershell

$env:HF_ENDPOINT = "https://hf-mirror.com"

注：建议将上面这一行写入 ~/.bashrc。

再执行

docker build -t mineru-api:v0.1 .

方法2.提前下载好模型文件并 COPY 进容器

conda create -n mineru python=3.10
conda activate mineru
pip install modelscope requests

新增 HugginFace 镜像，在 scripts/download_models.py 文件中

vim scripts/download_models.py## 新增 HugginFace 镜像
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com" 

下载模型文件 models 和 layoutreader

cd scripts
python download_models.py

文件路径分别在

• Linux

/home/admin/.cache/modelscope/hub/models/opendatalab/PDF-Extract-Kit-1.0/models/
/home/admin/.cache/modelscope/hub/models/ppaanngggg/layoutreader/

• Windows

C:\Users\Admin\.cache\modelscope\hub\models\opendatalab\PDF-Extract-Kit-1.0\modelsC:\Users\Admin\.cache\modelscope\hub\models\ppaanngggg\layoutreader

都复制到 MinerU/projects/web_api 下
以Linux为例

mkdir models
mkdir layoutreadercp -r /home/admin/.cache/modelscope/hub/models/opendatalab/PDF-Extract-Kit-1.0/models/* models/cp -r /home/admin/.cache/modelscope/hub/models/ppaanngggg/layoutreader/* layoutreader/

修改 MinerU/projects/web_api/Dockerfile

COPY models /opt/models
COPY layoutreader /opt/layoutreader

最后构建镜像

docker build -t mineru-api:v0.1 .

构建结果如下

---

你常用的 PDF 解析工具是哪一个？欢迎留言交流~

实践出真知，与君共勉~