MinerU Docker 部署：PDF、DOCX、PPTX 转 Markdown 配置

1. 场景

做 RAG 或企业知识库时，很多人会先调模型、向量库和 chunk size。但如果 PDF、扫描件、PPTX、XLSX 在解析阶段已经丢结构，后面怎么调都很难稳定。

MinerU 的位置是文档进入知识库前的解析层：把 PDF、图片、DOCX、PPTX、XLSX 转成 Markdown / JSON，再交给切分、向量库、搜索或 Agent。

本文记录一次 Docker 部署和排查顺序。

补充一点时效背景：MinerU 2026/06/18 发布 3.4，主要更新 OCR 能力、OCR 处理管线和模型下载体验；2026/06/11 发布 3.3，主要更新 Hybrid 解析性能和 VLM 模型能力。因此 6 月写 MinerU，不是单纯介绍工具，而是围绕"文档解析层能不能支撑 RAG 数据准备"这个问题。

2. 环境准备

先检查 Docker、Compose 和 GPU：

bash 复制代码

docker version
docker compose version
nvidia-smi

如果使用 VLM / vLLM 加速，官方文档要求显卡为 Volta 或更新架构，并有 8GB 以上可用显存。宿主机驱动也要支持所选基础镜像的 CUDA runtime。

MinerU Dockerfile 默认使用 vllm/vllm-openai:v0.21.0，面向 CUDA 13.0 兼容环境。如果需要 CUDA 12.9，可以按官方 Dockerfile 注释切换到 vllm/vllm-openai:v0.21.0-cu129。

基础镜像先预检：

bash 复制代码

docker pull docker.1ms.run/vllm/vllm-openai:v0.21.0

这里用 docker.1ms.run 只是先排除基础镜像拉取不稳定的问题。

3. Docker 启动参数

官方示例中的容器启动命令重点是 GPU、共享内存和端口映射：

bash 复制代码

docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 -p 7860:7860 -p 8000:8000 -p 8002:8002 \
  --ipc=host \
  -it mineru:latest \
  /bin/bash

参数说明：

参数	作用
`--gpus all`	让容器访问宿主机 GPU
`--shm-size 32g`	增大共享内存，减少大文档处理异常
`--ipc=host`	避免进程间通信受限
`30000`	OpenAI-compatible server
`7860`	Gradio WebUI
`8000`	Web API
`8002`	MinerU Router

生产环境不要把这些端口直接暴露到公网。先在内网验证解析质量。

4. Compose profile

官方提供 compose.yaml，可按 profile 启动不同服务。

bash 复制代码

docker compose -f compose.yaml --profile openai-server up -d
docker compose -f compose.yaml --profile api up -d
docker compose -f compose.yaml --profile router up -d
docker compose -f compose.yaml --profile gradio up -d

建议顺序：

先用 gradio 看解析结果是否符合预期。
再用 api 接批量任务。
如果需要 OpenAI-compatible 形式，再启 openai-server。
多服务或多 GPU 时，再考虑 router。

注意：vLLM 会预分配 GPU 显存，同一台机器上可能不能同时跑多个 vLLM 服务。如果容器起来了但服务异常，先看 nvidia-smi。

5. 解析质量检查

部署成功后，不要只看 HTTP 状态码。建议准备 5 类样本：

样本	验收点
普通 PDF	标题、段落、页码是否干扰正文
双栏 PDF	阅读顺序是否正确
扫描件	OCR 是否稳定
表格文档	表格是否转成可用 HTML
公式文档	公式是否转为 LaTeX
PPTX / XLSX	是否能保留主要业务结构

输出产物重点看 Markdown 和 JSON：

text 复制代码

原始文档
  -> MinerU 解析
  -> Markdown / JSON
  -> 人工抽样验收
  -> 切分和清洗
  -> 向量库 / 搜索 / RAG

如果需要更细验收，还要看 content_list.json / content_list_v2.json、中间结果和 layout/span 可视化文件。它们能帮助判断版面、表格和 span 是否被正确识别。

6. 常见问题

6.1 镜像构建慢

先单独拉基础镜像：

bash 复制代码

docker pull docker.1ms.run/vllm/vllm-openai:v0.21.0

如果团队有多台机器，可以先把基础镜像和构建缓存整理成内部基线。

6.2 GPU 不可见

检查：

bash 复制代码

nvidia-smi
docker run --rm --gpus all docker.1ms.run/vllm/vllm-openai:v0.21.0 nvidia-smi

如果宿主机能看到 GPU，容器看不到，多半是 NVIDIA Container Toolkit 或 Docker runtime 配置问题。

6.3 API 能打开但解析慢

看三层：

是否使用 VLM / vLLM 后端。
显存是否被其他服务占用。
文档是否 OCR 密集或页数过长。

6.4 Markdown 可读性不好

不要直接进入向量库。先回到样本抽检，看问题是版面顺序、表格、公式、OCR 还是切分策略。

7. 总结

MinerU Docker 部署的重点不是"容器是否启动"，而是"解析后的 Markdown / JSON 能不能进入下游流程"。

部署顺序建议：

固定基础镜像。
检查 GPU、CUDA 和显存。
选择 Gradio / API / Router 服务形态。
用典型文档抽检解析质量。
再接向量库、搜索或 RAG。

RAG 效果差时，先看文档解析层，通常比直接换模型更有效。