MinerU 摩尔线程（MooreThreads）MUSA 加速卡部署指南：Docker 镜像构建、关键环境变量与 vLLM 引擎适配

本文基于 MinerU 仓库中 docs/zh/usage/acceleration_cards/MooreThreads.md 整理并扩充，面向希望在摩尔线程 MTT S4000（MUSA）加速卡上部署 MinerU 的读者。文章完整覆盖官方指南给出的镜像构建与容器启动流程，并结合 docker/china/musa.Dockerfile 及 mineru/utils、mineru/backend/vlm 等源码，深入讲解 MINERU_VLLM_DEVICE、MINERU_MODEL_SOURCE 等环境变量的作用机制、musa 设备的自动探测链路，以及 vLLM v0/v1 引擎在摩尔线程平台上的兼容边界，帮助读者完成从构建镜像到稳定运行 pipeline / VLM 全链路的部署。

1. 适用环境与测试平台

该指南以摩尔线程 MTT S4000 加速卡为验证平台，官方指南中记录的测试环境如下，部署前建议先核对自己机器的对应项：

os: Ubuntu 22.04.4 LTS
cpu: Intel x86-64
dcu: MTT S4000
driver: 3.0.0-rc-KuaE2.0
docker: 24.0.7

从源码结构看，MinerU 将摩尔线程的运行时抽象为 musa 设备类型，其前提是环境中安装了对应的 MUSA 工具链（即 PyTorch 提供 torch.musa 后端）。仓库中所有加速卡适配逻辑均围绕该设备名展开，因此本文中的"musa 设备"指的就是通过 torch.musa 可探测到的摩尔线程加速卡。

2. 基于 musa.Dockerfile 构建镜像

MinerU 在 docker/china/musa.Dockerfile 中提供了针对摩尔线程平台的官方镜像定义文件。该文件要求 amd64（x86-64）CPU 加摩尔线程 GPU 的运行环境，关键内容如下：

# Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU + MooreThreads GPU.
FROM registry.mthreads.com/mcconline/vllm-musa-qy2-py310:v0.8.4-release

• 基础镜像：registry.mthreads.com/mcconline/vllm-musa-qy2-py310:v0.8.4-release，这是一个基于 vLLM v0.8.4（即 v0 引擎系列）的 MUSA 推理环境镜像。这也正是官方指南"注意事项"中提到"MinerU 现阶段采用 v0 引擎作为适配方案"的镜像层依据。
• 系统依赖：安装 fonts-noto-core、fonts-noto-cjk、fontconfig、libgl1 等，用于 OpenCV 的中文字体渲染与 PDF 版面元素输出。
• MinerU 安装：通过 pip 安装 mineru[gradio]>=3.4.0 及配套依赖（ftfy、shapely、pyclipper、omegaconf、固定版本 numpy==1.26.4 与 opencv-python==4.11.0.86）。
• 模型预置：RUN /bin/bash -c "mineru-models-download -s modelscope -m all"，在构建阶段即通过 ModelScope 下载全部模型到镜像内，避免容器启动后重复拉取。
• 入口行为：

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

ENTRYPOINT 会默认导出 MINERU_MODEL_SOURCE=local，让 MinerU 使用镜像内已下载的本地模型，而不是在线拉取。

构建命令（在包含 Dockerfile 的构建上下文目录中执行）：

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

其中 --network=host 用于保证构建阶段可访问模型下载源；镜像名 mineru:musa-vllm-latest 可按需替换。

3. 启动 Docker 容器与关键环境变量

官方指南给出的完整启动命令如下：

docker run -u root --name mineru_docker \
    --network=host \
    --ipc=host \
    --shm-size=80g \
    --privileged \
    -e MTHREADS_VISIBLE_DEVICES=all \
    -e MINERU_VLLM_DEVICE=musa \
    -e MINERU_MODEL_SOURCE=local \
    -it mineru:musa-vllm-latest \
    /bin/bash

执行该命令后会进入容器的交互式终端，可直接在容器内运行 MinerU 相关命令；也可以把结尾的 /bin/bash 替换为服务启动命令，直接拉起 MinerU 服务（API/WebUI/HTTP 客户端/Server 等启动方式可参考 docs/zh/usage/quick_usage.md 与 docs/zh/usage/cli_tools.md）。

各参数的作用说明：

参数 / 环境变量	作用
--network=host	容器与宿主机共享网络栈，便于 MUSA 运行时与后续服务端口直接访问
--ipc=host、--shm-size=80g	扩大共享内存，满足 vLLM 多进程（如 mp executor）的通信需求
--privileged	授予容器对 MUSA 设备的完整访问权限
MTHREADS_VISIBLE_DEVICES=all	控制容器可见的摩尔线程加速卡数量，指定方式与 NVIDIA GPU 类似，可参考摩尔线程官方文档的 GPU 枚举说明
MINERU_VLLM_DEVICE=musa	告知 MinerU 当前 vLLM 运行于摩尔线程设备，驱动设备级 vLLM 参数适配逻辑（详见第 5 节）
MINERU_MODEL_SOURCE=local	使用镜像内预置的本地模型，与 Dockerfile 的 ENTRYPOINT 行为一致，双重保证离线可用

3.1 MINERU_VLLM_DEVICE 在源码中的消费链路

MINERU_VLLM_DEVICE 并非普通提示性变量，它会被 mineru/backend/vlm/utils.py 中的 mod_kwargs_by_device_type() 实际读取：

• 在 mineru/backend/vlm/utils.py 中，mod_kwargs_by_device_type(kwargs_or_args, vllm_mode) 从环境变量 MINERU_VLLM_DEVICE 取出设备类型，再经 _get_device_config() 查询设备专属的 vLLM 配置（如 compilation_config、block_size 等），最后根据运行模式（server / sync_engine / async_engine）把配置注入到 vLLM 的启动参数或 kwargs 中。
• 在 server 模式（mineru-openai-server 等）下，mineru/model/vlm/vllm_server.py 会调用 mod_kwargs_by_device_type(args, vllm_mode="server")；在引擎模式下，mineru/backend/vlm/vlm_analyze.py 分别在 sync_engine 与 async_engine 两条路径上应用同样的适配。
• 值得注意的是，_get_device_config() 的 DEVICE_CONFIGS 字典中 musa 的配置条目当前处于注释状态（mineru/backend/vlm/utils.py），即历史上曾试验过 cudagraph_capture_sizes、simple_cuda_graph、block_size: 32 等编译优化，目前对 musa 不额外注入任何 vLLM 参数。因此对摩尔线程平台而言，MINERU_VLLM_DEVICE=musa 更多是设备识别与预留适配入口的作用，实际生效的默认参数来自基础镜像的 vLLM v0.8.4。

3.2 MINERU_MODEL_SOURCE 与 ENTRYPOINT 的关系

Dockerfile 的 ENTRYPOINT 已经默认 export MINERU_MODEL_SOURCE=local，容器启动命令中再次显式声明，属于双保险配置：即使未来修改 ENTRYPOINT 或改用自定义入口脚本，模型来源仍然锁定为本地镜像预置模型。

4. MinerU 如何识别 musa 设备：源码级探测链路

MinerU 的设备识别、显存读取与显存回收三处均对 musa 做了原生支持，部署排障时可对照以下链路：

1. 设备类型探测：mineru/utils/config_reader.py 中的 get_device() 先检查环境变量 MINERU_DEVICE_MODE（显式指定时优先级最高），否则按 cuda → mps → npu → gcu → musa → mlu → sdaa 的顺序逐级探测，最终兜底为 cpu。其中 musa 分支通过 torch.musa.is_available() 判断，返回字符串 "musa"。
2. 显存容量读取：mineru/utils/model_utils.py 的 get_vram() 对 musa 设备调用 torch.musa.get_device_properties(device).total_memory 换算为 GB；该值会进一步影响 mineru/backend/vlm/utils.py 中 vLLM 的默认显存利用率（set_default_gpu_memory_utilization）与批量大小（set_default_batch_size：显存 ≥16GB 取 8，≥8GB 取 4，否则 1）。此外还可用环境变量 MINERU_VIRTUAL_VRAM_SIZE 覆盖自动探测结果。
3. 显存回收：mineru/utils/model_utils.py 的 clean_memory() 对 musa 设备调用 torch.musa.empty_cache()，配合 clean_vram() 在显存低于阈值（默认 8GB）时主动释放，缓解长时批处理中的显存碎片问题。
4. 编译特性开关：mineru/backend/vlm/utils.py 的 enable_custom_logits_processors() 将 musa 设备的 compute capability 视为 8.0，与 npu、gcu 等国产卡同一档处理，用于决定 vLLM 的 custom_logits_processors 是否启用。

5. vLLM 引擎适配说明：为什么采用 v0 引擎

官方指南"注意事项"中有一条关键兼容性说明：由于摩尔线程目前对 vLLM v1 引擎的支持尚待完善，MinerU 现阶段采用 v0 引擎作为适配方案；受此限制，vLLM 的异步引擎（Async Engine）功能存在兼容性问题，可能导致部分使用场景无法正常运行。这与镜像选型一致——基础镜像 vllm-musa-qy2-py310:v0.8.4-release 本身就是 v0.8.4（v0 引擎系列）。

在源码层面，相关约束体现在两处：

• VLLM_USE_V1 环境变量：mineru/backend/vlm/utils.py 中 enable_custom_logits_processors() 会读取 VLLM_USE_V1（默认 "1"），当显式设为 0 时直接禁用 custom logits processors。在摩尔线程平台上，若观察到 v1 引擎相关问题，可通过该开关回退行为并观察日志。
• 引擎模式的分支：vlm_analyze.py 中同步引擎（sync_engine）与异步引擎（async_engine）是两条独立路径，异步引擎路径依赖 vLLM v1 的异步能力，这正是兼容性表格中 fastapi / gradio 服务下 <vlm/hybrid>-engine 模式不可用的根源（详见下节）。

6. 各使用场景的兼容性矩阵

不同环境下，MinerU 对摩尔线程加速卡的支持情况如下（来自官方指南，🟢=支持且运行较稳定、精度与 NVIDIA GPU 基本一致；🟡=支持但较不稳定，某些场景可能异常或精度存在差异；🔴=不支持，无法运行或精度差异较大）：

使用场景	后端模式	容器环境（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）	vllm	🟢

从表格可以得出两条实操结论：

1. 命令行（mineru）是最完整的入口：pipeline、engine、http-client 三种后端均可用。
2. 服务化部署优先选择 http-client 模式：在 fastapi 与 gradio 服务中，进程内 <vlm/hybrid>-engine 因依赖 vLLM 异步引擎而被标记为不可用；改为让服务进程通过 http-client 访问一个独立的 vLLM 推理端点（例如 mineru-openai-server 或独立 vllm 服务），即可绕开异步引擎限制，这也是"服务 + 外部推理节点"的典型拓扑。

7. 日常运维与设备管理提示

• 指定可见加速卡：摩尔线程加速卡枚举方式与 NVIDIA GPU 类似，可在容器参数中通过 MTHREADS_VISIBLE_DEVICES 指定，例如只暴露编号 0、1 的卡：-e MTHREADS_VISIBLE_DEVICES=0,1；不指定时默认为 all。
• 查看加速卡占用：在宿主机上执行 mthreads-gmi 命令可查看各加速卡的显存占用与使用状态，部署前据此挑选空闲的加速卡 ID，避免多容器/多任务间产生资源冲突。
• 显存不足的应急覆盖：若个别环境自动探测到的显存容量不符合预期，可通过环境变量 MINERU_VIRTUAL_VRAM_SIZE（单位 GB）覆盖 get_vram() 的自动探测结果（见 mineru/utils/model_utils.py）。
• 强制指定设备：若自动探测顺序导致设备识别不符合预期，可设置 MINERU_DEVICE_MODE=musa 直接指定设备类型（见 mineru/utils/config_reader.py）。

8. 小结

在摩尔线程 MTT S4000 上部署 MinerU 的路径是清晰的：使用 docker/china/musa.Dockerfile 构建基于 vLLM v0.8.4 MUSA 镜像的镜像（构建期即完成模型预置），通过 MTHREADS_VISIBLE_DEVICES、MINERU_VLLM_DEVICE=musa、MINERU_MODEL_SOURCE=local 三个环境变量打通设备可见性与模型来源，再依据兼容性矩阵选择后端模式——命令行全模式可用，服务化场景推荐 <vlm/hybrid>-http-client 配合独立推理端点。源码层面，MinerU 已在设备探测（torch.musa）、显存读取与回收、compute capability 判档等环节原生支持 musa 设备，为后续跟进摩尔线程 vLLM v1 引擎的进展预留了 MINERU_VLLM_DEVICE 适配入口，可持续关注 mineru/backend/vlm/utils.py 中 DEVICE_CONFIGS 的变化。