解锁高难度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，步骤如下

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

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

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

MinerU本地部署

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

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

2.1 Pip安装

先看看带ui界面的MinerU

pip 或 uv 安装

shell 复制代码

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

使用 MinerU

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

shell 复制代码

mineru -p <input_path> -o <output_path>

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

启动Gradio界面

复制代码

cd Projects/gradio_app

pip install gradio gradio-pdf

python app.py

网页中打开

复制代码

http://127.0.0.1:7860/

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

技巧1：突破20页限制

python 复制代码

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_server
  mineru_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: nvidia
              count: 0
              capabilities: [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 路径需调整为以下格式之一：

yaml 复制代码

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

第三方镜像（推荐）

bash 复制代码

docker pull quincyqiang/mineru:0.3-models

sudo 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 容器

bash 复制代码

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\models

C:\Users\Admin.cache\modelscope\hub\models\ppaanngggg\layoutreader

都复制到 MinerU/projects/web_api 下

以Linux为例

复制代码

mkdir models
mkdir layoutreader

cp -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 解析工具是哪一个？欢迎留言交流~

实践出真知，与君共勉~