MinerU Docker 部署实战：基于 vLLM 基础镜像构建镜像与 Compose 多服务编排指南-平芜编程栈

MinerU Docker 部署实战：基于 vLLM 基础镜像构建镜像与 Compose 多服务编排指南

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

本文以 MinerU 官方文档 Docker 部署指南为主体，系统讲解如何基于仓库内的全局 Dockerfile 构建 MinerU 容器镜像、启动容器并映射服务端口，以及如何利用 compose.yaml 通过 profile 机制按需拉起 OpenAI 兼容服务、Web API、Router 聚合网关与 Gradio WebUI 四类服务。读完后，你可以在一台 Linux 主机上完成从镜像构建到四类服务上线的全流程，并理解镜像中 vLLM 推理加速、模型预下载与MINERU_MODEL_SOURCE=local机制的底层设计。

适用环境与平台限制

MinerU 提供的 Docker 部署方式旨在快速搭建运行环境并规避一些棘手的环境兼容性问题，但在使用前必须明确以下限制（引自官方文档原文警告）：

仅支持 Linux 以及带 WSL2 的 Windows 环境进行 Docker 部署；
不要在 macOS 上使用 Docker 部署 MinerU。macOS 上的 Docker 无法访问 MPS 或 MLX 加速，Apple Silicon 设备在此工作流中无法获得预期的加速效果。

此外，MinerU 在开发阶段只针对特定硬件与软件环境做了优化与测试（详见 Quick Start 的前置说明），在非主流环境下不保证 100% 可用，遇到安装问题建议先查阅 FAQ。

使用 Dockerfile 构建镜像

官方推荐通过仓库中的全局 Dockerfile 构建镜像：

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/global/Dockerfile docker build -t mineru:latest -f Dockerfile .

构建出的镜像标记为mineru:latest，后续docker run与docker compose均以此为基础。结合 docker/global/Dockerfile 的实际内容，镜像构建包含四个关键环节：

基于 vLLM 官方镜像。Dockerfile 默认使用FROM vllm/vllm-openai:v0.21.0，该基础镜像自带vllm推理加速框架及其依赖，并支持 Volta、Turing、Ampere、Ada Lovelace、Hopper、Blackwell 架构的 GPU（Compute Capability 7.0 ≤ CC ≤ 12.1），同时支持 x86_64 与 ARM（AArch64）两种架构。默认基础镜像对应CUDA 13.0环境；如果你的环境需要 CUDA 12.9 兼容镜像，需要注释掉默认的FROM行，改用 Dockerfile 中已预留的注释行vllm/vllm-openai:v0.21.0-cu129。
安装运行时依赖。镜像内通过apt-get安装libgl1（OpenCV 运行依赖）以及fonts-noto-core、fonts-noto-cjk中文字体并执行fc-cache，保证 PDF 渲染与中文排版正常。
安装 MinerU 主包。执行pip install -U 'mineru[core]>=3.4.0' --break-system-packages并清理 pip 缓存，当前仓库版本号为 3.4.4，满足该约束。
预下载模型并固化入口。镜像构建阶段直接运行mineru-models-download -s huggingface -m all，把 pipeline 与 VLM 全套模型下载进镜像，并将模型路径与model-source写入配置文件。mineru-models-download命令的入口实现在 models_download.py，其中-m all会同时触发download_pipeline_models（下载 pp_doclayout_v2、unimernet、paddle OCR、slanet_plus、unet 表格结构、paddle_table_cls、pp_formulanet_plus_m 等 pipeline 模型）与download_vlm_models两个下载流程。镜像最后通过ENTRYPOINT在每次容器启动时自动export MINERU_MODEL_SOURCE=local，使容器内所有服务默认使用镜像内置的本地模型，无需运行时再联网拉取。

由于模型已内置于镜像，这一设计使得镜像体积较大但运行时完全离线可用，也是 compose.yaml 中各服务显式声明MINERU_MODEL_SOURCE: local的原因。

使用 vLLM 加速 VLM 推理的硬件前提

由于基础镜像自带 vLLM，在兼容设备上可以直接用它加速 VLM 模型推理。官方文档给出的硬性要求如下：

设备必须是Volta 架构及之后、可用显存 8GB 以上的显卡；
宿主机显卡驱动必须支持所选基础镜像使用的 CUDA 运行时：默认v0.21.0镜像要求CUDA 13.0 兼容驱动，v0.21.0-cu129要求CUDA 12.9 兼容驱动，可用nvidia-smi查看驱动版本；
Docker 容器必须能访问宿主机的 GPU 设备（即下面的--gpus all或 compose 中的 GPU 资源预留）。

从源码结构看，OpenAI 兼容服务入口 vlm_server.py 中-e/--engine参数支持auto、vllm、lmdeploy三种推理引擎，auto模式会优先探测 vLLM、探测失败再回落到 LMDeploy。Docker 镜像中预装了 vLLM，因此默认即走 vLLM 加速路径。

启动 Docker 容器

执行以下命令进入容器交互式终端：

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 暴露给容器，是 vLLM 推理加速的前提；
--shm-size 32g与--ipc=host：扩大共享内存，满足 PyTorch 多进程数据加载的需求；
四个端口分别对应 MinerU 的服务矩阵：30000为mineru-openai-server（OpenAI 兼容 VLM 推理服务），8000为mineru-api（Web API 服务），8002为mineru-router（聚合路由服务），7860为mineru-gradio（Gradio WebUI）。这四个入口均定义在 pyproject.toml 的脚本入口中：mineru-openai-server指向 vlm_server.py，mineru-api指向 fast_api.py，mineru-router指向 router.py，mineru-gradio指向 gradio_app.py。

进入容器后，可以直接运行mineru -p <input_path> -o <output_path>等 MinerU 命令完成解析。也可以把最后的/bin/bash替换为服务启动命令（如mineru-api、mineru-gradio）直接拉起对应服务，各服务的完整命令行参数可参考快速上手文档。

使用 Docker Compose 直接启动服务

仓库提供了 docker/compose.yaml，通过--profile机制将四类服务分组管理，可按需选择启动。获取方式：

# 下载 compose.yaml 文件 wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml

使用时注意：

compose.yaml包含 MinerU 的多个服务配置，可按需选择启动特定服务；
不同服务可能有额外的参数配置，均可在compose.yaml中查看和编辑；
由于 vLLM 框架会预分配 GPU 显存，同一台机器上通常无法同时运行多个 vLLM 服务。启动vlm-openai-server服务或使用vlm-vllm-engine后端之前，请确保其他可能占用 GPU 显存的服务已停止。

从 compose.yaml 的实现看，四个服务共用mineru:latest镜像并设置了restart: always，且都做了几项一致化配置：ulimits中放开memlock（vLLM 共享内存锁页所需）并加大stack；ipc: host提供共享内存；GPU 通过deploy.resources.reservations.devices预留，device_ids: ["0"]可修改为["0", "1"]等多卡列表；api、router、openai-server三个服务还配置了curl -f http://localhost:<port>/health健康检查（/health端点在 router.py 中定义为HEALTH_ENDPOINT）。此外，每个服务都保留了注释掉的--gpu-memory-utilization 0.5参数——显存不足时可通过它调低 vLLM 的 KV cache 占比，持续不足时建议降到0.4或更低。

启动 OpenAI 兼容 VLM 服务（openai-server）

mineru-openai-server服务以entrypoint: mineru-openai-server启动，监听--host 0.0.0.0 --port 30000，健康检查探测http://localhost:30000/health：

docker compose -f compose.yaml --profile openai-server up -d

随后在另一台终端（或同机的客户端环境）中，通过vlm-http-client后端连接该 OpenAI 兼容服务。此方式只需要 CPU 与网络，不需要 vLLM 环境：

mineru -p <input_path> -o <output_path> -b vlm-http-client -u http://<server_ip>:30000

从 backend_options.py 的源码看，vlm-http-client与hybrid-http-client属于 HTTP 客户端类后端，专门用于对接 OpenAI 兼容推理服务器；本地部署场景下还可选择pipeline（兼容性好）、vlm-engine、hybrid-engine（默认后端）三类本地后端。推理服务器与 CPU 客户端分离的架构，使得解析节点本身无需 GPU。

启动 Web API 服务（api）

mineru-api服务监听 8000 端口，提供完整的文档解析 API：

docker compose -f compose.yaml --profile api up -d

启动后可在浏览器访问http://<server_ip>:8000/docs查看 Swagger 交互式 API 文档。服务源码位于 fast_api.py，其--allow-public-http-client选项默认禁用；当绑定到0.0.0.0或::时该选项会重新启用*-http-client后端与server_url，官方注释明确要求仅在接受 SSRF 风险时才开启，公网部署时应保持关闭。

启动 MinerU Router 聚合服务（router）

mineru-router服务监听 8002 端口，默认以--local-gpus auto模式运行：

docker compose -f compose.yaml --profile router up -d

默认配置下，Router 在容器内自动拉起本地 worker，并在http://<server_ip>:8002/docs暴露统一入口；
如果希望聚合已存在的mineru-api服务而不是启动本地 worker，可参考compose.yaml中mineru-router服务下的注释示例，改为--local-gpus none并通过--upstream-url逐个指向上游，例如：

command: --local-gpus none --upstream-url http://mineru-api:8000 --upstream-url http://mineru-api-2:8000

从 router.py 源码看，--local-gpus支持auto、none及具体 GPU 列表取值，--upstream-url可重复指定多个上游；上游健康探测对 5xx 状态码做了重试与连续失败阈值（UPSTREAM_FAILURE_THRESHOLD = 3）处理，任务结果默认保留 24 小时（DEFAULT_TASK_RETENTION_SECONDS）。这说明 Router 定位于多实例聚合与统一任务查询网关。

启动 Gradio WebUI 服务（gradio）

mineru-gradio服务监听 7860 端口：

docker compose -f compose.yaml --profile gradio up -d

启动后在浏览器访问http://<server_ip>:7860即可使用可视化解析界面。compose.yaml中还预留了--enable-api false（禁用 API）与--max-convert-pages 20（限制转换页数）两个可选参数，可按需启用。

部署要点小结

关注点	说明	依据
平台限制	仅 Linux 与 Windows WSL2；macOS 下 Docker 无法使用 MPS/MLX 加速，禁止部署	官方文档
CUDA 版本选择	默认`v0.21.0`对应 CUDA 13.0；CUDA 12.9 环境切换`v0.21.0-cu129`	Dockerfile
模型离线可用	构建期执行`mineru-models-download -s huggingface -m all`，运行期`MINERU_MODEL_SOURCE=local`	Dockerfile
多 vLLM 互斥	vLLM 预分配显存，启动 openai-server / vllm-engine 前须停掉其他占卡服务	compose.yaml 注释与官方文档
显存不足	调低`--gpu-memory-utilization`（0.5 → 0.4 或更低）	compose.yaml 注释
端口矩阵	30000 / 8000 / 8002 / 7860 对应 openai-server / api / router / gradio	compose.yaml
客户端免 GPU	用`-b vlm-http-client -u <url>:30000`对接远端推理服务	backend_options.py

整套 Docker 方案的核心价值在于：镜像一次性解决依赖与模型下载问题，docker run满足单机命令行使用，compose.yaml的四类 profile 覆盖「推理服务器、API 服务、聚合网关、WebUI」的完整服务端形态，并天然支持「GPU 推理节点 + CPU 解析节点」的分离部署。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考