MinerU 燧原 Enflame GCU 加速卡部署实战指南：从镜像构建到设备识别的完整链路

本篇基于 MinerU 仓库中的官方加速卡适配文档与配套源码，完整讲解 MinerU 在燧原 Enflame GCU 加速卡（以 S60 为例）上的部署方法：包括测试平台信息、GCU 专用 Docker 镜像的构建与容器启动、各入口（CLI / FastAPI / Gradio / OpenAI Server）的支持情况矩阵，以及 MinerU 底层如何识别 GCU 设备、管理显存与调度 vLLM 推理的源码级原理。读完本文，你可以直接在 Enflame 平台上复现 MinerU 的部署，并理解 TOPS_VISIBLE_DEVICES、efsmi 等关键操作背后的实现机制。

1. 测试平台与硬件环境

官方适配指南给出的测试平台信息如下，可作为环境基线参考（来源：docs/zh/usage/acceleration_cards/Enflame.md）：

os: Ubuntu 22.04.4 LTS
cpu: Intel x86-64
gcu: Enflame S60
driver: 1.7.0.9
docker: 28.0.1

几点适用前提需要说明：

• 该环境组合是官方验证过的参考配置。其他驱动版本（TopsRider）或 CUDA 兼容模式下，镜像内预装的 PyTorch/vLLM 版本可能与驱动不完全匹配，建议以官方基础镜像版本为锚点；
• CPU 平台限定为 amd64（x86-64）。这一点在 Dockerfile 中有明确注释：Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU + Enflame GCU，即非 x86-64 平台不适用该镜像；
• 驱动版本 1.7.0.9 与镜像内 TopsRider 运行时共同决定 torch.gcu 是否可用，后文会结合源码说明 MinerU 是如何做这一探测的。

2. 使用 Dockerfile 构建 GCU 专用镜像

官方提供两条路径构建镜像。其一，通过 wget 从仓库拉取 Dockerfile 后本地构建（官方指南命令）：

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

其二，直接使用仓库内维护的 docker/china/gcu.Dockerfile 构建。下面逐段解析该 Dockerfile，它同时揭示了镜像的技术栈构成：

基础镜像：

# Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU + Enflame GCU.
FROM crpi-vofi3w62lkohhxsp.cn-shanghai.personal.cr.aliyuncs.com/opendatalab-mineru/gcu:docker_images_topsrider_i3x_3.6.20260106_vllm0.11_pytorch2.8.0

从镜像 tag 可以读出完整的软件栈版本信息：TopsRider i3x 3.6（燧原 GCU 运行时）+ vLLM 0.11 + PyTorch 2.8.0。这意味着 vlm/hybrid 后端的 vLLM 推理能力是在这个基础镜像中预置的，构建过程不需要也不适合自行改装 vLLM 的 GCU 适配层。

中文字体安装：镜像通过阿里云源安装了 fonts-noto-core、fonts-noto-cjk 与 fontconfig，并执行 fc-cache -fv。这是因为 MinerU 的可视化输出与 PDF 渲染依赖系统字体，缺失 CJK 字体会导致中文乱码或缺字。

安装 MinerU：

RUN python3 -m pip install "mineru[core]>=3.4.0" \
                            numpy==1.26.4 \
                            opencv-python==4.11.0.86 \
                            -i https://mirrors.aliyun.com/pypi/simple && \
    python3 -m pip cache purge

安装 mineru[core] extra 版本并锁定了 numpy 与 opencv 版本（与基础镜像中 TopsRider/PyTorch 编译依赖保持兼容），构建时使用国内 PyPI 镜像加速。

模型预下载与入口：

RUN /bin/bash -c "mineru-models-download -s modelscope -m all"

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

镜像构建时即通过 mineru-models-download -s modelscope -m all 下载了全部模型权重，而 ENTRYPOINT 自动导出 MINERU_MODEL_SOURCE=local，使容器默认走本地模型目录而非在线下载——这与后文容器启动命令中 -e MINERU_MODEL_SOURCE=local 是双重保险，确保离线环境也能直接推理。

3. 启动 Docker 容器

进入容器交互式终端的命令如下：

docker run -u root --name mineru_docker \
    --network=host \
    --ipc=host \
    --privileged \
    -e MINERU_MODEL_SOURCE=local \
    -it mineru:gcu-vllm-latest \
    /bin/bash

各参数作用说明：

参数	作用
-u root	以 root 身份运行，便于容器内管理权限与设备访问
--network=host	共享宿主机网络栈，vLLM 等服务端口直接暴露于宿主机
--ipc=host	共享宿主机 IPC 命名空间，PyTorch 多进程/多卡数据共享需要较大的共享内存，该参数可规避默认 IPC 限制
--privileged	放开设备权限，GCU 加速卡的设备节点访问通常依赖该方式直通
-e MINERU_MODEL_SOURCE=local	明确告知 MinerU 使用本地已下载的模型目录

执行命令后即可在容器内直接运行 MinerU 相关命令。如果需要以常驻服务方式启动而非交互式终端，官方指南建议直接替换末尾的 /bin/bash 为服务启动命令（如 mineru-api、mineru-gradio 等入口），各入口的具体命令与参数可参考 通过命令启动服务 一节。

4. 使用场景支持矩阵

不同入口与后端的组合下，MinerU 对 Enflame GCU 的支持情况如下（容器环境均为 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 基本一致；
• 🟡 支持但较不稳定，某些场景可能出现异常或精度差异；
• 🔴 不支持，无法运行或精度差异较大。

当前 Enflame GCU 在 vllm 容器环境下全场景 🟢。结合 README 中对国产芯片适配列表（Ascend · Cambricon · Enflame · MetaX · Moore Threads · Kunlunxin · Iluvatar · Hygon · Biren · T-Head）的说明，以及 changelog 中“Added support for the Hygon, Enflame, and Moore Threads domestic computing platforms”的记录，可以确认 GCU 适配是 MinerU 官方持续维护的一等公民路径，而非实验性支持。

5. 源码解析：MinerU 如何识别并适配 GCU 设备

GCU 支持并非靠外部包装脚本，而是内建于 MinerU 的设备抽象层。以下从源码结构看关键实现链路（均位于 mineru/utils/config_reader.py 与 mineru/utils/model_utils.py）。

5.1 设备发现：get_device 的探测顺序

get_device() 首先读取环境变量 MINERU_DEVICE_MODE，若显式设置则直接返回；否则按以下顺序探测硬件：

1. torch.cuda.is_available() → 返回 "cuda"；
2. torch.backends.mps.is_available() → 返回 "mps"；
3. torch_npu.npu.is_available() → 返回 "npu"；
4. torch.gcu.is_available() → 返回 "gcu"；
5. 依次尝试 torch.musa、torch.mlu、torch.sdaa；
6. 全部不可用则回退 "cpu"。

这说明在 GCU 机器上，只要 TopsRider 提供的 PyTorch 补丁使 torch.gcu 可用且优先级位于 CUDA/NPU 之后，MinerU 无需任何额外配置即可自动落到 GCU 后端；同时任何阶段都可用 MINERU_DEVICE_MODE=gcu 强制指定，便于排障或资源隔离场景。

5.2 显存管理：clean_memory 与 get_vram 对 gcu 分支的支持

get_vram() 与 clean_memory() 对 gcu 前缀设备有专门分支：

elif str(device).startswith("gcu"):
    if torch.gcu.is_available():
        total_memory = round(torch.gcu.get_device_properties(device).total_memory / (1024 ** 3))  # 转为 GB

elif str(device).startswith("gcu"):
    if torch.gcu.is_available():
        torch.gcu.empty_cache()

• get_vram 通过 torch.gcu.get_device_properties(device).total_memory 读取加速卡显存总量（GB），该值驱动 MinerU 的 clean_vram 逻辑——当显存小于阈值（默认 8GB）时自动触发垃圾回收。若自动探测不可靠，还可用环境变量 MINERU_VIRTUAL_VRAM_SIZE 覆盖（见 get_vram 实现）；
• clean_memory 调用 torch.gcu.empty_cache() 释放缓存块，行为与 CUDA 路径对称，保证 pipeline 逐页推理时显存可回收。

5.3 vLLM 推理路径：GCU 按 Compute Capability 8.0 处理

MinerU 的 vlm/hybrid 后端在 vLLM 推理时需要判断是否启用 custom logits processors。enable_custom_logits_processors() 中的设备分支如下：

elif hasattr(torch, 'gcu') and torch.gcu.is_available():
    compute_capability = "8.0"

即源码结构上，GCU 与 NPU/MUSA/MLU/SDAA 一样被统一按 Compute Capability 8.0 对待：在 vLLM ≥ 0.10.1 且 VLLM_USE_V1 不为 0 时启用自定义 logits 处理器。这与第 2 节基础镜像中预置的 vLLM 0.11 版本是配套的——版本条件与设备条件同时满足时，vlm/hybrid-engine 场景才能稳定达到与 Nvidia GPU 一致的精度表现。

6. 指定可用加速卡与查看卡状态

多卡机器上为 MinerU 指定可见加速卡的方式与 NVIDIA GPU 的 CUDA_VISIBLE_DEVICES 机制类似，官方指南给出的做法是：将环境变量 CUDA_VISIBLE_DEVICES 替换为 TOPS_VISIBLE_DEVICES 即可，例如在容器启动时追加 -e TOPS_VISIBLE_DEVICES=0。CUDA_VISIBLE_DEVICES 的基本用法与多卡指定细节可参考 高级 CLI 参数 中对应章节。

另外，在 Enflame 平台上可通过 efsmi 命令查看加速卡的实时使用情况（显存占用、利用率等），据此选择空闲卡 ID 再指定给 MinerU 容器，避免与同机其他任务产生资源冲突。

7. 小结与部署核对清单

在 Enflame GCU 上部署 MinerU 的关键路径可以归纳为：

1. 硬件/驱动：x86-64 + Enflame GCU（如 S60）+ 官方验证过的驱动（参考 1.7.0.9），Docker ≥ 28.x；
2. 镜像：使用 docker/china/gcu.Dockerfile 构建 mineru:gcu-vllm-latest，镜像内已含 TopsRider + vLLM 0.11 + PyTorch 2.8.0 + mineru[core] ≥ 3.4.0 + 全量模型；
3. 容器：--privileged + --ipc=host + --network=host + MINERU_MODEL_SOURCE=local，交互式使用或替换为 mineru-api/mineru-gradio/mineru-openai-server 服务命令；
4. 排障：确认 torch.gcu 可用（MinerU 的 get_device() 依赖它自动识别设备），必要时用 MINERU_DEVICE_MODE=gcu 强制指定、TOPS_VISIBLE_DEVICES 绑定卡、efsmi 检查卡状态；
5. 后端选择：pipeline 与 vlm/hybrid 的 engine、http-client 模式在 vllm 容器下均已获 🟢 支持，可按精度/延迟需求自由选择。

以上流程全部基于当前仓库文档与源码可验证的行为，适用前提是使用仓库官方提供的 GCU 基础镜像；若自行更换 vLLM 或 PyTorch 版本，需重新核对 enable_custom_logits_processors() 中的版本分支条件。