本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 建立 Amazon SageMaker Studio Classic 的自訂 SageMaker 映像
<a name="studio-byoi-create"></a>

**重要**  
允許 Amazon SageMaker Studio 或 Amazon SageMaker Studio Classic 建立 Amazon SageMaker 資源的自訂 IAM 政策也必須授與許可，才能將標籤新增至這些資源。需要將標籤新增至資源的許可，因為 Studio 和 Studio Classic 會自動標記它們建立的任何資源。如果 IAM 政策允許 Studio 和 Studio Classic 建立資源，但不允許標記，則在嘗試建立資源時可能會發生 "AccessDenied" 錯誤。如需詳細資訊，請參閱[提供標記 SageMaker AI 資源的許可](security_iam_id-based-policy-examples.md#grant-tagging-permissions)。  
提供許可來建立 SageMaker 資源的 [AWS Amazon SageMaker AI 的 受管政策](security-iam-awsmanpol.md) 已包含建立這些資源時新增標籤的許可。

**重要**  
自 2023 年 11 月 30 日起，先前的 Amazon SageMaker Studio 體驗現在命名為 Amazon SageMaker Studio Classic。下節專門介紹如何使用 Studio Classic 應用程式。如需使用已更新 Studio 體驗的資訊，請參閱 [Amazon SageMaker Studio](studio-updated.md)。  
Studio Classic 仍會針對現有工作負載進行維護，但無法再用於加入。您只能停止或刪除現有的 Studio Classic 應用程式，而且無法建立新的應用程式。建議您[將工作負載遷移至新的 Studio 體驗](studio-updated-migrate.md)。

本主題描述如何使用 SageMaker AI 主控台或 AWS CLI建立自訂 SageMaker 映像。

當您從主控台建立映像時，SageMaker AI 也會建立初始映像版本。每個映像版本代表存放在 [Amazon Elastic 容器登錄檔 (ECR)](https://console.aws.amazon.com/ecr/) 中的容器映像。容器映像檔必須滿足要在 Amazon SageMaker Studio Classic 中使用的要求。如需詳細資訊，請參閱[Amazon SageMaker Studio Classic 的自訂 Amazon SageMaker 映像規格](studio-byoi-specs.md)。如需在本機測試映像並解決常見問題的相關資訊，請參閱 [SageMaker Studio Classic 自訂映像範例存放庫](https://github.com/aws-samples/sagemaker-studio-custom-image-samples/blob/main/DEVELOPMENT.md)。

建立自訂 SageMaker 映像後，您必須將其連接至您的網域或共用空間，才能與 Studio Classic 搭配使用。如需詳細資訊，請參閱[在 Amazon SageMaker Studio Classic 中連接自訂 SageMaker 映像](studio-byoi-attach.md)。

## 從主控台建立 SageMaker 映像
<a name="studio-byoi-create-console"></a>

下節示範如何從 SageMaker AI 主控台建立自訂 SageMaker 映像。

**建立映像**

1. 開啟 Amazon SageMaker AI 主控台，網址為 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。

1. 在左側導覽窗格中，選擇**管理員組態**。

1. 在**管理員組態**下，選擇**映像**。

1. 在**自訂映像**頁面中，選擇**建立映像**。

1. 對於**映像來源**，請在 Amazon ECR 中輸入容器映像的登錄檔路徑。路徑格式如下。

   ` acct-id.dkr.ecr.region.amazonaws.com/repo-name[:tag] or [@digest] `

1. 選擇**下一步**。

1. 在**映像屬性**下，輸入下列內容：
   + 圖片名稱 — 此名稱對您目前的帳戶而言都必須是唯一的 AWS 區域。
   + (選用) 顯示名稱 - 顯示在 Studio Classic 使用者介面中的名稱。如果未提供，`Image name` 則會顯示出來。
   + (選用) 描述 – 映像的一項描述。
   + IAM 角色 – 該角色必須以連接 [AmazonSageMakerFullAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AmazonSageMakerFullAccess) 政策。在下拉式清單中，選擇下列其中一個選項：
     + 建立新角色 — 指定您希望筆記本使用者可以存取的任何其他 Amazon Simple Storage Service (Amazon S3) 儲存貯體。如果您不想將存取許可新增至更多儲存貯體，請選擇**無**。

       SageMaker AI 會將 `AmazonSageMakerFullAccess` 政策連接到角色。此角色可讓筆記本使用者存取核取標記旁列出的 S3 儲存貯體。
     + 輸入自訂 IAM 角色 ARN — 輸入 IAM 角色的 Amazon Resource Name (ARN)。
     + 使用現有角色 — 從清單中選擇一個現有角色。
   + (選用) 映像標籤 — 選擇**新增標籤**。您最多可以新增 50 個標籤。您可以使用 Studio Classic 使用者介面、SageMaker AI 主控台或 SageMaker AI `Search` API 來搜尋標籤。

1. 選擇**提交**。

新映像會顯示在**自訂映像**清單中並以重點標示。已成功建立映像後，您可以選擇映像名稱來檢視其屬性，或選擇**建立版本**建立其他版本。

**若要建立其他映像版本**

1. 在與映像相同的行上選擇**建立版本**。

1. 對於**映像來源**，請輸入 Amazon ECR 容器映像的登錄檔路徑。容器映像不應與先前版本的 SageMaker 映像中使用的映像相同。

## 從 建立 SageMaker 映像 AWS CLI
<a name="studio-byoi-sdk-create-image"></a>

您可以執行下列步驟，以使用 AWS CLI從容器映像建立 SageMaker 映像。
+ 建立 `Image`。
+ 建立 `ImageVersion`。
+ 建立一個程式組態檔案。
+ 建立 `AppImageConfig`。

**若要建立 SageMaker 映像實體**

1. 建立 SageMaker 映像。

   ```
   aws sagemaker create-image \
       --image-name custom-image \
       --role-arn arn:aws:iam::<acct-id>:role/service-role/<execution-role>
   ```

   回應看起來應該類似以下的內容。

   ```
   {
       "ImageArn": "arn:aws:sagemaker:us-east-2:acct-id:image/custom-image"
   }
   ```

1. 從容器映像建立 SageMaker 映像版本。

   ```
   aws sagemaker create-image-version \
       --image-name custom-image \
       --base-image <acct-id>.dkr.ecr.<region>.amazonaws.com/smstudio-custom:custom-image
   ```

   回應看起來應該類似以下的內容。

   ```
   {
       "ImageVersionArn": "arn:aws:sagemaker:us-east-2:acct-id:image-version/custom-image/1"
   }
   ```

1. 檢查映像檔版本是否已成功建立。

   ```
   aws sagemaker describe-image-version \
       --image-name custom-image \
       --version-number 1
   ```

   回應看起來應該類似以下的內容。

   ```
   {
       "ImageVersionArn": "arn:aws:sagemaker:us-east-2:acct-id:image-version/custom-image/1",
       "ImageVersionStatus": "CREATED"
   }
   ```
**注意**  
如果回應為 `"ImageVersionStatus": "CREATED_FAILED"`，則回應也會包含失敗原因。權限問題是導致失敗的常見原因。如果您在為自訂映像啟動或執行 KernelGateway 應用程式時發生故障，也可以檢查 Amazon CloudWatch Logs。日誌群組的名稱為 `/aws/sagemaker/studio`。日誌串流的名稱為 `$domainID/$userProfileName/KernelGateway/$appName`。

1. 建立名為 `app-image-config-input.json` 的組態檔案。`KernelSpecs` 的 `Name` 值必須符合與此 `AppImageConfig` 相關聯之映像中可用之 KernelSpec 的名稱。此值區分大小寫。您可以從容器內的 Shell 執行 `jupyter-kernelspec list`，在映像中找到可用的核心規格。`MountPath` 是掛載 Amazon Elastic File System (Amazon EFS) 主目錄的映像內的路徑。它必須與您在容器內使用的路徑不同，因為掛載 Amazon EFS 主目錄時，該路徑將被覆寫。
**注意**  
下列 `DefaultUID` 與 `DefaultGID` 組合是唯一可接受的值：  
 預設值：1000 和預設值：100 
 預設值：0 和預設值：0 

   ```
   {
       "AppImageConfigName": "custom-image-config",
       "KernelGatewayImageConfig": {
           "KernelSpecs": [
               {
                   "Name": "python3",
                   "DisplayName": "Python 3 (ipykernel)"
               }
           ],
           "FileSystemConfig": {
               "MountPath": "/home/sagemaker-user",
               "DefaultUid": 1000,
               "DefaultGid": 100
           }
       }
   }
   ```

1. 使用在上一步中建立的檔案來建立 AppImaage 組態。

   ```
   aws sagemaker create-app-image-config \
       --cli-input-json file://app-image-config-input.json
   ```

   回應看起來應該類似以下的內容。

   ```
   {
       "AppImageConfigArn": "arn:aws:sagemaker:us-east-2:acct-id:app-image-config/custom-image-config"
   }
   ```