昇腾 NPU 部署指南与原理分析一、npu.Dockerfile 是做什么的npu.Dockerfile是 MinerU 为华为昇腾AscendNPU 加速卡专门提供的 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 numpy1.26.4 opencv-python4.11.0.86 # 下载全部模型从 ModelScope RUN mineru-models-download -s modelscope -m all # 入口设置本地模型源 ENTRYPOINT [/bin/bash, -c, export MINERU_MODEL_SOURCElocal exec \$\, --]关键点基础镜像已经打包好了torch_npu、CANN、vllm-ascend等全部底层依赖Dockerfile 只需在上层安装 MinerU 应用和模型即可。二、如何部署到昇腾机器上2.1 硬件要求项目要求CPUARM AArch64如鲲鹏 920NPUAtlas A2 / A3 / 300I Duo 系列操作系统Linux如 CTyunOS、EulerOS、CentOSDocker20.10NPU 驱动23.0.3参考测试平台支持的设备清单Atlas A2 系列800T A2, 900 A2 PoD, 200T A2 Box16, 300T A2, 800I A2Atlas A3 系列800T A3, 900 A3 SuperPoD, 9000 A3 SuperPoD, 800I A3Atlas 300I Duo (310p)实验性支持2.2 构建镜像方案 A使用 vLLM 引擎推荐支持设备最多wgethttps://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/npu.Dockerfiledockerbuild--networkhost-tmineru:npu-vllm-latest-fnpu.Dockerfile.如果使用 A3 系列设备修改 Dockerfile 第 3 行的 tagFROM 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 系列wgethttps://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/npu.Dockerfile# 将基础镜像从 vllm 切换为 lmdeploy注释第3行取消注释第5行sed-i3s/^/# /npu.Dockerfilesed-i5s/^# //npu.Dockerfiledockerbuild--networkhost-tmineru:npu-lmdeploy-latest-fnpu.Dockerfile.2.3 启动容器dockerrun-uroot--namemineru_docker--privilegedtrue\--ipchost\--networkhost\--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\-eVLLM_WORKER_MULTIPROC_METHODspawn\-eMINERU_MODEL_SOURCElocal\-eMINERU_LMDEPLOY_DEVICEascend\-itmineru:npu-vllm-latest\/bin/bash关键参数说明参数作用--device/dev/davinci0~7将 NPU 设备透传到容器内--device/dev/davinci_managerNPU 管理设备--device/dev/devmm_svmNPU 共享虚拟内存--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_METHODspawnAscend 必须使用 spawn 模式MINERU_LMDEPLOY_DEVICEascend即使使用 vllm 也必须设置MINERU_MODEL_SOURCElocal使用镜像内已下载的模型2.4 容器内使用# 命令行解析 PDFmineru-pinput.pdf-ooutput/-bhybrid-auto-engine# 启动 API 服务mineru-api--host0.0.0.0--port8000# 启动 OpenAI 兼容服务mineru-openai-server--port30000# 启动 Gradio Web UImineru-gradio--host0.0.0.0--port7860310p 设备需额外参数不支持图模式和 bf16mineru-openai-server--port30000--enforce-eager--dtypefloat16三、宿主机显卡驱动依赖是的必须考虑宿主机驱动。这是昇腾 NPU 部署与 NVIDIA GPU 部署的一个核心区别。宿主机必须预装的组件组件说明作用Ascend NPU 驱动(Driver)驱动版本 23.0.3提供/dev/davinci*设备节点CANN Toolkit通常已打包在基础镜像内提供 NPU 算子库类似 CUDAnpu-smi随驱动安装NPU 监控工具类似 nvidia-smiDCMI随驱动安装设备管理接口容器与宿主机的驱动关系┌──────────────────────────────────────────┐ │ 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 DriverAscend Driver内核级驱动CUDA ToolkitCANN Toolkit计算框架/算子库cuDNNCANN 中的算子库深度学习算子torch.cudatorch_npuPyTorch NPU 后端vllm (GPU)vllm-ascendVLM 推理引擎nvidia-sminpu-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与之匹配的 PyTorchvllm-ascend v0.11.0所以 CANN 版本由基础镜像决定而非 Dockerfile 直接指定。宿主机驱动的兼容性宿主机的 Ascend Driver 版本需要与镜像内的 CANN Toolkit 版本兼容。通常Ascend Driver 版本 CANN Toolkit 要求的最低版本即可官方测试平台使用 Driver 23.0.3建议使用与基础镜像发布时间相近的驱动版本六、现有的 torch、模型文件是否支持 CANNNPUPyTorch 层面MinerU 在 NPU 上通过torch_npu运行代码中已有完善的适配# 自动检测 NPU 设备importtorch_npuiftorch_npu.npu.is_available():devicenpu# NPU 特定初始化ifstr(device).startswith(npu):torch_npu.npu.set_compile_mode(jit_compileFalse)模型文件层面模型文件权重是硬件无关的。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 基本一致七、总结部署核心流程宿主机安装Ascend NPU 驱动Driver 23.0.3构建镜像docker build -f npu.Dockerfile基础镜像已包含 CANN torch_npu vllm启动容器时挂载驱动目录和透传 NPU 设备容器内运行MinerU 命令版本关系核心结论问题结论Dockerfile 是否指定 CANN 版本否但基础镜像隐式锁定了 CANN 版本宿主机需要安装什么只需 Ascend Driver npu-smiCANN 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、算子不支持等。难点 2CANN 安装包获取和安装CANN 不是通过 pip 安装的而是需要下载.run安装包# 需要安装 3 个包910B 场景wgethttps://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.1/Ascend-cann-toolkit_8.5.1_linux-aarch64.runwgethttps://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.1/Ascend-cann-910b-ops_8.5.1_linux-aarch64.runwgethttps://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.1/Ascend-cann-nnal_8.5.1_linux-aarch64.runchmodx *.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 大小。难点 3torch_npu 的版本匹配根据 Ascend/pytorch 官方仓库的版本匹配表截至 2025 年CANN 版本支持的 PyTorch 版本对应 torch_npu 版本CANN 8.5.02.6.0 / 2.7.1 / 2.8.0 / 2.9.02.6.0.post5 / 2.7.1.post2 / 2.8.0.post2 / 2.9.0CANN 8.3.RC12.6.0 / 2.7.1 / 2.8.0 / 2.1.02.6.0.post3 / 2.7.1 / 2.8.0 / 2.1.0.post17CANN 8.2.RC12.5.1 / 2.6.02.5.1.post1 / 2.6.0CANN 8.1.RC12.4.0 / 2.5.12.4.0.post4 / 2.5.1MinerU 要求 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 infoCANN 版本影响CANN 版本直接决定可用的算子算子就是类似 cuDNN 的概念如果 CANN 版本太低某些模型所需的算子可能不存在导致运行时报错vllm-ascend v0.11.0 要求 CANN 8.1.RC1固件版本固件Firmware版本需要与 Driver 版本匹配固件是烧录在 NPU 硬件中的低层程序一般由运维人员更新8.3 推荐的两种路线路线 A基于官方基础镜像制作内网镜像推荐这是最省心的方案在能访问外网的昇腾机器上构建然后导出镜像# 步骤 1在有外网的昇腾机器上构建wgethttps://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/npu.Dockerfiledockerbuild--networkhost-tmineru:npu-vllm-latest-fnpu.Dockerfile.# 步骤 2导出镜像为 tar 文件dockersave mineru:npu-vllm-latest-omineru-npu-vllm.tar# 步骤 3拷贝到内网环境scpmineru-npu-vllm.tar userinternal-host:/path/# 步骤 4在内网昇腾机器上加载镜像dockerload-imineru-npu-vllm.tar# 步骤 5启动容器同前述 docker run 命令dockerrun... 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_npu2.6.0.post5# 步骤 3创建 conda 环境conda create-nminerupython3.11conda activate mineru# 步骤 4安装 PyTorchpipinstalltorch2.6.0# 步骤 5安装 torch_npu需要提前下载好 wheel 包pipinstalltorch_npu2.6.0.post5# 步骤 6安装 vllm-ascend需要提前下载好pipinstallvllm0.11.0 pipinstallvllm-ascend0.11.0# 步骤 7安装 MinerU需要提前下载好所有依赖 wheel 包pipinstallmineru[core]3.0.0numpy1.26.4 opencv-python4.11.0.86# 步骤 8下载模型文件并拷贝到内网# 需要在有网机器上运行# mineru-models-download -s modelscope -m all# 然后将 ~/.mineru/models/ 目录整体打包拷贝到内网# 步骤 9设置环境变量source/usr/local/Ascend/ascend-toolkit/set_env.shsource/usr/local/Ascend/nnal/atb/set_env.shexportMINERU_MODEL_SOURCElocalexportMINERU_LMDEPLOY_DEVICEascendexportVLLM_WORKER_MULTIPROC_METHODspawn8.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 架构必须是 aarch64uname-m# 2. 确认 NPU 型号npu-smi info# 3. 确认 Driver 版本需要 23.0.3npu-smi info|head-5# 4. 确认 CANN 版本如果已安装cat/usr/local/Ascend/ascend-toolkit/version.info2/dev/null||echoCANN 未安装# 5. 确认 NNAL 是否安装libatb.sofind/usr/local/Ascend-namelibatb.so2/dev/null||echoNNAL 未安装# 6. 确认 Python 版本python3--version# 7. 确认 Docker 版本docker--version# 8. 确认设备节点是否存在ls/dev/davinci*2/dev/null||echoNPU 设备节点不存在根据以上输出结果再决定走路线 A 还是路线 B。