MinerU 平头哥 PPU 加速卡部署指南vLLM / LMDeploy 镜像构建、容器启动与后端支持矩阵【免费下载链接】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 仓库中的平头哥T-HeadPPU 加速卡适配指南 THead.md完整覆盖测试平台要求、两种推理引擎镜像的构建方式、Docker 容器启动参数以及各使用场景的支持情况并结合仓库内 ppu.Dockerfile 与推理引擎选择逻辑源码帮助你把 MinerU 稳定部署到国产 PPU 平台上理解vllm与lmdeploy两种加速路线在 MinerU 中的实际落点。1. 测试平台与软硬件要求官方指南给出的测试环境如下部署前可对照检查自己的平台是否满足等价条件os: Ubuntu 22.04 cpu: INTEL x86_64 ppu: ZW810E driver: 1.4.0 docker: 26.1.4几个关键点架构要求amd64x86_64CPU 平头哥 PPU 加速卡。这一点在 ppu.Dockerfile 的首行注释中也被明确写明“要求 amd64(x86-64) CPU t-head PPU”加速卡型号测试使用 ZW810E驱动版本 1.4.0容器运行时Docker 26.1.4更高版本通常兼容但建议以官方测试版本为基准。根据 changelog 记录MinerU 已适配多个国产算力平台其中明确包含“平头哥/ppu”在 PPU 平台上可以运行pipeline与vlm两类模型并使用vllm/lmdeploy引擎加速 VLM 模型推理。2. 环境准备构建 MinerU PPU 镜像PPU 加速卡支持使用vllm或lmdeploy进行 VLM 模型推理加速。请根据实际需求选择安装和使用其中之一。两条路线的差异本质上是基础镜像不同vLLM 路线基于包含 vLLM 推理环境的基础镜像LMDeploy 路线基于包含 LMDeploy 推理环境的基础镜像两者都已在 ppu.Dockerfile 中预置好通过注释切换。2.1 使用 Dockerfile 构建镜像vLLM 路线wget https://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/ppu.Dockerfile docker build --networkhost -t mineru:ppu-vllm-latest -f ppu.Dockerfile .如果你已经拥有 MinerU 仓库源码则无需 wget直接指定仓库内的 docker/china/ppu.Dockerfile 构建即可构建上下文需为仓库根目录docker build --networkhost -t mineru:ppu-vllm-latest -f docker/china/ppu.Dockerfile .2.2 使用 Dockerfile 构建镜像LMDeploy 路线wget https://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/ppu.Dockerfile # 将基础镜像从 vllm 切换为 lmdeploy sed -i 3s/^/# / ppu.Dockerfile sed -i 5,6s/^# // ppu.Dockerfile docker build --networkhost -t mineru:ppu-lmdeploy-latest -f ppu.Dockerfile .两条sed命令的作用与 ppu.Dockerfile 的实际结构一一对应# 第 3 行vLLM 路线的基础镜像默认启用 FROM crpi-.../opendatalab-mineru/ppu:ppu-pytorch2.6.0-ubuntu24.04-cuda12.6-vllm0.8.5-py312 # 第 4 行说明注释 # Base image containing the LMDeploy inference environment, ... # 第 5 行LMDeploy 路线的基础镜像默认被注释 # FROM crpi-.../lmdeploy_dlinfer/ppu:mineru-ppu # 第 6 行构建参数默认被注释 # ARG BACKENDlmdeploysed -i 3s/^/# /在第 3 行行首加#将 vLLM 的FROM行注释掉sed -i 5,6s/^# //去掉第 5、6 行的注释前缀启用 LMDeploy 的FROM行与ARG BACKENDlmdeploy参数。修改后 Dockerfile 以 LMDeploy 基础镜像构建且BACKEND变量被置为lmdeploy。2.3 构建过程中的关键步骤源码级解读从 ppu.Dockerfile 的完整内容看无论选择哪条路线构建流程还包含以下关键步骤安装 OpenCV 依赖与中文字体L8-L17安装libgl1、fonts-noto-cjk等保障文档渲染与中文输出正常安装 MinerU 核心包L20-L28通过国内 PyPI 镜像源安装mineru[core]3.4.0并固定numpy1.26.4、opencv-python4.11.0.86以保证与基础镜像环境兼容。值得注意的是Dockerfile 中的安装逻辑会检查BACKEND变量——仅当BACKENDlmdeploy时才会额外安装qwen-vl-utils依赖if [ $BACKEND lmdeploy ]; then \ python3 -m pip install qwen-vl-utils0.0.14,1 -i https://mirrors.aliyun.com/pypi/simple; \ fi这也是为什么 LMDeploy 路线必须通过sed启用ARG BACKENDlmdeploy而不只是换FROM镜像——否则qwen-vl-utils不会被安装预下载全部模型L31执行mineru-models-download -s modelscope -m all从 ModelScope 拉取全量模型写入镜像使容器内可离线使用本地模型固定模型源为 localL34入口命令通过ENTRYPOINT注入export MINERU_MODEL_SOURCElocal确保容器启动后直接读取镜像内预置的本地模型无需运行时联网下载。3. 启动 Docker 容器docker run --privilegedtrue \ --name mineru_docker \ --device/dev/alixpu \ --device/dev/alixpu_ctl \ --ipchost \ --networkhost \ --ulimit memlock-1 \ --ulimit stack67108864 \ --shm-size500g \ -v /mnt:/mnt \ -v /datapool:/datapool \ -v /var/run/docker.sock:/var/run/docker.sock \ -e MINERU_MODEL_SOURCElocal \ -it mineru:ppu-vllm-latest \ /bin/bash关键参数说明参数作用--device/dev/alixpu、--device/dev/alixpu_ctl将宿主机上的 PPU 加速卡设备节点映射进容器是 PPU 版本对应 NVIDIA--gpus all的机制--privilegedtrue授权容器访问加速卡所需的硬件权限--ipchost、--shm-size500g共享内存配置VLM 多进程/多卡推理对共享内存要求较高官方直接放开到 500g--networkhost容器与宿主机共用网络栈便于对外暴露 API 服务端口--ulimit memlock-1、--ulimit stack67108864放开锁存内存与线程栈大小限制满足推理运行时需求-v /mnt:/mnt、-v /datapool:/datapool挂载宿主机数据目录按实际情况调整-e MINERU_MODEL_SOURCElocal强制使用本地模型与 Dockerfile 的 ENTRYPOINT 设置保持一致双保险提示请根据实际情况选择vllm或lmdeploy版本的镜像如需使用 lmdeploy将上述命令中的mineru:ppu-vllm-latest替换为mineru:ppu-lmdeploy-latest即可。执行该命令后你将进入 Docker 容器的交互式终端可以直接在容器内运行 MinerU 相关命令。如果你要直接启动 MinerU 服务而非进入 bash可以把命令末尾的/bin/bash替换为对应的服务启动命令如mineru-api、mineru-gradio等各入口的启动方式详见 快速使用指南。4. 使用场景与后端支持矩阵官方指南给出了 PPU 平台上 MinerU 各入口 × 后端的支持情况vLLM 与 LMDeploy 两条路线的支持范围一致使用场景后端vLLMLMDeploy命令行工具minerupipeline命令行工具mineruvlm/hybrid-engine命令行工具mineruvlm/hybrid-http-clientfastapi 服务mineru-apipipelinefastapi 服务mineru-apivlm/hybrid-enginefastapi 服务mineru-apivlm/hybrid-http-clientgradio 界面mineru-gradiopipelinegradio 界面mineru-gradiovlm/hybrid-enginegradio 界面mineru-gradiovlm/hybrid-http-clientopenai-server 服务mineru-openai-server—图例 支持运行较稳定精度与 NVIDIA GPU 基本一致 支持但较不稳定 不支持。PPU 平台所有行列均为 即全场景稳定支持。对照 mineru/cli/backend_options.py 可以确认矩阵中出现的后端名与源码定义一致pipeline、vlm-engine、hybrid-engine默认后端、vlm-http-client、hybrid-http-client其中vlm/hybrid-engine表示vlm-engine与hybrid-engine均可用。-http-client系列则是把推理请求代理到独立的 openai-server 服务见下节从而与mineru-openai-server一一对应。关于mineru-openai-server的引擎选择从 vlm_server.py 的源码可以看到其默认行为--engine参数支持auto、vllm、lmdeploy三种取值默认auto时会先尝试import vllm导入失败则回退到lmdeploy。因此 vLLM 镜像会自动选 vLLMLMDeploy 镜像会自动选 LMDeploy一般无需显式指定--engine。5. 注意事项5.1 指定可用的加速卡PPU 加速卡指定可用加速卡的方式与 NVIDIA GPU 类似即通过CUDA_VISIBLE_DEVICES环境变量控制可见设备详细说明见 命令行参数进阶 中的 CUDA_VISIBLE_DEVICES 章节例如CUDA_VISIBLE_DEVICES0,1 mineru-api --host 127.0.0.1 --port 8000该写法对mineru、mineru-openai-server、mineru-gradio、mineru-api和mineru-router全部生效且对pipeline、vlm后端均适用。5.2 查看加速卡状态在 T-Head 平台上可以通过ppu-smi命令查看加速卡的使用情况显存占用、利用率等并根据需要指定空闲的加速卡 ID避免多任务之间的资源冲突。5.3 引擎选择与推理参数透传选择 vLLM 或 LMDeploy 时构建的镜像不同见第 2 节的sed切换方式运行mineru-openai-server等入口时引擎会按auto逻辑自动匹配无需额外配置所有 vLLM/LMDeploy 官方支持的推理参数都可以通过命令行参数透传给 MinerU 各入口如mineru、mineru-openai-server、mineru-gradio、mineru-api、mineru-router参数同时支持--foo value与--foovalue两种写法更多细节见 命令行参数进阶。6. 小结在平头哥 PPU 平台部署 MinerU 的完整路径是准备 amd64 PPU如 ZW810E环境 → 按需选择 vLLM 或 LMDeploy 基础镜像构建mineru:ppu-*-latest镜像Dockerfile 已内置全量模型与MINERU_MODEL_SOURCElocal入口→ 通过--device/dev/alixpu等参数启动容器 → 在容器内使用任一 MinerU 入口CLI、fastapi、gradio、openai-server与任意后端pipeline / vlm / hybrid并用CUDA_VISIBLE_DEVICES与ppu-smi管理多卡。各步骤的原始文档见 docs/zh/usage/acceleration_cards/THead.md。【免费下载链接】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 平头哥 PPU 加速卡部署指南：vLLM / LMDeploy 镜像构建、容器启动与后端支持矩阵
MinerU 平头哥 PPU 加速卡部署指南vLLM / LMDeploy 镜像构建、容器启动与后端支持矩阵【免费下载链接】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 仓库中的平头哥T-HeadPPU 加速卡适配指南 THead.md完整覆盖测试平台要求、两种推理引擎镜像的构建方式、Docker 容器启动参数以及各使用场景的支持情况并结合仓库内 ppu.Dockerfile 与推理引擎选择逻辑源码帮助你把 MinerU 稳定部署到国产 PPU 平台上理解vllm与lmdeploy两种加速路线在 MinerU 中的实际落点。1. 测试平台与软硬件要求官方指南给出的测试环境如下部署前可对照检查自己的平台是否满足等价条件os: Ubuntu 22.04 cpu: INTEL x86_64 ppu: ZW810E driver: 1.4.0 docker: 26.1.4几个关键点架构要求amd64x86_64CPU 平头哥 PPU 加速卡。这一点在 ppu.Dockerfile 的首行注释中也被明确写明“要求 amd64(x86-64) CPU t-head PPU”加速卡型号测试使用 ZW810E驱动版本 1.4.0容器运行时Docker 26.1.4更高版本通常兼容但建议以官方测试版本为基准。根据 changelog 记录MinerU 已适配多个国产算力平台其中明确包含“平头哥/ppu”在 PPU 平台上可以运行pipeline与vlm两类模型并使用vllm/lmdeploy引擎加速 VLM 模型推理。2. 环境准备构建 MinerU PPU 镜像PPU 加速卡支持使用vllm或lmdeploy进行 VLM 模型推理加速。请根据实际需求选择安装和使用其中之一。两条路线的差异本质上是基础镜像不同vLLM 路线基于包含 vLLM 推理环境的基础镜像LMDeploy 路线基于包含 LMDeploy 推理环境的基础镜像两者都已在 ppu.Dockerfile 中预置好通过注释切换。2.1 使用 Dockerfile 构建镜像vLLM 路线wget https://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/ppu.Dockerfile docker build --networkhost -t mineru:ppu-vllm-latest -f ppu.Dockerfile .如果你已经拥有 MinerU 仓库源码则无需 wget直接指定仓库内的 docker/china/ppu.Dockerfile 构建即可构建上下文需为仓库根目录docker build --networkhost -t mineru:ppu-vllm-latest -f docker/china/ppu.Dockerfile .2.2 使用 Dockerfile 构建镜像LMDeploy 路线wget https://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/ppu.Dockerfile # 将基础镜像从 vllm 切换为 lmdeploy sed -i 3s/^/# / ppu.Dockerfile sed -i 5,6s/^# // ppu.Dockerfile docker build --networkhost -t mineru:ppu-lmdeploy-latest -f ppu.Dockerfile .两条sed命令的作用与 ppu.Dockerfile 的实际结构一一对应# 第 3 行vLLM 路线的基础镜像默认启用 FROM crpi-.../opendatalab-mineru/ppu:ppu-pytorch2.6.0-ubuntu24.04-cuda12.6-vllm0.8.5-py312 # 第 4 行说明注释 # Base image containing the LMDeploy inference environment, ... # 第 5 行LMDeploy 路线的基础镜像默认被注释 # FROM crpi-.../lmdeploy_dlinfer/ppu:mineru-ppu # 第 6 行构建参数默认被注释 # ARG BACKENDlmdeploysed -i 3s/^/# /在第 3 行行首加#将 vLLM 的FROM行注释掉sed -i 5,6s/^# //去掉第 5、6 行的注释前缀启用 LMDeploy 的FROM行与ARG BACKENDlmdeploy参数。修改后 Dockerfile 以 LMDeploy 基础镜像构建且BACKEND变量被置为lmdeploy。2.3 构建过程中的关键步骤源码级解读从 ppu.Dockerfile 的完整内容看无论选择哪条路线构建流程还包含以下关键步骤安装 OpenCV 依赖与中文字体L8-L17安装libgl1、fonts-noto-cjk等保障文档渲染与中文输出正常安装 MinerU 核心包L20-L28通过国内 PyPI 镜像源安装mineru[core]3.4.0并固定numpy1.26.4、opencv-python4.11.0.86以保证与基础镜像环境兼容。值得注意的是Dockerfile 中的安装逻辑会检查BACKEND变量——仅当BACKENDlmdeploy时才会额外安装qwen-vl-utils依赖if [ $BACKEND lmdeploy ]; then \ python3 -m pip install qwen-vl-utils0.0.14,1 -i https://mirrors.aliyun.com/pypi/simple; \ fi这也是为什么 LMDeploy 路线必须通过sed启用ARG BACKENDlmdeploy而不只是换FROM镜像——否则qwen-vl-utils不会被安装预下载全部模型L31执行mineru-models-download -s modelscope -m all从 ModelScope 拉取全量模型写入镜像使容器内可离线使用本地模型固定模型源为 localL34入口命令通过ENTRYPOINT注入export MINERU_MODEL_SOURCElocal确保容器启动后直接读取镜像内预置的本地模型无需运行时联网下载。3. 启动 Docker 容器docker run --privilegedtrue \ --name mineru_docker \ --device/dev/alixpu \ --device/dev/alixpu_ctl \ --ipchost \ --networkhost \ --ulimit memlock-1 \ --ulimit stack67108864 \ --shm-size500g \ -v /mnt:/mnt \ -v /datapool:/datapool \ -v /var/run/docker.sock:/var/run/docker.sock \ -e MINERU_MODEL_SOURCElocal \ -it mineru:ppu-vllm-latest \ /bin/bash关键参数说明参数作用--device/dev/alixpu、--device/dev/alixpu_ctl将宿主机上的 PPU 加速卡设备节点映射进容器是 PPU 版本对应 NVIDIA--gpus all的机制--privilegedtrue授权容器访问加速卡所需的硬件权限--ipchost、--shm-size500g共享内存配置VLM 多进程/多卡推理对共享内存要求较高官方直接放开到 500g--networkhost容器与宿主机共用网络栈便于对外暴露 API 服务端口--ulimit memlock-1、--ulimit stack67108864放开锁存内存与线程栈大小限制满足推理运行时需求-v /mnt:/mnt、-v /datapool:/datapool挂载宿主机数据目录按实际情况调整-e MINERU_MODEL_SOURCElocal强制使用本地模型与 Dockerfile 的 ENTRYPOINT 设置保持一致双保险提示请根据实际情况选择vllm或lmdeploy版本的镜像如需使用 lmdeploy将上述命令中的mineru:ppu-vllm-latest替换为mineru:ppu-lmdeploy-latest即可。执行该命令后你将进入 Docker 容器的交互式终端可以直接在容器内运行 MinerU 相关命令。如果你要直接启动 MinerU 服务而非进入 bash可以把命令末尾的/bin/bash替换为对应的服务启动命令如mineru-api、mineru-gradio等各入口的启动方式详见 快速使用指南。4. 使用场景与后端支持矩阵官方指南给出了 PPU 平台上 MinerU 各入口 × 后端的支持情况vLLM 与 LMDeploy 两条路线的支持范围一致使用场景后端vLLMLMDeploy命令行工具minerupipeline命令行工具mineruvlm/hybrid-engine命令行工具mineruvlm/hybrid-http-clientfastapi 服务mineru-apipipelinefastapi 服务mineru-apivlm/hybrid-enginefastapi 服务mineru-apivlm/hybrid-http-clientgradio 界面mineru-gradiopipelinegradio 界面mineru-gradiovlm/hybrid-enginegradio 界面mineru-gradiovlm/hybrid-http-clientopenai-server 服务mineru-openai-server—图例 支持运行较稳定精度与 NVIDIA GPU 基本一致 支持但较不稳定 不支持。PPU 平台所有行列均为 即全场景稳定支持。对照 mineru/cli/backend_options.py 可以确认矩阵中出现的后端名与源码定义一致pipeline、vlm-engine、hybrid-engine默认后端、vlm-http-client、hybrid-http-client其中vlm/hybrid-engine表示vlm-engine与hybrid-engine均可用。-http-client系列则是把推理请求代理到独立的 openai-server 服务见下节从而与mineru-openai-server一一对应。关于mineru-openai-server的引擎选择从 vlm_server.py 的源码可以看到其默认行为--engine参数支持auto、vllm、lmdeploy三种取值默认auto时会先尝试import vllm导入失败则回退到lmdeploy。因此 vLLM 镜像会自动选 vLLMLMDeploy 镜像会自动选 LMDeploy一般无需显式指定--engine。5. 注意事项5.1 指定可用的加速卡PPU 加速卡指定可用加速卡的方式与 NVIDIA GPU 类似即通过CUDA_VISIBLE_DEVICES环境变量控制可见设备详细说明见 命令行参数进阶 中的 CUDA_VISIBLE_DEVICES 章节例如CUDA_VISIBLE_DEVICES0,1 mineru-api --host 127.0.0.1 --port 8000该写法对mineru、mineru-openai-server、mineru-gradio、mineru-api和mineru-router全部生效且对pipeline、vlm后端均适用。5.2 查看加速卡状态在 T-Head 平台上可以通过ppu-smi命令查看加速卡的使用情况显存占用、利用率等并根据需要指定空闲的加速卡 ID避免多任务之间的资源冲突。5.3 引擎选择与推理参数透传选择 vLLM 或 LMDeploy 时构建的镜像不同见第 2 节的sed切换方式运行mineru-openai-server等入口时引擎会按auto逻辑自动匹配无需额外配置所有 vLLM/LMDeploy 官方支持的推理参数都可以通过命令行参数透传给 MinerU 各入口如mineru、mineru-openai-server、mineru-gradio、mineru-api、mineru-router参数同时支持--foo value与--foovalue两种写法更多细节见 命令行参数进阶。6. 小结在平头哥 PPU 平台部署 MinerU 的完整路径是准备 amd64 PPU如 ZW810E环境 → 按需选择 vLLM 或 LMDeploy 基础镜像构建mineru:ppu-*-latest镜像Dockerfile 已内置全量模型与MINERU_MODEL_SOURCElocal入口→ 通过--device/dev/alixpu等参数启动容器 → 在容器内使用任一 MinerU 入口CLI、fastapi、gradio、openai-server与任意后端pipeline / vlm / hybrid并用CUDA_VISIBLE_DEVICES与ppu-smi管理多卡。各步骤的原始文档见 docs/zh/usage/acceleration_cards/THead.md。【免费下载链接】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），仅供参考