MinerU 平头哥 PPU 加速卡部署指南：vLLM / LMDeploy 镜像构建、容器启动与后端支持矩阵

本文基于 MinerU 仓库中的平头哥（T-Head）PPU 加速卡适配指南 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

几个关键点：

• 架构要求：amd64（x86_64）CPU + 平头哥 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/MinerU@master/docker/china/ppu.Dockerfile
docker build --network=host -t mineru:ppu-vllm-latest -f ppu.Dockerfile .

如果你已经拥有 MinerU 仓库源码，则无需 wget，直接指定仓库内的 docker/china/ppu.Dockerfile 构建即可（构建上下文需为仓库根目录）：

docker build --network=host -t mineru:ppu-vllm-latest -f docker/china/ppu.Dockerfile .

2.2 使用 Dockerfile 构建镜像（LMDeploy 路线）

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/ppu.Dockerfile
# 将基础镜像从 vllm 切换为 lmdeploy
sed -i '3s/^/# /' ppu.Dockerfile && sed -i '5,6s/^# //' ppu.Dockerfile
docker build --network=host -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 BACKEND=lmdeploy

• sed -i '3s/^/# /'：在第 3 行行首加 # ，将 vLLM 的 FROM 行注释掉；
• sed -i '5,6s/^# //'：去掉第 5、6 行的注释前缀，启用 LMDeploy 的 FROM 行与 ARG BACKEND=lmdeploy 参数。

修改后 Dockerfile 以 LMDeploy 基础镜像构建，且 BACKEND 变量被置为 lmdeploy。

2.3 构建过程中的关键步骤（源码级解读）

从 ppu.Dockerfile 的完整内容看，无论选择哪条路线，构建流程还包含以下关键步骤：

1. 安装 OpenCV 依赖与中文字体（L8-L17）：安装 libgl1、fonts-noto-cjk 等，保障文档渲染与中文输出正常；

2. 安装 MinerU 核心包（L20-L28）：通过国内 PyPI 镜像源安装 mineru[core]>=3.4.0，并固定 numpy==1.26.4、opencv-python==4.11.0.86 以保证与基础镜像环境兼容。值得注意的是，Dockerfile 中的安装逻辑会检查 BACKEND 变量——仅当 BACKEND=lmdeploy 时，才会额外安装 qwen-vl-utils 依赖：

   if [ "$BACKEND" = "lmdeploy" ]; then \
       python3 -m pip install 'qwen-vl-utils>=0.0.14,<1' -i https://mirrors.aliyun.com/pypi/simple; \
   fi
   

   这也是为什么 LMDeploy 路线必须通过 sed 启用 ARG BACKEND=lmdeploy 而不只是换 FROM 镜像——否则 qwen-vl-utils 不会被安装；

3. 预下载全部模型（L31）：执行 mineru-models-download -s modelscope -m all，从 ModelScope 拉取全量模型写入镜像，使容器内可离线使用本地模型；

4. 固定模型源为 local（L34）：入口命令通过 ENTRYPOINT 注入 export MINERU_MODEL_SOURCE=local，确保容器启动后直接读取镜像内预置的本地模型，无需运行时联网下载。

3. 启动 Docker 容器

docker run --privileged=true \
  --name mineru_docker \
  --device=/dev/alixpu \
  --device=/dev/alixpu_ctl \
  --ipc=host \
  --network=host \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  --shm-size=500g \
  -v /mnt:/mnt \
  -v /datapool:/datapool \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e MINERU_MODEL_SOURCE=local \
  -it mineru:ppu-vllm-latest \
  /bin/bash

关键参数说明：

参数	作用
--device=/dev/alixpu、--device=/dev/alixpu_ctl	将宿主机上的 PPU 加速卡设备节点映射进容器，是 PPU 版本对应 NVIDIA --gpus all 的机制
--privileged=true	授权容器访问加速卡所需的硬件权限
--ipc=host、--shm-size=500g	共享内存配置，VLM 多进程/多卡推理对共享内存要求较高，官方直接放开到 500g
--network=host	容器与宿主机共用网络栈，便于对外暴露 API 服务端口
--ulimit memlock=-1、--ulimit stack=67108864	放开锁存内存与线程栈大小限制，满足推理运行时需求
-v /mnt:/mnt、-v /datapool:/datapool	挂载宿主机数据目录，按实际情况调整
-e MINERU_MODEL_SOURCE=local	强制使用本地模型（与 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 两条路线的支持范围一致）：

使用场景	后端	vLLM	LMDeploy
命令行工具（mineru）	pipeline	🟢	🟢
命令行工具（mineru）	<vlm/hybrid>-engine	🟢	🟢
命令行工具（mineru）	<vlm/hybrid>-http-client	🟢	🟢
fastapi 服务（mineru-api）	pipeline	🟢	🟢
fastapi 服务（mineru-api）	<vlm/hybrid>-engine	🟢	🟢
fastapi 服务（mineru-api）	<vlm/hybrid>-http-client	🟢	🟢
gradio 界面（mineru-gradio）	pipeline	🟢	🟢
gradio 界面（mineru-gradio）	<vlm/hybrid>-engine	🟢	🟢
gradio 界面（mineru-gradio）	<vlm/hybrid>-http-client	🟢	🟢
openai-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 镜像会自动选 vLLM，LMDeploy 镜像会自动选 LMDeploy，一般无需显式指定 --engine。

5. 注意事项

5.1 指定可用的加速卡

PPU 加速卡指定可用加速卡的方式与 NVIDIA GPU 类似，即通过 CUDA_VISIBLE_DEVICES 环境变量控制可见设备，详细说明见 命令行参数进阶 中的 CUDA_VISIBLE_DEVICES 章节，例如：

CUDA_VISIBLE_DEVICES=0,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 与 --foo=value 两种写法，更多细节见 命令行参数进阶。

6. 小结

在平头哥 PPU 平台部署 MinerU 的完整路径是：准备 amd64 + PPU（如 ZW810E）环境 → 按需选择 vLLM 或 LMDeploy 基础镜像构建 mineru:ppu-*-latest 镜像（Dockerfile 已内置全量模型与 MINERU_MODEL_SOURCE=local 入口）→ 通过 --device=/dev/alixpu 等参数启动容器 → 在容器内使用任一 MinerU 入口（CLI、fastapi、gradio、openai-server）与任意后端（pipeline / vlm / hybrid），并用 CUDA_VISIBLE_DEVICES 与 ppu-smi 管理多卡。各步骤的原始文档见 docs/zh/usage/acceleration_cards/THead.md。