MinerU 在 IluvatarCorex 加速卡上的 vLLM Docker 部署与源码级适配详解

2026-09-05 14:11:34作者：宣聪麟

本文以官方指南 docs/zh/usage/acceleration_cards/IluvatarCorex.md 为主体，完整覆盖 MinerU 在天数智芯（IluvatarCorex）加速卡上的测试环境、Docker 镜像构建、容器启动全流程，并结合仓库源码深入剖析 MINERU_VLLM_DEVICE=corex 这一环境变量背后 vLLM 编译参数注入、OCR 批量检测降级等关键适配逻辑。读完后你可以独立完成 Iluvatar BI-V150 环境下 MinerU 镜像的构建与部署，理解各启动参数的含义，并掌握显存释放、多卡指定等运维要点。

1. 测试平台与适用前提

官方指南给出的验证环境如下，部署前请确认你的平台与之对齐（尤其是 CPU 架构必须为 amd64/x86-64，基础镜像仅提供了该架构）：

项目	取值
操作系统	Ubuntu 22.04.5 LTS
CPU	Intel x86-64
加速卡	Iluvatar BI-V150
驱动	4.4.0
Docker	28.1.1

镜像的软件栈版本可以从 docker/china/corex.Dockerfile 中确认，基础镜像标签为 4.4.0_torch2.7.1_vllm0.11.2_py3.10，即驱动 4.4.0、PyTorch 2.7.1、vLLM 0.11.2、Python 3.10：

# Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU + iluvatar GPU.
FROM crpi-vofi3w62lkohhxsp.cn-shanghai.personal.cr.aliyuncs.com/opendatalab-mineru/corex:4.4.0_torch2.7.1_vllm0.11.2_py3.10

2. 构建 mineru:corex Docker 镜像

构建入口是仓库内的 corex.Dockerfile。完整构建命令为（在仓库根目录下执行，或直接使用已下载的该文件）：

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

该 Dockerfile 仅五步，每一步都有明确职责，值得逐条理解：

基础镜像：已内置完整的 vLLM 推理环境（见上文版本组合），因此后续无需再安装 PyTorch/vLLM，避免国产卡编译环境被破坏；
中文字体：安装 fonts-noto-core、fonts-noto-cjk、fontconfig 并执行 fc-cache -fv，用于渲染文档中的中文字形，防止 PDF/图片输出乱码；
安装 MinerU：通过阿里云 PyPI 镜像安装 mineru[core]>=3.4.0，并钉死 numpy==1.26.4、opencv-python==4.11.0.86，保证与基础镜像中 PyTorch 2.7.1 的二进制兼容；
预下载模型：mineru-models-download -s modelscope -m all 在构建期即拉取全部模型，配合运行期的 MINERU_MODEL_SOURCE=local 使容器离线可用；
入口点：

ENTRYPOINT ["/bin/bash", "-c", "export MINERU_MODEL_SOURCE=local && exec \"$@\"", "--"]

ENTRYPOINT 会强制注入 MINERU_MODEL_SOURCE=local，确保模型一律从本地加载，再 exec 外部传入的命令（如 /bin/bash 或服务启动命令），因此第 3 节中的 -e MINERU_MODEL_SOURCE=local 是双保险。

3. 启动 Docker 容器并接入加速卡

以下是官方指南给出的完整启动命令，参数较多，逐项说明如下：

docker run --name mineru_docker \
   -v /usr/src:/usr/src \
   -v /lib/modules:/lib/modules \
   -v /dev:/dev \
   --privileged \
   --cap-add=ALL \
   --pid=host \
   --group-add video \
   --network=host \
   --shm-size '400gb' \
   --ulimit memlock=-1 \
   --security-opt seccomp=unconfined \
   --security-opt apparmor=unconfined \
   -e VLLM_ENFORCE_CUDA_GRAPH=1 \
   -e MINERU_MODEL_SOURCE=local \
   -e MINERU_VLLM_DEVICE=corex \
   -it mineru:corex-vllm-latest \
   /bin/bash

参数分组解读：

设备直通：-v /dev:/dev、--privileged、--cap-add=ALL、--pid=host、--group-add video、--security-opt seccomp=unconfined、--security-opt apparmor=unconfined 一整套配置用于让容器直接访问宿主机上的 Iluvatar 加速卡设备节点（Iluvatar 的驱动运行方式与 NVIDIA 的 nvidia-container-toolkit 类似，依赖设备文件直通而非专用 runtime）；
共享挂载：-v /usr/src:/usr/src 与 -v /lib/modules:/lib/modules 便于容器内加载/匹配宿主机内核模块；
网络与共享内存：--network=host 使 vLLM 服务端口直接暴露于宿主机；--shm-size '400gb' 为数据并行/批量推理提供充足的共享内存；--ulimit memlock=-1 解除锁页内存限制，是 GPU 类设备通信的常见要求；
三个关键环境变量：
- MINERU_VLLM_DEVICE=corex：告诉 MinerU 当前是天数智芯设备，触发源码中的设备专属适配（见第 4 节）；
- MINERU_MODEL_SOURCE=local：模型只从本地目录加载，不在线下载；
- VLLM_ENFORCE_CUDA_GRAPH=1：强制 vLLM 启用 CUDA Graph 加速解码，配合源码中为 corex 注入的 FULL_DECODE_ONLY 编译模式（见 4.1 节）。

执行该命令后进入容器交互式终端，可直接运行 mineru 等命令；也可以把结尾的 /bin/bash 替换为服务启动命令来直接拉起 API/WebUI/HTTP-Client 服务，具体启动方式参见通过命令启动服务。

4. 源码级剖析：MinerU 如何为 corex 设备做适配

MINERU_VLLM_DEVICE=corex 并不只是一个标记，MinerU 源码在多处基于该值做了差异化处理。

4.1 vLLM 推理引擎：按设备注入编译参数

设备配置的集中定义位于 mineru/backend/vlm/utils.py 的 _get_device_config 函数中。其中 corex 的专属配置为：

"corex": {
    "compilation_config_dict": {
        "cudagraph_mode": "FULL_DECODE_ONLY",
        "level": 0
    },
},

含义是：仅对解码（decode）阶段做完整的 CUDA Graph 捕获（FULL_DECODE_ONLY），并把编译优化级别降为 level: 0，这是针对国产卡算子编译稳定性的调优组合，与容器启动时设置的 VLLM_ENFORCE_CUDA_GRAPH=1 相呼应。

该配置通过 mod_kwargs_by_device_type（mineru/backend/vlm/utils.py#L175-L196）注入，函数首先读取环境变量：

device_type = os.getenv("MINERU_VLLM_DEVICE", "")
config = _get_device_config(device_type)
if config is None:
    return kwargs_or_args

即若未设置该环境变量，MinerU 不做任何设备特化，走 vLLM 默认路径——这正是必须显式 -e MINERU_VLLM_DEVICE=corex 的原因。按 vllm_mode 分三条注入路径：

server 模式（mineru-openai-server 等，见 mineru/model/vlm/vllm_server.py#L55）：把 compilation_config_dict 序列化为 JSON，以 --compilation-config 参数追加到 vLLM 命令行，其余键值按 block_size → block-size 的下划线转横线规则透传；
sync_engine 模式（mineru/backend/vlm/vlm_analyze.py#L124）：配置以 dict 形式直接塞入 vllm.LLM(**kwargs) 的 compilation_config；
async_engine 模式（mineru/backend/vlm/vlm_analyze.py#L151）：配置会被构造成 vllm.config.CompilationConfig 对象后传入 AsyncLLM.from_engine_args。

三条路径均使用 _add_server_arg_if_missing / _add_engine_kwarg_if_missing 这类“缺失才补”的工具函数，保证用户显式传入的参数优先级更高。

此外，vLLM server 端还有与卡显存挂钩的默认值逻辑（mineru/model/vlm/vllm_server.py#L45-L53）：未指定时默认端口 30000；gpu_memory_utilization 由 set_default_gpu_memory_utilization 计算——vLLM ≥ 0.11.0 且显存 ≤ 8 GB 时取 0.7，否则取 0.5（mineru/backend/vlm/utils.py#L83-L92）。BI-V150 显存大于 8 GB，因此实际默认值为 0.5。

4.2 pipeline/hybrid 模式：关闭 OCR 文本检测批量推理

除了 vLLM 路径，MinerU 的 pipeline 与 hybrid 后端也对 corex 做了针对性降级。在 mineru/backend/pipeline/model_init.py#L319-L330 中：

def ocr_det_batch_setting():
    import torch
    from packaging import version
    device_type = os.getenv("MINERU_LMDEPLOY_DEVICE", "")
    if device_type.lower() in ["corex"]:
        enable_ocr_det_batch = False
    else:
        if version.parse(torch.__version__) >= version.parse("2.8.0"):
            os.environ["TORCH_CUDNN_V8_API_DISABLED"] = "1"
        enable_ocr_det_batch = True
    return enable_ocr_det_batch

从源码结构看，在 corex 设备上 OCR 检测模型的批量推理（enable_ocr_det_batch）被关闭，其余平台才启用；mineru/backend/pipeline/pipeline_analyze.py 中的 batch_analyze 同样有对等的 corex 分支（mineru/backend/pipeline/pipeline_analyze.py#L371-L377），把 enable_ocr_det_batch=False 传给 BatchAnalyze。可以推断这是为保证国产卡上检测模型批处理稳定性所做的保守策略。

4.3 自动批大小等其他联动参数

vLLM 路径中若未显式指定 batch_size，set_default_batch_size 会按显存分档自动取值：≥16 GB 取 8，≥8 GB 取 4，否则取 1（mineru/backend/vlm/utils.py#L95-L111）。BI-V150 属于 ≥16 GB 档位，默认批大小为 8，一般无需干预。

5. 支持矩阵：各使用场景 × 推理引擎

官方指南按“使用场景 × 引擎”给出了完整的支持状态（容器环境下 vLLM 引擎列）：

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

6. 注意事项与运维建议

显存释放问题：目前 Iluvatar 方案使用 vLLM 作为推理引擎时，可能出现服务停止后显存无法正常释放的问题。若遇到该问题，请重启 Docker 容器以释放显存——这是官方指南中明确给出的处置方式，无需在宿主机上重启驱动或整机。
指定可用加速卡：Iluvatar 加速卡指定可用卡的方式与 NVIDIA GPU 类似，通过 CUDA_VISIBLE_DEVICES 类环境变量指定，详见 advanced_cli_parameters.md 中的“使用指定GPU设备”章节。
查看加速卡占用：在 Iluvatar 平台上可以用 ixsmi 命令查看加速卡的使用情况，部署多实例（如同时跑 pipeline 服务和 openai-server 服务）时，应先用 ixsmi 确认空闲卡 ID，再配合指定卡环境变量启动，避免资源冲突。

7. 小结

在 IluvatarCorex 平台上落地 MinerU 的关键路径可以概括为三步：用 docker/china/corex.Dockerfile 构建 mineru:corex-vllm-latest 镜像（内含 torch 2.7.1 + vLLM 0.11.2 + 全量本地模型）→ 以设备直通参数启动容器并设置 MINERU_VLLM_DEVICE=corex、MINERU_MODEL_SOURCE=local、VLLM_ENFORCE_CUDA_GRAPH=1 → 视需要替换入口命令启动 mineru/mineru-api/mineru-gradio/mineru-openai-server。源码层面，MINERU_VLLM_DEVICE=corex 会触发 mineru/backend/vlm/utils.py 中 FULL_DECODE_ONLY + level 0 的 vLLM 编译配置注入，以及 mineru/backend/pipeline/model_init.py 中 OCR 检测批量推理的关闭，这些是国产卡上稳定运行的隐性保障，也是排查 corex 环境异常时值得优先核对的两处逻辑。