MinerU 在昆仑芯（Kunlunxin）加速卡上的 vLLM 容器化部署：从镜像构建到全场景支持详解

本文基于 MinerU 官方加速卡适配文档，讲解如何在昆仑芯（Kunlunxin）XPU 平台上通过 Docker 构建并部署 MinerU 的 vLLM 推理环境。读完本文，你将了解 Kunlunxin 平台的测试环境前提、kxpu.Dockerfile 镜像的构建方式与内部细节、容器启动命令中各设备与参数配置的作用，以及 MINERU_VLLM_DEVICE=kxpu 在 MinerU 源码中触发的 vLLM 引擎适配逻辑，并掌握 XPU_VISIBLE_DEVICES、xpu-smi 等设备管理用法。

1. 测试平台与适用前提

官方文档在昆仑芯 P800 卡上完成了本指南的验证，测试平台信息如下，供环境选型参考：

os: Ubuntu 22.04.5 LTS
cpu: Intel x86-64
xpu: P800
driver: 515.58
docker: 20.10.5

需要注意的前提是：该方案面向 amd64（x86-64）CPU + 昆仑芯 XPU 的组合，底层依赖一个已内置 vLLM 昆仑芯推理环境的基础镜像；驱动版本（515.58）与 Docker 版本（20.10.5）为官方验证过的组合，其他版本可用但未经同等验证。

2. 环境准备：使用 kxpu.Dockerfile 构建镜像（vllm）

MinerU 仓库在 docker/china/kxpu.Dockerfile 中提供了专门的昆仑芯镜像定义文件。官方文档给出的标准构建流程是先获取该 Dockerfile，再在仓库根目录执行构建：

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

如果你在本地已克隆了 MinerU 仓库，也可以直接引用仓库内的文件路径构建，二者等价：

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

2.1 Dockerfile 内部做了什么

结合 kxpu.Dockerfile 源码，可以明确镜像构建的四个关键环节：

1. 基础镜像：基于 wjie520/vllm_kunlun:v0.10.1.1rc1，这是一个已包含 vLLM 昆仑芯推理环境（Python 3.10 虚拟环境 vllm_kunlun_0.10.1.1）的 amd64 镜像，这也是为什么宿主机必须为 x86-64 架构的原因。
2. 中文字体：安装 fonts-noto-core、fonts-noto-cjk 与 fontconfig 并重建字体缓存，保证 PDF 输出时中文渲染正常。
3. 安装 MinerU：通过阿里云 PyPI 镜像安装 mineru[gradio]>=3.4.0 及 ftfy、shapely、pyclipper、omegaconf 等依赖；随后用 sed 对 vllm_kunlun/models/qwen2_vl.py 的前 200 行做了一处修补——将 self.act = act_layer() 替换为 self.act = nn.GELU()，用于规避基础镜像中 Qwen2-VL 激活层的兼容性问题（从源码结构看，这是针对特定基础镜像版本的一次性补丁）。
4. 模型预置：执行 mineru-models-download -s modelscope -m all 从 ModelScope 下载全部模型，并把环境变量 MINERU_MODEL_SOURCE=local 写入 ENTRYPOINT。这解释了第 3 节容器启动时为什么不再重复下载模型——镜像内模型已就绪，运行时直接从本地加载。

3. 启动 Docker 容器

构建完成后，按官方文档执行以下命令启动容器：

docker run -u root --name mineru_docker \
    --device=/dev/xpu0:/dev/xpu0 \
    --device=/dev/xpu1:/dev/xpu1 \
    --device=/dev/xpu2:/dev/xpu2 \
    --device=/dev/xpu3:/dev/xpu3 \
    --device=/dev/xpu4:/dev/xpu4 \
    --device=/dev/xpu5:/dev/xpu5 \
    --device=/dev/xpu6:/dev/xpu6 \
    --device=/dev/xpu7:/dev/xpu7 \
    --device=/dev/xpuctrl:/dev/xpuctrl \
    --net=host \
    --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
    --tmpfs /dev/shm:rw,nosuid,nodev,exec,size=32g \
    --cap-add=SYS_PTRACE \
    -v /home/users/vllm-kunlun:/home/vllm-kunlun \
    -v /usr/local/bin/xpu-smi:/usr/local/bin/xpu-smi \
    -w /workspace \
    -e MINERU_MODEL_SOURCE=local \
    -e MINERU_FORMULA_CH_SUPPORT=true \
    -e MINERU_VLLM_DEVICE=kxpu \
    -it mineru:kxpu-vllm-latest \
    /bin/bash

关键参数说明：

参数	作用
--device=/dev/xpu0 ~ /dev/xpu7、/dev/xpuctrl	将 8 张昆仑芯 XPU 及控制设备节点透传进容器，这是 XPU 在容器内可见的前提
--net=host	使用宿主机网络，便于 --host 形式的服务端口直接对外暴露
--tmpfs /dev/shm:rw,nosuid,nodev,exec,size=32g	扩大共享内存至 32 GB，满足多进程推理（vLLM 使用 mp 后端）对共享内存的需求
-v /usr/local/bin/xpu-smi:/usr/local/bin/xpu-smi	把宿主机上的 xpu-smi 工具挂载进容器，方便在容器内查看加速卡占用情况
-v /home/users/vllm-kunlun:/home/vllm-kunlun	持久化挂载 vLLM 昆仑芯相关目录（可按需调整为宿主机上的实际路径）
-e MINERU_MODEL_SOURCE=local	告知 MinerU 使用本地模型，不触发在线下载（与镜像 ENTRYPOINT 中的设置一致）
-e MINERU_FORMULA_CH_SUPPORT=true	开启中文公式实验性支持
-e MINERU_VLLM_DEVICE=kxpu	声明设备类型为昆仑芯，触发 MinerU 的 vLLM 引擎适配逻辑，详见第 4 节
-it ... /bin/bash	进入交互式终端；替换为服务启动命令即可直接拉起服务

执行该命令后，您会进入 Docker 容器的交互式终端，可以直接在容器内运行 mineru 等命令使用 MinerU 的功能。您也可以直接将命令末尾的 /bin/bash 替换为服务启动命令（如 mineru-api --host 0.0.0.0 --port 8000、mineru-openai-server --port 30000、mineru-gradio）来启动 MinerU 服务，各服务的启动方式可参考 快速上手文档 中"通过命令启动服务"一节。

4. 源码解析：MINERU_VLLM_DEVICE=kxpu 触发了什么

MINERU_VLLM_DEVICE 是 MinerU 为不同加速设备提供的 vLLM 配置开关。在 mineru/backend/vlm/utils.py 中，_get_device_config() 维护了一张设备类型到 vLLM 参数的映射表，其中 kxpu 的配置为：

"kxpu": {
    "compilation_config_dict": {
        "splitting_ops": [
            "vllm.unified_attention", "vllm.unified_attention_with_output",
            "vllm.unified_attention_with_output_kunlun", "vllm.mamba_mixer2",
            "vllm.mamba_mixer", "vllm.short_conv", "vllm.linear_attention",
            "vllm.plamo2_mamba_mixer", "vllm.gdn_attention", "vllm.sparse_attn_indexer"
        ]
    },
    "block_size": 128,
    "dtype": "float16",
    "distributed_executor_backend": "mp",
    "enable_chunked_prefill": False,
    "enable_prefix_caching": False,
},

这些参数针对昆仑芯平台做了专门调优：dtype=float16 表明推理精度选用 FP16；block_size=128 调整 KV Cache 分块大小；distributed_executor_backend=mp 采用多进程执行后端；enable_chunked_prefill 与 enable_prefix_caching 均关闭；splitting_ops 则列出编译时需要拆分处理的算子（含昆仑芯专属的 unified_attention_with_output_kunlun），规避图编译在 XPU 上的兼容性问题。

应用这些配置的入口是 mod_kwargs_by_device_type()（mineru/backend/vlm/utils.py），它读取环境变量 MINERU_VLLM_DEVICE 并按运行模式分发：

• server 模式：将配置项转换为 --block-size 128、--dtype float16、--no-enable-chunked-prefill、--no-enable-prefix-caching、--compilation-config ... 等 vLLM 命令行参数。调用点见 mineru/model/vlm/vllm_server.py，即 mineru-openai-server --engine vllm 这类直接拉起 vLLM server 的场景。
• sync_engine / async_engine 模式：将配置写入引擎 kwargs，并把 compilation_config_dict 构造为 vLLM 的 CompilationConfig 对象。调用点见 mineru/backend/vlm/vlm_analyze.py，对应 mineru 命令行工具和 mineru-api 服务中使用 <vlm/hybrid>-engine 的场景。

函数内部均采用"参数不存在才补默认值"的策略（_add_server_arg_if_missing / _add_engine_kwarg_if_missing），因此用户显式传入的 vLLM 参数始终优先于设备默认配置，这一点与官方文档中"所有 vLLM/lmdeploy 官方支持的参数都可以通过命令行参数传递给 MinerU"（见 命令行进阶参数）的说明一致。

5. Kunlunxin 平台上的支持情况

不同使用场景下，MinerU 对昆仑芯加速卡的支持情况如下（官方验证结果）：

使用场景	引擎	支持状态
命令行工具（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 基本一致；🟡 支持但较不稳定，某些场景可能出现异常或精度存在一定差异；🔴 不支持，无法运行或精度存在较大差异。

也就是说，在昆仑芯平台上，从本地命令行解析、到 FastAPI 服务化部署、再到 Gradio 界面与 OpenAI 兼容服务，全部组合均已验证可用。

6. 注意事项：指定 XPU 设备与查看占用

官方文档给出两条运维要点：

1. 指定可用加速卡的方式与 NVIDIA GPU 类似。在 高级 CLI 参数文档 的 CUDA_VISIBLE_DEVICES 章节中介绍的"在命令前加环境变量指定可见设备"用法，在昆仑芯平台上只需将环境变量 CUDA_VISIBLE_DEVICES 替换为 XPU_VISIBLE_DEVICES，例如：

   XPU_VISIBLE_DEVICES=1 mineru -p <input_path> -o <output_path>
   

2. 使用 xpu-smi 查看加速卡使用情况。该命令即为第 3 节容器启动时挂载进容器的宿主机工具，可用于检查各张 XPU 的占用，从而指定空闲的加速卡 ID，避免多服务、多任务之间的资源冲突。

7. 小结

在昆仑芯平台上部署 MinerU 的路径是清晰的：以内置 vLLM 昆仑芯环境的 amd64 基础镜像为底座，用 docker/china/kxpu.Dockerfile 构建出预装模型与 MinerU 的镜像；启动时透传 /dev/xpu* 设备、挂载 xpu-smi、并通过 MINERU_MODEL_SOURCE=local、MINERU_FORMULA_CH_SUPPORT=true、MINERU_VLLM_DEVICE=kxpu 三个环境变量分别锁定本地模型、中文公式支持与设备适配配置。源码层面，MINERU_VLLM_DEVICE=kxpu 会在 mineru/backend/vlm/utils.py 中命中专属的 vLLM 参数集（FP16、block_size 128、mp 后端、关闭 chunked prefill 与 prefix caching、自定义 splitting_ops），并自动注入到 server 与引擎两种运行模式。按此配置，命令行工具、FastAPI 服务、Gradio 界面与 OpenAI 兼容服务均可在昆仑芯上稳定运行。