本文档基于天翼云（CTyunOS）生态环境，针对昇腾910B物理机实例，提供MinerU2.1服务从环境准备、服务启停到API调用的完整操作指南。通过遵循本文档步骤，可在天翼云CTyunOS镜像环境中高效部署MinerU2.1服务，充分利用昇腾910B的算力优势，满足模型推理等AI服务需求。

1 环境准备

1.1 前置条件

• 操作系统镜像：使用天翼云官方提供的CTyunOS - CTyunOS 23.01.2@GalaxyCompute-NPU25.0.rc1.1 64位镜像，该镜像已针对天翼云算力环境优化，适配昇腾硬件。

• 云服务器实例：选用天翼云昇腾910B物理机实例，套餐规格为physical.Icas910b.2xlarge11，确保具备满足MinerU2.1服务运行的算力与硬件资源。

1.2 本地NVME分区

需将节点的nvme1n1和nvme0n1两块NVME盘分别挂载至/mnt/nvme1n1和/mnt/nvme0n1目录（后续MinerU2.1的模型、容器镜像存储及服务启动将依赖这两个挂载点），执行以下脚本完成分区挂载与开机自动挂载配置：

#!/bin/bash

# 设备列表
devices=("/dev/nvme0n1" "/dev/nvme1n1")
mount_points=("/mnt/nvme0n1" "/mnt/nvme1n1")
fs_type="xfs"

# 确保 root 权限
if [[ $EUID -ne 0 ]]; then
    echo "请使用 root 运行此脚本！"
    exit 1
fi

for i in "${!devices[@]}"; do
    device="${devices[$i]}"
    mount_point="${mount_points[$i]}"

    # 创建挂载目录
    mkdir -p "$mount_point"

    # 获取设备的文件系统类型
    current_fs=$(blkid -s TYPE -o value "$device")

    if [[ -z "$current_fs" ]]; then
        echo "设备 $device 没有文件系统，正在格式化为 $fs_type..."
        mkfs.xfs -f "$device"
    else
        echo "$device 已格式化为 $current_fs，跳过格式化"
    fi

    # 确保设备未被挂载后再尝试挂载
    umount "$device" 2>/dev/null
    mount -t "$fs_type" "$device" "$mount_point"

    if [[ $? -ne 0 ]]; then
        echo "错误：无法挂载 $device 到 $mount_point，请检查设备或文件系统！"
        exit 1
    fi

    echo "$device 已成功挂载到 $mount_point"

    # 获取 UUID 并更新 /etc/fstab，避免重复添加
    uuid=$(blkid -s UUID -o value "$device")
    if ! grep -q "$uuid" /etc/fstab; then
        echo "UUID=$uuid  $mount_point  $fs_type  defaults  0 0" >> /etc/fstab
        echo "$device (UUID=$uuid) 已添加到 /etc/fstab"
    else
        echo "$device 已存在于 /etc/fstab，无需添加"
    fi

done

echo "所有磁盘已成功挂载并配置为开机自动挂载！"

执行以下命令可查看磁盘分区及挂载情况，确认NVMe盘挂载正常：

$ lsblk
NAME               MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
loop0                7:0    0   4.2G  1 loop 
sda                  8:0    0 446.6G  0 disk 
├─sda1               8:1    0   122M  0 part 
├─sda2               8:2    0 976.6M  0 part /boot/efi
├─sda3               8:3    0   1.9G  0 part /boot
└─sda4               8:4    0 443.6G  0 part 
  ├─system-lv_swap 253:0    0    16G  0 lvm  [SWAP]
  └─system-lv_root 253:1    0 427.6G  0 lvm  /
nvme1n1            259:0    0   2.9T  0 disk 
└─nvme1n1p1        259:4    0   2.9T  0 part /mnt/nvme1n1
nvme0n1            259:1    0   2.9T  0 disk 
└─nvme0n1p1        259:3    0   2.9T  0 part /mnt/nvme0n1

NOTE：本文档部署方案中，模型文件与MindIE容器镜像将存储在每个节点的/mnt/nvme1n1目录，/mnt/nvme0n1目录用于MinerU2.1服务启动操作。

1.3 下载脚本

下载MinerU服务脚本包并解压至/mnt/nvme0n1目录（该目录为前文配置的NVME挂载点，具备充足存储空间），执行命令如下：

$ cd /mnt/nvme0n1
$ wget https://jiangsu-10.zos.ctyun.cn/galaxy/deployment/mineru.tar
--2025-08-28 15:26:15--  https://jiangsu-10.zos.ctyun.cn/galaxy/deployment/mineru.tar
Resolving jiangsu-10.zos.ctyun.cn (jiangsu-10.zos.ctyun.cn)... 117.88.33.209, 117.88.33.247, 218.91.113.207
Connecting to jiangsu-10.zos.ctyun.cn (jiangsu-10.zos.ctyun.cn)|117.88.33.209|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 10240 (10K) [application/x-tar]
Saving to: ‘mineru.tar.1’

mineru.tar.1                               100%[========================================================================================>]  10.00K  --.-KB/s    in 0s      

2025-08-28 15:26:15 (141 MB/s) - ‘mineru.tar.1’ saved [10240/10240]

$ tar -xvf mineru.tar 
mineru/
mineru/stop.sh
mineru/logs/
mineru/start.sh
mineru/mindie_2.1.RC1-800I-A2-py311-openeuler24.03-lts-mineru.sif

1.4 下载MindIE

将MindIE容器文件下载至/mnt/nvme1n1/apptainer目录（该目录为前文配置的NVME存储目录，用于存放容器镜像），并在服务启动目录创建软链接以简化调用，执行命令如下：

1. 下载MindIE容器：

   $ mkdir -p /mnt/nvme1n1/apptainer
   $ cd /mnt/nvme1n1/apptainer
   $ wget https://jiangsu-10.zos.ctyun.cn/galaxy/apptainer/mindie/mindie_2.1.RC1-800I-A2-py311-openeuler24.03-lts-mineru.sif

2. 在服务启动目录创建软链接：

   $ cd /mnt/nvme0n1/mineru
   $ ln -s /mnt/nvme1n1/apptainer/mindie_2.1.RC1-800I-A2-py311-openeuler24.03-lts-mineru.sif .

NOTE：MinerU2.1模型已集成到上述MindIE容器中，无需额外下载模型文件。

2 起停服务

2.1 指定NPU卡

MinerU2.1服务运行依赖昇腾910B算力，需根据实际需要使用的NPU卡编号，修改start.sh脚本中的NPU卡指定配置，具体操作如下：

编辑/mnt/nvme0n1/mineru/start.sh文件，找到以下配置行：

export ASCEND_RT_VISIBLE_DEVICES=0

• 参数说明：ASCEND_RT_VISIBLE_DEVICES用于指定服务使用的NPU卡编号，默认值为0（即使用0号NPU卡），可根据实际硬件情况修改为其他有效编号（如1、2等，需与节点NPU卡数量匹配）。

2.2 启动MinerU服务

完成NPU卡配置后，仅需2条命令即可启动MinerU2.1服务，执行步骤如下：

$ cd /mnt/nvme0n1/mineru
$ sh start.sh
INFO:    instance started successfully
MinerU2.1 启动完成，日志：logs/log_2025-08-28_14-55-29.out

服务启动后，可通过查看日志目录下的错误日志文件，确认服务是否正常启动，执行命令如下：

$ tail -f logs/log_2025-08-28_14-55-29.err
2025-08-28 14:55:42.607 | WARNING  | mineru.backend.vlm.predictor:<module>:35 - sglang is not installed. If you are not using sglang, you can ignore this warning.
INFO:     Started server process [15]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:11025 (Press CTRL+C to quit)

NOTE：MinerU2.1服务默认使用11025端口对外提供服务，若需修改端口，需调整服务配置文件（具体以实际部署版本为准）。

2.3 查看MinerU服务

启动服务后，可通过apptainer命令查看MinerU2.1服务的运行实例信息，确认服务进程状态，执行命令如下：

$ apptainer instance list
INSTANCE NAME    PID        IP    IMAGE
mineru           3237672          /mnt/nvme0n1/apptainer/mineru/mindie_2.1.RC1-800I-A2-py311-openeuler24.03-lts-mineru.sif

• 输出说明：INSTANCE NAME为服务实例名称（此处为mineru），PID为服务进程ID（此处为3237672），IMAGE为服务依赖的MindIE容器路径。

2.4 停止MinerU服务

若需停止MinerU2.1服务，仅需在服务目录执行停止脚本即可，操作命令如下：

$ sh stop.sh
INFO:    Stopping mineru instance of /mnt/nvme0n1/apptainer/mineru/mindie_2.1.RC1-800I-A2-py311-openeuler24.03-lts-mineru.sif (PID=3237672)

执行完成后，可再次通过apptainer instance list命令确认服务实例已停止（无mineru实例输出即为停止成功）。

3 调用Web API服务

MinerU2.1服务启动后，支持通过Web API进行调用，可通过浏览器访问API文档页面查看接口详情，具体操作如下：

在本地浏览器地址栏输入URL：http://<server_ip>:11025/docs

• 参数说明：<server_ip>需替换为天翼云昇腾910B物理机实例的公网IP或内网IP（根据访问网络环境选择，内网访问需确保客户端与实例在同一天翼云私有网络内）。

访问成功后，将展示MinerU2.1服务的所有API接口列表，包括接口名称、请求参数、响应格式等信息，可根据文档指引发起API调用（如模型推理、服务状态查询等）。