本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 如何自带映像 以下页面将提供有关如何自带自定义映像的说明。请先确保满足以下先决条件，然后再继续操作。 ## 先决条件 您需要完成以下先决条件才能将自己的图片带到 Amazon A SageMaker I。 + 设置 Docker 应用程序。有关更多信息，请参阅 *Docker 文档*中的[开始使用](https://docs.docker.com/get-started/)。 + AWS CLI 按照*版本 2 AWS Command Line Interface 用户指南中的 “[入门” AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) 中的步骤安装最新版本*。 + 访问 Amazon Elastic Container Registry (Amazon ECR) 服务的权限。有关更多信息，请参阅《Amazon ECR 用户指南》**中的 [Amazon ECR 托管策略](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ecr_managed_policies.html)。 + 附加了[AmazonSageMakerFullAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerFullAccess)策略的 AWS Identity and Access Management 角色。 **Topics** + [先决条件](#studio-updated-byoi-how-to-prerequisites) + [创建自定义映像并将其推送到 Amazon ECR](studio-updated-byoi-how-to-prepare-image.md) + [将自定义映像附加到域](studio-updated-byoi-how-to-attach-to-domain.md) + [更新容器配置](studio-updated-byoi-how-to-container-configuration.md) # 创建自定义映像并将其推送到 Amazon ECR 此页面提供了有关如何创建本地 Dockerfile、构建容器映像以及将其添加到 Amazon Elastic Container Registry（Amazon ECR）的说明。 **注意** 在以下示例中，未指定标签，系统将默认使用标签 `latest`。如果要指定标签，需在映像名称末尾追加 `:tag`。有关更多信息，请参阅 *Docker 文档*中的 [Docker 映像标签](https://docs.docker.com/reference/cli/docker/image/tag/)。 **Topics** + [创建本地 Dockerfile 并构建容器映像](#studio-updated-byoi-how-to-create-local-dockerfile) + [件 Docker 映像添加到 Amazon ECR](#studio-updated-byoi-add-container-image) ## 创建本地 Dockerfile 并构建容器映像 按照以下说明操作，创建带所需软件和依赖项的 Dockerfile。 **创建 Dockerfile** 1. 首先为接下来的 AWS CLI 命令设置变量。 ``` LOCAL_IMAGE_NAME=local-image-name ``` `local-image-name` 是您在此处定义的本地设备上的容器映像的名称。 1. 创建符合[自定义映像规范](studio-updated-byoi-specs.md)中规范的名为 `Dockerfile` 的基于文本的文档。 可以在 [Dockerfile 示例](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates)中找到受支持的应用程序的 `Dockerfile` 示例。 **注意** 如果您要将自己的镜像带到 SageMaker Unified Studio，则需要遵循*亚马逊 Unifie SageMaker d Studio 用户*[指南中的 Dockerfile 规范](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html)。 `Dockerfile` SageMaker Unified Studio 的示例可以在*亚马逊 Unified Studio 用户指南的 Docker SageMaker f* [ile 示例](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-specifications.html#byoi-specifications-example)中找到。 1. 在包含 `Dockerfile` 的目录下，使用以下命令构建 Docker 映像。句点（`.`）指定 `Dockerfile` 应该在构建命令的上下文中。 ``` docker build -t ${LOCAL_IMAGE_NAME} . ``` 构建完成后，您可以使用以下命令列出您的容器映像信息。 ``` docker images ``` 1. （可选）可使用以下命令测试映像。 ``` docker run -it ${LOCAL_IMAGE_NAME} ``` 在输出中，您会发现服务器正在一个 URL（如 `http://127.0.0.1:8888/...`）上运行。可通过将该 URL 复制到浏览器来测试映像。 如果这样做不起作用，您可能需要在 docker run 命令中添加 `-p port:port`。此选项会将容器上的公开端口映射到主机系统上的端口。有关 docker run 的更多信息，请参阅 *Docker 文档*中的[正在运行的容器](https://docs.docker.com/engine/containers/run/)。 在确认服务器正在运行后，可以停止服务器并关闭所有内核，然后再继续操作。可在输出中查看说明。 ## 件 Docker 映像添加到 Amazon ECR 要将容器映像添加到 Amazon ECR，您需要执行以下操作。 + 创建 Amazon ECR 存储库。 + 登录到默认注册表。 + 将映像推送到 Amazon ECR 存储库。 **注意** Amazon ECR 存储库必须与您要将图像附加到的域名 AWS 区域 相同。 **构建容器映像并将其推送到 Amazon ECR** 1. 首先为接下来的 AWS CLI 命令设置变量。 ``` ACCOUNT_ID=account-id REGION=aws-region ECR_REPO_NAME=ecr-repository-name ``` + `account-id` 是您的账户 ID。你可以在任何 AWS 主机页面的右上角找到它。例如，[SageMaker AI 控制台](https://console.aws.amazon.com/sagemaker)。 + `aws-region`是 AWS 区域 您的亚马逊 A SageMaker I 域名。你可以在任何 AWS 主机页面的右上角找到它。 + `ecr-repository-name` 是您在此处定义的 Amazon Elastic Container Registry 存储库的名称。要查看您的 Amazon ECR 存储库，请参阅 [Amazon ECR 控制台](https://console.aws.amazon.com/ecr)。 1. 登录 Amazon ECR，然后登录 Docker。 ``` aws ecr get-login-password \ --region ${REGION} | \ docker login \ --username AWS \ --password-stdin ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com ``` 在身份验证成功后，您将收到一条登录成功消息。 **重要** 如果收到错误，您可能需要安装或升级到最新版本的 AWS CLI。有关更多信息，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。 1. 使用与 Amazon ECR 兼容的格式标记映像以将其推送到存储库。 ``` docker tag \ ${LOCAL_IMAGE_NAME} \ ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/${ECR_REPO_NAME} ``` 1. 使用 AWS CLI创建一个 Amazon ECR 存储库。要使用 Amazon ECR 控制台创建存储库，请参阅[创建 Amazon ECR 私有存储库以存储映像](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html)。 ``` aws ecr create-repository \ --region ${REGION} \ --repository-name ${ECR_REPO_NAME} ``` 1. 将映像推送到 Amazon ECR 存储库。也可以为 Docker 映像添加标签。 ``` docker push ${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com/${ECR_REPO_NAME} ``` 在成功将映像添加到 Amazon ECR 存储库后，可以在 [Amazon ECR 控制台](https://console.aws.amazon.com/ecr)中查看该映像。 # 将自定义映像附加到域 此页面提供了有关如何将自定义映像附加到域的说明。使用以下步骤使用 Amazon SageMaker AI 控制台导航到您的域并开始**附加图片**流程。 以下说明假设您已将映像推送到与您的域名 AWS 区域 相同的 Amazon ECR 存储库。如果您尚未这样做，请参阅[创建自定义映像并将其推送到 Amazon ECR](studio-updated-byoi-how-to-prepare-image.md)。 当您选择附加映像时，将有两个选项： + 附加**新图片**：此选项将在您的 SageMaker AI 图像存储中创建图像和图像版本，然后将其附加到您的网域。 **注意** 如果要继续执行 BYOI 流程，请在[创建自定义映像并将其推送到 Amazon ECR](studio-updated-byoi-how-to-prepare-image.md)中，使用**新镜像**选项。 + 附加**现有图像**：如果您已经在 SageMaker AI 图像存储中创建了预期的自定义图像，请使用此选项。此选项会将现有自定义映像附加到域。要在 SageMaker AI 图像存储中查看您的自定义图像，请参阅[查看自定义映像详细信息（控制台）](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console)。 ------ #### [ New image ] **将新映像附加到域** 1. 打开 A [SageMaker I 控制台](https://console.aws.amazon.com/sagemaker)。 1. 展开**管理员配置**部分（如果尚未这样做）。 1. 在**管理员配置**下，选择**域**。 1. 在**域**列表中，选择要将映像附加到的域。 **注意** 如果您要将图像附加到 SageMaker Unified Studio 项目，并且需要说明要使用哪个域，请参阅[查看与您的项目关联的 SageMaker AI 域详细信息](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/view-project-details.html#view-project-details-smai-domain)。 1. 打开**环境**选项卡。 1. 在**个人 Studio 应用程序的自定义镜像**部分，选择**附加镜像**。 1. 对于**镜像源**，选择**新镜像**。 1. 包含 Amazon ECR 映像 URI。格式如下所示。 ``` account-id.dkr.ecr.aws-region.amazonaws.com/repository-name:tag ``` 1. 要获取 Amazon ECR 映像 URI，请导航到 [Amazon ECR 私有存储库](https://console.aws.amazon.com/ecr/private-registry/repositories)页面。 1. 选择存储库名称链接。 1. 选择与映像版本对应的**复制 URI** 图标（**镜像标签**）。 1. 按照其余说明操作以附加自定义映像。 **注意** 确保您使用的应用程序类型与您的 `Dockerfile` 一致。有关更多信息，请参阅 [Dockerfile 示例](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates)。 成功将映像附加到域后，您可以在**环境**选项卡中查看映像。 ------ #### [ Existing image ] **将现有映像附加到域** 1. 打开 A [SageMaker I 控制台](https://console.aws.amazon.com/sagemaker)。 1. 展开**管理员配置**部分（如果尚未这样做）。 1. 在**管理员配置**下，选择**域**。 1. 在**域**列表中，选择要将映像附加到的域。 **注意** 如果您要将图像附加到 SageMaker Unified Studio 项目，并且需要说明要使用哪个域，请参阅[查看与您的项目关联的 SageMaker AI 域详细信息](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/view-project-details.html#view-project-details-smai-domain)。 1. 打开**环境**选项卡。 1. 在**个人 Studio 应用程序的自定义镜像**部分，选择**附加镜像**。 1. 对于**镜像源**，选择**现有镜像**。 1. 从 A SageMaker I 图像存储中选择现有的图像和图像版本。 如果您无法查看映像版本，则可能需要创建映像版本。有关更多信息，请参阅 [查看自定义映像详细信息（控制台）](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console)。 1. 按照其余说明操作以附加自定义映像。 **注意** 确保您使用的应用程序类型与您的 `Dockerfile` 一致。有关更多信息，请参阅 [Dockerfile 示例](studio-updated-byoi-specs.md#studio-updated-byoi-specs-dockerfile-templates)。 成功将映像附加到域后，您可以在**环境**选项卡中查看映像。 ------ 在映像成功附加到域后，域用户可以为其应用程序选择该映像。有关更多信息，请参阅 [在 Studio 中启动自定义映像](studio-updated-byoi-how-to-launch.md)。 **注意** 如果您已将自定义映像附加到 SageMaker Unified Studio 项目，则需要从 Uni SageMaker fied Studio 中启动该应用程序。有关更多信息，请参阅 *Amazon SageMaker Unified Studio 用户指南*中的[启动您的自定义镜像](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/byoi-launch-custom-image.html)。 # 更新容器配置 您可以将自定义 Docker 映像用于机器学习工作流。自定义这些映像的一个关键方面是配置容器配置或 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html)。以下页面提供了有关如何配置 `ContainerConfig` 的示例。 入口点是在容器启动时运行的命令或脚本。利用自定义入口点，您可以在应用程序启动之前设置环境、初始化服务或执行任何必要的设置。 此示例说明如何使用为您的 JupyterLab 应用程序配置自定义入口点。 AWS CLI此示例假定您已创建一个自定义映像和域。有关说明，请参阅[将自定义映像附加到域](studio-updated-byoi-how-to-attach-to-domain.md)。 1. 首先为接下来的 AWS CLI 命令设置变量。 ``` APP_IMAGE_CONFIG_NAME=app-image-config-name ENTRYPOINT_FILE=entrypoint-file-name ENV_KEY=environment-key ENV_VALUE=environment-value REGION=aws-region DOMAIN_ID=domain-id IMAGE_NAME=custom-image-name IMAGE_VERSION=custom-image-version ``` + `app-image-config-name` 是应用程序映像配置的名称。 + `entrypoint-file-name` 是容器入口点脚本的名称。例如 `entrypoint.sh`。 + `environment-key` 是环境变量的名称。 + `environment-value` 是分配给环境变量的值。 + `aws-region`是 AWS 区域 您的亚马逊 A SageMaker I 域名。你可以在任何 AWS 主机页面的右上角找到它。 + `domain-id` 是域 ID。要查看域，请参阅[查看领域](domain-view.md)。 + `custom-image-name` 是自定义映像的名称。要查看自定义映像详细信息，请参阅[查看自定义映像详细信息（控制台）](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console)。 如果您已按照[将自定义映像附加到域](studio-updated-byoi-how-to-attach-to-domain.md)中的说明操作，则可能需要使用该过程中使用的同一映像名称。 + `custom-image-version` 是自定义映像的版本号。它应为整数，代表映像的版本。要查看自定义映像详细信息，请参阅[查看自定义映像详细信息（控制台）](studio-updated-byoi-view-images.md#studio-updated-byoi-view-images-console)。 1. 使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateAppImageConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateAppImageConfig.html) API 创建映像配置。 ``` aws sagemaker create-app-image-config \ --region ${REGION} \ --app-image-config-name "${APP_IMAGE_CONFIG_NAME}" \ --jupyter-lab-app-image-config "ContainerConfig = { ContainerEntrypoint = "${ENTRYPOINT_FILE}", ContainerEnvironmentVariables = { "${ENV_KEY}"="${ENV_VALUE}" } }" ``` 1. 使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html) API 更新域的默认设置。这将附加自定义映像以及应用程序映像配置。 ``` aws sagemaker update-domain \ --region ${REGION} \ --domain-id "${DOMAIN_ID}" \ --default-user-settings "{ \"JupyterLabAppSettings\": { \"CustomImages\": [ { \"ImageName\": \"${IMAGE_NAME}\", \"ImageVersionNumber\": ${IMAGE_VERSION}, \"AppImageConfigName\": \"${APP_IMAGE_CONFIG_NAME}\" } ] } }" ```