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

# 将你的本地代码当作 SageMaker 训练作业来运行
<a name="train-remote-decorator"></a>

您可以将本地机器学习 (ML) Python 代码作为大型单节点 Amazon SageMaker 训练作业或多个并行作业运行。您可以使用 @remote 装饰器为代码添加注释来做到这一点，如以下代码示例中所示。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 函数不支持分布式训练作业。

以下部分介绍如何使用 @remote 装饰器为本地机器学习代码添加注释，以及如何针对使用案例定制体验。这包括自定义您的环境以及与 SageMaker 实验集成。

**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 实验记录参数和指标](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 经典版运行你的代码
<a name="train-remote-decorator-env-studio"></a>

通过创建 SageMaker 笔记本并附上 Studio Classic 图像上可用的任何图像，您可以从 SageMaker Studio Class SageMaker ic 中注释和运行本地机器学习代码。以下说明可帮助您创建 SageMaker 笔记本、安装 SageMaker Python SDK 以及使用装饰器为代码添加注释。

1. 创建 SageMaker 笔记本并在 SageMaker Studio Classic 中附加图像，如下所示：

   1. 按照《亚马逊 A * SageMaker I 开发者指南*》中[启动 Amazon SageMaker Studio Classic](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-launch.html) 中的说明进行操作。

   1. 从左侧导航窗格中选择 **Studio**。这将打开一个新窗口。

   1. 在**开始使用**对话框中，从下拉箭头选择用户配置文件。这将打开一个新窗口。

   1. 选择**打开 Studio Classic**。

   1. 从主工作区中选择**打开启动程序**。这将打开一个新页面。

   1. 从主工作区中选择**创建笔记本**。

   1. 在**更改环境**对话框中，从**映像**旁边的向下箭头中选择 **Base Python 3.0**。

      @remote 装饰器会自动检测附加到 SageMaker Studio Classic 笔记本上的图像并使用它来运行 SageMaker训练作业。如果在装饰器或配置文件中将 `image_uri` 指定为参数，则将使用 `image_uri` 中指定的值而不是检测到的图像。

      有关如何在 Studio Class SageMaker ic 中创建笔记本的更多信息，请参阅**创建[或打开 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 开发工具包。

   要在 SageMaker Studio Classic Notebook 中使用 @remote 函数为你的代码添加注释，你必须安装 Pyth SageMaker on SDK。安装 SageMaker Python 开发工具包，如以下代码示例所示。

   ```
   !pip install sagemaker
   ```

1. 使用 @remote 装饰器在 SageMaker 训练作业中运行函数。

   要运行您的本地 ML 代码，请先创建一个依赖项文件以指示 SageMaker AI 在哪里找到您的本地代码。为此，请按照以下步骤操作：

   1. 在 SageMaker Studio Classic Launcher 主工作区的 “**实用工具和文件**” 中，选择 “**文本文件**”。这将打开一个新选项卡，其中包含一个名为 `untitled.txt.` 的文本文件。

      有关 SageMaker Studio 经典用户界面 (UI) 的更多信息，请参阅 [Amazon SageMaker Studio 经典用户界面概述](https://docs.aws.amazon.com//sagemaker/latest/dg/studio-ui.html)。

   1. 将 `untitled.txt ` 重命名为 `requirements.txt`。

   1. 将代码所需的所有依赖项以及 A SageMaker I 库添加到`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 软件开发工具包**，必须重启内核。有关更多信息，请参阅 *Amazon A SageMaker I 开发者指南*中的[使用 SageMaker Studio 经典笔记本工具栏](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. 打开 SageMaker AI 控制台，网址为[https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。

   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. 等待 notebook 实例的**状态**从 “**待定**” 变为**InService**。

1. 在笔记本实例中创建 Jupyter 笔记本。

   以下说明说明如何在新创建的实例中使用 Python 3.10 创建 Jupyter 笔记本。 SageMaker 

   1. 在上一步中的笔记本实例**状态**变为之后 **InService**，执行以下操作：

      1. 在包含新创建的笔记本实例**名称**的行中的**操作**下选择**打开 Jupyter**。这将打开一个新的 Jupyter 服务器。

   1. 在 Jupyter 服务器中，从右上角的菜单中选择**新建**。

   1. 从向下箭头中选择 **conda\_custom\_python310**。这将创建一个使用 Python 3.10 内核的新 Jupyter 笔记本。现在可以像使用本地 Jupyter 笔记本一样使用这个新的 Jupyter 笔记本。

1. 安装 SageMaker Python 开发工具包。

   虚拟环境运行后，使用以下代码示例安装 SageMaker Python SDK。

   ```
   !pip install sagemaker
   ```

1. 使用 @remote 装饰器在 SageMaker 训练作业中运行函数。

   当你在 SageMaker 笔记本内用 @remote 装饰器为本地机器学习代码添加注释时， SageMaker 训练将自动解释你的代码的功能并将其作为 SageMaker 训练作业运行。通过执行以下操作来设置笔记本：

   1. 在笔记本菜单中，从您在步骤 1 “**使用自定义内核创建 SageMaker笔记本实例” 中创建的 SageMaker 笔记本实例中选择内核**名称。

      有关更多信息，请参阅[更改映像或内核](https://docs.aws.amazon.com/sagemaker/latest/dg/notebooks-run-and-manage-change-image.html)。

   1. 从向下箭头中，选择使用 3.7 或更高版本的 Python 的自定义 `conda` 内核。

      例如，选择 `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 装饰器为本地机器学习代码添加注释。以下步骤说明了必要的先决条件、如何安装 Python SDK 以及如何使用 @remote 装饰器为代码添加注释。

1. 通过设置 AWS Command Line Interface (AWS CLI) 并创建角色来安装必备组件，如下所示：
   + 按照[设置 Amazon SageMaker AI **AWS CLI 先决条件的 “先决条件**” 部分中的说明登录 SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/gs-set-up.html#gs-cli-prereq) 域。
   + 按照 AI 角色的**创建执行角色**部分创建 I [SageMaker AM 角色](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html)。

1. 使用 PyCharm 或`conda`并使用 Python 3.7 或更高版本（最高 3.10.x）创建虚拟环境。
   + 使用 PyCharm 以下方法设置虚拟环境：

     1. 从主菜单中选择**文件**。

     1. 选择**新项目**。

     1. 从**使用的新环境**下的向下箭头中选择 **Conda**。

     1. 在 **Python 版本**字段中，使用向下箭头选择 3.7 或更高版本的 Python 版本。您可以从列表中选择最高 3.10.x。  
![Python 新环境选定为 Conda，Python 版本选定为 3.10。](http://docs.aws.amazon.com/zh_cn/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 开发工具包。

   要从首选 IDE 中包装代码，您必须使用 Python 3.7 或更高版本（最高 3.10x 版）设置虚拟环境。您还需要兼容的容器映像。使用以下代码示例安装 SageMaker Python 开发工具包。

   ```
   pip install sagemaker
   ```

1. 将您的代码封装在 @remote 装饰器中。P SageMaker ython SDK 将自动解释您的代码的功能并将其作为 SageMaker训练作业运行。以下代码示例演示如何导入必要的库、设置 SageMaker 会话以及如何使用 @remote 装饰器为函数添加注释。

   您可以通过直接提供所需的依赖项或使用活动的 `conda` 环境中的依赖项来运行代码。
   + 要直接提供依赖项，请执行以下操作：
     + 在代码所在的工作目录中创建一个 `requirements.txt` 文件。
     + 将代码所需的所有依赖项与 SageMaker 库一起添加。以下部分提供了示例 `divide` 函数的 `requirements.txt` 的最小代码示例。

       ```
       sagemaker
       ```
     + 通过传递依赖项文件，使用 @remote 装饰器运行您的代码。在以下代码示例中，`The IAM role name`替换为 SageMaker 要用于运行任务的 AWS Identity and Access Management (IAM) 角色 ARN。

       ```
       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` 环境的依赖项，请将值 `auto_capture` 用于 `dependencies` 参数，如下所示。

     ```
     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 专业版原生支持 Jupyter。有关更多指导，请参阅文档中的 [Jupyter 笔记本支持](https://www.jetbrains.com/help/pycharm/ipython-notebook-support.html) PyCharm。