ModelScope 昇腾Ascend镜像指南为 Atlas NPU 构建与运行 ms-swift 全栈容器环境【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope在 Model-as-a-Service 的工程实践中把推理与训练环境容器化是保证可复现性与快速交付的关键一步。本指南以 ModelScope 仓库中的 docker/ascend/OVERVIEW.ascend.zh.md 为主体系统讲解如何在华为昇腾AscendAtlas NPU 上构建一个开箱即用的 ms-swift 镜像从 CANN 基础镜像选型、组件版本矩阵、tag 命名规范到本地构建参数、Dockerfile 分层安装逻辑、容器运行与 NPU 验证。读完本文你将掌握用一条build_image.py命令产出固定版本 Ascend 镜像、并为 A2/A3 等 Atlas 平台编写可复现构建与运行方案的能力。一、镜像定位面向昇腾 Atlas NPU 的 ms-swift 运行环境ms-swift Ascend 镜像面向华为昇腾 Atlas NPU提供可直接使用的 ms-swift 运行环境。镜像基于 Ascend CANN 容器镜像构建预置了完成 Ascend 推理和训练工作流所需的完整软件栈包括Python版本由基础镜像 tag 决定CANN昇腾异构计算架构继承自基础镜像TorchNPUPyTorch 的昇腾适配层vLLM vLLM AscendNPU 上的大模型推理引擎FLAflash-linear-attention线性注意力加速库Megatron-LM MindSpeed mcore-bridge大模型分布式训练组件ms-swift 与 ModelScope 运行组件从实现上看这套环境由 docker/ascend/Dockerfile.ascend 模板在构建时渲染生成最终落地为一个可直接docker run的镜像。镜像的推理侧vLLM Ascend与训练侧Megatron/MindSpeed/ms-swift是同时装配的这与 GPU 镜像只侧重单一工作流的做法不同——它明确服务于在昇腾 NPU 上完整跑通 ms-swift 训练与推理这一目标。二、快速参考构建入口与默认配置构建和使用该镜像涉及以下关键要素要素取值基础镜像quay.io/ascend/cann:cann-version-hardware-os-pypython-version构建模板docker/ascend/Dockerfile.ascend构建入口docker/build_image.py --image_type ascend默认基础镜像quay.io/ascend/cann:8.5.1-a3-ubuntu22.04-py3.11支持的基础 OSUbuntu 与 openEuler由 CANN 基础镜像 tag 选择默认输出 tag${DOCKER_REGISTRY}:main-cann8.5.1-torch_npu2.9.0.post2-a3-ubuntu22.04-py3.11-archAscend runtime 环境/usr/local/Ascend/ascend-toolkit/set_env.shNNAL/ATB 环境若镜像内存在/usr/local/Ascend/nnal/atb/set_env.sh在源码层面构建入口的分发逻辑位于 docker/build_image.py 末尾args.image_type.lower() ascend时会实例化AscendImageBuilder并调用其__call__流程生成 Dockerfile → 保存到根目录 → 构建 → push。注意两个细节AscendImageBuilder继承自StableGPUImageBuilder但完全重写了 Dockerfile 生成与 tag 逻辑Ascend 路径并不会复用 GPU 模板其push()方法直接返回 0docker/build_image.py即当前 Ascend 镜像分支只构建、不执行 push发布动作由 CI 另行完成。两个set_env.sh会被写入镜像内的/root/.bashrc见 docker/ascend/Dockerfile.ascend进入容器即自动加载 CANN 与 NNAL/ATB 环境无需手动 source。三、镜像内容全览组件版本矩阵Ascend Dockerfile 安装与配置的组件及其版本来源如下组件版本 / 来源CANN继承自选定的quay.io/ascend/cann基础镜像可通过--base_image配置Python继承自基础镜像 tag例如py3.11通过--base_image选择匹配的 Python tagPyTorch默认torch2.9.0可通过--torch_version配置同时需要传入匹配的--torchvision_version和--torchaudio_versionTorchNPU默认torch_npu2.9.0.post2可通过--torch_npu_version配置但必须与 PyTorch 基础版本匹配torchvision / torchaudio默认torchvision0.24.0、torchaudio2.9.0覆盖--torch_version时可通过--torchvision_version和--torchaudio_version配置vLLM默认从官方vllm-project/vllm源码 tagv0.18.0构建可通过--vllm_version配置使用 empty target devicevLLM Ascend默认从官方vllm-project/vllm-ascend源码 tagv0.18.0构建可通过--vllm_ascend_version配置会初始化 submodule构建与运行依赖以华为云 Ascend PyPI 为主索引、官方 PyPI 为备用索引FLA从fla-org/flash-linear-attention源码 checkout默认main分支可通过--fla_version指定分支或 release tagMegatron-LM源码 checkout默认分支v0.15.3可通过--megatron_branch配置MindSpeed源码 checkout默认分支core_r0.15.3可通过--mindspeed_branch配置mcore-bridge从modelscope/mcore-bridge源码 checkout 并以 editable 模式安装默认main分支可通过--mcore_bridge_branch指定分支或 release tagms-swift来自modelscope/ms-swift的源码 checkout默认分支main可通过--swift_branch配置DeepSpeed安装满足deepspeed0.19的最新发布包TORCH_DEVICE_BACKEND_AUTOLOAD0仅作用于构建时的安装命令ModelScope通过pip install -U modelscope安装 PyPI 最新发布包Ascend 镜像不再 clone ModelScope 或 modelscope-hub 源码仓库triton-ascend在 vLLM 之前安装并在所有 editable 安装完成后再次固定版本安装时以华为云 Ascend PyPI 为主索引、官方 PyPI 为备用索引CANN8.5.*默认3.2.0、CANN9.0.*默认3.2.1可通过--triton_ascend_version配置这张表的默认值在 docker/build_image.py 中以类常量形式集中定义_DEFAULT_TORCH_VERSION 2.9.0、_DEFAULT_TORCH_NPU_VERSION 2.9.0.post2、_DEFAULT_VLLM_VERSION 0.18.0、_DEFAULT_TRITON_ASCEND_VERSIONS {8.5: 3.2.0, 9.0: 3.2.1}等。理解几个关键设计ModelScope 走 PyPI 发布包而非源码 cloneDockerfile 中pip install --no-cache-dir -U modelscopedocker/ascend/Dockerfile.ascend明确注释不要把镜像绑定到源码仓库快照上保证镜像始终携带最新发布版本vLLM 以 empty target device 构建VLLM_TARGET_DEVICEemptydocker/ascend/Dockerfile.ascend避免在无 GPU 环境下编译 CUDA 算子triton-ascend 安装两段式先于 vLLM 安装docker/ascend/Dockerfile.ascend待所有 editable 安装完成后再强制重装固定版本docker/ascend/Dockerfile.ascend防止 vllm-ascend 的依赖解析覆盖掉 CANN 专用版本移除 CUDA-only 依赖构建末尾会卸载flashinfer、tvm-ffi、torch-c-dlpack-extdocker/ascend/Dockerfile.ascend这些由 vLLM 引入的包在 NPU 上会引发missing libtorch_cuda.so错误。四、镜像 Tag 规范通过docker/build_image.py --image_type ascend构建的镜像使用以下 tag 格式${DOCKER_REGISTRY}:swift-branch-cann-version-tag-torch_npuTorchNPU-version-hardware-tag-os-tag-python-tag-arch各字段含义与解析方式字段示例说明swift-branchmain构建镜像时使用的 ms-swift 分支cann-version-tagcann8.5.1、cann9.0.0从 CANN 基础镜像 tag 解析TorchNPU-version2.9.0.post2来自--torch_npu_version默认2.9.0.post2hardware-tag910b、a3、950直接从 CANN 基础镜像 tag 解析当前对应的 Atlas 平台名称为a2、a3、a5仅用于文档说明不参与 tag 映射os-tagubuntu22.04、openeuler24.03从 CANN 基础镜像 tag 解析避免不同 OS 的镜像 tag 冲突python-tagpy3.11从 CANN 基础镜像 tag 解析archaarch64、x86_64从宿主机架构或--arch推导A2 / CANN 9.0.0 示例CANN 硬件 tag 为910b${DOCKER_REGISTRY}:main-cann9.0.0-torch_npu2.9.0.post2-910b-ubuntu22.04-py3.11-aarch64Tag 生成逻辑与基础镜像解析逻辑在源码中一一对应_get_cann_image_tags()docker/build_image.py把基础镜像 tag 按-拆成cann_version-hardware-os_tag-pyversion四段并对每一段做正则校验CANN 版本、硬件 tag、OS tag、Python tag 任一非法都会直接抛ValueError_normalize_arch()docker/build_image.py将x86/amd64规范化为x86_64、arm/aarch64/arm64规范化为aarch64image()方法docker/build_image.py按上述字段拼接 tag 并统一转为小写。已发布的 tag 索引见仓库内 docker/ascend/supported_tags.md该文件按 ms-swift 版本分组列出了活跃 tag、对应 Dockerfile 与镜像包含内容toolkit/ops/nnal/torch_npu/ms-swift/vllm-ascend/mindspeed例如v4.5.2-cann9.1.0-torch_npu2.10.0.post2-a3-ubuntu22.04-py3.12。五、本地构建 Ascend 镜像5.1 最小构建命令构建前先设置目标镜像仓库。构建脚本会把 docker/ascend/Dockerfile.ascend 渲染成根目录Dockerfile然后执行docker buildAscend 镜像分支当前不执行 push。export DOCKER_REGISTRYregistry.example.com/ms-swift/ms-swift python docker/build_image.py \ --image_type ascend5.2 完整固定版本参考以下示例固定了 CANN 9.1.0、Atlas A2、Ubuntu 22.04、Python 3.12、ARM64 的完整版本矩阵适合作为生产环境的可复现构建基线export DOCKER_REGISTRYregistry.example.com/ms-swift/ms-swift python docker/build_image.py \ --image_type ascend \ --base_image quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12 \ --soc_version ascend910b1 \ --arch arm \ --torch_version 2.10.0 \ --torch_npu_version 2.10.0.post2 \ --torchvision_version 0.25.0 \ --torchaudio_version 2.10.0 \ --vllm_version v0.23.0 \ --vllm_ascend_version v0.23.0 \ --fla_version main \ --triton_ascend_version 3.2.2 \ --modelscope_branch master \ --swift_branch v4.5.2 \ --megatron_branch core_v0.16.0 \ --mindspeed_branch core_r0.16.0 \ --mcore_bridge_branch v1.6.2渲染机制解读AscendImageBuilder.generate_dockerfile()docker/build_image.py读取模板后用str.replace依次替换{base_image}、{soc_version}、{cann_version}、{torch_version}、{torch_npu_version}、{vllm_git_ref}、{vllm_ascend_git_ref}、{triton_ascend_version}、{fla_version}、{swift_branch}、{megatron_branch}、{mindspeed_branch}、{mcore_bridge_branch}等占位符随后_save_dockerfile()将渲染结果写入根目录Dockerfile再执行docker build -t tag -f Dockerfile .。六、自定义构建参数详解使用--image_type ascend选择 Ascend 构建器后以下参数实际生效参数默认值说明--base_imagequay.io/ascend/cann:8.5.1-a3-ubuntu22.04-py3.11选择 CANN、硬件、OS 和 Pythontag 必须符合cann-version-hardware-os-pypython-version格式--soc_versionascend910_9391设置 vLLM Ascend 构建的目标 SoC 和运行时SOC_VERSION必须与目标硬件匹配--arch根据宿主机自动检测可选arm或x86输出 tag 中会规范化为aarch64或x86_64--torch_version2.9.0选择 PyTorch覆盖时必须同时传入匹配的--torchvision_version和--torchaudio_version--torch_npu_version2.9.0.post2基础版本必须与--torch_version完全一致--torchvision_version0.24.0选择 torchvision覆盖--torch_version时必须显式传入--torchaudio_version2.9.0选择 torchaudio覆盖--torch_version时必须显式传入--vllm_version0.18.0选择官方 vLLM 源码 tag可以带或不带前置v--vllm_ascend_version0.18.0选择官方 vLLM Ascend 源码 tag可以带或不带前置v--fla_versionmain选择 FLA 分支或 release tag--triton_ascend_version取决于 CANN 版本CANN 8.5 使用3.2.0CANN 9.0 使用3.2.1其他 CANN 系列包括 9.1必须显式传入--pip_extra_index_url华为云 Ascend PyPI设置 Ascend 特定依赖的主索引--pypi_official_index_urlhttps://pypi.org/simple设置备用包索引--swift_branchmain选择 ms-swift 源码分支或 tag并写入输出镜像 tag--megatron_branchv0.15.3选择 Megatron-LM 源码分支或 tag--mindspeed_branchcore_r0.15.3选择 MindSpeed 源码分支或 tag--mcore_bridge_branchmain选择 mcore-bridge 源码分支或 release tag并以 editable 模式安装--soc_version的可选参考值来自 vLLM Ascend 上游安装文档表示其构建目标不代表本 Dockerfile 已验证全部硬件路径Atlas A2ascend910b1Atlas A3ascend910_9391Atlas 300I DUOascend310p1Atlas 950DTascend950dt_9582两个容易踩坑的特殊规则源码中有明确校验Python 版本必须通过--base_image选择Ascend 镜像的--python_version不会生效。AscendImageBuilder._generate_python_tag()docker/build_image.py直接返回从基础镜像 tag 解析出的ascend_python_tag绕过了父类的 Python 版本生成逻辑--modelscope_branch无效虽然共用参数解析器接受该参数但 Ascend Dockerfile 不使用它当前通过pip install -U modelscope安装 ModelScope 最新发布包。版本一致性校验_init_torch_versions()docker/build_image.py只覆盖--torch_version而未同时传--torchvision_version/--torchaudio_version→ 抛错只传--torchvision_version/--torchaudio_version而未显式指定--torch_version→ 抛错--torch_npu_version必须匹配正则^(?Ptorch_version\d\.\d\.\d)(?:\.post\d)?$且其基础版本如2.10.0必须与--torch_version完全一致否则抛错。triton-ascend 的默认版本推导_init_component_versions()docker/build_image.py取 CANN 版本的前两段如9.1在默认映射表中查找查不到例如 CANN 9.1就会报错并要求显式传入--triton_ascend_version——这也是上面完整示例中显式指定3.2.2的原因。七、构建流程源码级解读了解 docker/ascend/Dockerfile.ascend 的分层安装顺序有助于在自定义参数时预判可能出现的问题。整体流程如下系统依赖按/etc/os-release判断 OS 家族。Ubuntu 走apt-getgcc/cmake/ninja-build/libnuma-dev/libgl1 等openEuler 走yum对应 RPM 包不支持的 OS 直接exit 1docker/ascend/Dockerfile.ascendpip 全局源切换为华为云 PyPI 镜像docker/ascend/Dockerfile.ascendPyTorch TorchNPUx86_64 从https://download.pytorch.org/whl/cpu安装 CPU 版 torch/torchvision/torchaudioaarch64 从华为云镜像安装随后以华为云 Ascend PyPI 为主索引、官方 PyPI 为备用索引安装torch_npu{torch_npu_version}docker/ascend/Dockerfile.ascendtriton-ascend 预装先卸载可能存在的triton/triton-ascend再强制重装指定版本docker/ascend/Dockerfile.ascendvLLM从官方源码 tag 克隆到/vllmVLLM_TARGET_DEVICEempty下以 editable 模式安装docker/ascend/Dockerfile.ascendvLLM Ascend克隆到/vllm-ascend并git submodule update --init --recursive以华为云 Ascend PyPI 为主索引 editable 安装docker/ascend/Dockerfile.ascend训练侧源码克隆 Megatron-LM/Megatron-LM、MindSpeed/MindSpeed来自 Ascend 官方仓库、mcore-bridge/mcore-bridge、ms-swift/ms-swiftGIT_LFS_SKIP_SMUDGE1跳过 LFS 大文件docker/ascend/Dockerfile.ascend核心训练组件安装MindSpeed 与 mcore-bridge 以 editable 安装pip install -U modelscope装最新发布包ms-swift 以 editable 安装docker/ascend/Dockerfile.ascend重新固定 torch 与 torch_npu由于 editable 安装可能改写依赖此处按架构区分强制重装 CPU 版 torch 系列并重装匹配的 torch_npudocker/ascend/Dockerfile.ascend移除 CUDA-only 包docker/ascend/Dockerfile.ascendSwift 附加组件pip、icecream、funasr、qwen 系列工具、transformers/accelerate/peft/trl 等以及/ms-swift/requirements/eval.txt、evalscope、ms-agent、diffusers、omegaconf 等docker/ascend/Dockerfile.ascend训练与评估依赖TORCH_DEVICE_BACKEND_AUTOLOAD0 pip install -U deepspeed0.19 ray liger_kernel pre-commit——注意该环境变量只影响构建时安装命令不写入镜像运行时docker/ascend/Dockerfile.ascendFLA从flash-linear-attention源码 checkout 后 editable 安装docker/ascend/Dockerfile.ascend重新固定 triton-ascenddocker/ascend/Dockerfile.ascend运行时自检构建最后一段会检查 editable 包vllm、vllm_ascend、swift、megatron、mindspeed、fla是否确实从保留的源码树解析、modelscope 是否可导入且版本存在、triton-ascend 版本是否与目标一致docker/ascend/Dockerfile.ascend任何一项不满足都会导致构建失败——这是一道重要的可追溯性保障。八、运行 Ascend 容器8.1 宿主机前置条件宿主机需要提前安装兼容的 Ascend driver 和 firmware。容器通过挂载宿主机 NPU 设备与 driver 库来使用昇腾硬件。8.2 docker run 示例docker run --rm -it \ --name ms_swift_ascend \ --device /dev/davinci0 \ --device /dev/davinci_manager \ --device /dev/devmm_svm \ --device /dev/hisi_hdc \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ -v /mnt/workspace:/mnt/workspace \ ${DOCKER_REGISTRY}:main-cann9.0.0-torch_npu2.9.0.post2-910b-ubuntu22.04-py3.11-aarch64 \ bash要点说明--device /dev/davinci0挂载 NPU 设备节点davinci_manager、devmm_svm、hisi_hdc是昇腾运行所需的配套设备driver 相关路径dcmi、npu-smi、lib64、version.info、ascend_install.info必须从宿主机映射进容器否则容器内无法访问 NPU/mnt/workspace建议挂载为数据与模型缓存目录——与镜像内MODELSCOPE_CACHE/mnt/workspace/.cache/modelscope/hub环境变量对应模型下载缓存可持久化。8.3 容器内验证进入容器后依次执行以下命令验证 NPU 与各 Python 组件npu-smi info python -c import torch, torch_npu; print(torch.__version__, torch_npu.__version__) python -c import vllm, vllm_ascend; print(vllm ascend ok) pip show ms-swift modelscope mcore-bridge torch-npu triton-ascendnpu-smi info应能看到 Atlas NPU 设备及其健康状态torch 与 torch_npu 版本号应匹配例如2.9.0 2.9.0.post2vllm/vllm_ascend可正常导入说明推理栈装配完整pip show用于核对各关键组件版本确认镜像与预期矩阵一致。九、环境变量说明镜像预置了以下环境变量与 docker/ascend/Dockerfile.ascend 中的ENV一一对应变量值SOC_VERSION选定的 Ascend SoC例如ascend910b1或ascend910_9391可通过--soc_version配置用于指定 vLLM Ascend 的构建目标并保留在运行时环境中tag 中的硬件字段来自--base_imageCANN_VERSION从基础镜像 tag 解析得到MEGATRON_LM_PATH/Megatron-LMPYTHONPATH包含/Megatron-LMVLLM_USE_MODELSCOPETrueLMDEPLOY_USE_MODELSCOPETrueMODELSCOPE_CACHE/mnt/workspace/.cache/modelscope/hubSOC_VERSION与CANN_VERSION在 Dockerfile 顶部通过构建参数注入ENV SOC_VERSION{soc_version} CANN_VERSION{cann_version}MEGATRON_LM_PATH与PYTHONPATH保证 Megatron-LM 的源码树可在容器内直接 importVLLM_USE_MODELSCOPE/LMDEPLOY_USE_MODELSCOPE使 vLLM 与 LMDeploy 优先从 ModelScope Hub 拉取模型与MODELSCOPE_CACHE配合实现模型缓存的统一管理。十、注意事项与最佳实践结合文档与源码实现使用该镜像时应注意以下几点版本兼容性CANN、firmware 和 driver 版本必须互相兼容任一环节不匹配都可能导致 NPU 设备无法被容器识别系统依赖差异Ubuntu 基础镜像通过apt-get安装系统依赖openEuler 基础镜像通过yum安装对应 RPM 包。选择基础镜像 tag 时需考虑宿主机运维习惯索引优先级不保证triton-ascend 与 vLLM Ascend editable 安装的依赖以华为云 Ascend PyPI 为主索引、官方 PyPI 为备用索引。pip 会汇总所有已配置索引的候选版本并不保证严格的仓库优先级因此请选择与 CANN、Python 和架构兼容的版本必要时显式指定--triton_ascend_versionCUDA-only 包会被移除镜像面向 Ascend NPU 上的 ms-swift 工作流依赖安装过程中引入且与 NPU runtime 冲突的 CUDA-only 包如 flashinfer、tvm-ffi、torch-c-dlpack-ext会被移除不要在这些组件上编写依赖逻辑生产环境使用固定 tag不要依赖浮动分支名如main建议按第五节给出的完整版本矩阵固定所有组件版本并使用固定镜像 tag 交付editable 安装与源码树vLLM、vLLM Ascend、ms-swift、Megatron-LM、MindSpeed、FLA 均为 editable 安装运行时从保留的源码目录解析包如需在镜像内二次开发可直接修改对应源码目录并即时生效。Licensems-swift 和 ModelScope 组件遵循各自上游仓库的 license。CANN、MindSpeed、TorchNPU、vLLM Ascend 以及其他预装第三方组件遵循各自上游 license。在使用镜像进行商业化部署前请自行核对所涉及组件的许可条款。【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考