【MinerU】 Docker 使用问答记录

Q1：mineru[core] 和 mineru[all] 有什么区别？使用 docker 安装后，是否可以不使用 vllm 加速？

A1：

mineru[core] 与 mineru[all] 的区别

定义在 pyproject.toml:110-120：

安装选项	包含的模块
mineru[core]	vlm + pipeline + gradio
mineru[all]	core 全部 + 平台特定加速框架

具体来说，all 在 core 基础上额外安装：

• Linux → vllm>=0.10.1.1（vLLM 加速推理）
• Windows → lmdeploy>=0.10.2（LMDeploy 加速推理）
• macOS → mlx-vlm（MLX 加速推理）

所以 core 是基础功能集，all 是 core + 推理加速框架。

Docker 中是否可以不使用 vllm 加速？

Docker 镜像基于 vllm/vllm-openai 构建，默认包含 vllm，但 你并非必须使用 vllm 加速。根据文档说明：

1. vllm 加速有硬件要求 （docs/en/quick_start/docker_deployment.md:22-26）：

   • Volta 架构或更新的 GPU，显存 ≥ 8GB
   • 宿主机显卡驱动支持 CUDA 12.9.1+
   • Docker 容器需能访问宿主机 GPU

2. 不使用 vllm 的替代方案：

   • 可以使用 pipeline 后端（最低 4GB 显存即可），它不走 VLM 推理，速度更快且不会产生幻觉
   • 也可以使用 OpenAI 兼容的 HTTP 客户端 （mineru-openai-server），将推理请求发给外部服务，本地只需 2GB 显存

3. 如果你没有符合条件的 GPU 或不想用 vllm，选择 pipeline 后端即可正常使用 MinerU 的文档解析功能，无需 GPU 加速。

总结 ：Docker 中虽然预装了 vllm，但你完全可以选择 pipeline 模式运行，不依赖 vllm 加速。

---

Q2：pipeline 模式是否支持 vllm 加速？默认的是 pipeline 还是 vlm？

A2：

Pipeline 不支持 vllm 加速

这是两个完全不同的解析后端，互不相关：

后端	特点	vllm
pipeline	快速稳定、无幻觉、支持纯 CPU 运行	不使用 vllm，用 ONNX 模型推理
vlm-engine	高精度，需要 VLM 大模型	使用 vllm/LMDeploy/mlx 加速
hybrid-engine	高精度 + 原生文本提取	使用 vllm 加速

Pipeline 走的是轻量级模型路线（布局检测、公式识别等小模型），不走 VLM 大模型推理，所以根本不需要 vllm。

默认后端是 pipeline

# 默认命令（即使用 pipeline）
mineru -p <input_path> -o <output_path>

# 显式指定 pipeline（用于纯 CPU 环境）
mineru -p <input_path> -o <output_path> -b pipeline

不加 -b 参数时默认就是 pipeline 模式。

总结：默认是 pipeline，它不需要也不支持 vllm。只有 vlm-engine 和 hybrid-engine 才会使用 vllm 加速。

---

Q3：如何切换后端模式？Docker 中如何挂载测试文件？

A3：

切换后端模式

使用 -b 参数指定后端：

# vlm-engine 模式（需要先启动 vllm 服务）
mineru -p <input_path> -o <output_path> -b vlm-auto-engine

# hybrid-engine 模式（需要先启动 vllm 服务）
mineru -p <input_path> -o <output_path> -b hybrid-auto-engine

# pipeline 模式（默认）
mineru -p <input_path> -o <output_path> -b pipeline

对于 *-auto-engine 模式，需要先启动对应的 VLM 推理服务（如 vllm server），然后再执行解析命令。

Docker 挂载文件

在 docker run 时加 -v 参数挂载宿主机目录：

docker run --gpus all \
  --shm-size 32g \
  -p 30000:30000 -p 7860:7860 -p 8000:8000 -p 8002:8002 \
  --ipc=host \
  -v /path/on/host/test.pdf:/home/test.pdf \
  -it mineru:latest \
  /bin/bash

挂载整个目录（更常用）：

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

格式是 -v 宿主机路径:容器内路径。进入容器后，/data 目录下就能看到挂载的测试文件。

注意：Windows + WSL2 环境下，宿主机路径要用 WSL 格式，如：

-v /mnt/e/test_files:/data

---

Q4：在容器内执行解析的具体命令

A4：

Pipeline 模式（最简单，无需额外服务）

mineru -p /data/test.pdf -o /data/output

VLM-Engine 模式（需要两步）

第一步：启动 vllm 推理服务（后台运行）

mineru-vllm-server &

等服务启动完成后（会看到 Uvicorn running on 类似提示），再执行：

第二步：执行解析

mineru -p /data/test.pdf -o /data/output -b vlm-auto-engine

Hybrid-Engine 模式（同样需要两步）

# 第一步：启动 vllm 服务
mineru-vllm-server &

# 第二步：解析
mineru -p /data/test.pdf -o /data/output -b hybrid-auto-engine

参数说明

• -p：输入文件或目录路径
• -o：输出目录路径
• -b：指定后端（不写则默认 pipeline）
• /data/ 是挂载进容器的目录，替换为实际路径

建议先用 pipeline 模式验证基本流程是否跑通，再尝试其他模式。