昇腾 NPU 部署指南与原理分析

一、npu.Dockerfile 是做什么的？

npu.Dockerfile 是 MinerU 为华为昇腾（Ascend）NPU 加速卡专门提供的 Docker 构建文件，用于在昇腾硬件上运行 MinerU 的全部功能（pipeline、vlm-auto-engine、hybrid-auto-engine 等）。

Dockerfile 逐段解析

# 基础镜像：vLLM-Ascend，已包含 torch_npu、CANN 等依赖
# 要求 ARM(AArch64) CPU + Ascend NPU 硬件
FROM quay.m.daocloud.io/ascend/vllm-ascend:v0.11.0

# 备选基础镜像：LMDeploy-Ascend
# FROM crpi-4crprmm5baj1v8iv.cn-hangzhou.personal.cr.aliyuncs.com/lmdeploy_dlinfer/ascend:mineru-a2

# 安装 OpenCV 依赖库和中文字体
RUN apt-get update && apt-get install -y fonts-noto-core fonts-noto-cjk ...

# 安装 MinerU 核心包
RUN pip install 'mineru[core]>=3.0.0' numpy==1.26.4 opencv-python==4.11.0.86

# 下载全部模型（从 ModelScope）
RUN mineru-models-download -s modelscope -m all

# 入口：设置本地模型源
ENTRYPOINT ["/bin/bash", "-c", "export MINERU_MODEL_SOURCE=local && exec \"$@\"", "--"]

关键点：基础镜像已经打包好了 torch_npu、CANN、vllm-ascend 等全部底层依赖，Dockerfile 只需在上层安装 MinerU 应用和模型即可。

---

二、如何部署到昇腾机器上

2.1 硬件要求

项目	要求
CPU	ARM AArch64（如鲲鹏 920）
NPU	Atlas A2 / A3 / 300I Duo 系列
操作系统	Linux（如 CTyunOS、EulerOS、CentOS）
Docker	20.10+
NPU 驱动	23.0.3+（参考测试平台）

支持的设备清单：

• Atlas A2 系列：800T A2, 900 A2 PoD, 200T A2 Box16, 300T A2, 800I A2
• Atlas A3 系列：800T A3, 900 A3 SuperPoD, 9000 A3 SuperPoD, 800I A3
• Atlas 300I Duo (310p)：实验性支持

2.2 构建镜像

方案 A：使用 vLLM 引擎（推荐，支持设备最多）

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/npu.Dockerfile
docker build --network=host -t mineru:npu-vllm-latest -f npu.Dockerfile .

如果使用 A3 系列设备，修改 Dockerfile 第 3 行的 tag：

FROM quay.m.daocloud.io/ascend/vllm-ascend:v0.11.0-a3

如果使用 310p 设备，修改为：

FROM quay.m.daocloud.io/ascend/vllm-ascend:v0.10.0rc1-310p

方案 B：使用 LMDeploy 引擎（仅支持 A2 系列）

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/npu.Dockerfile
# 将基础镜像从 vllm 切换为 lmdeploy（注释第3行，取消注释第5行）
sed -i '3s/^/# /' npu.Dockerfile && sed -i '5s/^# //' npu.Dockerfile
docker build --network=host -t mineru:npu-lmdeploy-latest -f npu.Dockerfile .

2.3 启动容器

docker run -u root --name mineru_docker --privileged=true \
    --ipc=host \
    --network=host \
    --device=/dev/davinci0 \
    --device=/dev/davinci1 \
    --device=/dev/davinci2 \
    --device=/dev/davinci3 \
    --device=/dev/davinci4 \
    --device=/dev/davinci5 \
    --device=/dev/davinci6 \
    --device=/dev/davinci7 \
    --device=/dev/davinci_manager \
    --device=/dev/devmm_svm \
    --device=/dev/hisi_hdc \
    -v /var/log/npu/:/usr/slog \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -e VLLM_WORKER_MULTIPROC_METHOD=spawn \
    -e MINERU_MODEL_SOURCE=local \
    -e MINERU_LMDEPLOY_DEVICE=ascend \
    -it mineru:npu-vllm-latest \
    /bin/bash

关键参数说明：

参数	作用
--device=/dev/davinci0~7	将 NPU 设备透传到容器内
--device=/dev/davinci_manager	NPU 管理设备
--device=/dev/devmm_svm	NPU 共享虚拟内存
--device=/dev/hisi_hdc	华为 HDC 通信设备
-v /usr/local/Ascend/driver	挂载宿主机 NPU 驱动
-v /usr/local/dcmi	挂载 DCMI（设备管理接口）
-v /usr/local/bin/npu-smi	挂载 NPU 监控工具
VLLM_WORKER_MULTIPROC_METHOD=spawn	Ascend 必须使用 spawn 模式
MINERU_LMDEPLOY_DEVICE=ascend	即使使用 vllm 也必须设置
MINERU_MODEL_SOURCE=local	使用镜像内已下载的模型

2.4 容器内使用

# 命令行解析 PDF
mineru -p input.pdf -o output/ -b hybrid-auto-engine

# 启动 API 服务
mineru-api --host 0.0.0.0 --port 8000

# 启动 OpenAI 兼容服务
mineru-openai-server --port 30000

# 启动 Gradio Web UI
mineru-gradio --host 0.0.0.0 --port 7860

310p 设备需额外参数（不支持图模式和 bf16）：

mineru-openai-server --port 30000 --enforce-eager --dtype float16

---

三、宿主机显卡驱动依赖

是的，必须考虑宿主机驱动。 这是昇腾 NPU 部署与 NVIDIA GPU 部署的一个核心区别。

宿主机必须预装的组件

组件	说明	作用
Ascend NPU 驱动 (Driver)	驱动版本 23.0.3+	提供 /dev/davinci* 设备节点
CANN Toolkit	通常已打包在基础镜像内	提供 NPU 算子库（类似 CUDA）
npu-smi	随驱动安装	NPU 监控工具（类似 nvidia-smi）
DCMI	随驱动安装	设备管理接口

容器与宿主机的驱动关系

┌──────────────────────────────────────────┐
│              Docker 容器                  │
│  ┌────────────────────────────────────┐  │
│  │  MinerU (Python 应用层)            │  │
│  ├────────────────────────────────────┤  │
│  │  torch_npu (类似 torch.cuda)       │  │
│  ├────────────────────────────────────┤  │
│  │  CANN Toolkit (算子库，镜像内置)     │  │
│  ├────────────────────────────────────┤  │
│  │  vllm-ascend / lmdeploy (推理引擎)  │  │
│  └──────────┬─────────────────────────┘  │
│             │  通过 -v 挂载               │
│  ┌──────────▼─────────────────────────┐  │
│  │  宿主机 NPU Driver (/usr/local/Ascend/driver)  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

核心原则：宿主机提供驱动（Driver），容器内提供算子库（CANN Toolkit）和应用层。

• 宿主机必须安装：Ascend NPU 驱动（提供设备节点 /dev/davinci*）
• 容器内已包含：CANN Toolkit、torch_npu、vllm-ascend（都打包在基础镜像中）
• 通过 volume 挂载：-v /usr/local/Ascend/driver:/usr/local/Ascend/driver 让容器访问宿主机驱动

---

四、torch / transformers 与 CANN 的版本关系

类比 NVIDIA 生态

NVIDIA 生态	昇腾生态	作用
GPU 硬件	NPU 硬件 (Ascend)	计算设备
NVIDIA Driver	Ascend Driver	内核级驱动
CUDA Toolkit	CANN Toolkit	计算框架/算子库
cuDNN	CANN 中的算子库	深度学习算子
torch.cuda	torch_npu	PyTorch NPU 后端
vllm (GPU)	vllm-ascend	VLM 推理引擎
nvidia-smi	npu-smi	设备监控

版本对应关系

在昇腾生态中，版本匹配链如下：

Ascend Driver (宿主机)
    ↓ 兼容
CANN Toolkit 版本 (镜像内置)
    ↓ 适配
torch_npu 版本 (镜像内置)
    ↓ 兼容
PyTorch 版本 (镜像内置)
    ↓ 依赖
vllm-ascend / lmdeploy (镜像内置)
    ↓
MinerU (Dockerfile 中安装)

关键结论：这一切版本匹配已经由基础镜像处理好了。

基础镜像 quay.m.daocloud.io/ascend/vllm-ascend:v0.11.0 内部已经包含了互相兼容的：

• CANN Toolkit（特定版本）
• torch_npu（与 CANN 匹配的版本）
• PyTorch（与 torch_npu 匹配的版本）
• vllm-ascend（与上述全部匹配的版本）

---

五、Dockerfile 是否指定了 CANN 版本？

直接回答

npu.Dockerfile 本身没有显式指定 CANN 版本，但 基础镜像隐式锁定了 CANN 版本。

FROM quay.m.daocloud.io/ascend/vllm-ascend:v0.11.0

这个基础镜像 vllm-ascend:v0.11.0 是由 vllm-ascend 项目官方构建的，里面已经打包了：

• 特定版本的 CANN Toolkit
• 与之匹配的 torch_npu
• 与之匹配的 PyTorch
• vllm-ascend v0.11.0

所以 CANN 版本由基础镜像决定，而非 Dockerfile 直接指定。

宿主机驱动的兼容性

宿主机的 Ascend Driver 版本需要与镜像内的 CANN Toolkit 版本兼容。通常：

• Ascend Driver 版本 >= CANN Toolkit 要求的最低版本 即可
• 官方测试平台使用 Driver 23.0.3
• 建议使用与基础镜像发布时间相近的驱动版本

---

六、现有的 torch、模型文件是否支持 CANN（NPU）？

PyTorch 层面

MinerU 在 NPU 上通过 torch_npu 运行，代码中已有完善的适配：

# 自动检测 NPU 设备
import torch_npu
if torch_npu.npu.is_available():
    device = "npu"

# NPU 特定初始化
if str(device).startswith('npu'):
    torch_npu.npu.set_compile_mode(jit_compile=False)

模型文件层面

模型文件（权重）是硬件无关的。MinerU 使用的模型（VLM、OCR、版面检测等）都是标准的 PyTorch 模型权重，可以通过 torch_npu 加载到 NPU 上运行。Dockerfile 中通过 mineru-models-download -m all 下载的模型与 GPU 版完全相同。

vllm-ascend / lmdeploy 对模型的支持

• vllm-ascend 对主流模型架构（如 Qwen2-VL 等视觉语言模型）提供了 NPU 适配
• lmdeploy 同样支持在 Ascend 上运行常见 VLM 模型
• MinerU 使用的 VLM 模型（MinerU2.5-Pro-2604-1.2B）已验证可在昇腾 NPU 上运行，精度与 NVIDIA GPU 基本一致

---

七、总结

部署核心流程

1. 宿主机安装 Ascend NPU 驱动（Driver 23.0.3+）
2. 构建镜像 docker build -f npu.Dockerfile（基础镜像已包含 CANN + torch_npu + vllm）
3. 启动容器 时挂载驱动目录和透传 NPU 设备
4. 容器内运行 MinerU 命令

版本关系核心结论

问题	结论
Dockerfile 是否指定 CANN 版本？	否，但基础镜像隐式锁定了 CANN 版本
宿主机需要安装什么？	只需 Ascend Driver + npu-smi
CANN Toolkit 在哪里？	打包在基础镜像内，无需宿主机安装
torch/模型是否支持 NPU？	是，通过 torch_npu 适配，模型权重硬件无关
宿主机 Driver 版本要求？	23.0.3+，需与镜像内 CANN 版本兼容
是否需要关心 CANN 与 cuDNN 的关系？	昇腾生态中没有 cuDNN 概念，对应的是 CANN 内置的算子库，版本已由基础镜像处理

---

八、自行构建 conda 环境 vs 使用官方镜像：可行性分析

8.1 核心难点

自行从头搭建昇腾环境的难度确实不低，主要原因：

难点 1：版本匹配链长且严格

昇腾生态的版本依赖链比 NVIDIA 更严格，需要手动匹配以下层级：

宿主机 Ascend Driver (固件/驱动)
    ↓ 必须兼容
CANN Toolkit (算子库，需要安装 3 个子包)
    ├── cann-toolkit       (核心工具包)
    ├── cann-910b-ops      (910B 专用算子)
    └── cann-nnal          (神经网络加速库，提供 libatb.so)
    ↓ 必须匹配
torch_npu (PyTorch NPU 适配层)
    ↓ 必须匹配
PyTorch (标准 PyTorch)
    ↓ 必须匹配
vllm-ascend 或 lmdeploy (推理引擎)
    ↓
MinerU

任何一层版本不匹配都会导致运行失败，且报错信息往往不直观（如 libatb.so not found、算子不支持等）。

难点 2：CANN 安装包获取和安装

CANN 不是通过 pip 安装的，而是需要下载 .run 安装包：

# 需要安装 3 个包（910B 场景）
wget https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.1/Ascend-cann-toolkit_8.5.1_linux-aarch64.run
wget https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.1/Ascend-cann-910b-ops_8.5.1_linux-aarch64.run
wget https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.1/Ascend-cann-nnal_8.5.1_linux-aarch64.run

chmod +x *.run
./Ascend-cann-toolkit_8.5.1_linux-aarch64.run --full
./Ascend-cann-910b-ops_8.5.1_linux-aarch64.run --install
./Ascend-cann-nnal_8.5.1_linux-aarch64.run --install

内网环境需要提前下载好这些包并拷贝进去，每个包都有数 GB 大小。

难点 3：torch_npu 的版本匹配

根据 Ascend/pytorch 官方仓库的版本匹配表（截至 2025 年）：

CANN 版本	支持的 PyTorch 版本	对应 torch_npu 版本
CANN 8.5.0	2.6.0 / 2.7.1 / 2.8.0 / 2.9.0	2.6.0.post5 / 2.7.1.post2 / 2.8.0.post2 / 2.9.0
CANN 8.3.RC1	2.6.0 / 2.7.1 / 2.8.0 / 2.1.0	2.6.0.post3 / 2.7.1 / 2.8.0 / 2.1.0.post17
CANN 8.2.RC1	2.5.1 / 2.6.0	2.5.1.post1 / 2.6.0
CANN 8.1.RC1	2.4.0 / 2.5.1	2.4.0.post4 / 2.5.1

MinerU 要求 PyTorch >= 2.6.0，因此 CANN 版本至少需要 8.2.RC1，建议使用 CANN 8.5.0。

8.2 内网 910B 的 CANN / Driver 版本是否有影响？

有重大影响。 具体来说：

宿主机 Driver 版本

• 内网机器上已安装的 Ascend Driver 版本决定了你能使用的 CANN Toolkit 版本上限
• CANN Toolkit 版本必须 <= Driver 支持的最高版本
• 如果内网机器的 Driver 版本较旧（如早于 23.0.x），可能无法使用最新的 CANN 8.5
• 查看 Driver 版本：npu-smi info

CANN 版本影响

• CANN 版本直接决定可用的 算子（算子就是类似 cuDNN 的概念）
• 如果 CANN 版本太低，某些模型所需的算子可能不存在，导致运行时报错
• vllm-ascend v0.11.0 要求 CANN >= 8.1.RC1

固件版本

• 固件（Firmware）版本需要与 Driver 版本匹配
• 固件是烧录在 NPU 硬件中的低层程序，一般由运维人员更新

8.3 推荐的两种路线

路线 A：基于官方基础镜像制作内网镜像（推荐）

这是最省心的方案，在能访问外网的昇腾机器上构建，然后导出镜像：

# 步骤 1：在有外网的昇腾机器上构建
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/npu.Dockerfile
docker build --network=host -t mineru:npu-vllm-latest -f npu.Dockerfile .

# 步骤 2：导出镜像为 tar 文件
docker save mineru:npu-vllm-latest -o mineru-npu-vllm.tar

# 步骤 3：拷贝到内网环境
scp mineru-npu-vllm.tar user@internal-host:/path/

# 步骤 4：在内网昇腾机器上加载镜像
docker load -i mineru-npu-vllm.tar

# 步骤 5：启动容器（同前述 docker run 命令）
docker run ... mineru:npu-vllm-latest /bin/bash

优点：版本全部匹配，不需要手动处理任何依赖
前提：需要有一台与内网机器相同架构（ARM + 910B）且能访问外网的机器来构建

路线 B：自行安装 conda 环境（可行但困难）

如果无法获得外网昇腾机器，需要在内网从零搭建：

# 步骤 1：确认内网 910B 的 Driver 和 CANN 版本
npu-smi info                    # 查看驱动版本
cat /usr/local/Ascend/ascend-toolkit/version.info  # 查看 CANN 版本

# 步骤 2：根据 CANN 版本选择 torch_npu 版本
# 例如 CANN 8.5.0 + PyTorch 2.6.0 → torch_npu==2.6.0.post5

# 步骤 3：创建 conda 环境
conda create -n mineru python=3.11
conda activate mineru

# 步骤 4：安装 PyTorch
pip install torch==2.6.0

# 步骤 5：安装 torch_npu（需要提前下载好 wheel 包）
pip install torch_npu==2.6.0.post5

# 步骤 6：安装 vllm-ascend（需要提前下载好）
pip install vllm==0.11.0
pip install vllm-ascend==0.11.0

# 步骤 7：安装 MinerU（需要提前下载好所有依赖 wheel 包）
pip install 'mineru[core]>=3.0.0' numpy==1.26.4 opencv-python==4.11.0.86

# 步骤 8：下载模型文件并拷贝到内网
# 需要在有网机器上运行：
# mineru-models-download -s modelscope -m all
# 然后将 ~/.mineru/models/ 目录整体打包拷贝到内网

# 步骤 9：设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh
export MINERU_MODEL_SOURCE=local
export MINERU_LMDEPLOY_DEVICE=ascend
export VLLM_WORKER_MULTIPROC_METHOD=spawn

8.4 路线 B 的关键风险点

风险	说明	严重程度
CANN 版本不匹配	内网已有 CANN 版本可能太旧，不支持所需的 torch_npu 版本	高
Driver 版本太旧	固件/驱动版本可能需要升级（需要运维权限）	高
依赖包下载	需要在有网机器上提前下载几百个 wheel 包	中
torch_npu 编译	如果没有预编译的 wheel，需要从源码编译（极困难）	高
算子缺失	CANN 版本过低导致某些模型算子不可用	中
NNAL 缺失	缺少 libatb.so 导致 vllm-ascend 无法运行	高

8.5 最终建议

如果内网 910B 机器已经安装了 CANN 8.2+ 和 Driver 23.0+：

• 路线 B 可行，但需要仔细匹配版本
• 提前在有网机器上下载所有 wheel 包

如果内网 910B 机器的 CANN/Driver 版本未知或较旧：

• 强烈建议先确认版本
• 如果 Driver/CANN 版本太旧，可能需要运维升级固件和驱动
• 升级固件/驱动有硬件风险，需要华为技术支持

如果条件允许：

• 强烈推荐路线 A（基于官方镜像导出/导入）
• 版本匹配由官方保证，风险最低

8.6 内网环境需要确认的清单

在动手之前，先在内网 910B 机器上执行以下命令确认环境：

# 1. 确认 CPU 架构（必须是 aarch64）
uname -m

# 2. 确认 NPU 型号
npu-smi info

# 3. 确认 Driver 版本（需要 23.0.3+）
npu-smi info | head -5

# 4. 确认 CANN 版本（如果已安装）
cat /usr/local/Ascend/ascend-toolkit/version.info 2>/dev/null || echo "CANN 未安装"

# 5. 确认 NNAL 是否安装（libatb.so）
find /usr/local/Ascend -name "libatb.so" 2>/dev/null || echo "NNAL 未安装"

# 6. 确认 Python 版本
python3 --version

# 7. 确认 Docker 版本
docker --version

# 8. 确认设备节点是否存在
ls /dev/davinci* 2>/dev/null || echo "NPU 设备节点不存在"

根据以上输出结果，再决定走路线 A 还是路线 B。