MinerU 寒武纪（Cambricon MLU）加速卡部署指南：lmdeploy 与 vLLM 双推理引擎实战

本文基于 MinerU 官方加速卡适配文档（docs/zh/usage/acceleration_cards/Cambricon.md），完整覆盖 MinerU 在寒武纪 MLU 加速卡上的 Docker 镜像构建、容器启动与运行参数配置。读完本文，你可以独立完成 lmdeploy / vLLM 两套 VLM 推理加速方案的部署，理解 MINERU_LMDEPLOY_DEVICE 等关键环境变量在源码中的作用，并依据兼容性矩阵选择适合你业务场景的运行模式。

1. 测试平台与适用前提

官方指南在如下平台上完成了测试，供部署环境对照参考：

os: Ubuntu 22.04.5 LTS
cpu: Hygon Hygon C86 7490
mlu: MLU590-M9D
driver: v6.2.11
docker: 28.3.0

需要注意的适用前提：

• 硬件要求为 amd64（x86-64）CPU + Cambricon MLU，这一点在构建镜像的 docker/china/mlu.Dockerfile 首行注释中已明确说明；
• 寒武纪加速卡支持使用 lmdeploy 或 vllm 进行 VLM 模型推理加速，两者按需二选一，不能混用同一镜像；
• 镜像内置模型，通过 MINERU_MODEL_SOURCE=local 使用本地模型，适合离线环境。

2. 使用 Dockerfile 构建镜像

仓库中对应的构建文件为 docker/china/mlu.Dockerfile，它默认基于 lmdeploy 基础镜像（lmdeploy_dlinfer/camb:mineru25），并通过 ARG BACKEND=lmdeploy 控制安装分支；文件中同时以注释形式提供了 vllm 基础镜像（vllm0.8.3-torch2.6.0-torchmlu1.26.1-ubuntu22.04-py310）。

2.1 构建 lmdeploy 版镜像

官方指南给出的标准流程：

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/mlu.Dockerfile
docker build --network=host -t mineru:mlu-lmdeploy-latest -f mlu.Dockerfile .

直接构建即可，默认 BACKEND=lmdeploy。从 Dockerfile 源码看，lmdeploy 分支会额外安装 qwen-vl-utils>=0.0.14,<1 与 accelerate==1.2.0，并固定 numpy==1.26.4、opencv-python==4.11.0.86，最后执行 mineru-models-download -s modelscope -m all 预下载全部模型，因此构建产物是“模型 + 环境”一体化的完整镜像。

2.2 构建 vllm 版镜像

构建 vllm 版本时，需要先切换 Dockerfile 中的基础镜像。官方指南采用 sed 一行完成：

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/mlu.Dockerfile
# 将基础镜像从 lmdeploy 切换为 vllm
sed -i -e '3,4s/^/# /' -e '6,7s/^# //' mlu.Dockerfile
docker build --network=host -t mineru:mlu-vllm-latest -f mlu.Dockerfile .

这条 sed 命令的作用与 docker/china/mlu.Dockerfile 的行结构精确对应：第 3~4 行是 lmdeploy 的 FROM 与 ARG BACKEND=lmdeploy（加注释屏蔽），第 6~7 行是 vllm 的 FROM 与 ARG BACKEND=vllm（取消注释启用）。切换后 vllm 分支会安装 transformers==4.50.3（而非 lmdeploy 分支的 qwen-vl-utils/accelerate），并且模型下载步骤会在 /torch/venv3/pytorch_infer 虚拟环境中执行。

3. 启动 Docker 容器

3.1 容器运行参数说明

docker run --name mineru_docker \
   --privileged \
   --ipc=host \
   --network=host \
   --shm-size=400g \
   --ulimit memlock=-1 \
   -v /dev:/dev \
   -v /lib/modules:/lib/modules:ro \
   -v /usr/bin/cnmon:/usr/bin/cnmon \
   -e MINERU_MODEL_SOURCE=local \
   -e MINERU_LMDEPLOY_DEVICE=camb \
   -it mineru:mlu-lmdeploy-latest \
   /bin/bash

各参数的含义：

参数	作用
--privileged + -v /dev:/dev	让容器访问宿主机 MLU 设备节点，是加速卡容器化的必要条件
-v /lib/modules:/lib/modules:ro	挂载内核模块目录（只读），供驱动加载
-v /usr/bin/cnmon:/usr/bin/cnmon	将寒武纪监控工具 cnmon 映射进容器，便于观察加速卡占用
--shm-size=400g、--ipc=host	放大共享内存，避免批量推理时共享内存不足
MINERU_MODEL_SOURCE=local	使用镜像内预下载模型，不在线下载（Dockerfile 的 ENTRYPOINT 也会默认导出该变量，双保险）
MINERU_LMDEPLOY_DEVICE=camb	声明 lmdeploy 推理目标设备为寒武纪，源码据此选择推理后端（见第 4 节）
-it ... /bin/bash	进入交互式终端，可直接执行 MinerU 命令；替换 /bin/bash 为服务启动命令则可直接拉起服务，参考 通过命令启动服务

3.2 切换到 vllm 镜像的虚拟环境

如果使用 vllm 版镜像，需要做两处替换/补充：

1. 将镜像名 mineru:mlu-lmdeploy-latest 替换为 mineru:mlu-vllm-latest；
2. 进入容器后激活 vllm 的虚拟环境：

source /torch/venv3/pytorch_infer/bin/activate

激活成功后命令行前会出现 (pytorch_infer) 标识，表示已进入 vllm 环境。这与 docker/china/mlu.Dockerfile 中 vllm 分支的安装逻辑一致：vllm 分支的 pip install 都先 source /torch/venv3/pytorch_infer/bin/activate，因此运行时也必须在该 venv 中操作。

4. 源码级解读：camb 设备在 MinerU 中的处理

从源码结构看，寒武纪设备标识 camb 在 MinerU 中贯穿 lmdeploy 与 vLLM 两条链路：

4.1 lmdeploy 链路：设备决定推理后端

在 mineru/model/vlm/lmdeploy_server.py 中，MINERU_LMDEPLOY_DEVICE 的合法取值为 cuda、ascend、maca、camb，不在此列表内会直接抛出 ValueError；在 mineru/backend/vlm/vlm_analyze.py 的 engine 后端中同样做了该取值校验。

设备到推理后端的映射逻辑在 mineru/backend/vlm/utils.py 的 set_lmdeploy_backend() 中：camb（以及 ascend、maca）统一使用 pytorch 后端，而非 turbomind。也就是说，只要设置了 MINERU_LMDEPLOY_DEVICE=camb，lmdeploy 会自动落在 PyTorch 后端上，无需手动指定 MINERU_LMDEPLOY_BACKEND。

4.2 vLLM 链路：MLU 设备识别与 v0 引擎适配

• mineru/backend/vlm/utils.py 的 enable_custom_logits_processors() 通过 torch.mlu.is_available() 识别寒武纪设备，并将其 compute capability 视为 8.0 参与 custom logits processor 的开关判断；
• 该函数还读取环境变量 VLLM_USE_V1（默认为 1），当其为 0 时禁用 custom logits processors，这正对应寒武纪平台采用 vLLM v0 引擎的适配需求（见下文注意事项）；
• vLLM server 启动入口 mineru/model/vlm/vllm_server.py 会补齐 --port、--gpu-memory-utilization 等默认参数（默认值逻辑见 mineru/backend/vlm/utils.py），再转交 vllm 原生 serve 流程。

5. 注意事项与兼容性矩阵

5.1 vLLM v0 引擎说明

官方文档明确：由于寒武纪目前对 vLLM v1 引擎的支持尚待完善，MinerU 现阶段采用 v0 引擎作为适配方案。受此限制，vLLM 的异步引擎（Async Engine）功能存在兼容性问题，可能导致部分使用场景无法正常运行；项目方会持续跟进寒武纪对 v1 引擎的支持并做相应适配。这也解释了源码中 VLLM_USE_V1 环境变量以及 Async Engine 在兼容性矩阵中的降级标记。

5.2 不同环境的兼容支持情况

官方给出的支持情况矩阵（🟢 稳定支持 / 🟡 支持但不稳定 / 🔴 不支持）如下：

使用场景	运行模式	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）	—	🟡	🟢

其中黄灯的已知问题在原文档中有明确注释：

• lmdeploy 黄灯：不能输入文件夹使用批量解析功能，输入单个文件时表现正常；
• vllm 黄灯：精度未完全对齐，在部分场景下可能出现预期外结果。

因此，在寒武纪平台上对稳定性要求较高的场景，lmdeploy 镜像整体覆盖度更好（除命令行 engine 批量场景外全为绿灯）；pipeline 模式两种引擎均稳定可用，是最稳妥的选择。

5.3 指定可用加速卡与资源监控

• 设备指定：Cambricon 加速卡指定可用卡的方式与 NVIDIA GPU 类似，做法是把 使用指定 GPU 设备 一节中的 CUDA_VISIBLE_DEVICES 环境变量替换为 MLU_VISIBLE_DEVICES 即可；
• 资源监控：在 Cambricon 平台可通过 cnmon 命令查看加速卡使用情况，并据此指定空闲的加速卡 ID 以避免资源冲突（容器参数中 -v /usr/bin/cnmon:/usr/bin/cnmon 即为把该工具映射进容器）。

6. 小结

在寒武纪 MLU 上部署 MinerU 的标准路径是：下载 mlu.Dockerfile → 按需构建 lmdeploy 或 vllm 镜像（vllm 需 sed 切换基础镜像）→ 以特权模式启动容器并设置 MINERU_LMDEPLOY_DEVICE=camb、MINERU_MODEL_SOURCE=local → 依据兼容性矩阵选择 pipeline / engine / http-client 运行模式。lmdeploy 链路由源码保证自动落到 pytorch 后端；vllm 链路因 v0 引擎适配，在精度与 Async Engine 上存在已知限制。相关实现可进一步查阅 docker/china/mlu.Dockerfile、mineru/backend/vlm/utils.py、mineru/model/vlm/lmdeploy_server.py 与 mineru/model/vlm/vllm_server.py。