MinerU 壁仞（Biren）加速卡部署指南：从镜像加载到服务启动的完整实操

本文基于 MinerU 官方中文文档中的壁仞加速卡适配指南，完整覆盖壁仞 Biren 106C 平台下 MinerU 的镜像获取、Docker 容器启动、环境变量配置以及各运行场景的支持矩阵，并结合当前仓库源码解释设备选择与环境变量生效的机制，帮助你把 MinerU 文档解析能力完整部署到壁仞算力上。

1. 测试平台与环境基线

官方指南给出了验证过可用性的参考测试平台，搭建前可先对照自己的硬件与软件版本：

os: Ubuntu 22.04.4 LTS
cpu: Intel x86-64
gpu: Biren 106C
driver: 1.10.0
docker: 28.0.4

需要说明的是，壁仞镜像及运行参数以壁仞内部发布的版本为准。如果你的驱动版本、Docker 版本与上表差距较大，建议以壁仞官方交付的运行手册为准，再结合下文的启动方式做适配。

2. 环境准备：下载并加载 vLLM 镜像

壁仞平台上的 MinerU 镜像并非公开仓库拉取，而是以 tar 包形式由壁仞官方提供（vLLM 运行时版本）：

wget http://birentech.com/xxx/MinerU/mineru-vllm.tar  # 链接获取请联系壁仞内部人员（邮箱：[e-mail]）
docker load -i mineru-vllm.tar

执行 docker load 后，本地会得到镜像 mineru:biren-vllm-latest，它是后续所有容器启动命令的镜像基础。

3. 启动 Docker 容器

官方推荐的容器启动命令如下，参数已针对壁仞加速卡做了完整配置：

docker run -it --name mineru_docker \
    --privileged \
    --network=host \
    --shm-size=100G \
    -e MINERU_MODEL_SOURCE=local \
    -e MINERU_DEVICE_MODEL=supa \
    -e SHAPE_TRANSFORM_GRANK=true \
    mineru:biren-vllm-latest \
    /bin/bash

各参数作用拆解：

参数	作用
--privileged	授予容器特权模式权限，用于访问壁仞加速卡的底层设备节点
--network=host	使用宿主机网络，方便外部直接访问容器内启动的 API/Gradio 端口
--shm-size=100G	扩大共享内存，满足大模型推理与多进程数据交换需求
-e MINERU_MODEL_SOURCE=local	指定模型来源为本地，容器内直接使用随镜像预置的模型，无需在线下载
-e MINERU_DEVICE_MODEL=supa	标记运行设备为壁仞 supa 平台，供镜像内运行时识别加速卡后端
-e SHAPE_TRANSFORM_GRANK=true	壁仞运行时相关开关，启用形状转换行为

执行该命令后，会进入 Docker 容器的交互式终端，可以在容器内直接运行 MinerU 相关命令。如果不需要交互调试，也可以把命令末尾的 /bin/bash 替换为具体的服务启动命令（见第 4 节），实现一键启动服务。

3.1 源码视角：设备与环境变量是如何生效的

从源码结构看，MinerU 通过环境变量与设备探测函数协同决定模型运行在哪个后端：

• config_reader.py 中的 get_device() 首先读取设备覆盖环境变量，若未设置则按 cuda → mps → npu → gcu → musa → mlu → sdaa 的顺序探测可用后端，最终兜底为 cpu。壁仞镜像中 MINERU_DEVICE_MODEL=supa 即属于这类设备标记约定，用于让运行时将模型加载到壁仞加速卡上；
• router.py 中 get_local_device_visible_env_name() 与 detect_visible_local_devices() 展示了 MinerU 解析“可见设备”环境变量的通用机制：按设备类型选择对应的可见性变量（NVIDIA 为 CUDA_VISIBLE_DEVICES，NPU 为 ASCEND_RT_VISIBLE_DEVICES），壁仞平台则约定使用 SUPA_VISIBLE_DEVICES（见第 5 节）。

因此，把 MINERU_MODEL_SOURCE=local 与设备标记一起注入容器，是保证 MinerU 在壁仞卡上开箱即用的关键。

4. 容器内启动 MinerU 服务

进入容器后，可按官方使用文档选择以下任一类入口（命令形态与 快速上手 一致）：

入口	说明	典型用途
mineru	命令行工具，批量解析 PDF/Office 文档	离线批处理、脚本化集成
mineru-api	FastAPI 服务	对接自研业务系统
mineru-gradio	Gradio 交互界面	快速验证、演示
mineru-openai-server	OpenAI 兼容服务（vLLM 引擎）	LLM-ready 内容产出与 Agent 工作流
mineru-router	路由/聚合入口	多实例部署

例如在容器内执行 mineru -p <input_path> -o <output_path> 即可完成一次文档解析；启动 HTTP 服务时，可将容器命令末尾的 /bin/bash 直接替换为对应的服务启动命令，实现容器化一键拉起。更多参数细节可参考 CLI 工具说明 与 高级命令行参数。

5. 支持矩阵：壁仞加速卡（vLLM 容器环境）

官方指南给出了一张“使用场景 × 后端 × 容器环境（vllm）”的支持情况矩阵，在壁仞平台的 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. 指定加速卡与资源查看

壁仞平台下指定可见加速卡的方式与 NVIDIA GPU 类似：将 CUDA_VISIBLE_DEVICES 替换为 SUPA_VISIBLE_DEVICES 即可，具体用法可参考 指定 GPU 设备说明（如 SUPA_VISIBLE_DEVICES=1 mineru -p <input_path> -o <output_path> 的形式）。

此外，壁仞平台提供 brsmi 命令查看加速卡的占用情况，建议多实例部署前先用 brsmi 确认空闲卡号，再指定空闲的加速卡 ID，避免资源冲突。

7. 小结与注意事项

• 壁仞部署链路为：向壁仞获取 mineru-vllm.tar 镜像 → docker load → 按第 3 节命令启动容器 → 容器内运行 mineru/mineru-api/mineru-gradio/mineru-openai-server；
• --privileged、MINERU_MODEL_SOURCE=local、MINERU_DEVICE_MODEL=supa、SHAPE_TRANSFORM_GRANK=true 四项配置缺一不可，共同保证加速卡设备访问、模型本地加载与运行时行为正确；
• 多卡/多实例场景统一通过 SUPA_VISIBLE_DEVICES 控制可见卡，配合 brsmi 观察卡资源使用；
• 若平台版本或驱动与第 1 节测试基线存在差异，以壁仞官方交付的运行说明为准。