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

# 使用 LCC 脚本自定义 SageMaker 笔记本实例
<a name="notebook-lifecycle-config"></a>

**重要**  
允许 Amazon SageMaker Studio 或 Amazon SageMaker Studio Classic 创建亚马逊 SageMaker资源的自定义 IAM 策略还必须授予向这些资源添加标签的权限。之所以需要为资源添加标签的权限，是因为 Studio 和 Studio Classic 会自动为创建的任何资源添加标签。如果 IAM 策略允许 Studio 和 Studio Classic 创建资源但不允许标记，则在尝试创建资源时可能会出现 AccessDenied “” 错误。有关更多信息，请参阅 [提供标记 A SageMaker I 资源的权限](security_iam_id-based-policy-examples.md#grant-tagging-permissions)。  
[AWS 亚马逊 A SageMaker I 的托管策略](security-iam-awsmanpol.md)授予创建 SageMaker 资源的权限已经包括在创建这些资源时添加标签的权限。

*生命周期配置* (LCC) 提供了 Shell 脚本，仅在您创建笔记本实例或者随时启动笔记本实例时运行。创建笔记本实例时，您可以创建新的 LCC 或附加已有的 LCC。生命周期配置脚本对以下使用场景非常有用：
+ 在笔记本实例上安装软件包或示例笔记本
+ 为笔记本实例配置网络和安全性
+ 使用 shell 脚本自定义笔记本实例

您也可以使用生命周期配置脚本从笔记本访问 AWS 服务。例如，您可以创建一个脚本，允许您使用笔记本来控制其他 AWS 资源，例如 Amazon EMR 实例。

我们维护着一个包含笔记本生命周期配置脚本的公共存储库，这些脚本解决了自定义笔记本实例的常见用例，网址为 [https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples](https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples)。

**注意**  
每个脚本的字符数上限为 16384 个字符。  
可用于这两个脚本的 `$PATH` 环境变量的值是 `/usr/local/sbin:/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin`。工作目录（这是 `$PWD` 环境变量的值）是 `/`。  
在 CloudWatch 日志流的日志组中查看笔记本实例生命周期配置`/aws/sagemaker/NotebookInstances`的日志`[notebook-instance-name]/[LifecycleConfigHook]`。  
脚本运行时间不能超过 5 分钟。如果脚本运行时间超过 5 分钟，它会失败，并且不创建或启动笔记本实例。为了缩短脚本的运行时间，请尝试以下方法：  
减少所需的步骤。例如，限制在哪些 conda 环境中安装大型软件包。
在并行进程中运行任务。
在脚本中使用 `nohup` 命令。

您可以通过在 A SageMaker I 控制台中选择生命周期配置来查看之前创建的笔记本实例**生命周期配置**列表。创建新笔记本实例时，可以附加笔记本实例 LCC。有关创建笔记本实例的更多信息，请参阅 [创建 Amazon SageMaker 笔记本实例](howitworks-create-ws.md)。

# 创建生命周期配置脚本
<a name="notebook-lifecycle-config-create"></a>

以下过程说明如何创建用于 Amazon SageMaker 笔记本实例的生命周期配置脚本。有关创建笔记本实例的更多信息，请参阅 [创建 Amazon SageMaker 笔记本实例](howitworks-create-ws.md)。

**创建生命周期配置**

1. 打开 SageMaker AI 控制台，网址为[https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。

1. 在左侧导航窗格中，选择**管理员配置**。

1. 在**管理员配置**下，选择**生命周期配置**。

1. 在**生命周期配置**页面中，选择**笔记本实例**选项卡。

1. 选择**创建配置**。

1. 对于**名称**，请键入使用字母数字字符和 -（但不能含空格）的名称。名称最多可包含 63 个字符。

1. （可选）要创建在您创建笔记本和每次启动笔记本时运行的脚本，请选择**启动笔记本**。

1. 在**启动笔记本**编辑器中，键入脚本。

1. （可选）要创建仅运行一次的脚本，则在创建笔记本时，选择**创建笔记本**。

1. 在**创建笔记本**编辑器中，键入脚本配置网络。

1. 选择**创建配置**。

## 生命周期配置最佳实践
<a name="nbi-lifecycle-config-bp"></a>

以下是使用生命周期配置的最佳实践：

**重要**  
我们不建议在生命周期配置脚本中存储敏感信息。

**重要**  
无论笔记本用户的根访问权限设置如何，生命周期配置脚本都使用根访问权限和笔记本实例的 IAM 执行角色权限运行。有权创建或修改生命周期配置以及更新 notebook 实例的委托人可以使用执行角色的凭据执行代码。请参阅[控制对 SageMaker 笔记本实例的 root 访问权限](nbi-root-access.md)了解更多信息。
+ 以 `root` 用户身份运行生命周期配置。如果您的脚本在 `/home/ec2-user/SageMaker` 目录中进行任何更改（例如，通过 `pip` 安装软件包），请使用命令 `sudo -u ec2-user` 以 `ec2-user` 用户的身份运行。这与运行 Amazon A SageMaker I 的用户相同。
+ SageMaker AI 笔记本实例使用`conda`环境为 Jupyter 笔记本实现不同的内核。如果要安装可用于一个或多个笔记本内核的软件包，请在安装软件包的命令中加入 `conda` 环境命令，以便激活包含要安装软件包的内核的 conda 环境。

  例如，如果只想为 `python3` 环境安装软件包，请使用以下代码：

  ```
  #!/bin/bash
  sudo -u ec2-user -i <<EOF
  
  # This will affect only the Jupyter kernel called "conda_python3".
  source activate python3
  
  # Replace myPackage with the name of the package you want to install.
  pip install myPackage
  # You can also perform "conda install" here as well.
  
  source deactivate
  
  EOF
  ```

  如果要在笔记本实例的所有 conda 环境中安装软件包，请使用以下代码：

  ```
  #!/bin/bash
  sudo -u ec2-user -i <<EOF
  
  # Note that "base" is special environment name, include it there as well.
  for env in base /home/ec2-user/anaconda3/envs/*; do
      source /home/ec2-user/anaconda3/bin/activate $(basename "$env")
  
      # Installing packages in the Jupyter system environment can affect stability of your SageMaker
      # Notebook Instance.  You can remove this check if you'd like to install Jupyter extensions, etc.
      if [ $env = 'JupyterSystemEnv' ]; then
        continue
      fi
  
      # Replace myPackage with the name of the package you want to install.
      pip install --upgrade --quiet myPackage
      # You can also perform "conda install" here as well.
  
      source /home/ec2-user/anaconda3/bin/deactivate
  done
  
  EOF
  ```
+ 必须将所有 conda 环境存储在默认环境文件夹 (/home/user/anaconda3/envs) 中。

**重要**  
当您创建或更改脚本时，我们建议您使用提供 Unix 样式换行符的文本编辑器，例如，创建笔记本时可在控制台中使用的文本编辑器。从非 Linux 操作系统复制文本可能会引入不兼容的换行符，并导致意外错误。

# 外部库和内核安装
<a name="nbi-add-external"></a>

**重要**  
目前，笔记本实例环境中的所有软件包均已获得与 Amazon A SageMaker I 配合使用的许可，不需要额外的商业许可。但是，这可能会在未来发生变化，我们建议定期查看许可条款以了解任何更新。

Amazon SageMaker 笔记本实例已经安装了多个环境。这些环境包含 Jupyter 内核和 Python 包，包括：scikit、Pandas、、和。 NumPy TensorFlow MXNet当您停止和启动笔记本实例时，这些环境以及 `sample-notebooks` 文件夹中的所有文件均会刷新。您也可以安装自己的包含所选软件包和内核的环境。

Amazon SageMaker 笔记本实例中的不同 Jupyter 内核是独立的 conda 环境。有关 conda 环境的信息，请参阅 *Conda* 文档中的[管理环境](https://conda.io/docs/user-guide/tasks/manage-environments.html)。

在笔记本实例的 Amazon EBS 卷上安装自定义环境和内核。这样可以确保在您停止和重启笔记本实例时它们仍然存在，并且您安装的任何外部库都不会被 SageMaker AI 更新。为此，可使用一个生命周期配置，该配置既包括创建笔记本实例 (`on-create)`) 时运行的脚本，也包括每次重新启动笔记本实例 (`on-start`) 时运行的脚本。有关使用笔记本实例生命周期配置的更多信息，请参阅 [使用 LCC 脚本自定义 SageMaker 笔记本实例](notebook-lifecycle-config.md)。[SageMaker AI Notebook Instance Lifecycle Config 示例中有一个包含示例生命周期配置脚本](https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples)的 GitHub存储库。

[https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples/blob/master/scripts/persistent-conda-ebs/on-create.sh 和 https://github.com/aws-samples/ amazon-sagemaker-notebook-instance-lifecycle-config-samples/blob/master/scripts/persistent-conda-ebs/on](https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples/blob/master/scripts/persistent-conda-ebs/on-create.sh)[-start.sh](https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples/blob/master/scripts/persistent-conda-ebs/on-start.sh) 中的示例显示了在笔记本实例上安装环境和内核的最佳实践。`on-create` 脚本会安装 `ipykernel` 库来创建自定义环境作为 Jupyter 内核，然后使用 `pip install` 和 `conda install` 来安装库。您可以调整脚本以创建自定义环境并安装所需的库。 SageMaker 当您停止并重新启动 notebook 实例时，AI 不会更新这些库，因此您可以确保您的自定义环境中包含所需的特定版本的库。`on-start` 脚本会将您创建的任何自定义环境安装为 Jupyter 内核，这样它们就会出现在 Jupyter **新建**菜单的下拉列表中。

## 软件包安装工具
<a name="nbi-add-external-tools"></a>

SageMaker 笔记本支持以下软件包安装工具：
+ conda 安装
+ pip 安装

您可以使用以下方法安装软件包：
+ 生命周期配置脚本。

  有关脚本示例，请参阅 [SageMaker AI Notebook 实例生命周期配置示例](https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples)。有关生命周期配置的更多信息，请参阅[使用生命周期配置脚本自定义笔记本实例](https://docs.aws.amazon.com/sagemaker/latest/dg/notebook-lifecycle-config.html)。
+ 笔记本 – 支持以下命令。
  + `%conda install`
  + `%pip install`
+ Jupyter 终端 – 您可以直接使用 pip 和 conda 安装软件包。

在笔记本中，您可以使用系统命令语法（以 \$1 开头的行）安装软件包，例如 `!pip install` 和 `!conda install`。最近，新命令已添加到 IPython:`%pip`和`%conda`。这些命令是从笔记本安装软件包的推荐方式，因为它们会正确考虑使用中的活动环境或解释器。有关更多信息，请参阅[添加 %pip 和 %conda 魔术函数](https://github.com/ipython/ipython/pull/11524)。

### Conda
<a name="nbi-add-external-tools-conda"></a>

Conda 是一个开源软件包管理系统和环境管理系统，可以安装软件包及其依赖项。 SageMaker AI 支持将 Conda 与两个主通道中的任何一个一起使用，即默认频道和 conda-forge 频道。有关更多信息，请参阅 [Conda 通道](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/channels.html)。conda-forge 通道是一个社区通道，贡献者可以在这里上传软件包。

**注意**  
由于 Conda 解决依赖关系图的方式，从 conda-forge 安装软件包可能需要更长的时间（在最坏的情况下，可能需要 10 分钟以上）。

深度学习 AMI 预装了许多 conda 环境和软件包。由于预装软件包数量众多，要找到一组保证兼容的软件包非常困难。您可能会看到“环境不一致，请仔细检查软件包计划”的警告。尽管有此警告，但 SageMaker 人工智能仍可确保所有 SageMaker 人工智能提供的环境都是正确的。 SageMaker AI 无法保证任何用户安装的软件包都能正常运行。

**注意**  
在2024年2月1日之前， SageMaker 人工智能 AWS Deep Learning AMIs 和Amazon EMR的用户在这些服务中使用Anaconda时，无需获得商业许可即可访问商用Anaconda存储库。对于 2024 年 2 月 1 日之后使用商用 Anaconda 存储库的情况，客户应自行确定其 Anaconda 许可证要求。

Conda 有两种激活环境的方法：con activate/deactivate, and source activate/deactivate da。有关更多信息，请参阅[我应该在 Linux 中使用“conda 激活”还是“源代码激活”](https://stackoverflow.com/questions/49600611/python-anaconda-should-i-use-conda-activate-or-source-activate-in-linux)。

SageMaker AI 支持将 Conda 环境迁移到 Amazon EBS 卷上，该卷在实例停止时会保持不变。当环境安装到根卷时，环境不会被持久化，这是默认行为。有关生命周期脚本的示例，请参阅[persistent-conda-ebs](https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples/tree/master/scripts/persistent-conda-ebs)。

**支持的 conda 操作（请参阅本主题底部的注释）**
+ 在单个环境中 conda install 软件包
+ 在所有环境中 conda install 软件包
+ conda 在 R 环境中安装 R 软件包
+ 从主 conda 存储库安装软件包
+ 从 conda-forge 安装软件包
+ 更改 Conda 安装位置以使用 EBS
+ 同时支持 conda 激活和源代码激活

### Pip
<a name="nbi-add-external-tools-pip"></a>

Pip 实际上是安装和管理 Python 软件包的工具。默认情况下，Pip 在 Python 软件包索引 (PyPI) 上搜索软件包。与 Conda 不同，pip 没有内置的环境支持，对于具有库依赖关系的软件包，pip 也不如 Conda 那么彻底。 native/system Pip 可以用来在 Conda 环境中安装软件包。

您可以将替代软件包存储库与 Pip 一起使用，而不是 PyPI。有关生命周期脚本示例，请参阅 [on-start.sh](https://github.com/aws-samples/amazon-sagemaker-notebook-instance-lifecycle-config-samples/blob/master/scripts/add-pypi-repository/on-start.sh)。

**支持的 Pip 操作（请参阅本主题底部的注释）**
+ 使用 Pip 在没有活动 conda 环境的情况下安装软件包（在系统范围内安装软件包）
+ 使用 Pip 在 conda 环境中安装软件包
+ 使用 Pip 在所有 conda 环境中安装软件包
+ 更改 Pip 安装位置以使用 EBS
+ 使用 Pip 安装软件包时使用替代存储库

### 不支持
<a name="nbi-add-external-tools-misc"></a>

SageMaker AI 旨在支持尽可能多的软件包安装操作。但是，如果这些包是由 SageMaker AI 或 DLAMI 安装的，并且您对这些软件包使用了以下操作，则可能会使您的笔记本实例变得不稳定：
+ 卸载
+ 降级
+ Upgrading

我们不支持通过 yum install 安装软件包或从 CRAN 安装 R 软件包。

由于网络条件或配置方面的潜在问题，或者 Conda 的可用性 PyPi，我们无法保证软件包将在固定或确定的时间内安装。

**注意**  
我们不能保证软件包安装一定成功。尝试在依赖关系不兼容的环境中安装软件包可能会导致安装失败。在这种情况下，您应该联系库的维护者，看看是否有可能更新软件包的依赖关系。或者，您也可以尝试修改环境，以便允许安装。不过，这种修改很可能意味着删除或更新现有软件包，这意味着我们无法再保证该环境的稳定性。

# 笔记本实例软件更新
<a name="nbi-software-updates"></a>

Amazon SageMaker AI 会定期测试和发布安装在笔记本实例上的软件。这包括：
+ 内核更新
+ 安全补丁
+ AWS 软件开发工具包更新
+ [亚马逊 SageMaker Python 软件开发工具包](https://sagemaker.readthedocs.io/en/stable)更新
+ 开源软件更新

为确保您拥有最新的软件更新，请在 SageMaker AI 控制台中或通过调用停止并重启您的笔记本实例 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StopNotebookInstance.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StopNotebookInstance.html)。

您也可以在笔记本实例运行时，通过终端或笔记本中的更新命令手动更新安装在其上的软件。

**注意**  
更新内核和某些软件包可能取决于笔记本实例是否启用了根访问权限。有关更多信息，请参阅 [控制对 SageMaker 笔记本实例的 root 访问权限](nbi-root-access.md)。

您可以查看 [Personal Health Dashboard](https://aws.amazon.com/premiumsupport/technology/personal-health-dashboard/) 或[安全公告](https://aws.amazon.com/security/security-bulletins/)中的安全公告以获取更新。

# 使用笔记本控制 Amazon EMR Spark 实例
<a name="nbi-lifecycle-config-emr"></a>

**重要**  
允许 Amazon SageMaker Studio 或 Amazon SageMaker Studio Classic 创建亚马逊 SageMaker资源的自定义 IAM 策略还必须授予向这些资源添加标签的权限。之所以需要为资源添加标签的权限，是因为 Studio 和 Studio Classic 会自动为创建的任何资源添加标签。如果 IAM 策略允许 Studio 和 Studio Classic 创建资源但不允许标记，则在尝试创建资源时可能会出现 AccessDenied “” 错误。有关更多信息，请参阅 [提供标记 A SageMaker I 资源的权限](security_iam_id-based-policy-examples.md#grant-tagging-permissions)。  
[AWS 亚马逊 A SageMaker I 的托管策略](security-iam-awsmanpol.md)授予创建 SageMaker 资源的权限已经包括在创建这些资源时添加标签的权限。

您可以使用使用自定义生命周期配置脚本创建的笔记本实例从您的笔记本访问 AWS 服务。例如，您可以创建一个脚本，该脚本允许您使用带有 Sparkmagic 的笔记本来控制其他 AWS 资源，例如 Amazon EMR 实例。然后，您可以使用 Amazon EMR 实例来处理数据，而不用在笔记本上运行数据分析。这样就可以创建一个较小的笔记本实例，因为您不会使用该实例来处理数据。当您有大型数据集，需要大型笔记本实例来处理数据时，这很有帮助。

该过程需要使用 Amazon A SageMaker I 控制台执行三个过程：
+ 创建 Amazon EMR Spark 实例
+ 创建 Jupyter 笔记本
+ 测试 notebook-to-Amazon EMR 连接

**创建可以使用 Sparkmagic 从笔记本控制的 Amazon EMR Spark 实例**

1. 打开 Amazon EMR 控制台（[https://console.aws.amazon.com/elasticmapreduce/](https://console.aws.amazon.com/elasticmapreduce/)）。

1. 在导航窗格中，选择**创建集群**。

1. 在**创建集群 - 快速选项**页面上，在**软件配置**下，选择 **Spark：Hadoop 2.8.5 YARN 上的 Spark 2.4.4，带有 Ganglia 3.7.2 和 Zeppelin 0.8.2**。

1. 在页面上设置其他参数，然后选择**创建集群**。

1. 在**集群**页面上，选择您创建的集群名称。记下**主公有 DNS**、**EMR 主设备的安全组**以及在其中创建 EMR 集群的 VPC 名称和子网 ID。在创建笔记本时，将使用这些值。

**创建使用 Sparkmagic 控制 Amazon EMR Spark 实例的笔记本**

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

1. 在导航窗格中的**笔记本实例**下，选择**创建笔记本**。

1. 输入笔记本实例名称并选择实例类型。

1. 选择**其他配置**，然后在**生命周期配置**下选择**创建新的生命周期配置**。

1. 将以下代码添加到生命周期配置脚本中：

   ```
   # OVERVIEW
   # This script connects an Amazon EMR cluster to an Amazon SageMaker notebook instance that uses Sparkmagic.
   #
   # Note that this script will fail if the Amazon EMR cluster's master node IP address is not reachable.
   #   1. Ensure that the EMR master node IP is resolvable from the notebook instance.
   #      One way to accomplish this is to have the notebook instance and the Amazon EMR cluster in the same subnet.
   #   2. Ensure the EMR master node security group provides inbound access from the notebook instance security group.
   #       Type        - Protocol - Port - Source
   #       Custom TCP  - TCP      - 8998 - $NOTEBOOK_SECURITY_GROUP
   #   3. Ensure the notebook instance has internet connectivity to fetch the SparkMagic example config.
   #
   # https://aws.amazon.com/blogs/machine-learning/build-amazon-sagemaker-notebooks-backed-by-spark-in-amazon-emr/
   
   # PARAMETERS
   EMR_MASTER_IP=your.emr.master.ip
   
   
   cd /home/ec2-user/.sparkmagic
   
   echo "Fetching Sparkmagic example config from GitHub..."
   wget https://raw.githubusercontent.com/jupyter-incubator/sparkmagic/master/sparkmagic/example_config.json
   
   echo "Replacing EMR master node IP in Sparkmagic config..."
   sed -i -- "s/localhost/$EMR_MASTER_IP/g" example_config.json
   mv example_config.json config.json
   
   echo "Sending a sample request to Livy.."
   curl "$EMR_MASTER_IP:8998/sessions"
   ```

1. 在脚本的 `PARAMETERS` 部分中，将 `your.emr.master.ip` 替换为 Amazon EMR 实例的主公有 DNS 名称。

1. 选择**创建配置**。

1. 在**创建笔记本**页面上，选择**网络 - 可选**。

1. 选择 Amazon EMR 实例所在的 VPC 和子网。

1. 选择 Amazon EMR 主节点使用的安全组。

1. 选择**创建笔记本实例**。

创建笔记本实例时，状态为 **Pending**。实例创建完毕并且生命周期配置脚本成功运行后，状态为**InService**。

**注意**  
如果笔记本实例无法连接到 Amazon EMR 实例，则 SageMaker AI 无法创建笔记本实例。如果 Amazon EMR 实例和笔记本不在同一 VPC 和子网中，如果笔记本未使用 Amazon EMR 主安全组，如果脚本中的主公有 DNS 名称不正确，则连接可能会失败。

**测试 Amazon EMR 实例与笔记本之间的连接**

1.  当笔记本的状态为 “打开 Jupyter” 时 **InService**，选择 “**打开 Jupyter**” 以打开笔记本。

1. 选择 “**新建**”，然后选择 **Sparkmagic (PySpark)**。

1. 在代码单元格中，输入 **%%info** 并运行单元格。

   输出内容应该类似于以下内容

   ```
   Current session configs: {'driverMemory': '1000M', 'executorCores': 2, 'kind': 'pyspark'}
                       No active sessions.
   ```