MinerU 在瀚博 VastAI 加速卡上的部署与使用：vLLM 后端 VLM 推理实战指南

本文围绕 MinerU 官方加速卡适配指南中的瀚博（VastAI）章节展开，讲解如何在 VastAI 加速卡环境上，基于 vllm_vacc 基础镜像完成 MinerU 的安装与运行，覆盖 vlm-engine 与 vlm-http-client 两种 VLM 推理模式的完整命令、关键启动参数（--enforce_eager、--tensor-parallel-size 等）的来源与传递机制，以及各解析后端的支持情况。读完本文，你可以按步骤在 VastAI 平台上搭建一套可用的 MinerU 文档解析环境，并理解哪些后端可选、哪些必须避开。

1. 适用场景与支持边界

VastAI（瀚博半导体）加速卡对 MinerU 的支持有明确边界：仅支持 vlm-engine 和 vlm-http-client 两种 VLM 推理加速形式，pipeline、hybrid-engine、hybrid-http-client 等后端均不可用。这一点直接决定了在 VastAI 平台上只能走 VLM（视觉语言模型）解析路线。

官方文档给出的完整支持矩阵如下（转写自 VastAI.md）：

使用场景	解析后端	支持情况
命令行工具（mineru）	pipeline	🔴
命令行工具（mineru）	hybrid-http-client	🔴
命令行工具（mineru）	hybrid-engine	🔴
命令行工具（mineru）	vlm-engine	🟢
命令行工具（mineru）	vlm-http-client	🟢
FastAPI 服务（mineru-api）	pipeline	🔴
FastAPI 服务（mineru-api）	hybrid-http-client	🔴
FastAPI 服务（mineru-api）	hybrid-engine	🔴
FastAPI 服务（mineru-api）	vlm-engine	🟢
FastAPI 服务（mineru-api）	vlm-http-client	🟢
Gradio 界面（mineru-gradio）	pipeline / hybrid 系列	🔴
Gradio 界面（mineru-gradio）	vlm-engine / vlm-http-client	🟢
OpenAI Server 服务（mineru-openai-server）	—	🟢

图例说明：🟢 支持，运行较稳定，精度与 NVIDIA GPU 基本一致；🟡 支持但较不稳定，某些场景下可能出现异常或精度差异；🔴 不支持，无法运行或精度存在较大差异。此外，vlm-engine 模式下 VastAI 仅支持 vLLM 后端。

2. 参考测试平台

官方指南列出了测试所用的平台信息，可作为部署时的环境参照：

os: Ubuntu-22.04.3-LTS-x86_64
cpu: Hygon C86-4G
gpu: VA16 / VA1L / VA10L
torch: 2.8.0+cpu
torch-vacc: 1.3.3.777
vllm: 0.11.1.dev0+gb8b302cde.d20251030.cpu
vllm-vacc: 0.11.0.777
driver: 00.25.12.30 d3_3_v2_9_a3_1 a76bf37 20251230
docker: 28.1.1

可以看出，VastAI 路线的核心软件栈是瀚博自研的 torch-vacc 与 vllm-vacc（vLLM 的瀚博适配版本），而非标准 CUDA 版 PyTorch/vLLM。这意味着整套环境必须运行在官方提供的基础镜像之内，自行安装标准版 vLLM 是无法工作的。

3. 环境准备：基础镜像与容器

3.1 获取并启动 vllm_vacc 基础镜像

第一步是拉取 vllm_vacc 基础镜像并启动容器。该镜像内已包含 torch/vllm 等相关依赖，后续只需在其中安装 MinerU 即可：

sudo docker pull harbor.vastaitech.com/ai_deliver/vllm_vacc:VVI-25.12.SP2

启动容器时需要注意几个关键参数（与 VastAI.md 中的原始命令一致）：

sudo docker run -it \
    --privileged=true \
    --shm-size=256g \
    --name vllm_service \
    --ipc=host \
    --network=host \
    harbor.vastaitech.com/ai_deliver/vllm_vacc:VVI-25.12.SP2 bash

各参数含义：

• --privileged=true：赋予容器特权模式，是加速卡设备访问的常见前提；
• --shm-size=256g：官方文档特别强调"需指定适当的 --shm-size 虚拟内存"，多卡张量并行（--tensor-parallel-size 2）下进程间共享内存不足会导致 vLLM 启动失败或运行不稳定；
• --ipc=host：复用宿主机 IPC 命名空间，配合大共享内存使用；
• --network=host：使用宿主机网络，便于 vlm-http-client 模式通过 http://127.0.0.1:8090 直连本机 vLLM 服务。

3.2 指定可见计算卡

与 NVIDIA 硬件下使用 CUDA_VISIBLE_DEVICES 类似，在 VastAI 硬件上可以用 VACC_VISIBLE_DEVICES 环境变量指定可见计算卡 ID，例如在 docker run 或 docker exec 中追加：

-e VACC_VISIBLE_DEVICES=0,1,2,3

从源码结构看，MinerU 仓库内部对"可见设备环境变量"的分支只区分了 NPU（ASCEND_RT_VISIBLE_DEVICES）与其他设备（CUDA_VISIBLE_DEVICES），见 router.py 中的 get_local_device_visible_env_name。VACC_VISIBLE_DEVICES 是瀚博运行时/驱动层面的设备可见性控制机制，不在 MinerU 源码内做特殊处理，而是在容器启动阶段由厂商环境生效。

3.3 容器内安装 MinerU

进入容器后，可按官方安装流程（参见 README_zh-CN.md 的"安装 MinerU"一节）安装 MinerU。指南给出的两种方式是源码安装与 pip 安装：

# 进入容器
sudo docker exec -it vllm_service bash

# 可选 pypi 源
# https://mirrors.163.com/pypi/simple/
# https://mirrors.aliyun.com/pypi/simple/
# https://pypi.mirrors.ustc.edu.cn/simple/
# https://pypi.tuna.tsinghua.edu.cn/simple/
# https://mirror.baidu.com/pypi/simple

# 方式一：通过源码安装 MinerU
git clone https://github.com/opendatalab/MinerU.git
git checkout 8c4b3ef3a20b11ddac9903f25124d24ea82639b5
pip install -e .[core] -i https://mirrors.aliyun.com/pypi/simple

# 方式二：通过 pip 安装 MinerU
pip install -U "mineru[core]==2.7.0" -i https://mirrors.aliyun.com/pypi/simple

适用前提需要留意：指南注明，截至 2025/12/31，VastAI 已支持 MinerU 至最新版本 2.7.0（对应 master 分支提交 8c4b3ef3）。当前仓库版本已演进到 3.4.4（见 version.py），因此在 VastAI 平台上验证过的稳定版本是 2.7.0 及对应提交，直接使用更新版本时建议先自行验证。

4. 功能一：vlm-engine 一体化解析

vlm-engine 模式下，MinerU 在进程内直接拉起 vLLM 引擎完成 VLM 推理，一条命令即可完成解析。命令中需要模型准备（下载 MinerU2.5 VLM 模型，模型获取方式参见 model_source.md），并设置模型源：

export MINERU_MODEL_SOURCE=modelscope

# step1，以 vlm-engine 方式启动 MinerU 解析任务
mineru -p image.png \
-o ./output \
-b vlm-engine \
--http-timeout 1200 \
--tensor-parallel-size 2 \
--enforce_eager \
--trust-remote-code \
--max-model-len 16384

参数说明：

• -b vlm-engine：指定使用 VLM 后端、引擎进程内运行模式；
• --tensor-parallel-size 2：vLLM 张量并行度，跨 2 张加速卡切分模型，因此要求 VACC_VISIBLE_DEVICES 中至少有 2 张可见卡；
• --enforce_eager：必须追加。官方文档明确指出"注意在执行任意与 vllm 相关命令需追加 --enforce_eager 参数"，即在瀚博平台上关闭 CUDA Graph 类优化，改用 eager 执行，这是 VastAI 适配的硬性要求；
• --trust-remote-code：允许执行模型仓库中的自定义代码（MinerU2.5 模型为自定义实现，需要此项）；
• --max-model-len 16384：限制模型最大上下文长度，控制显存/计算卡内存占用；
• --http-timeout 1200：VLM 请求超时时间（秒）。

这些以 -- 开头的引擎参数为什么能被 MinerU 命令行接受？从源码看，MinerU 的 CLI 通过 cli_parser.py 中的 parse_unknown_args 把所有未显式声明的 --xxx 参数解析为键值对（自动把 - 归一化为 _），再经由 FastAPI 服务入口 fast_api.py 的 main() 中 arg_parse(ctx) 拆分为"服务配置"与"模型配置"两部分，最终透传给 vLLM 引擎初始化。因此 --tensor-parallel-size、--enforce_eager、--max-model-len 这类参数本质上是原样转发给 vLLM 的构造参数，这也解释了为什么不同加速卡平台的适配文档都只需给出"追加哪些 vLLM 参数"，而不需要修改 MinerU 本身。

5. 功能二：vlm-http-client 分离式部署

vlm-http-client 模式把 VLM 推理与解析流程解耦：先用 vLLM 独立启动一个 API Server，再由 MinerU 以 HTTP 客户端身份调用它。这种模式便于把 vLLM 服务长期驻留、多任务复用，也便于在 FastAPI 服务（mineru-api）场景下集中管理推理资源。

step 1：启动 vLLM API Server：

vllm serve /root/.cache/modelscope/hub/models/OpenDataLab/MinerU2.5-2509-1.2B \
--tensor-parallel-size 2 \
--trust-remote-code \
--enforce_eager \
--port 8090 \
--max-model-len 16384 \
--served-model-name MinerU2.5-2509-1.2B

step 2：以 vlm-http-client 方式启动 MinerU 解析任务：

mineru -p demo/pdfs/demo1.pdf \
-o ./output \
-b vlm-http-client \
-u http://127.0.0.1:8090 \
--http-timeout 1200

要点：

• vllm serve 指向本地已下载的 MinerU2.5-2509-1.2B 模型路径（示例中使用 modelscope 缓存目录），--served-model-name 指定对外服务名，--port 8090 指定监听端口；
• MinerU 侧通过 -u http://127.0.0.1:8090 指定服务端点，--http-timeout 1200 控制单次 VLM 请求的超时；
• 两种模式同样都必须携带 --enforce_eager；
• 由于容器使用 --network=host，127.0.0.1:8090 在容器内外均可直达，简化了服务发现。

需要强调的边界：pipeline 与 hybrid-* 后端在 VastAI 卡上均标记为 🔴 不可用，因为它们依赖通用 CUDA 生态下的检测/识别/表格模型，而非 vLLM-vacc 加速链路。如果你的工作流包含 pipeline 模型，需要另行评估适配情况，不能直接套用本指南。

6. 部署核对清单

结合官方文档与仓库实现，在 VastAI 平台上部署 MinerU 时可逐项核对：

1. 镜像：使用 harbor.vastaitech.com/ai_deliver/vllm_vacc:VVI-25.12.SP2，确认 torch-vacc/vllm-vacc 已在镜像内，不要手动覆盖为 CUDA 版依赖；
2. 容器：--privileged=true --shm-size=256g --ipc=host --network=host 均不可省略，--shm-size 需按卡数与并行度留足余量；
3. 设备：用 VACC_VISIBLE_DEVICES 控制可见卡，保证数量不少于 --tensor-parallel-size 取值；
4. 版本：MinerU 以 2.7.0（或提交 8c4b3ef3）为已验证版本，升级新版本前先做回归验证；
5. 后端：只使用 -b vlm-engine 或 -b vlm-http-client；
6. 参数：所有 vLLM 相关命令一律追加 --enforce_eager，并保留 --trust-remote-code 与 --max-model-len 16384（可按显存情况调整）。

说明：本文内容以当前仓库中的 VastAI.md 文档为准，相关实现参考了 cli_parser.py、fast_api.py 与 router.py 中的参数解析与设备识别逻辑；设备可见性、--enforce_eager 的必要性等厂商约束以瀚博官方文档表述为准。