准备推理镜像

推理镜像规范

部署服务用户镜像需要满足如下镜像规范。

1. 镜像定义的推理接口支持的协议必须是HTTP、HTTPS、WS或WSS，接口协议为HTTPS或WSS时，支持开启TLS认证。
2. 镜像定义的自定义监控采集指标接口支持的协议必须是HTTP或HTTPS，接口协议为HTTPS时，不支持开启双向认证。
3. 镜像定义的HTTP请求健康检查方式的接口支持的协议必须是HTTP或HTTPS，接口协议为HTTPS时，不支持开启双向认证。
4. 镜像定义的推理接口、自定义指标采集接口及健康检查接口支持单独配置接口协议与端口号，可提前在镜像中完成端口分配。
5. 镜像定义的执行命令健康检查方式对命令无限制，可在镜像中按需设计。
6. 在线服务支持代码、密钥挂载，如果镜像中有需要使用代码或密钥配置的地方，可提前在镜像中规划挂载路径。
7. 推理平台本身对镜像大小不做限制要求，镜像要小于购买资源池时选择的容器盘大小，否则会导致启动推理服务时镜像拉取失败。
8. 推理平台本身不对容器启动用户做要求，可以是root用户或ma-user，取决于用户镜像中的设置。

推理镜像制作完整流程

用户可以通过ECS或CCE拉取已有推理业务镜像，或者制作推理业务镜像，再将推理业务镜像推送到SWR，部署推理服务时输入SWR镜像地址即可。

此处直接用CCE集群来制作镜像，是因为CCE节点中默认已安装可用的Containerd。如果希望使用已有的ECS制作镜像，则需要满足以下条件：

• CPU架构根据实际选择，镜像推荐选择EulerOS。
• 机器上已安装可用的Containerd。

步骤一 创建单节点CCE集群

1. 在CCE控制台创建一个Containerd容器的单节点CCE集群。
   1. 登录CCE控制台。在页面左上角处，选择集群部署区域，所选区域与资源部署区域的距离越近，网络时延越低，访问速度越快。

      确认区域后，请单击“购买集群”。如果是首次使用CCE则需要创建委托，请根据页面提示进行处理。

   2. 对集群的基础信息进行配置。关键参数如下，更多参数说明请见购买CCE集群。
      • 集群类型：CCE Standard 集群
      • 集群版本：选择“v1.33”
      • 集群最大管理规模：选择“50节点”
      • 集群 master 实例数：选择“单实例”
      • 容器网络模型：容器隧道网络
      • 容器网段：自动设置网段

      其他参数选择默认或自定义。

2. 创建节点。
   1. 在左侧导航栏中选择“集群管理”，单击上一步创建的集群名称进入集群控制台。
   2. 在集群控制台左侧导航栏中选择“节点管理”，切换至“节点”页签并单击右上角的“创建节点”，在节点配置步骤中设置节点参数。更多参数说明请参见创建节点。
      • 登录方式：选择密码，填入密码
      • 存储配置：系统盘、数据盘大小根据待制作的镜像大小进行评估设置。

      其他参数保持默认。

   3. 单击“下一步：规格确认”，阅读使用说明，确认无误后单击“提交”。

步骤二 创建镜像组织

进入容器镜像服务管理控制台，在总览页，单击右上角“创建组织”，填写组织名称，单击“确定”完成创建。

图1 创建镜像组织

步骤三 在CCE节点中登录SWR

1. 进入弹性公网EIP控制台，在我的EIP页面，单击“购买弹性公网IP”，创建一个临时使用的EIP。

   详情请见获取EIP。

2. 前往CCE服务控制台“集群管理”页面，单击集群名称进入集群详情页，单击“节点管理>节点”，单击步骤一 创建单节点CCE集群中创建的节点名称，在弹框中单击“确定”跳转至ECS服务。
3. 切换至“弹性公网IP”页签，单击“绑定弹性公网IP”，在弹框中勾选前面创建的EIP，单击“确定”进行绑定。
4. 使用PuTTY通过EIP，使用root用户登录CCE节点。具体操作请见登录节点。
   图2 CCE节点登录成功
   

步骤四：编写Dockerfile（可选）

如果用户已经有推理业务镜像，可以跳过此步骤。也可以参考本步骤编写推理镜像的Dockerfile。

制作推理业务镜像时，推荐基于ModelArts提供的官方镜像制作，官方镜像中已预装驱动/CUDA/CANN等必备软件，节省工作。官方镜像不满足诉求时，用户也可以基于其他镜像制作推理业务镜像，满足以上推理镜像规范即可。

ModelArts官方镜像列表请参见文档ModelArts官方镜像。MA官方镜像托管于SWR仓库，可通过以下方式获取：

# 在 ModelArts 控制台> 镜像管理 中查看可用官方镜像列表
# 示例：拉取镜像，此处的镜像地址为示例
docker pull swr.{region}.myhuaweicloud.com/atelier/pytorch_ascend:pytorch_2.7.1-cann_8.5.2-py_3.12-hce_2.0.2512-aarch64-snt9b-20260417112518-aabfd52
#{region}替换为实际区域代码，如cn-north-4、cn-southwest-2等。

基于官方 NPU 推理镜像制作时，以下规范已在官方镜像中预置，无需手动处理：

• 基础系统：已预置
• CANN 软件包：已预装且环境变量已配置
• Python：已预装Python

您只需关注以下核心规范的体现：

• 推理端口：EXPOSE 8080
• 推理接口与健康检查：在推理服务脚本中实现
• 启动入口：ENTRYPOINT设置推理服务启动命令
• 模型加载路径：确保模型加载目录存在，例如：/home/ma-user/model
• 依赖预装：pip install --no-cache-dir
• 日志输出：推理服务代码中输出到 stdout

以下是一个完整的 Dockerfile 示例，并在关键行注释了对应的规范要求：

#拉取ModelArts官方镜像base_image
FROM ${base_image}
# 切换到 root 用户进行安装操作
USER root
# 安装额外系统依
RUN apt-get update && apt-get install -y --no-install-recommends \
    vim \
    curl \
    && rm -rf /var/lib/apt/lists/*
# 安装额外 Python 包（推理框架及依赖），此处依赖及版本仅为举例，请按需安装
RUN pip install --no-cache-dir \
    transformers==4.30.0 \
    accelerate==0.21.0 \
    fastapi==0.100.0 \
    uvicorn==0.23.0
# 复制推理服务脚本，此处inference_server.py举例，请根据实际填写
COPY inference_server.py /home/ma-user/inference_server.py
# 确保 ma-user 目录权限正确
RUN chown -R ma-user:ma-user /home/ma-user
# 确保模型加载路径目录存在，例如：/home/ma-user/model
RUN mkdir -p /home/ma-user/model && chown ma-user:ma-user /home/ma-user/model
# 暴露推理服务端口
EXPOSE 8080
# 切换回 ma-user
USER ma-user
# 设置工作目录
WORKDIR /home/ma-user
# 设置推理服务启动命令
ENTRYPOINT ["python", "/home/ma-user/inference_server.py"]
# 构建新镜像{image}
docker build -t ${image}

步骤五 上传推理镜像至CCE节点

1. 将准备好的镜像加载到CCE节点。

   在CCE节点输入命令：

   ctr image import <镜像包名>

   参数说明：

   <镜像包名>：镜像包的名称，包含后缀名。例如：helloworld-aarch64_1.0.20250322104447.tar

   示例：

   ctr image import helloworld-aarch64_1.0.20250322104447.tar

   图3 导入镜像包成功
   
2. 给加载好的镜像包打tag。

   在CCE节点输入命令：

   ctr image tag <原始包路径> <新包路径>

   参数说明：

   原始包地址：通过ctr image list命令获取。例如：swr.example.myhuaweicloud.com/itep-test-mock/helloworld-aarch64:1.0.20250322104447。

   图4 获取原始包路径
   

   新包路径地址：局点SWR地址/组织名称/镜像名称/tag。例如：swr.ma-region-3.ma03.external.com/yrx/helloworld-aarch64:1.0.20250322104447。

   示例：

   ctr image tag swr.cn-north-7.myhuaweicloud.com/itep-test-mock/helloworld-aarch64:1.0.20250322104447 swr.ma-region-3.ma03.external.com/yrx/helloworld-aarch64:1.0.20250322104447

   图5 镜像包打tag成功
   

步骤六 上传镜像到SWR

在CCE节点输入命令：

ctr image push --user <资源空间名>@<AK>:<登录密钥>  <局点SWR地址>/<组织名称>/<镜像名称>:<tag>

参数说明：

• <资源空间名>：登录管理控制台，单击右上角您的用户名处，单击“个人设置”。在“资源空间列表”页签中查找当前区域对应的资源空间。例如：ma-region-3。
• <AK>的获取方法：
  1. 登录管理控制台，单击右上角您的用户名处，单击“个人设置”。
  2. 在“个人设置”页面，单击“管理访问密钥”页签。
  3. 单击“新增访问密钥”，新建AK/SK。
  4. 单击“确定”，自动下载访问密钥。
  5. 下载成功后，在“credentials”文件中即可获取AK和SK信息。
• <登录密钥>：登录一台linux系统的计算机，执行如下命令获取登录密钥。根据credentials文件中的AK和SK替换$AK和$SK。

  printf "$AK" | openssl dgst -binary -sha256 -hmac "$SK" | od -An -vtx1 | sed 's/[ \n]//g' | sed 'N;s/\n//'

• <局点SWR地址>：填写对应局点的SWR地址。例如：swr.ma-region-3.ma03.external.com。
• <组织名称>：前面步骤中创建的组织名称。例如：yrx。
• <镜像名称>:<tag>：定义镜像名称。示例：helloworld-aarch64:1.0.20250322104447。

示例：

ctr image push --user ma-region-3_test_01@<AK>:<登录密钥>  swr.ma-region-3.ma03.external.com/yrx/helloworld-aarch64:1.0.20250322104447

图6 上传镜像到SWR成功

如果拉取/推送镜像报swr域名相关 x509: certificate has expired or is not yet valid，直接在push或pull命令最后加 -k规避。

下一步操作

推理在线服务单机部署：在ModelArts部署模型为在线服务，并对部署成功的在线服务进行预测。