# 准备推理镜像 在推理服务部署场景中，开发人员通常需要将训练好的模型封装为镜像进行部署，并将镜像上传至容器镜像服务SWR（SoftWare Repository for Container），利用其安全存储和版本管理能力，实现镜像的高效分发和推理服务的快速部署。用户可以通过ECS或CCE拉取已有推理业务镜像，或者制作推理业务镜像，再将推理业务镜像推送到SWR，部署推理服务时输入SWR镜像地址即可。 本节介绍如何制作推理镜像并上传到SWR，以便于部署推理服务。 #### 推理镜像规范 部署服务用户镜像需要满足如下镜像规范。 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，取决于用户镜像中的设置。 下表将每一条推理镜像规范要求，映射到 Dockerfile 中具体的编写方式，帮助您在制作镜像时逐项落实规范。 表1推理镜像规范与 Dockerfile 编写对照表 | 规范项 | Dockerfile 中的体现方式 | 说明 | |:---|:---|:---| | 推理端口 8080 | ``` EXPOSE 8080 ``` #推理服务代码中监听 8080 ``` uvicorn.run(app, host="0.0.0.0", port=8080) ``` | Dockerfile 中声明暴露端口，推理服务启动时监听 8080。平台通过该端口转发推理请求。 此端口即部署推理服务时的容器端口。 | | 推理接口 HTTP POST | 在推理服务脚本中实现 POST 接口（如/infer、/v1/completions） #Dockerfile 中复制服务脚本，脚本名称示例inference_server.py ``` COPY inference_server.py /home/ma-user/inference_server.py ``` | 接口协议支持 HTTP/HTTPS/WS/WSS。 | | 健康检查接口 HTTP GET | 在推理服务脚本中实现GET /health 或 GET /ping，返回码 200\~399。 | 配置健康检查前，必须在镜像中提前部署该接口，否则会直接导致模型部署失败。 | | 自定义指标接口（可选） | 在推理服务脚本中实现GET /metrics，协议为 HTTP 或 HTTPS。 | 接口协议为 HTTPS 时，不支持开启双向认证。 | | 依赖预装 | ``` RUN pip install --no-cache-dir <包列表> ``` 系统依赖: ``` RUN apt-get install -y --no-install-recommends <包列表> && rm -rf /var/lib/apt/lists/* ``` | 所有依赖必须在 Dockerfile 中预装，不要在运行时动态安装。 使用--no-cache-dir 和 --no-install-recommends 减小镜像体积。 | | 日志输出到 stdout | 推理服务代码中使用print() 或 logging 输出到stdout。 | 确保日志不写文件，而是输出到标准输出，以便ModelArts采集。 | | 推理服务开启TLS 认证（可选） | 需要在镜像中做如下设置： 1. 推理服务开启 HTTPS/WSS 协议。 2. 推理服务开启客户端证书校验。 | 当用户出于安全考虑需要开启 TLS 认证时使用。 | | 代码/密钥挂载路径规划 | Dockerfile 中预留挂载路径，如/home/ma-user/code、 /home/ma-user/keys | 在线服务支持代码和密钥挂载，如有需要可提前规划挂载路径。 | | 镜像体积控制 | 使用多阶段构建（multi-stage build） 清理中间文件: ``` rm -rf /var/lib/apt/lists/* yum clean all ``` 合并 RUN 层减少层数 | 镜像过大将影响部署速度和存储成本。通过多阶段构建分离编译环境和运行环境，清理缓存和中间文件。 | | 推理平台本身不对容器启动用户做要求，如果用户需要使用 ma-user（UID 1000）启动容器时 | 创建UID和ma-user用户 ``` RUN groupadd -g 1000 ma-user && useradd -u 1000 -g 1000 -m -s /bin/bash ma-user ``` 安装完成后切换到 ma-user ``` USER ma-user ``` | 如果使用ma-user用户启动容器，则UID 设置为 1000。 | | 设置工作目录，以 /home/ma-user为例 | ``` WORKDIR /home/ma-user RUN mkdir -p /home/ma-user && chown -R ma-user:ma-user /home/ma-user ``` | 设置为容器默认工作目录，确保属主为 ma-user，具有写入权限。 | | 设置模型加载路径，以 /home/ma-user/model为例 | ``` RUN mkdir -p /home/ma-user/model && chown ma-user:ma-user /home/ma-user/model ``` | 模型文件需放置于该路径，且目录属主为 ma-user。如平台挂载模型至该路径，需确保目录已创建。 root 启动场景：属主可为 root 或 ma-user，root 用户拥有全部权限可正常读写。 | #### 推理镜像制作完整流程 用户可以通过ECS或CCE拉取已有推理业务镜像，或者制作推理业务镜像，再将推理业务镜像推送到SWR，部署推理服务时输入SWR镜像地址即可。 此处直接用CCE集群来制作镜像，是因为CCE节点中默认已安装可用的Containerd。如果希望使用已有的ECS制作镜像，则需要满足以下条件： - CPU架构根据实际选择，镜像推荐选择EulerOS。 - 机器上已安装可用的Containerd。 若使用已有的ECS，后续关于CCE上的操作，改为在您已有的ECS上操作。ECS上操作可以参考实践案例中的内容。 #### 步骤一 创建单节点CCE集群 1. 在CCE控制台创建一个Containerd容器的单节点CCE集群。 1. 登录[CCE控制台](https://console.huaweicloud.com/cce2.0/?#/cce/cluster/list)。在页面左上角![](https://support.huaweicloud.com/inference-modelarts/figure/zh-cn_image_0000002694657998.png)处，选择集群部署区域，所选区域与资源部署区域的距离越近，网络时延越低，访问速度越快。 确认区域后，请单击"购买集群"。如果是首次使用CCE则需要创建委托，请根据页面提示进行处理。 2. 对集群的基础信息进行配置。关键参数如下，更多参数说明请见[购买CCE集群](https://support.huaweicloud.com/usermanual-cce/cce_10_0028.html)。 - 集群类型：CCE Standard 集群 - 集群版本：选择"v1.33" - 集群最大管理规模：选择"50节点" - 集群 master 实例数：选择"单实例" - 容器网络模型：容器隧道网络 - 容器网段：自动设置网段 其他参数选择默认或自定义。 2. 创建节点。 1. 在左侧导航栏中选择"集群管理"，单击上一步创建的集群名称进入集群控制台。 2. 在集群控制台左侧导航栏中选择"节点管理"，切换至"节点"页签并单击右上角的"创建节点"，在节点配置步骤中设置节点参数。更多参数说明请参见[创建节点](https://support.huaweicloud.com/usermanual-cce/cce_10_0363.html)。 - 登录方式：选择密码，填入密码 - 存储配置：系统盘、数据盘大小根据待制作的镜像大小进行评估设置。 其他参数保持默认。 3. 单击"下一步：规格确认"，阅读使用说明，确认无误后单击"提交"。 #### 步骤二 创建镜像组织 进入容器镜像服务管理控制台，在总览页，单击右上角"创建组织"，填写组织名称，单击"确定"完成创建。 图1创建镜像组织 ![](https://support.huaweicloud.com/inference-modelarts/figure/zh-cn_image_0000002724297477.png) #### 步骤三 在CCE节点中登录SWR 1. 进入弹性公网EIP控制台，在我的EIP页面，单击"购买弹性公网IP"，创建一个临时使用的EIP。 详情请见[获取EIP](https://support.huaweicloud.com/usermanual-eip/eip_0008.html)。 2. 前往CCE服务控制台"集群管理"页面，单击集群名称进入集群详情页，单击"节点管理\>节点"，单击[步骤一 创建单节点CCE集群]中创建的节点名称，在弹框中单击"确定"跳转至ECS服务。 3. 切换至"弹性公网IP"页签，单击"绑定弹性公网IP"，在弹框中勾选前面创建的EIP，单击"确定"进行绑定。 4. 使用PuTTY通过EIP，使用root用户登录CCE节点。具体操作请见[登录节点](https://support.huaweicloud.com/usermanual-cce/cce_10_0185.html)。 图2CCE节点登录成功 ![](https://support.huaweicloud.com/inference-modelarts/figure/zh-cn_image_0000002724297431.png) #### 步骤四：编写Dockerfile（可选） 如果用户已经有推理业务镜像，可以跳过此步骤。也可以参考本步骤编写推理镜像的Dockerfile。 制作推理业务镜像时，推荐基于ModelArts提供的官方镜像制作，官方镜像中已预装驱动/CUDA/CANN等必备软件，节省工作。官方镜像不满足诉求时，用户也可以基于其他镜像制作推理业务镜像，满足以上推理镜像规范即可。 ModelArts官方镜像列表请参见文档[ModelArts官方镜像](https://support.huaweicloud.com/docker-modelarts/docker-modelarts_6030.html)。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导入镜像包成功 ![](https://support.huaweicloud.com/inference-modelarts/figure/zh-cn_image_0000002694658082.png) 2. 给加载好的镜像包打tag。 在CCE节点输入命令： ``` ctr image tag <原始包路径> <新包路径> ``` 参数说明： 原始包地址：通过**ctr image list**命令获取。例如：swr.example.myhuaweicloud.com/itep-test-mock/helloworld-aarch64:1.0.20250322104447。 图4获取原始包路径 ![](https://support.huaweicloud.com/inference-modelarts/figure/zh-cn_image_0000002724137511.png) 新包路径地址：局点SWR地址/组织名称/镜像名称/tag。例如：swr.ma-region-3.ma03.external.com/test/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/test/helloworld-aarch64:1.0.20250322104447 ``` 图5镜像包打tag成功 ![](https://support.huaweicloud.com/inference-modelarts/figure/zh-cn_image_0000002699612170.png) #### 步骤六 上传镜像到SWR 在CCE节点输入命令： ``` ctr image push --user <资源空间名>@:<登录密钥> <局点SWR地址>/<组织名称>/<镜像名称>: ``` 参数说明： - \<资源空间名\>：登录管理控制台，单击右上角您的用户名处，单击"个人设置"。在"资源空间列表"页签中查找当前区域对应的资源空间。例如：ma-region-3。 - \的获取方法： 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。 - \<组织名称\>：前面步骤中创建的组织名称。例如：test。 - \<镜像名称\>:\：定义镜像名称。示例：helloworld-aarch64:1.0.20250322104447。 示例： ``` ctr image push --user ma-region-3_test_01@:<登录密钥> swr.ma-region-3.ma03.external.com/test/helloworld-aarch64:1.0.20250322104447 ``` 图6上传镜像到SWR成功 ![](https://support.huaweicloud.com/inference-modelarts/figure/zh-cn_image_0000002694498108.png) ![](https://support.huaweicloud.com/inference-modelarts/public_sys-resources/note_3.0-zh-cn.png) 如果拉取/推送镜像报swr域名相关 x509: certificate has expired or is not yet valid，直接在push或pull命令最后加 -k规避。 #### 下一步操作 [推理在线服务单机部署](https://support.huaweicloud.com/inference-modelarts/inference2.0-modelarts-0004.html)：在ModelArts部署模型为在线服务，并对部署成功的在线服务进行预测。