本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 自带映像（BYOI）
<a name="studio-updated-byoi"></a>

映像是一个文件，可标识运行应用程序所需的内核、语言包和其他依赖项。它包括：
+ 编程语言（如 Python 或 R）
+ 内核
+ 库和软件包
+ 其他必需的软件

Amazon Distrib SageMaker ution (`sagemaker-distribution`) 是一组 Docker 镜像，其中包括用于机器学习、数据科学和可视化的常用框架和软件包。有关更多信息，请参阅 [SageMaker 工作室图片支持政策](sagemaker-distribution.md)。

如果您需要不同的功能，可以自带映像（BYOI）。在以下情况下，您可能需要创建自定义映像：
+ 您需要特定版本的编程语言或库
+ 您想包含自定义工具或软件包
+ 您正在使用标准映像中未提供的专用软件

## 关键术语
<a name="studio-updated-byoi-basics"></a>

下一节定义了将自己的图像用于 SageMaker AI 的关键术语。
+ **Dockerfile：**一个基于文本的文档，其中包含 Docker 映像构建说明。此文档标识了 Docker 映像的语言包和其他依赖项。
+ **Docker 映像：**通过 Dockerfile 构建的一组已打包的软件及依赖项。
+ **SageMaker AI 图像存储：**在 SageMaker AI 中存储您的自定义图像。

**Topics**
+ [关键术语](#studio-updated-byoi-basics)
+ [自定义映像规范](studio-updated-byoi-specs.md)
+ [如何自带映像](studio-updated-byoi-how-to.md)
+ [在 Studio 中启动自定义映像](studio-updated-byoi-how-to-launch.md)
+ [查看自定义映像详细信息](studio-updated-byoi-view-images.md)
+ [使用 SOCI 加快容器启动速度](soci-indexing.md)
+ [分离并清理自定义映像资源](studio-updated-byoi-how-to-detach-from-domain.md)

# 自定义映像规范
<a name="studio-updated-byoi-specs"></a>

您在 Dockerfile 中指定的映像必须符合以下各节中的规范，才能成功创建映像。

**Topics**
+ [运行映像](#studio-updated-byoi-specs-run)
+ [用户和文件系统规范](#studio-updated-byoi-specs-user-and-filesystem)
+ [应用程序的运行状况检查和 URL](#studio-updated-byoi-specs-app-healthcheck)
+ [Dockerfile 示例](#studio-updated-byoi-specs-dockerfile-templates)

## 运行映像
<a name="studio-updated-byoi-specs-run"></a>

以下配置可通过更新 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerConfig.html) 来完成。有关示例，请参阅[更新容器配置](studio-updated-byoi-how-to-container-configuration.md)。
+ `Entrypoint` – 您可以配置运行时传递给容器的 `ContainerEntrypoint` 和 `ContainerArguments`。建议您使用 `ContainerConfig` 配置入口点。有关示例，请参阅上方链接。
+ `EnvVariables` – 在使用 Studio 时，可以为容器定义自定义 `ContainerEnvironment` 变量。可以选择使用 `ContainerConfig` 更新环境变量。有关示例，请参阅上方链接。

  SageMaker 特定于 AI 的环境变量优先，并将覆盖所有同名的变量。例如， SageMaker AI 会自动提供前缀为和的环境变量`SAGEMAKER_`，以确保与 AWS 服务`AWS_`和 SageMaker AI 功能的正确集成。以下是一些 SageMaker 特定于 AI 的环境变量示例：
  + `AWS_ACCOUNT_ID`
  + `AWS_REGION`
  + `AWS_DEFAULT_REGION`
  + `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`
  + `SAGEMAKER_SPACE_NAME`
  + `SAGEMAKER_APP_TYPE`

## 用户和文件系统规范
<a name="studio-updated-byoi-specs-user-and-filesystem"></a>
+ `WorkingDirectory`：您空间的 Amazon EBS 卷已加载到路径 `/home/sagemaker-user`。无法更改挂载路径。使用 `WORKDIR` 指令将映像的工作目录设置为 `/home/sagemaker-user` 中的文件夹。
+ `UID`：Docker 容器的用户 ID。UID=1000 是一个支持值。您可以为用户添加 sudo 访问权限。对 IDs 它们进行了重新映射，以防止容器中运行的进程拥有超出必要权限的权限。
+ `GID`：Docker 容器的组 ID。GID=100 是一个支持值。您可以为用户添加 sudo 访问权限。对 IDs 它们进行了重新映射，以防止容器中运行的进程拥有超出必要权限的权限。
+ 元数据`/opt/ml`目录-使用的`/opt/.sagemakerinternal`和目录 AWS。`/opt/ml` 中的元数据文件包含有关 `DomainId` 等资源的元数据。

  使用以下命令显示文件系统内容：

  ```
  cat /opt/ml/metadata/resource-metadata.json
  ```
+ 日志记录目录 – 为应用程序及其相关扩展的日志记录目录保留 `/var/log/studio`。建议您在创建映像时不要使用这些文件夹。

## 应用程序的运行状况检查和 URL
<a name="studio-updated-byoi-specs-app-healthcheck"></a>

运行状况检查和 URL 取决于应用程序。选择以下与您正在为其构建映像的应用程序关联的链接。
+ 代码编辑器的 [应用程序的运行状况检查和 URL](code-editor-custom-images.md#code-editor-custom-images-app-healthcheck)
+  JupyterLab 的 [应用程序的运行状况检查和 URL](studio-updated-jl-admin-guide-custom-images.md#studio-updated-jl-admin-guide-custom-images-app-healthcheck)

## Dockerfile 示例
<a name="studio-updated-byoi-specs-dockerfile-templates"></a>

有关既符合本页要求、又满足特定的应用程序需求的 Dockerfile 示例，请导航到各自应用程序部分中的示例 Dockerfile。以下选项包括亚马逊 SageMaker Studio 应用程序。
+ 代码编辑器的 [Dockerfile 示例](code-editor-custom-images.md#code-editor-custom-images-dockerfile-templates)
+ [Dockerfile 示例](studio-updated-jl-admin-guide-custom-images.md#studio-updated-jl-custom-images-dockerfile-templates)对于 JupyterLab

**注意**  
如果您要将自己的镜像带到 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)中找到。

# 如何自带映像
<a name="studio-updated-byoi-how-to"></a>

以下页面将提供有关如何自带自定义映像的说明。请先确保满足以下先决条件，然后再继续操作。

## 先决条件
<a name="studio-updated-byoi-how-to-prerequisites"></a>

您需要完成以下先决条件才能将自己的图片带到 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
<a name="studio-updated-byoi-how-to-prepare-image"></a>

此页面提供了有关如何创建本地 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 并构建容器映像
<a name="studio-updated-byoi-how-to-create-local-dockerfile"></a>

按照以下说明操作，创建带所需软件和依赖项的 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
<a name="studio-updated-byoi-add-container-image"></a>

要将容器映像添加到 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)中查看该映像。

# 将自定义映像附加到域
<a name="studio-updated-byoi-how-to-attach-to-domain"></a>

此页面提供了有关如何将自定义映像附加到域的说明。使用以下步骤使用 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)。

# 更新容器配置
<a name="studio-updated-byoi-how-to-container-configuration"></a>

您可以将自定义 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}\"
                   }
               ]
           }
       }"
   ```

# 在 Studio 中启动自定义映像
<a name="studio-updated-byoi-how-to-launch"></a>

将自定义图像附加到 Amazon SageMaker AI 域后，该域中的用户即可使用该图像。按照以下说明操作，使用自定义映像启动一个应用程序。

**注意**  
如果您已将自定义映像附加到 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)。

1. 启动 Amazon SageMaker Studio。有关说明，请参阅[启动亚马逊 SageMaker Studio](studio-updated-launch.md)。

1. 如果尚未这样做，请展开**应用程序**部分。

1. 在**应用程序**部分中，选择该应用程序。如果您未看到该应用程序可用，则系统可能已对您隐藏该应用程序。在此情况下，请联系管理员。

1. 要创建空间，请选择 **\$1 创建*application*空间**，然后按照说明创建空间。

   要选择现有空间，请选择要打开的空间的链接名称。

   

1. 在**映像**下，选择要使用的映像。

   如果**映像**下拉列表不可用，您可能需要停止空间。选择**停止空间**以执行此操作。

1. 确认空间的设置，然后选择**运行空间**。

# 查看自定义映像详细信息
<a name="studio-updated-byoi-view-images"></a>

以下页面提供了有关如何在 SageMaker AI 图像存储中查看自定义图像详细信息的说明。

## 查看自定义映像详细信息（控制台）
<a name="studio-updated-byoi-view-images-console"></a>

以下内容提供了有关如何使用 SageMaker AI 控制台查看您的自定义镜像的说明。在此部分中，您可以查看和编辑映像详细信息。

**查看自定义映像（控制台）**

1. 打开 A [SageMaker I 控制台](https://console.aws.amazon.com/sagemaker)。

1. 展开**管理员配置**部分。

1. 在**管理员配置**下，选择**映像**。

1. 从**自定义镜像**列表中，选择映像名称的超链接。

## 查看自定义映像详细信息（AWS CLI）
<a name="studio-updated-byoi-view-images-cli"></a>

以下部分显示了有关如何使用 AWS CLI查看自定义映像的示例。

```
aws sagemaker list-images \
       --region aws-region
```

# 使用 SOCI 加快容器启动速度
<a name="soci-indexing"></a>

SOCI（Seekable 开放容器计划）索引允许在我们的 [亚马逊 SageMaker Studio](studio-updated.md) A [ma SageMaker ](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html) zon Unified Studio 中延迟加载自定义容器镜像。SOCI 将您的自定义[自带映像（BYOI）](studio-updated-byoi.md)容器的启动时间显著缩短了大约 30-70%。延迟改善因镜像大小、托管实例可用性和其他应用程序依赖关系而异。SOCI 创建了一个索引，该索引允许仅使用必要的组件启动容器，并根据需要按需获取其他文件。

SOCI 解决了容器启动时间缓慢的问题，这种启动时间会中断自定义映像的迭代机器学习 (ML) 开发工作流程。随着机器学习工作负载变得越来越复杂，容器镜像越来越大，从而造成启动延迟，阻碍了开发周期。

**Topics**
+ [主要优势](#soci-indexing-key-benefits)
+ [SOCI 索引的工作原理](#soci-indexing-how-works)
+ [架构组件](#soci-indexing-architecture-components)
+ [支持的工具](#soci-indexing-supported-tools)
+ [SOCI 索引的权限](soci-indexing-setup.md)
+ [使用 nerdctl 和 SOCI CLI 示例创建 SOCI 索引](soci-indexing-example-create-indexes.md)
+ [将社交索引图像与 Studio 示例集成](soci-indexing-example-integrate-studio.md)

## 主要优势
<a name="soci-indexing-key-benefits"></a>
+ **更快的迭代周期**：根据镜像和实例类型，减少容器启动时间
+ **通用优化**：将性能优势扩展到 Studio 中的所有自定义 BYOI 容器

## SOCI 索引的工作原理
<a name="soci-indexing-how-works"></a>

SOCI 会创建专门的元数据索引，用于映射容器镜像的内部文件结构。该索引允许访问单个文件，而无需下载整个图像。SOCI 索引作为符合 OCI（开放容器倡议）的构件存储在 A [mazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html) 中，并链接到您的原始容器映像，从而保留图像摘要和签名有效性。

在 Studio 中启动容器时，系统会使用 SOCI 索引来识别和下载启动所需的基本文件。其他组件可根据您的应用程序需要并行获取。

## 架构组件
<a name="soci-indexing-architecture-components"></a>
+ **原始容器图片**：您的基本容器存储在 Amazon ECR 中
+ **SOCI 索引工件**：映射图像文件结构的元数据
+ **OCI 图像索引清单**：链接您的原始图像和 SOCI 索引
+ **Finch 容器运行时**：启用与 Studio 的延迟加载集成

## 支持的工具
<a name="soci-indexing-supported-tools"></a>


| 工具 | 集成 | 
| --- | --- | 
| nerdctl | 需要安装 containerd | 
| Finch CLI | 原生 SOCI 支持 | 
| Docker \$1 SOCI CLI | 需要其他工具 | 

**Topics**
+ [主要优势](#soci-indexing-key-benefits)
+ [SOCI 索引的工作原理](#soci-indexing-how-works)
+ [架构组件](#soci-indexing-architecture-components)
+ [支持的工具](#soci-indexing-supported-tools)
+ [SOCI 索引的权限](soci-indexing-setup.md)
+ [使用 nerdctl 和 SOCI CLI 示例创建 SOCI 索引](soci-indexing-example-create-indexes.md)
+ [将社交索引图像与 Studio 示例集成](soci-indexing-example-integrate-studio.md)

# SOCI 索引的权限
<a name="soci-indexing-setup"></a>

在将 SOCI 索引与或 Amazon Unified Studio 一起使用之前，请为容器映像创建 SOCI 索引并将其存储在 [亚马逊 SageMaker Studio](studio-updated.md) A [ma SageMaker ](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html) zon ECR 中。

**Topics**
+ [先决条件](#soci-indexing-setup-prerequisites)
+ [所需的 IAM 权限](#soci-indexing-setup-iam-permissions)

## 先决条件
<a name="soci-indexing-setup-prerequisites"></a>
+ AWS 账户 具有管理权限的 [AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started.html)(IAM) 角色
  + [Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)
  + [亚马逊 SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/gs.html)
+ 用于@@ [存储容器镜像的 Amazon ECR 私有存储库](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Repositories.html)
+ [AWS CLI v2.0\$1](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 版本配置了适当的凭据
+ 以下容器工具：
  + 必需：[社交快照器](https://github.com/awslabs/soci-snapshotter)
  + 选项：
    + [nerdctl](https://github.com/containerd/nerdctl)
    + [雀科](https://github.com/runfinch/finch)

## 所需的 IAM 权限
<a name="soci-indexing-setup-iam-permissions"></a>

您的 IAM 角色需要以下权限：
+ 创建和管理 SageMaker AI 资源（域、图像、应用程序配置）。
  + 您可以使用[SageMakerFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonSageMakerFullAccess.html) AWS 托管策略。有关权限的更多详细信息，请参阅[AWS 托管策略： AmazonSageMakerFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSageMakerFullAccess)。
+ 将@@ [图像推送到 Amazon ECR 私有存储库的 IAM 权限](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-push-iam.html)。

# 使用 nerdctl 和 SOCI CLI 示例创建 SOCI 索引
<a name="soci-indexing-example-create-indexes"></a>

以下页面提供了有关如何使用 nerdctl 和 SOCI CLI 创建 SOCI 索引的示例。

**创建 SOCI 索引示例**

1. 首先为接下来的 AWS CLI 命令设置变量。以下是设置变量的示例。

   ```
   ACCOUNT_ID="111122223333"
   REGION="us-east-1"
   REPOSITORY_NAME="repository-name"
   ORIGINAL_IMAGE_TAG="original-image-tag"
   SOCI_IMAGE_TAG="soci-indexed-image-tag"
   ```

   变量定义：
   + `ACCOUNT_ID`是你的 AWS 账户 身份证
   + `REGION`是您的 AWS 区域 Amazon ECR 私有注册表
   + `REPOSITORY_NAME`是您的 Amazon ECR 私有注册表的名称
   + `ORIGINAL_IMAGE_TAG`是你原始图片的标签
   + `SOCI_IMAGE_TAG`是你的社交索引图片的标签

1. 安装所需的工具：

   ```
   # Install SOCI CLI, containerd, and nerdctl
   sudo yum install soci-snapshotter
   sudo yum install containerd jq  
   sudo systemctl start soci-snapshotter
   sudo systemctl restart containerd
   sudo yum install nerdctl
   ```

1. 设置您的注册表变量：

   ```
   REGISTRY_USER=AWS
   REGISTRY="$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com"
   ```

1. 导出您的地区并向 Amazon ECR 进行身份验证：

   ```
   export AWS_REGION=$REGION
   REGISTRY_PASSWORD=$(/usr/local/bin/aws ecr get-login-password --region $AWS_REGION)
   echo $REGISTRY_PASSWORD | sudo nerdctl login -u $REGISTRY_USER --password-stdin $REGISTRY
   ```

1. 提取您的原始容器镜像：

   ```
   sudo nerdctl pull $REGISTRY/$REPOSITORY_NAME:$ORIGINAL_IMAGE_TAG
   ```

1. 创建 SOCI 索引：

   ```
   sudo nerdctl image convert --soci $REGISTRY/$REPOSITORY_NAME:$ORIGINAL_IMAGE_TAG $REGISTRY/$REPOSITORY_NAME:$SOCI_IMAGE_TAG
   ```

1. 推送社交索引图片：

   ```
   sudo nerdctl push --platform linux/amd64 $REGISTRY/$REPOSITORY_NAME:$SOCI_IMAGE_TAG
   ```

此过程会为您的 ECR 存储库中的原始容器映像创建两个构件：
+ SOCI 索引-支持延迟加载的元数据
+ 图片索引清单-符合 OCI 的清单

# 将社交索引图像与 Studio 示例集成
<a name="soci-indexing-example-integrate-studio"></a>

要在 Studio 中使用社交索引图像，必须引用 Soci-Indexed 图像标签，而不是原始容器图像标签。使用您在 SOCI 转换过程中指定的标签（例如，`SOCI_IMAGE_TAG`在[使用 nerdctl 和 SOCI CLI 示例创建 SOCI 索引](soci-indexing-example-create-indexes.md)）。

**整合社交索引图片示例**

1. 首先为接下来的 AWS CLI 命令设置变量。以下是设置变量的示例。

   ```
   ACCOUNT_ID="111122223333"
   REGION="us-east-1"
   IMAGE_NAME="sagemaker-image-name"
   IMAGE_CONFIG_NAME="sagemaker-image-config-name"
   ROLE_ARN="your-role-arn"
   DOMAIN_ID="domain-id"
   SOCI_IMAGE_TAG="soci-indexed-image-tag"
   ```

   变量定义：
   + `ACCOUNT_ID`是你的 AWS 账户 身份证
   + `REGION`是您的 AWS 区域 Amazon ECR 私有注册表
   + `IMAGE_NAME`是你的 SageMaker 图片的名字
   + `IMAGE_CONFIG_NAME`是您的 SageMaker 映像配置的名称
   + `ROLE_ARN`是您的执行角色的 ARN，其权限列在[必需](soci-indexing-setup.md#soci-indexing-setup-iam-permissions)的 IAM 权限中
   + `DOMAIN_ID`是[域名 ID](https://docs.aws.amazon.com/sagemaker/latest/dg/domain-view.html)
**注意**  
如果您要将图像附加到 SageMaker Unified Studio 项目，并且需要说明要使用哪个域，请参阅[查看与您的项目关联的 SageMaker AI 域详细信息](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/view-project-details.html#view-project-details-smai-domain)。
   + `SOCI_IMAGE_TAG`是你的社交索引图片的标签

1. 导出您所在的地区：

   ```
   export AWS_REGION=$REGION
   ```

1. 创建 SageMaker 镜像：

   ```
   aws sagemaker create-image \
       --image-name "$IMAGE_NAME" \
       --role-arn "$ROLE_ARN"
   ```

1. 使用您的 SOCI 索引 URI 创建 SageMaker 图像版本：

   ```
   IMAGE_INDEX_URI="$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/$IMAGE_NAME:$SOCI_IMAGE_TAG"
   
   aws sagemaker create-image-version \
       --image-name "$IMAGE_NAME" \
       --base-image "$IMAGE_INDEX_URI"
   ```

1. 创建应用程序映像配置并更新您的 Amazon SageMaker AI 域以包含应用程序的自定义映像。你可以为基于 Code-OSS、Visual Studio 代码-开源（代码编辑器）和 JupyterLab应用程序的代码编辑器执行此操作。选择下面的应用程序选项以查看步骤。

------
#### [ Code Editor ]

   为代码编辑器创建应用程序映像配置：

   ```
   aws sagemaker create-app-image-config \
       --app-image-config-name "$IMAGE_CONFIG_NAME" \
       --code-editor-app-image-config '{ "FileSystemConfig": { "MountPath": "/home/sagemaker-user", "DefaultUid": 1000, "DefaultGid": 100 } }'
   ```

   更新您的 Amazon SageMaker AI 域名以包含代码编辑器的自定义图片：

   ```
   aws sagemaker update-domain \
       --domain-id "$DOMAIN_ID" \
       --default-user-settings '{
           "CodeEditorAppSettings": {
           "CustomImages": [{
               "ImageName": "$IMAGE_NAME", 
               "AppImageConfigName": "$IMAGE_CONFIG_NAME"
           }]
       }
   }'
   ```

------
#### [ JupyterLab ]

   为以下各项创建应用程序映像配置 JupyterLab：

   ```
   aws sagemaker create-app-image-config \
       --app-image-config-name "$IMAGE_CONFIG_NAME" \
       --jupyter-lab-app-image-config '{ "FileSystemConfig": { "MountPath": "/home/sagemaker-user", "DefaultUid": 1000, "DefaultGid": 100 } }'
   ```

   更新您的 Amazon SageMaker AI 域名以包含以下内容的自定义图片 JupyterLab：

   ```
   aws sagemaker update-domain \
       --domain-id "$DOMAIN_ID" \
       --default-user-settings '{
           "JupyterLabAppSettings": {
           "CustomImages": [{
               "ImageName": "$IMAGE_NAME", 
               "AppImageConfigName": "$IMAGE_CONFIG_NAME"
           }]
       }
   }'
   ```

------

1. 更新域名以包含您的自定义映像后，您可以使用您的自定义映像在 Studio 中创建应用程序。当您[在 Studio 中启动自定义映像](studio-updated-byoi-how-to-launch.md)确保使用的是您的自定义镜像时。

# 分离并清理自定义映像资源
<a name="studio-updated-byoi-how-to-detach-from-domain"></a>

以下页面提供了有关如何使用 Amazon A SageMaker I 控制台或 AWS Command Line Interface (AWS CLI) 分离您的自定义映像和清理相关资源的说明。

**重要**  
在从 SageMaker AI 图像存储库中删除图片之前，必须先将自定义图像与域分离。否则，您在查看域信息或将新的自定义映像附加到域时，可能会遇到错误。  
如果您在加载自定义映像时遇到错误，请参阅[加载自定义映像失败](studio-updated-troubleshooting.md#studio-updated-troubleshooting-custom-image)。

## 分离和删除自定义映像（控制台）
<a name="studio-updated-byoi-how-to-detach-from-domain-console"></a>

以下内容提供了有关如何使用控制台将您的自定义映像与 SageMaker AI 分离以及清理自定义图像资源的说明。

**将自定义映像与域分离**

1. 打开 A [SageMaker I 控制台](https://console.aws.amazon.com/sagemaker)。

1. 展开**管理员配置**部分。

1. 在**管理员配置**下，选择**域**。

1. 从**域**列表中选择一个域。

1. 打开**环境**选项卡。

1. 对于**个人 Studio 应用程序的自定义镜像**，请选中要分离的映像的复选框。

1. 选择**分离**。

1. 按照说明操作以进行分离。

**删除自定义映像**

1. 打开 A [SageMaker I 控制台](https://console.aws.amazon.com/sagemaker)。

1. 展开**管理员配置**部分（如果尚未这样做）。

1. 在**管理员配置**下，选择**映像**。

1. 从**映像**列表中，选择要删除的映像。

1. 选择**删除**。

1. 按照说明从 SageMaker AI 中删除您的图像及其所有版本。

**从 Amazon ECR 中删除自定义映像和存储库**
**重要**  
这也将删除此存储库中的所有容器映像和构件。

1. 打开 [Amazon ECR 控制台](https://console.aws.amazon.com/ecr)。

1. 如果尚未这样做，请展开左侧导航窗格。

1. 在**私有注册表**下，选择**存储库**。

1. 选择要删除的存储库。

1. 选择**删除**。

1. 按照说明操作以进行删除。

## 分离和删除自定义映像（AWS CLI）
<a name="studio-updated-byoi-how-to-detach-from-domain-cli"></a>

以下部分显示了有关如何使用 AWS CLI分离自定义映像的示例。

1. 首先为接下来的 AWS CLI 命令设置变量。

   ```
   ACCOUNT_ID=account-id
   REGION=aws-region
   APP_IMAGE_CONFIG=app-image-config
   SAGEMAKER_IMAGE_NAME=custom-image-name
   ```
   + `aws-region`是 AWS 区域 您的亚马逊 A SageMaker I 域名。你可以在任何 AWS 主机页面的右上角找到它。
   + `app-image-config` 是应用程序映像配置的名称。使用以下 AWS CLI 命令列出中的应用程序映像配置 AWS 区域。

     ```
     aws sagemaker list-app-image-configs \
            --region ${REGION}
     ```
   + `custom-image-name` 是自定义映像名称。使用以下 AWS CLI 命令列出您的中的图像 AWS 区域。

     ```
     aws sagemaker list-images \
            --region ${REGION}
     ```

1. 要按照这些说明操作以将映像和映像版本与域分离，您需要创建或更新域配置 json 文件。
**注意**  
如果已按照[将自定义映像附加到域](studio-updated-byoi-how-to-attach-to-domain.md)中的说明操作，则可能已使用名为 `update-domain.json` 的文件更新域。  
如果您没有此文件，可改为创建一个新的 json 文件。

   创建一个名为 `update-domain.json` 的文件，您将使用此文件更新域。

1. 要删除自定义映像，需将 `CustomImages` 留空，即 `"CustomImages": []`。选择以下选项之一，查看代码编辑器的示例配置文件或 JupyterLab。

------
#### [ Code Editor: update domain configuration file example ]

   使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CodeEditorAppSettings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CodeEditorAppSettings.html) 查看代码编辑器的配置文件示例。

   ```
   {
       "DomainId": "domain-id",
       "DefaultUserSettings": {
           "CodeEditorAppSettings": {
               "CustomImages": [
               ]
           }
       }
   }
   ```

------
#### [ JupyterLab: update domain configuration file example ]

   的配置文件示例 JupyterLab，使用[https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_JupyterLabAppSettings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_JupyterLabAppSettings.html)。

   ```
   {
       "DomainId": "domain-id",
       "DefaultUserSettings": {
           "JupyterLabAppSettings": {
               "CustomImages": [
               ]
           }
       }
   }
   ```

------

   `domain-id` 是映像附加到的域 ID。使用以下命令列出域。

   ```
   aws sagemaker list-domains \
         --region ${REGION}
   ```

1. 保存该文件。

1. 使用[更新域](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sagemaker/update-domain.html)配置文件调 AWS CLI 用更新域。`update-domain.json`
**注意**  
必须先删除域中的所有**应用程序**，之后才能更新自定义映像。您**无需**删除用户配置文件或共享空间。有关删除应用程序的说明，请选择以下选项之一。  
如果要使用 SageMaker AI 控制台，请参阅[关闭你域中的 SageMaker AI 资源](sm-console-domain-resources-shut-down.md)。
如果要使用 AWS CLI，请使用中的步骤 1 到 3 [删除亚马逊 A SageMaker I 域名 (AWS CLI)](gs-studio-delete-domain.md#gs-studio-delete-domain-cli)。

   ```
   aws sagemaker update-domain \
       --cli-input-json file://update-domain.json \
       --region ${REGION}
   ```

1. 删除应用程序映像配置。

   ```
   aws sagemaker delete-app-image-config \
       --app-image-config-name ${APP_IMAGE_CONFIG}
   ```

1. 删除自定义映像。这还会删除所有映像版本。这不会删除 Amazon ECR 容器映像和映像版本。为此，请使用以下可选步骤。

   ```
   aws sagemaker delete-image \
       --image-name ${SAGEMAKER_IMAGE_NAME}
   ```

1. （可选）删除 Amazon ECR 资源。以下列表提供了 AWS CLI 用于获取您的 Amazon ECR 资源信息的命令，用于执行以下步骤。

   1. 为接下来的 AWS CLI 命令设置变量。

      ```
      ECR_REPO_NAME=ecr-repository-name
      ```

      `ecr-repository-name` 是 Amazon Elastic Container Registry 存储库的名称。

      要列出存储库的详细信息，请使用以下命令。

      ```
      aws ecr describe-repositories \
              --region ${REGION}
      ```

   1. 从 Amazon ECR 中删除存储库。
**重要**  
这也将删除此存储库中的所有容器映像和构件。

      ```
      aws ecr delete-repository \
            --repository-name ${ECR_REPO_NAME} \
            --force \
            --region ${REGION}
      ```