使用 Docker 容器内部捆绑的入口点脚本运行训练作业使用在 Docker 容器外部的入口点脚本运行训练作业

Amazon SageMaker AI 如何运行训练映像

您可以使用自定义入口点脚本来自动配置基础设施，以便在生产环境中进行训练。如果您将入口点脚本传递到 Docker 容器中，则也可以将其作为独立脚本运行，而无需重新构建映像。SageMaker AI 使用 Docker 容器入口点脚本处理您的训练映像。

本节将介绍如何无需训练工具包来使用自定义入口点。如果您想使用自定义入口点，但不熟悉如何手动配置 Docker 容器，我们建议您改为使用 SageMaker 训练工具包库。有关如何使用训练工具包的更多信息，请参阅调整自己的训练容器。

默认情况下，SageMaker AI 会在您的容器中查找名为 train 的脚本。您也可以使用 AlgorithmSpecification API 的 ContainerArguments 和 ContainerEntrypoint 参数，手动提供自己的自定义入口点。

您可以采用以下两个选项来手动配置 Docker 容器以运行您的映像。

使用 CreateTrainingJob API 和其中包含入口点指令的 Docker 容器。
使用 CreateTrainingJob API，然后从 Docker 容器外部传递您的训练脚本。

如果您从 Docker 容器外部传递您的训练脚本，则在更新脚本时无需重新构建 Docker 容器。您也可以使用多个不同的脚本在同一个容器中运行。

您的入口点脚本应包含映像的训练代码。如果您在估算器中使用可选的 source_dir 参数，则它应引用相对 Amazon S3 路径，指向包含入口点脚本的文件夹。您可以使用 source_dir 参数引用多个文件。如果您不使用 source_dir，可以使用 entry_point 参数指定入口点。有关包含估算器的自定义入口点脚本的示例，请参阅 Bring Your Own Model with SageMaker AI Script Mode。

SageMaker AI 模型训练支持将高性能 S3 Express One Zone 存储类目录存储桶作为文件模式、快速文件模式和管道模式的数据输入位置。您还可以使用 S3 Express One Zone 目录存储桶来存储训练输出。要使用 S3 Express One Zone，请提供 S3 Express One Zone 目录存储桶的 URI，而不是 Amazon S3 通用存储桶的 URI。您只能使用具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3）对目录存储桶中的 SageMaker AI 输出数据进行加密。在目录存储桶中存储 SageMaker AI 输出数据时，目前不支持具有 Amazon KMS 密钥的服务器端加密（SSE-KMS）。有关更多信息，请参阅 S3 Express One Zone。

使用 Docker 容器内部捆绑的入口点脚本运行训练作业

SageMaker AI 可以运行您的 Docker 容器内部捆绑的入口点脚本。

默认情况下，Amazon SageMaker AI 运行以下容器。
```
docker run image train
```
SageMaker AI 通过在映像名称后指定 train 参数来覆盖容器中的任何默认 CMD 语句。在您的 Docker 容器中，使用 ENTRYPOINT 指令的 exec 形式：
```
ENTRYPOINT ["executable", "param1", "param2", ...]
```
以下示例显示如何指定名为 k-means-algorithm.py 的 Python 入口点指令。
```
ENTRYPOINT ["python", "k-means-algorithm.py"]
```
exec 形式的 ENTRYPOINT 指令直接启动可执行文件，而不是 /bin/sh 的子级。这使其能够接收来自 SageMaker API 的信号，如 SIGTERM 和 SIGKILL。使用 SageMaker API 时，以下条件适用。
- CreateTrainingJob API 有一个停止条件，它指示 SageMaker AI 在特定的时间后停止模型训练。
- 下面显示了 StopTrainingJob API。此 API 发出与 docker stop（具有 2 分钟超时）等效的命令，以便正常停止指定容器：
```
docker stop -t 120
```
  该命令尝试通过发送 SIGTERM 信号来停止正在运行的容器。在 2 分钟的超时时间后，API 会发送 SIGKILL，然后强行停止容器。如果容器正常处理了 SIGTERM 并在收到信号后的 120 秒内退出，则不会发送 SIGKILL。
如果您希望在 SageMaker AI 停止训练之后访问中间模型构件，则添加代码以处理在 SIGTERM 处理程序中保存构件的操作。
如果您计划使用 GPU 设备进行模型训练，请确保您的容器与 nvidia-docker 兼容。容器上仅包含 CUDA 工具包；不要将 NVIDIA 驱动程序与映像捆绑。有关 nvidia-docker 的更多信息，请参阅 NVIDIA/nvidia-docker。
您不能使用 tini 初始化程序作为 SageMaker AI 容器中的入口点脚本，因为它会被 train 参数和 serve 参数混淆。
/opt/ml 及其所有子目录是 SageMaker 训练保留的目录。在您构建算法的 Docker 映像时，请确保不要在此目录中放置算法所需的任何数据。因为如果这样做，则在训练期间数据可能不再可见。

要在 Docker 映像内部捆绑 Shell 或 Python 脚本，或者要在 Amazon S3 存储桶中提供脚本或使用 Amazon Command Line Interface (CLI)，请继续阅读以下部分。

在 Docker 容器内部捆绑您的 Shell 脚本

如果您要在 Docker 映像内部捆绑自定义 Shell 脚本，请使用以下步骤。

将 Shell 脚本从工作目录复制到 Docker 容器内部。以下代码片段将自定义入口点脚本 custom_entrypoint.sh 从当前工作目录，复制到位于 mydir 中的 Docker 容器。以下示例假定基本 Docker 映像已安装 Python。
```
FROM <base-docker-image>:<tag>

# Copy custom entrypoint from current dir to /mydir on container
COPY ./custom_entrypoint.sh /mydir/ 
```
按照《Amazon ECR 用户指南》中推送 Docker 映像的说明，构建 Docker 容器并将其推送到 Amazon Elastic Container Registry (Amazon ECR)。

通过运行以下 Amazon CLI 命令启动训练作业。


aws --region <your-region> sagemaker create-training-job \
--training-job-name <your-training-job-name> \
--role-arn <your-execution-role-arn> \
--algorithm-specification '{ \ 
    "TrainingInputMode": "File", \
    "TrainingImage": "<your-ecr-image>", \
    "ContainerEntrypoint": ["/bin/sh"], \
    "ContainerArguments": ["/mydir/custom_entrypoint.sh"]}' \
--output-data-config '{"S3OutputPath": "s3://custom-entrypoint-output-bucket/"}' \
--resource-config '{"VolumeSizeInGB":10,"InstanceCount":1,"InstanceType":"ml.m5.2xlarge"}' \
--stopping-condition '{"MaxRuntimeInSeconds": 180}'

在 Docker 容器内部捆绑您的 Python 脚本

要在 Docker 映像内部捆绑自定义 Python 脚本，请使用以下步骤。

将 Python 脚本从工作目录复制到 Docker 容器内部。以下代码片段将自定义入口点脚本 custom_entrypoint.py 从当前工作目录，复制到位于 mydir 中的 Docker 容器。
```
FROM <base-docker-image>:<tag>
# Copy custom entrypoint from current dir to /mydir on container
COPY ./custom_entrypoint.py /mydir/
```

通过运行以下 Amazon CLI 命令启动训练作业。


--algorithm-specification '{ \ 
    "TrainingInputMode": "File", \
    "TrainingImage": "<your-ecr-image>", \
    "ContainerEntrypoint": ["python"], \
    "ContainerArguments": ["/mydir/custom_entrypoint.py"]}' \

使用在 Docker 容器外部的入口点脚本运行训练作业

您可以使用自己的 Docker 容器进行训练，并将入口点脚本从 Docker 容器的外部传入。在容器之外构建入口点脚本有一些好处。如果您更新入口点脚本，则无需重新构建 Docker 容器。您也可以使用多个不同的脚本在同一个容器中运行。

使用 AlgorithmSpecification API 的 ContainerEntrypoint 和 ContainerArguments 参数，指定训练脚本的位置。这些入口点和参数的行为方式与 Docker 入口点和参数相同。这些参数中的值会覆盖提供作为 Docker 容器一部分的对应 ENTRYPOINT 或 CMD。

当您将自定义入口点脚本传递给 Docker 训练容器时，您提供的输入决定了容器的行为。

例如，如果您仅提供 ContainerEntrypoint，则使用 CreateTrainingJob API 的请求语法如下所示。
```
{
    "AlgorithmSpecification": {
        "ContainerEntrypoint": ["string"],   
        ...     
        }       
}
```
然后，SageMaker 训练后端如下所示运行您的自定义入口点。
```
docker run --entrypoint <ContainerEntrypoint> image
```
注意
如果提供了 ContainerEntrypoint，则 SageMaker 训练后端使用给定的入口点运行映像，并覆盖映像中的默认 ENTRYPOINT。
如果您仅提供 ContainerArguments，则 SageMaker AI 会假定 Docker 容器包含入口点脚本。使用 CreateTrainingJob API 的请求语法如下所示。
```
{
    "AlgorithmSpecification": {
        "ContainerArguments": ["arg1", "arg2"],
        ...
    }
}
```
SageMaker 训练后端如下所示运行您的自定义入口点。
```
docker run image <ContainerArguments>
```

如果您同时提供 ContainerEntrypoint 和 ContainerArguments，则使用 CreateTrainingJob API 的请求语法如下所示。


{
    "AlgorithmSpecification": {
        "ContainerEntrypoint": ["string"],
        "ContainerArguments": ["arg1", "arg2"],
        ...
    }
}

SageMaker 训练后端如下所示运行您的自定义入口点。


docker run --entrypoint <ContainerEntrypoint> image <ContainerArguments>

您可以在 CreateTrainingJob API 中使用任何支持的 InputDataConfig 源，提供入口点脚本来运行您的训练映像。

在 Amazon S3 存储桶中提供您的入口点脚本

要使用 S3 存储桶提供自定义入口点脚本，请使用 DataSource API 的 S3DataSource 参数来指定脚本的位置。如果使用 S3DataSource 参数，则需要以下信息。

InputMode 必须为类型 File。
S3DataDistributionType 必须为 FullyReplicated。

以下示例在 S3 存储桶的路径中放置了一个名为 custom_entrypoint.sh 的脚本：s3://<bucket-name>/<bucket prefix>/custom_entrypoint.sh。


#!/bin/bash
echo "Running custom_entrypoint.sh"
echo "Hello you have provided the following arguments: " "$@"

接下来，您必须设置输入数据通道的配置以运行训练作业。要执行此操作，请直接使用 Amazon CLI，也可以使用 JSON 文件。

使用 Amazon CLI 和 JSON 文件配置输入数据通道

要使用 JSON 文件配置输入数据通道，请按以下代码结构所示使用 Amazon CLI。确保以下所有字段都使用在 CreateTrainingJob API 中定义的请求语法。


// run-my-training-job.json
{
 "AlgorithmSpecification": { 
        "ContainerEntrypoint": ["/bin/sh"],
        "ContainerArguments": ["/opt/ml/input/data/<your_channel_name>/custom_entrypoint.sh"],
         ...
   },
  "InputDataConfig": [ 
    { 
        "ChannelName": "<your_channel_name>",
        "DataSource": { 
            "S3DataSource": { 
                "S3DataDistributionType": "FullyReplicated",
                "S3DataType": "S3Prefix",
                "S3Uri": "s3://<bucket-name>/<bucket_prefix>"
            }
        },
        "InputMode": "File",
    },
    ...]
}

接下来，运行 Amazon CLI 命令从 JSON 文件启动训练作业，如下所示。


aws sagemaker create-training-job --cli-input-json file://run-my-training-job.json

直接使用 Amazon CLI 配置输入数据通道

要配置输入数据通道而不使用 JSON 文件，请使用以下 Amazon CLI 代码结构。


aws --region <your-region> sagemaker create-training-job \
--training-job-name <your-training-job-name> \
--role-arn <your-execution-role-arn> \
--algorithm-specification '{ \
    "TrainingInputMode": "File", \
    "TrainingImage": "<your-ecr-image>", \
    "ContainerEntrypoint": ["/bin/sh"], \
    "ContainerArguments": ["/opt/ml/input/data/<your_channel_name>/custom_entrypoint.sh"]}' \
--input-data-config '[{ \
    "ChannelName":"<your_channel_name>", \
    "DataSource":{ \
        "S3DataSource":{ \
            "S3DataType":"S3Prefix", \
            "S3Uri":"s3://<bucket-name>/<bucket_prefix>", \
            "S3DataDistributionType":"FullyReplicated"}}}]' \
--output-data-config '{"S3OutputPath": "s3://custom-entrypoint-output-bucket/"}' \
--resource-config '{"VolumeSizeInGB":10,"InstanceCount":1,"InstanceType":"ml.m5.2xlarge"}' \
--stopping-condition '{"MaxRuntimeInSeconds": 180}'

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

带有自定义训练算法的容器

提供训练信息