在ModelArts中使用自定义镜像前,需在ECS服务器上以ModelArts官方镜像或第三方镜像为基础编写Dockerfile,构建镜像、推送到容器镜像服务SWR、注册到ModelArts,最后创建Notebook验证。
本文以Ubuntu 20.04系统的ECS(Snt9b镜像)为例,介绍安装昇腾相关软件(PyTorch+Ascend)并构建Notebook自定义镜像的完整流程。
前提条件
在使用ModelArts前,需完成华为云账号注册、实名认证及相关权限授权。具体操作,请参见一、前置准备:账号与权限。
Notebook自定义镜像规范约束
制作自定义镜像时,基础镜像需满足如下规范:
自定义镜像构建流程

- 准备一台Linux服务器,本文以ECS服务器为例。
- 在ECS中构建自定义镜像(本文提供Dockerfile样例文件)。
- 将构建的镜像推送到SWR。
- 注册SWR镜像到ModelArts。
- 创建Notebook并验证新镜像。
步骤一:准备ECS服务器并配置环境信息
在弹性云服务器(ECS)控制台购买一台ARM架构的Ubuntu系统服务器,并配置弹性公网IP。
由于昇腾NPU仅支持ARM架构,因此需选择ARM架构的ECS。
- 登录ECS控制台,在“弹性云服务器”页面右上角,单击“购买弹性云服务器”。
本文以自定义购买为例,“CPU架构”选择“鲲鹏计算”(即ARM架构),“操作系统”选择Ubuntu 20.04或22.04版本,其他参数按需配置。具体操作,请参见自定义购买ECS。
- 通过CloudShell或VNC登录ECS。具体操作,请参见登录Linux ECS。
- 在ECS中,执行以下命令,安装Docker。
wget https://cnnorth4-modelarts-sdk.obs.cn-north-4.myhuaweicloud.com/modelarts/custom-image-build/install_docker_on_ubuntu.sh
bash install_docker_on_ubuntu.sh
source /etc/profile
安装完成后,执行以下命令,查看Docker运行状态。
systemctl status docker
如果回显中显示“active (running)”,表示Docker正常运行。
图1 查看Docker运行状态
- (可选)执行以下命令,查看Docker Engine版本。
docker version | grep -A 1 Engine
如果回显中显示版本号,表示Docker Engine安装成功。
图2 查看Docker Engine版本
步骤二:制作自定义镜像
本节介绍如何通过Dockerfile安装必需软件包,并构建新的Notebook镜像。
- 昇腾相关软件包:Miniconda3、torch、torch-npu、cann-toolkit、cann-910b-ops。
- PyTorch框架依赖包:torchvision、torchaudio、numpy。
- Notebook依赖包:ipykernel。
- 查询基础镜像,用于编写Dockerfile文件(第三方镜像可跳过此步骤)。
获取ModelArts官方镜像地址,请参见ModelArts官方镜像。
- 连接容器镜像服务。
- 登录容器镜像服务控制台,选择左侧导航栏的“总览”,单击页面右上角的“登录指令”,在弹出的页面中单击复制登录指令。
登录指令用于完成Docker客户端与SWR之间的鉴权,后续才能push镜像。
图3 获取登录指令
按需选择有效时长。如果需要长期有效的登录指令,请参见获取长期有效登录指令。获取了长期有效的登录指令后,在有效期内的临时登录指令仍然可以使用。
- 在安装Docker的服务器中执行上一步复制的登录指令。登录成功会显示“Login Succeeded”。
- 编写容器镜像Dockerfile文件。
Dockerfile是一个文本文件,包含一系列指令,用于自动构建Docker镜像。通过Dockerfile定义镜像的构建过程,包括基础镜像、安装的软件包、配置文件的复制、环境变量的设置等。
- ModelArts官方镜像的Dockerfile文件示例(HCE系统):
# ModelArts官方镜像地址,可按需替换
FROM swr.cn-southwest-2.myhuaweicloud.com/atelier/pytorch_ascend:pytorch_2.7.1-cann_8.5.2-py_3.12-hce_2.0.2512-aarch64-snt9b23-20260417112518-aabfd52
# section1: 使用yum源 + 安装系统依赖
USER root
RUN yum install -y zip wget ca-certificates vim python3 python3-pip tzdata openssh-server && \
ln -fs /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
RUN rm /bin/sh && ln -s /bin/bash /bin/sh
# section2: 清除基础镜像自带的 CANN 8.5.2
RUN sed -i '/Ascend.*set_env\.sh/d' /etc/bashrc /etc/profile /etc/profile.d/*.sh /home/ma-user/.bashrc 2>/dev/null || true && \
rm -rf /usr/local/Ascend/ascend-toolkit /usr/local/Ascend/cann-* /usr/local/Ascend/latest && \
rm -rf /usr/local/Ascend/nnae /usr/local/Ascend/tfplugin /usr/local/Ascend/toolbox && \
rm -rf /usr/local/Ascend/driver/lib64/plugin 2>/dev/null || true
ENV ASCEND_AICPU_PATH="" \
ASCEND_OPP_PATH="" \
TOOLCHAIN_HOME="" \
ASCEND_HOME_PATH="" \
ASCEND_TOOLKIT_HOME=""
USER ma-user
# section3: 以 ma-user 身份安装 Miniconda3(aarch64版本,如已存在则跳过)
RUN if [ ! -d /home/ma-user/anaconda3 ]; then \
cd /home/ma-user/ && \
wget --no-check-certificate https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-aarch64.sh && \
bash Miniconda3-latest-Linux-aarch64.sh -b -p /home/ma-user/anaconda3 && \
rm -rf Miniconda3-latest-Linux-aarch64.sh; \
else \
echo "anaconda3 already exists, skip installation"; \
fi
# section4: 配置 pip 清华镜像源 + 初始化 conda + 清除基础镜像的清华conda源
RUN rm -f /home/ma-user/.condarc /home/ma-user/.condarc.bak && \
mkdir -p /home/ma-user/.pip && \
echo -e "[global]\nindex-url = https://pypi.tuna.tsinghua.edu.cn/simple\n[install]\ntrusted-host = pypi.tuna.tsinghua.edu.cn" > /home/ma-user/.pip/pip.conf && \
/home/ma-user/anaconda3/bin/conda init bash && \
source /home/ma-user/anaconda3/bin/activate base && \
conda config --remove-key channels 2>/dev/null || true && \
conda config --remove-key default_channels 2>/dev/null || true
# section5: 创建 PyTorch 2.6.0 专属 conda 虚拟环境(Python 3.9)+ 安装 torch/torch_npu
RUN /bin/bash -c '\
source /home/ma-user/anaconda3/bin/activate base && \
conda create -y -n pytorch_2_6 python=3.9.18 && \
conda run -n pytorch_2_6 \
pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn \
torchvision==0.21.0 torchaudio==2.6.0 numpy==1.26.4 && \
cd /home/ma-user && \
wget --no-check-certificate https://download.pytorch.org/whl/cpu/torch-2.6.0%2Bcpu-cp39-cp39-manylinux_2_28_aarch64.whl && \
conda run -n pytorch_2_6 pip install torch-2.6.0+cpu-cp39-cp39-manylinux_2_28_aarch64.whl && \
wget --no-check-certificate https://gitcode.com/Ascend/pytorch/releases/download/v7.3.0-pytorch2.6.0/torch_npu-2.6.0.post5-cp39-cp39-manylinux_2_28_aarch64.whl && \
conda run -n pytorch_2_6 pip install torch_npu-2.6.0.post5-cp39-cp39-manylinux_2_28_aarch64.whl && \
conda run -n pytorch_2_6 pip install protobuf==3.20 && \
rm -f torch-2.6.0+cpu-cp39-cp39-manylinux_2_28_aarch64.whl torch_npu-2.6.0.post5-cp39-cp39-manylinux_2_28_aarch64.whl \
'
# section6: 在 pytorch_2_6 conda 环境中安装 CANN toolkit/ops
RUN /bin/bash -c '\
source /home/ma-user/anaconda3/bin/activate base && \
conda run -n pytorch_2_6 \
pip install ascend-cann-toolkit==8.5.0 \
--extra-index-url https://ascend.devcloud.huaweicloud.com/cann/pypi/simple \
--trusted-host ascend.devcloud.huaweicloud.com && \
conda run -n pytorch_2_6 \
pip install ascend-cann-910b-ops==8.5.0 \
--extra-index-url https://ascend.devcloud.huaweicloud.com/cann/pypi/simple \
--trusted-host ascend.devcloud.huaweicloud.com \
'
# section7: notebook所需安装包
RUN /bin/bash -c '\
source /home/ma-user/anaconda3/bin/activate base && \
conda run -n pytorch_2_6 \
pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn \
ipykernel==6.7.0 \
'
# section8: 设置环境变量(CANN装在pytorch_2_6 conda环境的site-packages下)
ENV CANN_HOME=/home/ma-user/anaconda3/envs/pytorch_2_6/lib/python3.9/site-packages/ascend/cann-8.5.0
ENV PATH=/home/ma-user/anaconda3/envs/pytorch_2_6/bin:${CANN_HOME}/bin:${CANN_HOME}/compiler/ccec_compiler/bin:$PATH \
LD_LIBRARY_PATH=${CANN_HOME}/aarch64-linux/lib64:${CANN_HOME}/aarch64-linux/lib64/plugin/opskernel:${CANN_HOME}/aarch64-linux/lib64/plugin/nnengine:${CANN_HOME}\:opp/built-in/op_impl/ai_core/tbe/op_tiling/lib/linux/aarch64:$LD_LIBRARY_PATH/tools/aml/lib64:$LD_LIBRARY_PATH/tools:$LD_LIBRARY_PATH \
PYTHONPATH=${CANN_HOME}/python/site-packages:${CANN_HOME}/opp/op_impl/built-in/ai_core/tbe:$PYTHONPATH \
ASCEND_AICPU_PATH=${CANN_HOME} \
ASCEND_OPP_PATH=${CANN_HOME}/opp \
ASCEND_HOME_PATH=${CANN_HOME} \
ASCEND_TOOLKIT_HOME=${CANN_HOME} \
TOOLCHAIN_HOME=${CANN_HOME} \
PYTHONUNBUFFERED=1 \
USE_TRITON=0
ENV LD_LIBRARY_PATH=/usr/local/Ascend/toolbox/latest/Ascend-DMI/lib64:/usr/lib/aarch64-linux-gnu/hdf5/serial:/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/ascend-toolkit/latest/lib64:/usr/local/Ascend/ascend-toolkit/latest/compiler/lib64/plugin/opskernel:/usr/local/Ascend/ascend-toolkit/latest/compiler/lib64/plugin/nnengine:/usr/local/Ascend/ascend-toolkit/latest/opp/built-in/op_impl/ai_core/tbe/op_tiling/lib/:$LD_LIBRARY_PATH \
PYTHONPATH=/usr/local/Ascend/ascend-toolkit/latest/tools/ms_fmk_transplt/torch_npu_bridge:/usr/local/Ascend/ascend-toolkit/latest/python/site-packages:$PYTHONPATH
RUN echo "source ${CANN_HOME}/set_env.sh" >> /home/ma-user/.bashrc
USER ma-user
WORKDIR /home/ma-user - 非ModelArts官方镜像的Dockerfile文件示例:
如果拉取非ModelArts官方镜像,访问https://registry-1.docker.io/v2/出现“connection refused”或者“Client.Timeout exceeded”错误,需要配置Docker代理。
- 执行以下命令,编辑配置文件。
vi /etc/docker/daemon.json
- 添加以下配置。
{
"registry-mirrors":[
"https://docker.m.daocloud.io",
"https://docker.jianmuhub.com",
"https://huecker.io",
"https://dockerhub.timeweb.cloud",
"https://dockerhub1.beget.com",
"https://noohub.ru"]
} - 依次执行以下命令使配置生效。
systemctl daemon-reload
systemctl restart docker
FROM ubuntu:20.04
ENV DEBIAN_FRONTEND=noninteractive
# section1: 创建ma-user用户组与用户
USER root
RUN default_user=$(getent passwd 1000 | awk -F ':' '{print $1}') || echo "uid: 1000 does not exist" && \
default_group=$(getent group 100 | awk -F ':' '{print $1}') || echo "gid: 100 does not exist" && \
if [ ! -z "${default_user}" ] && [ "${default_user}" != "ma-user" ]; then \
userdel -r ${default_user}; \
fi && \
if [ ! -z "${default_group}" ] && [ "${default_group}" != "ma-group" ]; then \
groupdel -f ${default_group}; \
fi && \
if ! getent group 100 > /dev/null; then \
groupadd -g 100 ma-group; \
fi && \
useradd -d /home/ma-user -m -u 1000 -g 100 -s /bin/bash ma-user && \
chmod -R 750 /home/ma-user
# section2: 使用标准focal源(arm64架构使用ports源)+ 安装系统Python3和pip
RUN mv /etc/apt/sources.list /etc/apt/sources.list.bak && \
printf "deb http://ports.ubuntu.com/ubuntu-ports/ focal main restricted universe multiverse\n\
deb http://ports.ubuntu.com/ubuntu-ports/ focal-updates main restricted universe multiverse\n\
deb http://ports.ubuntu.com/ubuntu-ports/ focal-backports main restricted universe multiverse\n\
deb http://ports.ubuntu.com/ubuntu-ports/ focal-security main restricted universe multiverse\n" > /etc/apt/sources.list && \
apt-get update && \
apt-get install -y zip wget ca-certificates vim python3 python3-pip tzdata && \
ln -fs /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
dpkg-reconfigure --frontend noninteractive tzdata && \
apt update && echo Y | apt install openssh-server
RUN rm /bin/sh && ln -s /bin/bash /bin/sh
# section3: 以 ma-user 身份安装 Miniconda3(aarch64版本)
USER ma-user
RUN cd /home/ma-user/ && \
wget --no-check-certificate https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-aarch64.sh && \
bash Miniconda3-latest-Linux-aarch64.sh -b -p /home/ma-user/anaconda3 && \
rm -rf Miniconda3-latest-Linux-aarch64.sh
# section4: 配置 conda、pip 清华镜像源 + 初始化 conda
RUN mkdir -p /home/ma-user/.pip && \
echo -e "channels:\nshow_channel_urls: true\ndefault_channels:\n - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main\nremote_read_timeout: 120" > /home/ma-user/.condarc && \
echo -e "[global]\nindex-url = https://pypi.tuna.tsinghua.edu.cn/simple\n[install]\ntrusted-host = pypi.tuna.tsinghua.edu.cn" > /home/ma-user/.pip/pip.conf && \
/home/ma-user/anaconda3/bin/conda init bash && \
source /home/ma-user/anaconda3/bin/activate base && \
conda config --remove-key channels || true && \
conda config --append channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge && \
conda config --append channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main && \
conda tos accept --override-channels -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
# section5: 创建 PyTorch 2.6.0 专属 conda 虚拟环境(Python 3.9)+ 安装 torch/torch_npu
RUN /bin/bash -c '\
source /home/ma-user/anaconda3/bin/activate base && \
conda create -y --override-channels \
-c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge \
-c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main \
-n pytorch_2_6 python=3.9 && \
conda run -n pytorch_2_6 \
pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn \
torchvision==0.21.0 torchaudio==2.6.0 numpy==1.26.4 && \
cd /home/ma-user && \
conda run -n pytorch_2_6 pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn \
torch==2.6.0 && \
wget --no-check-certificate https://gitcode.com/Ascend/pytorch/releases/download/v7.3.0-pytorch2.6.0/torch_npu-2.6.0.post5-cp39-cp39-manylinux_2_28_aarch64.whl && \
conda run -n pytorch_2_6 pip install torch_npu-2.6.0.post5-cp39-cp39-manylinux_2_28_aarch64.whl && \
conda run -n pytorch_2_6 pip install protobuf==3.20 && \
rm -f torch_npu-2.6.0.post5-cp39-cp39-manylinux_2_28_aarch64.whl \
'
# section6: 在 pytorch_2_6 conda 环境中安装 CANN toolkit/ops
RUN /bin/bash -c '\
source /home/ma-user/anaconda3/bin/activate base && \
conda run -n pytorch_2_6 \
pip install ascend-cann-toolkit==8.5.0 \
--extra-index-url https://ascend.devcloud.huaweicloud.com/cann/pypi/simple \
--trusted-host ascend.devcloud.huaweicloud.com && \
conda run -n pytorch_2_6 \
pip install ascend-cann-910b-ops==8.5.0 \
--extra-index-url https://ascend.devcloud.huaweicloud.com/cann/pypi/simple \
--trusted-host ascend.devcloud.huaweicloud.com \
'
# section7: notebook所需安装包
RUN /bin/bash -c '\
source /home/ma-user/anaconda3/bin/activate base && \
conda run -n pytorch_2_6 \
pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn \
ipykernel==6.7.0 \
'
# section8: 设置环境变量(CANN装在pytorch_2_6 conda环境的site-packages下)
ENV CANN_HOME=/home/ma-user/anaconda3/envs/pytorch_2_6/lib/python3.9/site-packages/ascend/cann-8.5.0
ENV PATH=/home/ma-user/anaconda3/envs/pytorch_2_6/bin:${CANN_HOME}/bin:${CANN_HOME}/compiler/ccec_compiler/bin:$PATH \
LD_LIBRARY_PATH=${CANN_HOME}/aarch64-linux/lib64:${CANN_HOME}/aarch64-linux/lib64/plugin/opskernel:${CANN_HOME}/aarch64-linux/lib64/plugin/nnengine:${CANN_HOME}\:opp/built-in/op_impl/ai_core/tbe/op_tiling/lib/linux/aarch64:$LD_LIBRARY_PATH/tools/aml/lib64:$LD_LIBRARY_PATH/tools:$LD_LIBRARY_PATH \
PYTHONPATH=${CANN_HOME}/python/site-packages:${CANN_HOME}/opp/op_impl/built-in/ai_core/tbe:$PYTHONPATH \
ASCEND_AICPU_PATH=${CANN_HOME} \
ASCEND_OPP_PATH=${CANN_HOME}/opp \
ASCEND_HOME_PATH=${CANN_HOME} \
ASCEND_TOOLKIT_HOME=${CANN_HOME} \
TOOLCHAIN_HOME=${CANN_HOME} \
PYTHONUNBUFFERED=1 \
USE_TRITON=0
ENV LD_LIBRARY_PATH=/usr/local/Ascend/toolbox/latest/Ascend-DMI/lib64:/usr/lib/aarch64-linux-gnu/hdf5/serial:/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/ascend-toolkit/latest/lib64:/usr/local/Ascend/ascend-toolkit/latest/compiler/lib64/plugin/opskernel:/usr/local/Ascend/ascend-toolkit/latest/compiler/lib64/plugin/nnengine:/usr/local/Ascend/ascend-toolkit/latest/opp/built-in/op_impl/ai_core/tbe/op_tiling/lib/:$LD_LIBRARY_PATH \
PYTHONPATH=/usr/local/Ascend/ascend-toolkit/latest/tools/ms_fmk_transplt/torch_npu_bridge:/usr/local/Ascend/ascend-toolkit/latest/python/site-packages:$PYTHONPATH
RUN echo "source ${CANN_HOME}/set_env.sh" >> /home/ma-user/.bashrc
USER ma-user
WORKDIR /home/ma-user
- 构建容器镜像。
在Dockerfile文件目录中,执行以下命令,构建容器镜像。命令中的SWR镜像地址请按需修改。构建时间取决于网络带宽和镜像大小,大约30分钟。
docker build -t swr.cn-southwest-2.myhuaweicloud.com/dev-custom/pytorch2_6-cann8.5.0:v2 -f Dockerfile .
如果回显中显示“Successfully built”和“Successfully tagged”,表示镜像构建成功。
图4 容器镜像构建成功
步骤三:将镜像推送到SWR
- 执行以下命令,将本地构建的镜像上传到SWR。
docker push swr.cn-southwest-2.myhuaweicloud.com/dev-custom/pytorch2_6-cann8.5.0:v2
如果回显中显示“digest”和SHA256哈希值,表示镜像已成功上传到SWR。

- 在SWR控制台左侧导航栏,单击“我的镜像”,执行刷新操作后显示新增的镜像,单击镜像名称,可查看镜像详情。
图5 查看镜像详情
步骤四:在ModelArts注册新镜像
将新镜像注册到ModelArts镜像管理服务中,以便在ModelArts中使用该镜像。具体操作,请参见镜像注册与管理。
镜像源即为步骤三推送到SWR中的镜像。上述安装包均在ARM架构镜像下完成,因此架构类型选择ARM,类型选择NPU,规格选择Snt9b。
图6 注册镜像
步骤五:创建Notebook并验证新镜像
- 创建Notebook实例。
- 在ModelArts管理控制台左侧导航栏,按需选择以下操作,进入Notebook管理页面。
- 新版控制台:选择,进入“Notebook”页面。
- 旧版控制台:选择,进入“Notebook”页面。
- 在“Notebook”页面右上角,单击“创建”。
在“资源配置”区域,实例规格选择NPU;在“环境配置”区域,选择“自定义镜像”,单击
图标,选择步骤四注册的镜像及版本,WebIDE选择JupyterLab。
当Notebook实例的“状态”显示为“运行中”,表示Notebook实例创建成功。
- 在“Notebook”页面,单击操作列的“接入环境”,在“接入方式”对话框,单击JupyterLab接入右侧的“接入”。
- 在“ModelArts Launcher”页面的Notebook区域,单击pytorch_2_6,创建一个ipynb文件。
图8 打开pytorch_2_6
- 执行以下命令,导入PyTorch库,查看PyTorch版本号。
import torch
print(torch.__version__)
显示版本如下,表示PyTorch安装成功。
图9 查看PyTorch版本号
- 在“ModelArts Launcher”页面的Other区域,单击Terminal,执行以下命令,验证PyTorch框架和torch_npu插件是否安装成功。详情请参见PyTorch Ascend安装部署。
图10 打开Terminal
python3 -c "import torch;import torch_npu; a = torch.randn(3, 4).npu(); print(a + a);"
返回如下类似信息,表示安装成功。
tensor([[-0.6066, 6.3385, 0.0379, 3.3356],
[ 2.9243, 3.3134, -1.5465, 0.1916],
[-2.1807, 0.2008, -1.1431, 2.1523]], device='npu:0') 图11 PyTorch框架和torch_npu插件安装成功
- 在Terminal执行以下命令,验证CANN包是否安装成功,详情请参见CANN安装部署。
python3 -c "import acl;print(acl.get_soc_name())"
返回“Ascend910B4”表示安装成功。
图12 CANN包安装成功