本文檔基于天翼云（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 //jiangsu-10.zos.daliqc.cn/galaxy/deployment/mineru.tar
--2025-08-28 15:26:15--  //jiangsu-10.zos.daliqc.cn/galaxy/deployment/mineru.tar
Resolving jiangsu-10.zos.daliqc.cn (jiangsu-10.zos.daliqc.cn)... 117.88.33.209, 117.88.33.247, 218.91.113.207
Connecting to jiangsu-10.zos.daliqc.cn (jiangsu-10.zos.daliqc.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 //jiangsu-10.zos.daliqc.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 //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：//<server_ip>:11025/docs

• 參數說明：<server_ip>需替換為天翼云昇騰910B物理機實例的公網IP或內網IP（根據訪問網絡環境選擇，內網訪問需確保客戶端與實例在同一天翼云私有網絡內）。

訪問成功后，將展示MinerU2.1服務的所有API接口列表，包括接口名稱、請求參數、響應格式等信息，可根據文檔指引發起API調用（如模型推理、服務狀態查詢等）。