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_SOURCElocal机制的底层设计。适用环境与平台限制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/MinerUmaster/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 架构的 GPUCompute Capability 7.0 ≤ CC ≤ 12.1同时支持 x86_64 与 ARMAArch64两种架构。默认基础镜像对应CUDA 13.0环境如果你的环境需要 CUDA 12.9 兼容镜像需要注释掉默认的FROM行改用 Dockerfile 中已预留的注释行vllm/vllm-openai:v0.21.0-cu129。安装运行时依赖。镜像内通过apt-get安装libgl1OpenCV 运行依赖以及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_SOURCElocal使容器内所有服务默认使用镜像内置的本地模型无需运行时再联网拉取。由于模型已内置于镜像这一设计使得镜像体积较大但运行时完全离线可用也是 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 \ --ipchost \ -it mineru:latest \ /bin/bash参数要点--gpus all将宿主机全部 GPU 暴露给容器是 vLLM 推理加速的前提--shm-size 32g与--ipchost扩大共享内存满足 PyTorch 多进程数据加载的需求四个端口分别对应 MinerU 的服务矩阵30000为mineru-openai-serverOpenAI 兼容 VLM 推理服务8000为mineru-apiWeb API 服务8002为mineru-router聚合路由服务7860为mineru-gradioGradio WebUI。这四个入口均定义在 pyproject.toml 的脚本入口中mineru-openai-server指向 vlm_server.pymineru-api指向 fast_api.pymineru-router指向 router.pymineru-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/MinerUmaster/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中放开memlockvLLM 共享内存锁页所需并加大stackipc: 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-servermineru-openai-server服务以entrypoint: mineru-openai-server启动监听--host 0.0.0.0 --port 30000健康检查探测http://localhost:30000/healthdocker 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 服务apimineru-api服务监听 8000 端口提供完整的文档解析 APIdocker 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 聚合服务routermineru-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 服务gradiomineru-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 WSL2macOS 下 Docker 无法使用 MPS/MLX 加速禁止部署官方文档CUDA 版本选择默认v0.21.0对应 CUDA 13.0CUDA 12.9 环境切换v0.21.0-cu129Dockerfile模型离线可用构建期执行mineru-models-download -s huggingface -m all运行期MINERU_MODEL_SOURCElocalDockerfile多 vLLM 互斥vLLM 预分配显存启动 openai-server / vllm-engine 前须停掉其他占卡服务compose.yaml 注释与官方文档显存不足调低--gpu-memory-utilization0.5 → 0.4 或更低compose.yaml 注释端口矩阵30000 / 8000 / 8002 / 7860 对应 openai-server / api / router / gradiocompose.yaml客户端免 GPU用-b vlm-http-client -u url:30000对接远端推理服务backend_options.py整套 Docker 方案的核心价值在于镜像一次性解决依赖与模型下载问题docker run满足单机命令行使用compose.yaml的四类 profile 覆盖「推理服务器、API 服务、聚合网关、WebUI」的完整服务端形态并天然支持「GPU 推理节点 CPU 解析节点」的分离部署。【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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_SOURCElocal机制的底层设计。适用环境与平台限制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/MinerUmaster/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 架构的 GPUCompute Capability 7.0 ≤ CC ≤ 12.1同时支持 x86_64 与 ARMAArch64两种架构。默认基础镜像对应CUDA 13.0环境如果你的环境需要 CUDA 12.9 兼容镜像需要注释掉默认的FROM行改用 Dockerfile 中已预留的注释行vllm/vllm-openai:v0.21.0-cu129。安装运行时依赖。镜像内通过apt-get安装libgl1OpenCV 运行依赖以及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_SOURCElocal使容器内所有服务默认使用镜像内置的本地模型无需运行时再联网拉取。由于模型已内置于镜像这一设计使得镜像体积较大但运行时完全离线可用也是 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 \ --ipchost \ -it mineru:latest \ /bin/bash参数要点--gpus all将宿主机全部 GPU 暴露给容器是 vLLM 推理加速的前提--shm-size 32g与--ipchost扩大共享内存满足 PyTorch 多进程数据加载的需求四个端口分别对应 MinerU 的服务矩阵30000为mineru-openai-serverOpenAI 兼容 VLM 推理服务8000为mineru-apiWeb API 服务8002为mineru-router聚合路由服务7860为mineru-gradioGradio WebUI。这四个入口均定义在 pyproject.toml 的脚本入口中mineru-openai-server指向 vlm_server.pymineru-api指向 fast_api.pymineru-router指向 router.pymineru-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/MinerUmaster/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中放开memlockvLLM 共享内存锁页所需并加大stackipc: 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-servermineru-openai-server服务以entrypoint: mineru-openai-server启动监听--host 0.0.0.0 --port 30000健康检查探测http://localhost:30000/healthdocker 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 服务apimineru-api服务监听 8000 端口提供完整的文档解析 APIdocker 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 聚合服务routermineru-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 服务gradiomineru-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 WSL2macOS 下 Docker 无法使用 MPS/MLX 加速禁止部署官方文档CUDA 版本选择默认v0.21.0对应 CUDA 13.0CUDA 12.9 环境切换v0.21.0-cu129Dockerfile模型离线可用构建期执行mineru-models-download -s huggingface -m all运行期MINERU_MODEL_SOURCElocalDockerfile多 vLLM 互斥vLLM 预分配显存启动 openai-server / vllm-engine 前须停掉其他占卡服务compose.yaml 注释与官方文档显存不足调低--gpu-memory-utilization0.5 → 0.4 或更低compose.yaml 注释端口矩阵30000 / 8000 / 8002 / 7860 对应 openai-server / api / router / gradiocompose.yaml客户端免 GPU用-b vlm-http-client -u url:30000对接远端推理服务backend_options.py整套 Docker 方案的核心价值在于镜像一次性解决依赖与模型下载问题docker run满足单机命令行使用compose.yaml的四类 profile 覆盖「推理服务器、API 服务、聚合网关、WebUI」的完整服务端形态并天然支持「GPU 推理节点 CPU 解析节点」的分离部署。【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考