MinerU 在沐曦（METAX）MACA 加速卡上的部署实战：vllm/lmdeploy 双引擎镜像构建与容器启动

本文以 MinerU 仓库中面向沐曦（METAX）加速卡的官方部署文档为核心，系统讲解如何在 MACA 平台上构建 MinerU 推理镜像、启动 Docker 容器并指定加速卡设备，并结合仓库源码剖析 MinerU 识别 maca 设备的底层机制（引擎自动选择、lmdeploy 后端强制为 pytorch、cudnn 禁用等），帮助你在国产算力上稳定运行 pipeline、vlm/hybrid 与 openai-server 全场景。

1. 测试平台与适用前提

官方文档给出的验证环境如下，搭建前请先确认你的物理机满足同样的前提（amd64/x86-64 CPU + METAX GPU + 宿主机已安装 MACA 驱动）：

os: Ubuntu 22.04
cpu: INTEL x86_64
gpu: C500
driver: 2.1.2.13
docker: 28.1.1

说明：MinerU 对 MACA 加速卡的支持自 docs/reference/changelog.md 中记录起，与昇腾（npu）、平头哥（ppu）同属“国产算力平台适配”能力，覆盖 pipeline 与 vlm 两类后端，并支持 vllm/lmdeploy 引擎加速 VLM 推理。

2. 准备基础推理镜像

MACA 加速卡支持使用 vllm 或 lmdeploy 进行 VLM 模型推理加速，请根据实际需求选择安装和使用其中一个。两个引擎对应的官方基础镜像均可在 METAX 官方镜像仓库（SoftNova 镜像站）中获取：选择 AI 分类、软件包类型选择 vllm、操作系统选择 ubuntu，找到对应 amd64 镜像后复制拉取命令在本地终端执行。

两个引擎对应的基础镜像 tag 与 docker/china/maca.Dockerfile 中的 FROM 行严格一致：

推理引擎	基础镜像 tag
vllm	maca.ai3.1.0.7-torch2.6-py310-ubuntu22.04-amd64（来自 metax 官方仓库 public-ai-release/maca/vllm）
lmdeploy	maca.ai3.1.0.7-torch2.6-py310-ubuntu22.04-lmdeploy0.10.2-amd64（来自 OpenDataLab 个人容器仓库）

可以对照仓库 Dockerfile 的注释确认二者地位：docker/china/maca.Dockerfile 第 3 行是 vllm 基础镜像的 FROM，第 5-6 行是被注释掉的 lmdeploy 基础镜像与 ARG BACKEND=lmdeploy。

3. 构建 MinerU 镜像

仓库中已内置 docker/china/maca.Dockerfile，直接从仓库获取该文件（克隆仓库或从仓库下载均可）后即可构建。

3.1 构建 vllm 版镜像

docker build --network=host -t mineru:maca-vllm-latest -f maca.Dockerfile .

3.2 构建 lmdeploy 版镜像

# 将基础镜像从 vllm 切换为 lmdeploy
sed -i '3s/^/# /' maca.Dockerfile && sed -i '5,6s/^# //' maca.Dockerfile
docker build --network=host -t mineru:maca-lmdeploy-latest -f maca.Dockerfile .

两条 sed 命令的作用与 Dockerfile 结构一一对应：把第 3 行的 vllm FROM 注释掉，同时取消第 5-6 行 lmdeploy FROM 与 BACKEND 参数的注释，等价于手动编辑 Dockerfile 切换基础镜像。

3.3 Dockerfile 内部做了什么

结合 docker/china/maca.Dockerfile 源码，构建过程实际完成了 5 件事：

1. 系统依赖（第 8-17 行）：安装 fonts-noto-core、fonts-noto-cjk、fontconfig、libgl1 并执行 fc-cache，前者为 OpenCV 提供 libgl 支持，Noto 中文字体保证 PDF 渲染与 bbox 可视化时中文不丢失；
2. torchvision 版本修正（第 19-21 行）：把基础镜像里 torchvision-0.15.1+metax3.1.0.4 的 dist-info METADATA 版本号改写为 0.21.0+metax3.1.0.4，以与 metax 版 torch 2.6 的版本约束兼容——这是 MACA 平台特有的适配步骤；
3. 安装 MinerU（第 23-32 行）：pip install 'mineru[core]>=3.4.0' numpy==1.26.4 opencv-python==4.11.0.86；当 BACKEND=lmdeploy 时额外安装 qwen-vl-utils>=0.0.14,<1（lmdeploy 的 VL 推理需要）；
4. 预下载全部模型（第 35 行）：mineru-models-download -s modelscope -m all，从 ModelScope 下载 pipeline + vlm 全量模型，运行时不再依赖 HuggingFace 网络；
5. 入口点（第 38 行）：ENTRYPOINT 自动导出 MINERU_MODEL_SOURCE=local 后再执行容器内命令，因此容器默认走本地模型，无需再手动设置模型源。

4. 启动 Docker 容器

docker run --ipc host \
   --cap-add SYS_PTRACE \
   --privileged=true \
   --device=/dev/mem \
   --device=/dev/dri \
   --device=/dev/mxcd \
   --device=/dev/infiniband \
   --group-add video \
   --network=host \
   --shm-size '100gb' \
   --ulimit memlock=-1 \
   --security-opt seccomp=unconfined \
   --security-opt apparmor=unconfined \
   --name mineru_docker \
   -v /datapool:/datapool \
   -e MINERU_MODEL_SOURCE=local \
   -e MINERU_LMDEPLOY_DEVICE=maca \
   -it mineru:maca-vllm-latest \
   /bin/bash

关键参数说明：

参数	作用
--device=/dev/mem、--device=/dev/dri、--device=/dev/mxcd、--device=/dev/infiniband	挂载 MACA 驱动所需的设备节点（/dev/mxcd 是沐曦卡的核心设备节点），缺少任意一项容器内都探测不到加速卡
--privileged=true + SYS_PTRACE + seccomp=unconfined + apparmor=unconfined	MACA 运行时初始化需要的宽松安全配置
--shm-size 100gb、--ipc host、--ulimit memlock=-1	大共享内存与无锁内存，满足 VLM 推理时进程间通信与锁内存需求
-v /datapool:/datapool	挂载宿主机数据盘，输入 PDF 与输出结果均落在该目录，注意按实际路径替换
-e MINERU_MODEL_SOURCE=local	使用镜像构建期已下载的本地模型
-e MINERU_LMDEPLOY_DEVICE=maca	告知 MinerU 的 lmdeploy 栈当前运行在 MACA 设备上（详见第 5 节）

镜像选择：请根据实际情况选择使用 vllm 或 lmdeploy 版本的镜像；如需使用 lmdeploy，把命令中的 mineru:maca-vllm-latest 替换为 mineru:maca-lmdeploy-latest 即可。

执行该命令后将进入 Docker 容器的交互式终端，可直接运行 mineru 等命令进行解析。也可以把末尾的 /bin/bash 替换为服务启动命令直接拉起 MinerU 服务，例如 mineru-api --host 0.0.0.0 --port 8000、mineru-gradio --server-name 0.0.0.0 --server-port 7860 或 mineru-openai-server --port 30000，完整说明见 通过命令启动服务。

5. 源码级原理：MinerU 如何识别 maca 设备

MINERU_LMDEPLOY_DEVICE=maca 并非摆设，仓库源码中有三处直接消费该变量/设备类型的逻辑：

1. lmdeploy 后端强制为 pytorch。mineru/backend/vlm/utils.py 中 set_lmdeploy_backend() 明确将 ascend、maca、camb 三类国产设备统一映射到 pytorch 后端（turbomind 仅用于 CUDA 场景）：

   def set_lmdeploy_backend(device_type: str) -> str:
       if device_type.lower() in ["ascend", "maca", "camb"]:
           lmdeploy_backend = "pytorch"
   

2. 设备类型白名单校验与参数拼装。mineru/model/vlm/lmdeploy_server.py（mineru-openai-server 的 lmdeploy 入口）从环境变量读取设备类型，非法值直接抛 ValueError，最终把 --device maca --backend pytorch 拼进 lmdeploy serve api_server 启动参数；mineru/backend/vlm/vlm_analyze.py 中 lmdeploy-engine 的进程内引擎路径执行同样的白名单校验（cuda/ascend/maca/camb）与后端选择。

3. 禁用 cudnn。mineru/cli/common.py 在 CLI 入口处对 MACA 环境做了 torch 级别的兜底：

   if os.getenv("MINERU_LMDEPLOY_DEVICE", "") == "maca":
       import torch
       torch.backends.cudnn.enabled = False
   

   这是 MACA 平台上的专属处理，可避免部分算子在 MACA 版 torch 2.6 上走 cudnn 路径产生异常。

此外，引擎的自动选择由 mineru/utils/engine_utils.py 完成：Linux 环境下优先尝试 import vllm（成功则用 vllm/vllm-async），否则回退 lmdeploy，最后回退 transformers。因此 vllm 版镜像中 -b vlm-engine 会走 vLLM 路径，lmdeploy 版镜像则自动落到 lmdeploy 路径，无需手工指定引擎；mineru-openai-server 的 openai_server 入口 也采用相同的 auto 探测逻辑。

6. 支持情况矩阵

不同环境下 MinerU 对 MACA 加速卡的支持情况（引自官方文档，均为 🟢 支持）：

使用场景	后端	容器内 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 基本一致；🟡 支持但较不稳定，某些场景可能出现异常或精度存在一定差异；🟴 不支持，无法运行或精度存在较大差异。

7. 指定加速卡与运行监控

• 指定可用加速卡：MACA 加速卡指定可用加速卡的方式与 NVIDIA GPU 类似，在命令前加 CUDA_VISIBLE_DEVICES 环境变量即可，例如 CUDA_VISIBLE_DEVICES=1 mineru -p <input_path> -o <output_path>；更多用法（含 mineru-openai-server 多卡分端口、mineru-router 聚合多卡）见 命令行进阶参数 的 “CUDA_VISIBLE_DEVICES” 章节；
• 监控与排障：在 METAX 平台通过 mx-smi 命令查看加速卡使用情况（显存、占用率），并据此指定空闲的加速卡 ID，避免多容器/多进程资源冲突。

8. 小结

在沐曦 MACA 平台上使用 MinerU 的完整路径是：从 METAX 官方镜像仓库获取 vllm 或 lmdeploy 基础镜像 → 用仓库内的 docker/china/maca.Dockerfile 构建 mineru:maca-vllm-latest 或 mineru:maca-lmdeploy-latest（lmdeploy 版仅需两条 sed 命令切换基础镜像）→ 以挂载 /dev/mxcd 等设备节点、设置 MINERU_MODEL_SOURCE=local 与 MINERU_LMDEPLOY_DEVICE=maca 的参数启动容器 → 通过 CUDA_VISIBLE_DEVICES 与 mx-smi 管理设备。源码层面，MinerU 通过 lmdeploy 后端映射、设备白名单校验和 cudnn 禁用三处 MACA 专属逻辑（见第 5 节所列文件）保证了两个推理引擎在 MACA 卡上的开箱可用。