MinerU 太初元碁 Tecorigin 加速卡部署指南：vllm 镜像加载、Docker 容器启动与全场景支持矩阵

本篇基于 MinerU 仓库自带的 太初元碁 Tecorigin 适配指南，完整讲解在 Tecorigin T100 加速卡上通过官方 vllm 镜像部署 MinerU 的全部步骤：从测试平台前提、镜像下载加载，到 Docker 容器启动参数、vllm 虚拟环境切换，以及各使用场景（命令行、FastAPI、Gradio、OpenAI 兼容服务）的支持状态矩阵。读完本文，你可以直接在一台配有多张 Tecorigin 卡的服务器上把 MinerU 的 PDF 解析流水线跑起来，并用 SDAA_VISIBLE_DEVICES、teco-smi 正确编排多卡资源。

1. 测试平台前提

官方指南给出的测试验证平台信息如下，实际部署时建议对齐操作系统、驱动与 Docker 版本：

os: Ubuntu 22.04.5 LTS
cpu: AMD EPYC (amd64)
gpu: T100
driver: 3.0.0
docker: 28.0.4

其中 gpu: T100 即太初元碁的 SDAA 架构加速卡，driver: 3.0.0 为对应的太初驱动版本。MinerU 从 2.7.6 版本起正式纳入太初元碁平台适配，见 更新日志 中“新增国产算力平台昆仑芯、太初元碁的适配支持”的说明，项目主 README_zh-CN.md 的国产算力列表中也列出了太初元碁。

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

与部分国产平台需要通过 Dockerfile 自行构建镜像不同，Tecorigin 路线由厂商仓库直接提供打好包的 mineru-vllm 镜像（内含 vllm 运行环境），只需下载并导入 Docker：

wget http://wb.tecorigin.com:8082/repository/teco-customer-repo/Course/MinerU/mineru-vllm.tar

docker load -i mineru-vllm.tar

导入成功后，本机会出现名为 mineru:sdaa-vllm-latest 的镜像，sdaa 即太初 SDAA 加速卡的标识。后续所有解析后端（pipeline、vlm/hybrid-engine、vlm/hybrid-http-client）以及 mineru-api、mineru-gradio、mineru-openai-server 各类服务都基于这个镜像运行。

3. 启动 Docker 容器

官方给出的容器启动命令如下：

docker run -dit --name mineru_docker \
    --privileged \
    --cap-add SYS_PTRACE \
    --cap-add SYS_ADMIN \
    --network=host \
    --shm-size=500G \
    mineru:sdaa-vllm-latest \
    /bin/bash

各参数说明：

• --privileged / --cap-add SYS_PTRACE / --cap-add SYS_ADMIN：加速卡运行时通常需要在容器内访问 SDAA 设备节点与调试接口，因此采用特权容器并显式追加两个关键 capability；
• --network=host：使用主机网络，方便容器内服务（如 mineru-api、openai-server）直接被宿主机与其他进程访问，也免去端口映射；
• --shm-size=500G：分配大规格共享内存，满足 vllm 多卡、大 batch 推理场景下的进程间通信需求；
• 末尾的 /bin/bash：进入容器交互式终端，可以直接在容器内运行 mineru 等命令。

3.1 切换到 vllm conda 环境

进入容器后，若要通过 vllm 引擎运行 vlm/hybrid 后端，需先切换 conda 环境：

conda activate vllm_env_py310

切换成功后，命令行提示符前会出现 (vllm_env_py310) 标识，表示已成功进入 vllm 虚拟环境。该环境即指南支持矩阵中“容器环境：vllm”一列的运行环境。

3.2 直接以服务模式启动

也可以不把末尾的 /bin/bash 换成交互终端，而是替换为具体的服务启动命令，让容器直接拉起 MinerU 服务。MinerU 提供的入口命令包括（详见 命令行工具使用说明 与 快速使用）：

# FastAPI 服务（异步任务 + 同步解析接口）
mineru-api --host 0.0.0.0 --port 8000

# Gradio WebUI 可视化前端
mineru-gradio --server-name 0.0.0.0 --server-port 7860

# OpenAI 兼容服务（需 vllm 环境，即 3.1 中激活的环境）
mineru-openai-server --port 30000

# 多卡 / 多服务编排
mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto

例如把上面 docker run 命令最后的 /bin/bash 替换为 mineru-api --host 0.0.0.0 --port 8000，即可让容器直接以 API 服务模式运行；客户端侧仍可以用 mineru -p <input_path> -o <output_path> --api-url http://127.0.0.1:8000 直接调用，或通过 -b hybrid-http-client -u http://127.0.0.1:30000 方式对接 openai-server。

4. MinerU 各使用场景对 Tecorigin 加速卡的支持矩阵

官方指南按“入口 × 解析后端”维度给出了完整的支持状态表，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 兼容服务（mineru-openai-server）	vllm	🟢

状态图例：

• 🟢 支持，运行较稳定，精度与 NVIDIA GPU 基本一致；
• 🟡 支持但较不稳定，在某些场景下可能出现异常，或精度存在一定差异；
• 🔴 不支持，无法运行，或精度存在较大差异。

对应的 CLI 后端参数即 mineru 命令的 -b/--backend 选项，取值为 pipeline | vlm-engine | hybrid-engine | vlm-http-client | hybrid-http-client（见 mineru --help 输出）。需要注意：vlm-http-client 是轻量远程 client，不要求本地安装 torch；hybrid-http-client 则要求本地具备 mineru[pipeline] 及 torch 等 pipeline 依赖，这一点与 NVIDIA GPU 平台完全一致。

5. 指定可用加速卡与查看占用

5.1 用 SDAA_VISIBLE_DEVICES 指定卡

Tecorigin 加速卡指定可用卡的方式与 NVIDIA GPU 的 CUDA_VISIBLE_DEVICES 完全同构，只需把环境变量名替换为 SDAA_VISIBLE_DEVICES，详细语义可参考 命令行参数进阶 中“CUDA_VISIBLE_DEVICES 基本用法”一节。常见用法示例（按本文规则改写）：

# 只看到 1 号卡
SDAA_VISIBLE_DEVICES=1 mineru -p <input_path> -o <output_path>

# 看到 0、1 号卡
SDAA_VISIBLE_DEVICES=0,1 mineru -p <input_path> -o <output_path>

# 看到 0、2、3 号卡，1 号卡被屏蔽
SDAA_VISIBLE_DEVICES=0,2,3 mineru -p <input_path> -o <output_path>

# 不暴露任何加速卡
SDAA_VISIBLE_DEVICES="" mineru -p <input_path> -o <output_path>

该指定方式对所有命令行入口（mineru、mineru-openai-server、mineru-gradio、mineru-api、mineru-router）及 pipeline、vlm 后端均适用。多卡并行部署的典型用法：

# 终端 1：卡 0 上起一个 openai-server
SDAA_VISIBLE_DEVICES=0 mineru-openai-server --engine vllm --port 30000
# 终端 2：卡 1 上再起一个 openai-server
SDAA_VISIBLE_DEVICES=1 mineru-openai-server --engine vllm --port 30001

源码层面的佐证：MinerU 的 mineru-router 在为本地 worker 分配可见设备时，会按当前设备类型选择对应的可见设备环境变量——昇腾 NPU 使用 ASCEND_RT_VISIBLE_DEVICES，其余设备回落到 CUDA_VISIBLE_DEVICES（见 mineru/cli/router.py 的 get_local_device_visible_env_name）。Tecorigin 路线由于 vllm 运行时由厂商镜像内置的 SDAA 后端接管，仓库源码中不出现 SDAA 字样，卡可见性由容器运行时与厂商 vllm 实现处理，因此指南明确要求在命令行层面显式使用 SDAA_VISIBLE_DEVICES。

5.2 用 teco-smi 查看加速卡占用

在太初平台，使用 teco-smi 命令查看加速卡的使用情况（其中 -c 查看实时占用），并根据需要指定空闲的加速卡 ID 以避免资源冲突：

teco-smi -c

在多租户或一机多服务场景下，先跑 teco-smi -c 确认哪些卡空闲，再用 SDAA_VISIBLE_DEVICES=<空闲卡ID> 启动对应服务，是避免显存冲突的推荐流程。

6. 适用前提与限制

• 本部署路线基于厂商提供的 mineru-vllm 镜像，验证平台为 Ubuntu 22.04.5 LTS + T100 + 驱动 3.0.0 + Docker 28.0.4；其他 OS/驱动组合仓库未做官方验证，请以厂商交付环境为准；
• 镜像内已包含 vllm 环境（vllm_env_py310 conda 环境），vlm/hybrid-engine 后端依赖该环境；pipeline 后端不依赖 vllm；
• 若镜像内未预置所需模型，可按 模型源说明 通过 MINERU_MODEL_SOURCE 切换模型源或使用本地模型目录；
• 各入口与服务接口的详细参数（如 mineru-api 的 /health、/tasks、/file_parse 接口，mineru-router 的多上游聚合等）请参照 快速使用 与 命令行参数进阶，其在 GPU 平台上的用法在 Tecorigin 平台上同样成立，仅设备可见性环境变量名需替换为 SDAA_VISIBLE_DEVICES。