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

# 以 SageMaker 訓練工作方式執行本機代碼
<a name="train-remote-decorator"></a>

您可以大型單一節點 Amazon SageMaker 訓練工作方式或多個平行工作方式來執行本機機器學習 (ML) Python 程式碼。若要達成此操作，您可以利用 @remote 裝飾項目來註釋代碼，如下列代碼範例所示。遠端函式不支援[分散式訓練](https://docs.aws.amazon.com/sagemaker/latest/dg/distributed-training.html) (跨多個執行個體)。

```
@remote(**settings)
def divide(x, y):
    return x / y
```

SageMaker Python SDK 會將現有工作區環境以及任何關聯資料處理代碼與資料集自動翻譯成 SageMaker 訓練工作，並在 SageMaker 訓練平台執行。您還可以啟用持續快取功能，藉由快取先前下載的相依性套件，進一步減少任務開始延遲。相較於單獨使用 SageMaker AI 受管暖集區，此方法可更大幅減少工作延遲。如需詳細資訊，請參閱[使用持久性快取](train-warm-pools.md#train-warm-pools-persistent-cache)。

**注意**  
遠端函式不支援分散式訓練工作。

下列區段說明如何利用 @remote 裝飾項目來註釋本機機器學習 (ML) 程式碼，並針對您的使用案例量身打造您的體驗。這包含自訂環境以及整合 SageMaker Experiments。

**Topics**
+ [設定您的環境](#train-remote-decorator-env)
+ [調用遠端函式](train-remote-decorator-invocation.md)
+ [組態檔案](train-remote-decorator-config.md)
+ [自訂執行期環境](train-remote-decorator-customize.md)
+ [容器映像相容性](train-remote-decorator-container.md)
+ [使用 Amazon SageMaker Experiments 記錄參數與指標](train-remote-decorator-experiments.md)
+ [搭配 @remote 裝飾項目使用模組化代碼](train-remote-decorator-modular.md)
+ [適用執行期相依性的私有儲存庫](train-remote-decorator-private.md)
+ [範例筆記本](train-remote-decorator-examples.md)

## 設定您的環境
<a name="train-remote-decorator-env"></a>

請從下列三個選項選擇一個來設定環境。

### 從 Amazon SageMaker Studio Classic 執行代碼
<a name="train-remote-decorator-env-studio"></a>

您可以從 SageMaker Studio Classic 註釋及執行本機機器學習 (ML) 程式碼，方法是建立 SageMaker 筆記本並連接 SageMaker Studio Classic 映像可用的任何映像。下列指示可協助您建立 SageMaker 筆記本、安裝 SageMaker Python SDK，以及使用裝飾項目來註釋代碼。

1. 按照以下指示建立 SageMaker 筆記本並連接 SageMaker Studio Classic 映像：

   1. 請參閱 *Amazon SageMaker AI 開發人員指南*，遵循[啟動 Amazon SageMaker Studio Classic](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-launch.html) 的指示。

   1. 從左側導覽窗格選取 **Studio**。這會開啟新視窗。

   1. 在**入門**對話方塊，從向下箭頭選取使用者設定檔。這會開啟新視窗。

   1. 選取**開啟 Studio Classic**。

   1. 從主要工作區選取**開啟啟動器**。這會開啟新頁面。

   1. 從主要工作區選取**建立筆記本**。

   1. 在**變更環境**對話方塊，從**映像**旁邊的向下箭頭選取**基本 Python 3.0**。

      @remote 裝飾項目會自動偵測已連接至 SageMaker Studio Classic 筆記本的映像，並用以執行 SageMaker 訓練任務。如在裝飾項目或組態檔案指定 `image_uri` 為引數，則會採用 `image_uri` 指定的值，而非偵測到的映像。

      如需更多相關資訊了解如何在 SageMaker Studio Classic 建立筆記本，請參閱[建立或開啟 Amazon SageMaker Studio Classic 筆記本](https://docs.aws.amazon.com/sagemaker/latest/dg/notebooks-create-open.html#notebooks-create-file-menu)的**從檔案函式表建立筆記本**區段。

      如需可用映像檔清單，請參閱[支援的 Docker 映像](https://docs.aws.amazon.com/sagemaker/latest/dg/train-remote-decorator-container.html)。

1. 安裝 SageMaker Python SDK。

   若要在 SageMaker Studio Classic 筆記本內部使用 @remote 函式來註釋代碼，您必須安裝 SageMaker Python SDK。如下列代碼範例所示，安裝 SageMaker Python SDK。

   ```
   !pip install sagemaker
   ```

1. 利用 @remote 裝飾項目在 SageMaker 訓練工作執行函式。

   若要執行本機機器學習 (ML) 程式碼，請先建立相依性檔案，以便指示 SageMaker AI 於何處尋找本機程式碼。若要執行此作業，請遵循下列步驟：

   1. 從 SageMaker Studio Classic 啟動器主要工作區域的**公用程式與檔案**，選擇**文字檔案**。這會在新索引標籤開啟名為 `untitled.txt.` 的文字檔案 

      如需更多相關資訊了解 SageMaker Studio Classic 使用者介面 (UI)，請參閱 [Amazon SageMaker Studio Classic 使用者介面概觀](https://docs.aws.amazon.com//sagemaker/latest/dg/studio-ui.html)。

   1. 重新命名 `untitled.txt ` 為 `requirements.txt`。

   1. 新增代碼所需的所有相依性以及 SageMaker AI 程式庫至 `requirements.txt`。

      下個區段將針對範例 `divide` 函式的 `requirements.txt` 提供最小代碼範例，如下所示。

      ```
      sagemaker
      ```

   1. 透過傳遞相依性檔案，使用遠端裝飾項目來執行代碼，如下所示。

      ```
      from sagemaker.remote_function import remote
      
      @remote(instance_type="ml.m5.xlarge", dependencies='./requirements.txt')
      def divide(x, y):
          return x / y
      
      divide(2, 3.0)
      ```

      如需其他代碼範例，請參閱範例筆記本 [quick\_start.ipynb](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-remote-function/quick_start/quick_start.ipynb)。

      如您已在執行 SageMaker Studio Classic 筆記本，且您按照 **2 的指示安裝 Python SDK。在安裝 SageMaker Python SDK** 時，您必須重新啟動核心。如需更多資訊，請參閱 *Amazon SageMaker AI 開發人員指南*的[使用 SageMaker Studio Classic 筆記本工具列](https://docs.aws.amazon.com/sagemaker/latest/dg/notebooks-menu.html)。

### 從 Amazon SageMaker 筆記本執行代碼
<a name="train-remote-decorator-env-notebook"></a>

您可以從 SageMaker 筆記本執行個體註釋本機機器學習 (ML) 程式碼。下列指示說明如何使用自訂核心建立筆記本執行個體、如何安裝 SageMaker Python SDK，以及如何使用裝飾項目註釋代碼。

1. 利用自訂 `conda` 核心建立筆記本執行個體。

   您可以利用 @remote 裝飾項目註釋本機機器學習 (ML) 程式碼，以便用於 SageMaker 訓練工作內部。首先，您必須建立並自訂 SageMaker 筆記本執行個體，才能使用 Python 3.7 或更高版本 (最高為 3.10.x) 的核心。若要執行此作業，請遵循下列步驟：

   1. 開啟位在 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/) 的 SageMaker AI 主控台。

   1. 從左側導覽面板選擇**筆記本**並展開選項。

   1. 從展開的選項選擇**筆記本執行個體**。

   1. 選擇**建立筆記本執行個體**按鈕。這會開啟新頁面。

   1. 在**筆記本執行個體名稱**，輸入名稱 (上限為 63 個字元且無空格)。有效字元：**A-Z**、**a-z**、**0-9** 以及 **.****:****\+****=****@**** \_****%****-** (連字號)。

   1. 在**筆記本執行個體設定**對話方塊，展開**其他組態**旁邊的向右箭頭。

   1. 在**生命週期組態 - 選擇性**，展開向下箭頭並選取**建立新生命週期組態**。這將開啟新對話方塊。

   1. 針對**名稱**，輸入組態設定名稱。

   1. 在**指令碼**對話方塊的**開始筆記本**標籤，以下列指令碼取代文字方塊的現有內容。

      ```
      #!/bin/bash
      
      set -e
      
      sudo -u ec2-user -i <<'EOF'
      unset SUDO_UID
      WORKING_DIR=/home/ec2-user/SageMaker/custom-miniconda/
      source "$WORKING_DIR/miniconda/bin/activate"
      for env in $WORKING_DIR/miniconda/envs/*; do
          BASENAME=$(basename "$env")
          source activate "$BASENAME"
          python -m ipykernel install --user --name "$BASENAME" --display-name "Custom ($BASENAME)"
      done
      EOF
      
      echo "Restarting the Jupyter server.."
      # restart command is dependent on current running Amazon Linux and JupyterLab
      CURR_VERSION_AL=$(cat /etc/system-release)
      CURR_VERSION_JS=$(jupyter --version)
      
      if [[ $CURR_VERSION_JS == *$"jupyter_core     : 4.9.1"* ]] && [[ $CURR_VERSION_AL == *$" release 2018"* ]]; then
       sudo initctl restart jupyter-server --no-wait
      else
       sudo systemctl --no-block restart jupyter-server.service
      fi
      ```

   1. 在**指令碼**對話方塊的**建立筆記本**標籤，以下列指令碼取代文字方塊的現有內容。

      ```
      #!/bin/bash
      
      set -e
      
      sudo -u ec2-user -i <<'EOF'
      unset SUDO_UID
      # Install a separate conda installation via Miniconda
      WORKING_DIR=/home/ec2-user/SageMaker/custom-miniconda
      mkdir -p "$WORKING_DIR"
      wget https://repo.anaconda.com/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh -O "$WORKING_DIR/miniconda.sh"
      bash "$WORKING_DIR/miniconda.sh" -b -u -p "$WORKING_DIR/miniconda" 
      rm -rf "$WORKING_DIR/miniconda.sh"
      # Create a custom conda environment
      source "$WORKING_DIR/miniconda/bin/activate"
      KERNEL_NAME="custom_python310"
      PYTHON="3.10"
      conda create --yes --name "$KERNEL_NAME" python="$PYTHON" pip
      conda activate "$KERNEL_NAME"
      pip install --quiet ipykernel
      # Customize these lines as necessary to install the required packages
      EOF
      ```

   1. 選擇視窗底部右方的**建立組態**按鈕。

   1. 選擇視窗底部右方的**建立筆記本執行個體**按鈕。

   1. 等待筆記本執行個體的**狀態**從**待處理**變更為 **InService**。

1. 在筆記本執行個體建立 Jupyter 筆記本。

   下列指示說明如何在新建立的 SageMaker 執行個體運用 Python 3.10 建立 Jupyter 筆記本。

   1. 在上一步的筆記本執行個體**狀態**變為 **InService** 之後，請執行下列動作：

      1. 在包含新建立筆記本執行個體**名稱**的那一列，選取**動作**下的**開啟 Jupyter**。這會開啟新 Jupyter 伺服器。

   1. 在 Jupyter 伺服器，從頂部右方的函式表選取**新增**。

   1. 從向下箭頭選取 **conda\_custom\_python310**。這會建立採用 Python 3.10 核心的新 Jupyter 筆記本。您現可以運用本機 Jupyter 筆記本的類似方式使用此新 Jupyter 筆記本。

1. 安裝 SageMaker Python SDK。

   在執行虛擬環境之後，請利用下列代碼範例來安裝 SageMaker Python SDK。

   ```
   !pip install sagemaker
   ```

1. 利用 @remote 裝飾項目在 SageMaker 訓練工作執行函式。

   當您利用 SageMaker 筆記本內部的 @remote 裝飾項目註釋本機機器學習 (ML) 程式碼時，SageMaker 訓練會自動解譯程式碼的函式，並以 SageMaker 訓練工作的方式加以執行。執行下列操作以設定筆記本：

   1. 從您在步驟 1 (**利用自訂核心建立 SageMaker 筆記本執行個體**) 建立的 SageMaker 筆記本執行個體，選取筆記本函式表的核心名稱。

      如需更多資訊，請參閱[變更映像或核心](https://docs.aws.amazon.com/sagemaker/latest/dg/notebooks-run-and-manage-change-image.html)。

   1. 從向下箭頭，選擇自訂 `conda` 核心 (需採用 Python 3.7 版本或更高版本)。

      例如，選取 `conda_custom_python310` 即可選擇 Python 3.10 作為核心。

   1. 選擇**選取**。

   1. 等待核心狀態顯示為閒置，這表示核心已啟動。

   1. 在 Jupyter 伺服器首頁，從頂部右方的函式表選取**新增**。

   1. 選取向下箭頭旁邊的**文字檔案**。這會建立新文字檔案，名為 `untitled.txt.`

   1. 重新命名 `untitled.txt` 為 `requirements.txt`，並新增代碼所需的任何相依性以及 `sagemaker`。

   1. 透過傳遞相依性檔案，使用遠端裝飾項目來執行代碼，如下所示。

      ```
      from sagemaker.remote_function import remote
      
      @remote(instance_type="{{ml.m5.xlarge}}", dependencies='./requirements.txt')
      def divide(x, y):
          return x / y
      
      divide(2, 3.0)
      ```

      如需其他代碼範例，請參閱範例筆記本 [quick\_start.ipnyb](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-remote-function/quick_start/quick_start.ipynb)。

### 從本機 IDE 執行代碼
<a name="train-remote-decorator-env-ide"></a>

您可以在偏好的本機 IDE 內部利用 @remote 裝飾項目註釋本機機器學習 (ML) 程式碼。下列步驟顯示必備先決條件、如何安裝 Python SDK，以及如何使用 @remote 裝飾項目註釋代碼。

1. 透過設定 AWS Command Line Interface (AWS CLI) 和建立角色來安裝先決條件，如下所示：
   + 請參閱[設定 Amazon SageMaker AI 先決條件](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-set-up.html#gs-cli-prereq)的 **AWS CLI 先決條件**區段，按照指示加入 SageMaker AI 網域。
   + 按照 [SageMaker AI 角色](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html)的**建立執行角色**區段建立 IAM 角色。

1. 透過使用 PyCharm 或 `conda` 並採用 Python 3.7 或更高版本 (最高為 3.10.x) 來建立虛擬環境。
   + 利用 PyCharm 設定虛擬環境，如下所示：

     1. 從主功能表選取**檔案**。

     1. 選擇**新專案**。

     1. 從**新環境使用**下的向下箭頭選擇 **Conda**。

     1. 在 **Python 版本**欄位，利用向下箭頭選取 Python 版本，需為 3.7 或更高版本。您可以從清單選取的最高版本為 3.10.x。  
![已選取的 Python 新環境為 Conda，而已選取的 Python 版本為 3.10。](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/training-pycharm-ide.png)
   + 如您已安裝 Anaconda，您可以利用 `conda` 來設定虛擬環境，如下所示：
     + 開啟 Anaconda 提示終端機介面。
     + 利用 Python 3.7 或更高版本 (最高為 3.10x) 建立並啟用新 `conda` 環境。下列代碼範例示範如何利用 Python 3.10 版本建立 `conda` 環境。

       ```
       conda create -n {{sagemaker_jobs_quick_start}} python=3.10 pip
       conda activate {{sagemaker_jobs_quick_start}}
       ```

1. 安裝 SageMaker Python SDK。

   若要從偏好的 IDE 封裝代碼，您必須利用 Python 3.7 或更高版本 (最高為 3.10x) 來設定虛擬環境。您還需要相容的容器映像。利用下列代碼範例安裝 SageMaker Python SDK。

   ```
   pip install sagemaker
   ```

1. 將代碼包裝在 @remote 裝飾項目內部。SageMaker Python SDK 會自動解譯代碼的函式，並以 SageMaker 訓練工作的方式加以執行。下列代碼範例顯示如何匯入必要程式庫、設定 SageMaker 工作階段，以及如何使用 @remote 裝飾項目註釋函式。

   您可以直接提供所需的相依性，或利用已啟用 `conda` 環境的相依性來執行代碼。
   + 若要直接提供相依性，請執行下列操作：
     + 在代碼所在的工作目錄建立 `requirements.txt` 檔案。
     + 新增代碼所需的所有相依性以及 SageMaker 程式庫。下個區段將針對範例 `divide` 函式的 `requirements.txt` 提供最小代碼範例。

       ```
       sagemaker
       ```
     + 透過傳遞相依性檔案，使用 @remote 裝飾項目來執行代碼。在下列代碼範例，請以您希望 SageMaker 用來執行工作的 AWS Identity and Access Management (IAM) 角色 ARN 來取代 `The IAM role name`。

       ```
       import boto3
       import sagemaker
       from sagemaker.remote_function import remote
       
       sm_session = sagemaker.Session(boto_session=boto3.session.Session(region_name="{{us-west-2}}"))
       settings = dict(
           sagemaker_session=sm_session,
           role={{<The IAM role name>}},
           instance_type="{{ml.m5.xlarge}}",
           dependencies='./requirements.txt'
       )
       
       @remote(**settings)
       def divide(x, y):
           return x / y
       
       
       if __name__ == "__main__":
           print(divide(2, 3.0))
       ```
   + 若要使用已啟用 `conda` 環境的相依性，請針對 `dependencies` 參數採用值 `auto_capture`，如下所示。

     ```
     import boto3
     import sagemaker
     from sagemaker.remote_function import remote
     
     sm_session = sagemaker.Session(boto_session=boto3.session.Session(region_name="{{us-west-2}}"))
     settings = dict(
         sagemaker_session=sm_session,
         role={{<The IAM role name>}},
         instance_type="{{ml.m5.xlarge}}",
         dependencies="auto_capture"
     )
     
     @remote(**settings)
     def divide(x, y):
         return x / y
     
     
     if __name__ == "__main__":
         print(divide(2, 3.0))
     ```
**注意**  
您還可以在 Jupyter 筆記本內部實作先前的代碼。PyCharm Professional版本支援本機 Jupyter。有關更多指引，請參閱 PyCharm 文件的 [Jupyter 筆記本支援](https://www.jetbrains.com/help/pycharm/ipython-notebook-support.html)。