小泉水这周我把 MinerU 的 Docker 部署完整跑了一遍，顺带做了 API 验证，最后通过 Dify 自定义工具的方式把它接进了自己的知识库预处理流程。整个过程踩了不少坑，从镜像版本、模型缓存到自定义工具入参格式都折腾过几轮。这篇不是官方文档复读，而是我实际从零部署、调用、集成到 Dify 的完整记录，包括每一条命令、每一步验证和我后来返工的原因。
1. MinerU 解决的是哪一类问题：为什么我最终选了 Docker 部署
1.1 MinerU 的定位：一个“文档文字转结构化”的解析引擎
先说清楚 MinerU 是干什么的。如果平时有做 RAG 知识库、文档问答、批量文档结构化处理，大概率听过这类痛点：一份 PDF 里带着多栏排版、数学公式、复杂表格、页眉页脚，用常规的 pdfplumber 或 PyMuPDF 抽取文本，输出多半是乱的，段落到处断，公式变成乱码，表格直接丢失行列关系。MinerU 是一个开源的文档解析引擎，底层把版面检测、公式识别、表格结构识别、阅读顺序还原这些能力串成了一条流水线，最后一站式输出比较干净的 Markdown、JSON 或者 HTML。
它和传统抽取库最大的区别在于“版面意识”。你可以理解成矿工在挖矿前先对整个矿脉做了一次三维测绘——先识别哪一块是正文、哪一块是标题、哪一块是表格、哪一块是公式，再基于这个识别结果去做文字提取和结构重建。这个过程不是纯规则匹配，而是跑模型的，所以它对复杂版式的泛化能力比正则规则强很多。
1.2 Docker 部署相比 pip 本地部署赢在哪
我最初是在一台带 CUDA 的 Linux 机器上用 pip 直接装的 MinerU，模型文件是通过命令行手动下载的，跑起来也确实能出结果。但很快就遇到几个现实问题：第一是模型文件散落在本地目录，换机器要重新配一轮；第二是 MinerU 依赖的 Python 环境组件比较多，和一个正在跑 Stable Diffusion WebUI 的环境撞了依赖，单独建 venv 才勉强解决；第三是最麻烦的，团队里其他同事想用这个能力，我总不能让他们都去手动装一遍模型和 Python 依赖，然后各自写脚本调用。
换成 Docker 部署最大的好处就是“把环境复杂性关进容器里”。镜像里预置了 MinerU 依赖，模型文件可以通过挂载目录共享，启动一个容器就等于把一个可用的解析服务提供出来了，其他人只需要请求 HTTP 接口。对个人项目而言，Docker 方式还便于回滚版本：镜像 tag 一换，整个 MinerU 的环境就从 1.x 切到 2.x，而不是在本地 pip 里跟着依赖地狱挣扎。
1.3 CPU/GPU 镜像怎么选（含硬件门槛）
MinerU 官方主要维护两类镜像：纯 CPU 镜像和 GPU 镜像。选型时不要只看“性能”两个字，还要看你的使用场景。
- CPU 镜像：部署简单，不需要考虑 CUDA 版本，适合小规模文档解析、低频调用或纯文本简单的 PDF。缺点很直接，遇到带大量公式的论文型 PDF，解析速度会慢到你想放弃。一份 20 页的扫描版 PDF，CPU 跑到几分钟是常有的事。
- GPU 镜像：适合大批量文档处理、对延迟敏感的生产环境。MinerU 里的公式识别和版面模型都是深度模型，在 GPU 上和 CPU 上的推理耗时差距通常是数量级的。注意 MinerU 官方推荐的最低价 GPU 配置是 N 卡，显存建议不低于 8G，后面我会说为什么。
如果你已经有一台带 NVIDIA 显卡的开发机或服务器，优先考虑 GPU 版。如果只是临时试用或者给 Dify 知识库做一个低频解析工具，CPU 容器可以先跑起来，后面解析任务量上来再加 GPU 参数重启容器即可。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 部署前的准备：检查 Docker、选择镜像、理解目录挂载
2.1 Docker 环境与版本检查
动手之前先把 Docker 环境确认好，这一步能避免后面绝大多数“起了容器却连不上”的问题。
在 Linux 或 macOS 终端执行：
bash复制docker version
docker compose version
如果执行 docker version 报 permission denied，说明当前用户没有加入 docker 用户组，先执行 sudo usermod -aG docker $USER，然后重新登录终端。在 Windows 上用 Docker Desktop 的，要注意保证 Docker Desktop 状态栏显示的是绿色 Running，而不是黄色或者红色。
docker compose 这个子命令现在已经是 Docker 官方主推的形式了，老版本用 docker-compose，注意区分。Compose 版本影响不大，真正影响大的是是否能识别新版本的 compose 文件格式。我建议直接把 Docker Desktop 或 Linux 上的 Docker Engine 升级到较新的稳定版，因为 MinerU 的新镜像偶尔会用到一些新的镜像配置字段。
2.2 镜像拉取的关键注意事项
MinerU 的镜像托管在 Docker Hub 上，老地方是 opendatalab/mineru。CPU 版和 GPU 版的 tag 区隔比较明显，拉镜像之前最好先去 Docker Hub 页面看一下最新 tag，别凭记忆写旧版本，因为 MinerU 迭代比较快，不同 tag 之间的 API 路径有过调整。
拉取镜像执行：
bash复制docker pull opendatalab/mineru:2.2.1
如果当前环境网络拉取 Docker Hub 镜像很慢，先确认 Docker 是否配置了可用的镜像源，但不建议频繁 Ctrl+C 中断拉取，多层镜像中断后重新拉虽然会走缓存，但在 Docker 缓存层不命中的情况下反而容易留下大量 none 镜像。更实际的做法是让拉取任务慢慢跑，或者直接在非高峰时段拉取。拉取完成后用 docker images 看列表里是否出现对应 tag。
2.3 模型文件缓存目录的设计
这个是很多初次上手的人忽略的一步。MinerU 容器启动后，首次解析文档时要把几类模型文件加载进来，包括版面检测模型、公式检测/识别模型、表格识别模型。这些模型权重如果放在容器可写层里，容器删了模型就没了，下次重新起容器又要下一遍，非常浪费时间。
我建议在宿主机上准备一个平滑的目录专门放模型缓存，比如：
bash复制mkdir -p ~/mineru/models
启动容器时通过 -v 参数把该目录挂载到容器内 MinerU 默认的模型缓存路径下。具体是哪个路径建议看镜像文档，因为 Python 包和镜像版本不同，缓存路径可能不一样。如果挂载路径不对，模型文件会继续写进容器，日志里也能看到相关下载和加载输出，可以根据日志中的实际路径调整挂载点。
3. Docker 部署 MinerU 的完整操作步骤
3.1 启动 CPU 版服务
我这里以 2.2.1 这个 tag 为例，把模型缓存挂载好，端口映射到宿主机 8000 端口：
bash复制mkdir -p ~/mineru/models
docker run -d \
--name mineru \
-p 8000:8000 \
-v ~/mineru/models:/root/models \
-e MODEL_SOURCE=/root/models \
opendatalab/mineru:2.2.1
启动后马上用 docker logs -f mineru 观察日志。如果看到类似“waiting for requests”或访问地址提示，说明服务已经进入监听状态。第一次解析时模型如果找不到本地缓存，会自动从 HuggingFace 或指定仓库下载，这个阶段耗时取决于网络和模型体积，耐心等一会儿。
需要注意，如果你之前没有明确设置过 MinerU 的模型目录环境变量，不同版本的容器启动参数可能不完全一样，有的版本直接就没有 MODEL_SOURCE 这个变量，而是固定从某个路径读取模型权重。我的建议是以镜像官方 README 和容器日志为准，挂载目录可以先随便挂一个，服务起来后执行 docker exec -it mineru ls /root/ 看看到底有哪些目录，再对准目录名重新挂载。
3.2 GPU 加速版启动参数差异
在带 NVIDIA 显卡的机器上，GPU 版启动差异主要在镜像 tag 和 Docker 参数上。GPU 容器需要额外加 --gpus all 参数把显卡设备送入容器，同时需要宿主机已经安装好 NVIDIA 驱动和 NVIDIA Container Toolkit。
以 NVIDIA GPU 版镜像为例：
bash复制docker run -d \
--name mineru-gpu \
--gpus all \
-p 8000:8000 \
-v ~/mineru/models:/root/models \
opendatalab/mineru-gpu:2.2.1
如果没有安装 NVIDIA Container Toolkit，启动时 --gpus all 会直接报错。先执行：
bash复制docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
能正确输出显卡信息，再跑 MinerU GPU 容器才有意义。显存方面，如果只是解析普通 PDF，8G 显存基本够用，但显存偏小的时候遇到长文档分辨率极高、版面复杂的页面，可能出现 OOM，日志里会看到 CUDA out of memory。容量小的老卡可以建议把批次或并发压到很低，或者改用 CPU 镜像兜底。
3.3 用 docker-compose 编排的版本
使用 docker run 适合单机调试，但我最后在正式跑解析任务时还是改成了 docker-compose.yml，好处是参数固化，服务重启、环境迁移都方便。下面是我实际使用的 Compose 服务定义：
yaml复制services:
mineru:
image: opendatalab/mineru:2.2.1
container_name: mineru
ports:
- "8000:8000"
volumes:
- ~/mineru/models:/root/models
environment:
- MODEL_SOURCE=/root/models
restart: unless-stopped
保存为 mineru-compose.yml 后执行：
bash复制docker compose -f mineru-compose.yml up -d
由于 restart: unless-stopped，只要 Docker 服务在运行，容器意外退出后会自己拉起来，对于需要长期挂机跑批量解析的场景很管用。单独验证容器状态时就用：
bash复制docker compose -f mineru-compose.yml ps
docker logs -f mineru
4. MinerU API 验证：从 Swagger 到脚本调用
4.1 通过 /docs 确认当前镜像的 API 形态
MinerU 的服务端是基于 FastAPI 那一套框架实现的，所以容器起来后，浏览器直接访问 http://127.0.0.1:8000/docs 就能看到自动生成的 Swagger 接口文档页面。这是验证 API 最直观的方式。
我在实际操作中发现，不同版本的 MinerU API 路径设计存在差异。早期版本直接暴露 /file_parse 这样的同步接口，提交文件后等它解析完成返回结果；而 2.x 时代走了“提交任务 + 轮询结果”的模式，POST 上传文件后只返回一个 task_id，客户端需要拿这个 task_id 再去查询结果。所以我强烈建议先打开 /docs 页面看当前实际有哪些接口，不要照抄网上某篇过期教程的参数名。
如果你的 MinerU 容器开启了身份鉴权，/docs 页面上方会出现 Authorize 按钮，需要配置 API Key 后才能试调接口。没开鉴权时会发现所有接口都直接可调。
4.2 用 Python 完成一次文件解析
以 2.x 默认的任务式接口为例，我实际调用的 Python 脚本大致长这样：
python复制import time
import requests
base_url = "http://127.0.0.1:8000"
# 1. 上传文件，拿到 task_id
with open("sample.pdf", "rb") as fp:
resp = requests.post(
f"{base_url}/file_parse",
files={"file": fp},
data={
"enable_formula": "true",
"language": "ch",
}
)
resp.raise_for_status()
task_id = resp.json().get("task_id")
print("task_id:", task_id)
# 2. 轮询解析结果
for _ in range(120):
result_resp = requests.get(f"{base_url}/file_parse/{task_id}")
result = result_resp.json()
status = result.get("status")
print("status:", status)
if status == "done":
parse_result = result.get("result", {})
print(parse_result.get("markdown", "")[:2000])
break
elif status == "failed":
print("解析失败:", result.get("error"))
break
time.sleep(1)
注意，language 参数在中文文档解析时建议显式指定为中文，因为 MinerU 对中西文混排内容的识别默认行为不同。enable_formula 会根据页面里是否含数学公式决定是否走公式识别模型，开启后耗时明显上升，如果文本纯属普通商务合同，可以关掉以提速。
4.3 结果字段确认：Markdown、JSON 还是纯文本
解析完成后，从任务结果里能拿到好几个输出字段，常见的有 markdown、json、html 等。对 RAG 场景来说，Markdown 是平衡信息密度和可读性的最佳选择，因为 Markdown 会自动把表格转成管道的表格语法、公式会以较完整的形式保留，递给 LLM 时上下文结构清晰，比纯文本效果好很多。
我的建议是把解析结果中的 Markdown 内容落盘保存，命名时保留对应的 PDF 文件名，尽量做成“一个 PDF 对应一个 .md”的扁平目录结构，后边无论是导入 Dify 知识库还是做向量化都顺手。JSON 结构适合需要程序化消费每个版面块的场景，比如要做“阅读顺序精确还原”时有用。普通知识库场景不必纠结，拿到 Markdown 就够了。
4.4 长文档和并发任务处理思路
任务接口设计成异步轮询是有原因的：一个包含大量公式、几十页的论文型 PDF，单页推理在普通 CPU 上可能就需要数十秒，整个文件等几分钟都很正常。HTTP 同步返回结果会让连接长时间挂起，中间一个网络抖动就前功尽弃。
所以设计解析服务时，我建议调用方把所有解析任务都按“提交任务—轮询结果”的模型去处理，不要用 requests 默认超时去吊一个长时间请求。轮询间隔设置 1 到 2 秒比较合理，太短的轮询会给容器带来无意义压力。并发层面，MinerU 容器内解析模型加载后会常驻内存/显存，如果同时提交几百个大文件，后续任务会排队等待。实际处理批量文档时最好在外部做一个简单的并发控制，比如同时最多提交 3 到 5 个解析任务，避免任务无限堆积占满磁盘和显存。
5. 适配 Dify 集成的两种路线
5.1 先把解析预处理和 Dify 知识库分层清楚
Dify 本身的知识库支持上传 PDF 并做文本分段，默认抽取方式对普通电子版 PDF 效果还行，可一旦遇到扫描版、多栏、含复杂表格的文档，Dify 内置解析的效果就不理想了。很多人上来就试图把 MinerU 塞进 Dify 文件解析流程里，但 Dify 目前并没有开放自定义底层文件解析器的插件口子，所以要理清 MinerU 和 Dify 的实际边界。
我最终采用的架构不是让 Dify 内部直接调用 MinerU 去替换默认解析，而是把 MinerU 作为一条“文档预处理流水线”放在 Dify 外部：文件先进 MinerU，出来转换成干净的 Markdown，再把 Markdown 喂给 Dify 知识库做切片和向量化。这样的好处是质量可控，预处理环节的问题不影响 Dify 本身稳定性，而且 Markdown 本身已经是一种很好的知识库中间格式。
5.2 用 Dify 自定义工具暴露 MinerU
除了离线预处理模式，Dify 还支持自定义工具，可以让 Agent 或工作流在对话中直接调用 MinerU 的解析 API。这里的关键是把 MinerU 的 OpenAPI 描述导入到 Dify。
在 MinerU 服务启动后，通过浏览器访问 http://127.0.0.1:8000/openapi.json 可以拿到一个完整的 JSON Schema。Dify 的自定义工具创建页面支持直接填写 OpenAPI Schema。如果不愿意整份拷贝，也可以只写一个精简版，把上传文件的两个核心接口暴露出来就行，避免把 MinerU 全部内部接口都暴露给 Dify Agent。
在 Dify 中创建自定义工具时，servers 的 url 要看 Dify 和 MinerU 之间的网络关系，填法不同，后面专门说。工具动作名建议改成容易从工作流里识别的名称，比如 mineru_parse_file 和 mineru_get_parse_result，不要直接叫 file_parse，那个太笼统了，Action 列表里不好区分。
5.3 从工作流里调用解析接口
在 Dify 的工作流编排中，解析一个用户上传文档的流程大概是这样：
用户上传文件后，工作流先调用一个 HTTP 请求节点把文件提交给 MinerU，拿到 task_id，然后进入一个循环等待节点，每隔几秒查询一次 MinerU 的任务状态。等状态为 done 时，取出 Markdown 结果，再拼进后续提示词或存入知识库临时文件。
这个编排的关键在于文件传递。Dify 工作流里的文件变量，在 HTTP 请求节点里通常能以文件表单的格式发送，但不同版本的 Dify 对这个支持程度略有不同。我更建议的做法：如果只是想验证 MinerU 集成是否通路，先用一个简单的脚本生成一个小 PDF，在 Dify 工作流里通过代码节点或者直接把文件路径传给 HTTP 节点，确认通了再接入真实用户上传文件的复杂路径。
5.4 Dify 和 MinerU 不在同一网络环境时的联通方案
Dify 最典型的部署方式是 docker compose 拉起一组容器，MinerU 也是 Docker 容器。这种情况下两者之间的互通有三种处理方案。
如果 MinerU 也跑在 Docker，最简单是让两个 Compose 项目加入同一个 Docker 网络。启动 MinerU 时指定网络名称，然后在 Dify 自定义工具里使用 http://mineru:8000 这样的容器服务名访问。这个方案跨机器迁移时不稳定，因为容器名和网络名一变就找不到服务了。
如果 Dify 用 Docker Desktop 在 Windows/macOS 上跑，而 MinerU 直接跑在宿主机上，Dify 容器内访问宿主机端口可以通过 host.docker.internal 这个特殊域名：
bash复制http://host.docker.internal:8000
如果 Dify 和 MinerU 都在 Linux 的 Docker 容器里，但不在同一个 bridge 网络，可以在启动 Dify 相关服务时给容器加一个 --add-host=host.docker.internal:host-gateway 参数，让容器内也能通过 host.docker.internal 指向宿主机。不过这个参数在 docker compose 文件里对应的是 extra_hosts，需要在每个需要访问 MinerU 的服务下加。
6. 高频问题排查与性能经验（踩坑记录）
6.1 Docker 启动失败：虚拟化、内存与共享内存坑
Docker Desktop 在 Windows 上启动失败时，最常见的是启动日志里报告未开启虚拟化支持。解决方法是进入 BIOS 开启 VT-x/AMD-V，然后在 Windows 功能里确认“虚拟机平台”和“适用于 Linux 的 Windows 子系统”已勾选。改完之后要彻底重启，不是注销，是重启，很多人在这一步卡很久。
在 Linux 上容器意外退出，则要重点看内存。MinerU 在加载模型时需要较大内存，如果机器内存本身只有 8G，再加上页面缓存和其他服务，很容易触发 OOM。可以先限制容器内存和 swap 策略，但更实用的做法是别在跑 MinerU 的机器上同时堆太多重型服务。
还有一个隐蔽的问题，某些 MinerU 镜像运行时会写大量临时文件或需要 /dev/shm 空间，如果容器内共享内存不够，会报一些和共享内存相关的不明错误。可以在 compose 服务里加一项：
yaml复制shm_size: '2gb'
这个参数很多视频教程里不会提，但如果你解析超大 PDF 时频繁崩溃，值得检查。
6.2 模型下载慢或首次解析非常慢
初次运行 MinerU，容器会在本地找不到模型权重时自动下载，下载速度取决于网络到模型仓库的连通性。这个过程没有任何界面进度，终端日志也是一跳一跳输出，容易误以为卡死。碰到这种情况不要急着重启容器，反而应该在干净的日志上下文里等一段时间。
如果模型下载始终失败，更稳妥的做法是到模型仓库先手动把对应模型权重下载到宿主机挂载目录，再启动容器。要确认挂载进容器的路径确实是模型加载目录，最好先在容器里跑通一次，然后查看生成的模型目录实际路径。不要相信“我以为在这个目录”这种感觉，要以服务日志里的加载路径为准。
6.3 大 PDF 的内存和超时处理
解析那种几百 MB、上千页的扫描版 PDF，如果直接传 HTTP，可能还没轮到 MinerU 处理，代理层或请求方就已经超时断开了。解决方案分两层：一是 MinerU 服务侧如果有任务超时配置，调大超时上限；二是客户端侧把请求拆分为上传和轮询两步，始终用短请求去拉状态。
对于超大 PDF，最好先做分拆预处理。比如先把 PDF 按页面切分成小批次文件，逐批交给 MinerU，出结果后再合并 Markdown。拆分能显著降低单任务内存峰值和失败重试成本。我自己处理过一份 2000 页的扫描版政策文件汇编，直接整本解析时内存冲高到十几 GB，分拆成每 100 页一个子任务后，稳定性和整体耗时都改善了很多。
6.4 API 调用返回异常时的排查链路
当 API 返回非 200 或者任务状态直接变成 failed，我的排查顺序是：先确认文件类型是不是 MinerU 支持范围。MinerU 主要面向 PDF、图片、EPUB 这类输入，有些格式在早期版本里根本不支持，报错信息又很隐晦，这时只需要换成支持的样本一试便知。
再看上传文件内容本身。如果 PDF 是扫描图片且没有 OCR 文本层，MinerU 必须在 OCR 能力开启时才能抽出文字，否则即使解析流程跑完，markdown 内容也可能是空的。这个情况非常常见，但经常被误认为 MinerU 出了问题。
然后看容器日志中对应任务的报错堆栈。如果是“CUDA out of memory”，则降低并发、减少上传文件大小或切 CPU 容器。如果报的是“API token invalid”这类鉴权错误，那就是服务端开了 token 校验，需要在请求头里带上凭证，而不是去改 MinerU 的解析逻辑。
6.5 对外暴露服务时的安全补充
MinerU 默认启动后，如果端口直接暴露在公网或者服务器公网 IP 上，任何能访问到该端口的人都可以提交解析任务，消耗你的 CPU/GPU 资源。虽然部署文档里很少强调，但只要是开放了 HTTP 服务，就应该考虑加一层访问控制。
最简单的做法是在 MinerU 前面加一个 Nginx 反代，只允许内网 IP 访问；或者为 MinerU 容器设置防火墙规则，仅允许 Dify 容器所在网段访问。如果 MinerU 版本支持 token 校验，推荐开启，并把 token 放到 Dify 自定义工具请求头或 URL 参数中。不要用“反正只是内网用”这个理由省掉，内网可能还有别的服务会被利用。
7. 最后再分享一点实际使用体会
整个 MinerU + Docker + Dify 的链路跑通之后，我最深的感觉是，MinerU 本身解析能力优秀，但把它接入现有平台时真正花时间的不是模型调参，而是任务模型设计、网络联通和异常处理。Dify 自定义工具这个东西很灵活，但也意味着责任在你自己身上：你要保证 MinerU 接口 Schema 描述准确、任务轮询逻辑不卡死、权限控制不裸奔。
如果你也是第一次搭这个组合，我建议的顺序是：先在宿主机上用 Docker 把 MinerU 跑起来，在 /docs 页面完成一次小文件解析，再写脚本验证轮询逻辑，最后才去 Dify 里建自定义工具。不要一上来就要求 Dify 工作流一步到位，那样出了问题你分不清是 MinerU 没起好、API 参数不对，还是 Dify 工具配置错了。
另外一个小建议，尽量把 MinerU 解析产出的 Markdown 作为中间资产单独留存，而不是每次都在 Dify 里现解析。同一个文件如果反反复复提交解析，纯粹是浪费算力。把“解析一次、多次复用”的缓存思路带入知识库建设里，整体效率会明显提升。我这套流程稳定跑了这么久，最后真正省时间的反而是这个缓存策略。