企业官网建设流程全解析

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

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

本文围绕 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）：

图例说明：🟢 支持，运行较稳定，精度与 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的必要性等厂商约束以瀚博官方文档表述为准。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU