翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # 独自のアルゴリズムとモデルを使用したコンテナの作成 既存の SageMaker AI コンテナがニーズを満たしておらず、既存の独自コンテナがない場合は、新しい Docker コンテナを作成する必要があります。以下のセクションでは、SageMaker AI で使用するためにトレーニングおよび推論アルゴリズムを使用して Docker コンテナを作成する方法を説明します。 **Topics** + [カスタムトレーニングアルゴリズムを使用するコンテナ](your-algorithms-training-algo.md) + [カスタム推論コードを持つコンテナ](your-algorithms-inference-main.md) # カスタムトレーニングアルゴリズムを使用するコンテナ このセクションでは、Amazon SageMaker AI がカスタムトレーニングアルゴリズムを実行する Docker コンテナとやり取りする方法について説明します。この情報を使用してトレーニングコードを記述し、トレーニングアルゴリズムの Docker イメージを作成します。 **Topics** + [Amazon SageMaker AI がトレーニングイメージを実行する方法](your-algorithms-training-algo-dockerfile.md) + [Amazon SageMaker AI がトレーニング情報を提供する方法](your-algorithms-training-algo-running-container.md) + [EFA でトレーニングを実行する](your-algorithms-training-efa.md) + [Amazon SageMaker AI がアルゴリズムの成功と失敗を通知する方法](your-algorithms-training-signal-success-failure.md) + [Amazon SageMaker AI がトレーニングの出力を処理する方法](your-algorithms-training-algo-output.md) # Amazon SageMaker AI がトレーニングイメージを実行する方法 カスタムエントリポイントスクリプトを使用して、本番環境でトレーニングするインフラストラクチャを自動化できます。エントリポイントスクリプトを Docker コンテナに渡すと、イメージを再構築せずにスタンドアロンのスクリプトとして実行することもできます。SageMaker AI は Docker コンテナのエントリポイントスクリプトを使用してトレーニングイメージを処理します。 このセクションでは、トレーニングツールキットを使用せずにカスタムエントリポイントを使用する方法を示します。カスタムエントリポイントの使用を希望しているものの、Docker コンテナを手動で設定する方法に慣れていない場合は、代わりに [SageMaker トレーニングツールキットライブラリ](https://github.com/aws/sagemaker-training-toolkit)を使用することをお勧めします。ツールキットをトレーニングする方法の詳細については、「[独自のトレーニングコンテナの適応](adapt-training-container.md)」を参照してください。 デフォルトでは、SageMaker AI はコンテナ内の `train` と呼ばれるスクリプトを探します。また、[AlgorithmSpecification](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_AlgorithmSpecification.html) API の `ContainerArguments` と `ContainerEntrypoint` のパラメータを使用して、独自のカスタムエントリポイントを手動で指定することもできます。 イメージを実行するように Docker コンテナを手動で構成するには、次の 2 つの方法があります。 + [CreateTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) API と、内部にエントリポイント命令が含まれている Docker コンテナを使用する。 + `CreateTrainingJob` API を使用して、Docker コンテナの外部からトレーニングスクリプトを渡す。 Docker コンテナの外部からトレーニングスクリプトを渡す場合は、スクリプトを更新するときに Docker コンテナを再構築する必要はありません。さらに、同じコンテナで複数の異なるスクリプトを実行することもできます。 エントリポイントスクリプトには、イメージ用のトレーニングコードが含まれている必要があります。[推定器](https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html)内でオプションの `source_dir` パラメータを使用する場合、エントリポイントスクリプトを含むフォルダへの Amazon S3 の相対パスを参照する必要があります。`source_dir` パラメータを使用して複数のファイルを参照できます。`source_dir` を使用しない場合は、`entry_point` パラメータを使用してエントリポイントを指定できます。estimator を含むカスタムエントリポイントスクリプトの例については、「[Bring Your Own Model with SageMaker AI Script Mode](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-script-mode/sagemaker-script-mode.html)」を参照してください。 SageMaker AI モデルトレーニングは、ファイルモード、高速ファイルモード、パイプモードのデータ入力場所として、高性能の S3 Express One Zone ディレクトリバケットをサポートしています。S3 Express One Zone ディレクトリバケットを使用して、トレーニング出力を保存することもできます。S3 Express One Zone を使用するには、Amazon S3 汎用バケットの代わりに、S3 Express One Zone ディレクトリバケットの URI を指定します。SageMaker AI 出力データは、Amazon S3 マネージドキー (SSE-S3) を使用するサーバー側の暗号化でのみディレクトリバケットで暗号化できます。 AWS KMS キーによるサーバー側の暗号化 (SSE-KMS) は現在、SageMaker AI 出力データをディレクトリバケットに保存するためにサポートされていません。詳細については、「[S3 Express One Zone](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone.html)」を参照してください。 ## Docker コンテナ内でバンドルされたエントリポイントスクリプトを使ってトレーニングジョブを実行する SageMaker AI は Docker コンテナ内にバンドルされたエントリポイントスクリプトを実行できます。 + デフォルトでは、Amazon SageMaker AI は次のコンテナを実行します。 ``` docker run image train ``` + SageMaker AI はイメージ名の後に `train` 引数を指定して、コンテナ内のデフォルトの [CMD](https://docs.docker.com/engine/reference/builder/#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 を使用する場合には、以下の条件が適用されます。 + [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) API には、特定の時間後にモデルトレーニングを停止するよう SageMaker AI に指示する停止条件があります。 + 以下に [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StopTrainingJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StopTrainingJob.html) 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](https://github.com/NVIDIA/nvidia-docker) を参照してください。 + `tini` 引数と `train` 引数で混乱が生じるため、SageMaker AI コンテナでは、`serve` イニシャライザをエントリポイントスクリプトとして使用することはできません。 + `/opt/ml` とすべてのサブディレクトリが SageMaker トレーニングによって予約されています。アルゴリズムの Docker イメージを構築する場合は、アルゴリズムに必要なデータをこのディレクトリに配置しないでください。そうすると、トレーニング中にデータが表示されなくなる可能性があるためです。 Docker イメージ内にシェルまたは Python スクリプトをバンドルしたり、Amazon S3 バケットまたは AWS Command Line Interface (CLI) を使用してスクリプトを提供したりするには、次のセクションに進みます。 ### シェルスクリプトを Docker コンテナにバンドルします。 Docker イメージ内にカスタムシェルスクリプトをバンドルする場合は、以下の手順に従ってください。 1. シェルスクリプトを作業ディレクトリから Docker コンテナ内にコピーします。次のコードスニペットは、カスタムエントリポイントスクリプト `custom_entrypoint.sh` を現在の作業ディレクトリから `mydir` にある Docker コンテナにコピーします。次の例では、ベースの Docker イメージに Python がインストールされていることを前提としています。 ``` FROM : # Copy custom entrypoint from current dir to /mydir on container COPY ./custom_entrypoint.sh /mydir/ ``` 1. 「*Amazon ECR ユーザーガイド*」の「[Pushing a Docker image](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html)」にある指示に従って、Docker コンテナをビルドして [Amazon Elastic Container Registry (Amazon ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html) にプッシュします。 1. 次の AWS CLI コマンドを実行して、トレーニングジョブを起動します。 ``` aws --region sagemaker create-training-job \ --training-job-name \ --role-arn \ --algorithm-specification '{ \ "TrainingInputMode": "File", \ "TrainingImage": "", \ "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}' ``` ### Python スクリプトを Docker コンテナにバンドルします。 Docker イメージ内にカスタム Python スクリプトをバンドルする場合は、以下の手順に従ってください。 1. Python スクリプトを作業ディレクトリから Docker コンテナ内にコピーします。次のコードスニペットは、カスタムエントリポイントスクリプト `custom_entrypoint.py` を現在の作業ディレクトリから `mydir` にある Docker コンテナにコピーします。 ``` FROM : # Copy custom entrypoint from current dir to /mydir on container COPY ./custom_entrypoint.py /mydir/ ``` 1. 次の AWS CLI コマンドを実行して、トレーニングジョブを起動します。 ``` --algorithm-specification '{ \ "TrainingInputMode": "File", \ "TrainingImage": "", \ "ContainerEntrypoint": ["python"], \ "ContainerArguments": ["/mydir/custom_entrypoint.py"]}' \ ``` ## Docker コンテナ外のエントリポイントスクリプトを使用してトレーニングジョブを実行します。 独自の Docker コンテナをトレーニングに使用し、Docker コンテナの外部からエントリポイントスクリプトを渡すことができます。エントリポイントスクリプトをコンテナの外部で構築することには、いくつかの利点があります。エントリポイントスクリプトを更新する場合は、Docker コンテナを再構築する必要はありません。さらに、同じコンテナで複数の異なるスクリプトを実行することもできます。 [AlgorithmSpecification](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_AlgorithmSpecification.html) API の `ContainerEntrypoint` および `ContainerArguments` パラメータを使用してトレーニングスクリプトの場所を指定します。これらのエントリポイントと引数は Docker のエントリポイントと引数と同じように動作します。これらのパラメーターの値は、Docker コンテナーの一部として対応する `ENTRYPOINT` または `CMD` をオーバーライドします。 カスタムエントリポイントスクリプトを Docker トレーニングコンテナに渡すと、指定した入力によってコンテナの動作が決まります。 + 例えば、`ContainerEntrypoint` のみを指定した場合、CreateTrainingJob API を使用するリクエスト構文は次のようになります。 ``` { "AlgorithmSpecification": { "ContainerEntrypoint": ["string"], ... } } ``` 次に、SageMaker トレーニングバックエンドがカスタムエントリポイントを次のように実行します。 ``` docker run --entrypoint image ``` **注記** `ContainerEntrypoint` が指定されている場合、SageMaker トレーニングバックエンドは指定されたエントリポイントでイメージを実行し、イメージ内のデフォルト `ENTRYPOINT` をオーバーライドします。 + `ContainerArguments` のみを指定した場合、SageMaker AI は Docker コンテナにエントリポイントスクリプトが含まれていると仮定します。`CreateTrainingJob` API を使用するリクエスト構文は以下のとおりです。 ``` { "AlgorithmSpecification": { "ContainerArguments": ["arg1", "arg2"], ... } } ``` SageMaker トレーニングバックエンドがカスタムエントリポイントを次のように実行します。 ``` docker run image ``` + `ContainerEntrypoint` と `ContainerArguments` の両方を指定した場合、`CreateTrainingJob` API を使用するリクエスト構文は次のようになります。 ``` { "AlgorithmSpecification": { "ContainerEntrypoint": ["string"], "ContainerArguments": ["arg1", "arg2"], ... } } ``` SageMaker トレーニングバックエンドがカスタムエントリポイントを次のように実行します。 ``` docker run --entrypoint image ``` `CreateTrainingJob` API でサポートされている任意の `InputDataConfig` ソースを使用して、トレーニングイメージを実行するエントリポイントスクリプトを提供できます。 ### エントリポイントスクリプトを Amazon S3 バケットに提供する S3 バケットを使用してカスタムエントリポイントスクリプトを提供するには、[DataSource](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DataSource.html#sagemaker-Type-DataSource-S3DataSource) API `S3DataSource` のパラメータを使用してスクリプトの場所を指定します。この `S3DataSource` パラメータを使用する場合は、以下が必要です。 + [InputMode](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html#sagemaker-Type-Channel-InputMode) は `File` タイプでなければなりません。 + [S3DataDistributionType](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DataSource.html#sagemaker-Type-DataSource-S3DataSource) は `FullyReplicated` でなければなりません。 次の例では、custom\$1entrypoint.sh というスクリプトを S3 バケット `s3:////custom_entrypoint.sh` へのパスに配置しています。 ``` #!/bin/bash echo "Running custom_entrypoint.sh" echo "Hello you have provided the following arguments: " "$@" ``` 次に、トレーニングジョブを実行するための入力データチャネルの設定を行う必要があります。これを行うには、 AWS CLI を直接使用するか、JSON ファイルを使用します。 #### JSON ファイル AWS CLI で を使用して入力データチャネルを設定する JSON ファイルを使用して入力データチャネルを設定するには、次のコード構造 AWS CLI に示すように を使用します。以下のすべてのフィールドが [CreateTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html#API_CreateTrainingJob_RequestSyntax) API で定義されているリクエスト構文を使用していることを確認してください。 ``` // run-my-training-job.json { "[AlgorithmSpecification](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html#sagemaker-CreateTrainingJob-request-AlgorithmSpecification)": { "ContainerEntrypoint": ["/bin/sh"], "ContainerArguments": ["/opt/ml/input/data//custom_entrypoint.sh"], ... }, "[InputDataConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html#sagemaker-CreateTrainingJob-request-InputDataConfig)": [ { "[ChannelName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html#sagemaker-Type-Channel-ChannelName)": "", "[DataSource](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html#sagemaker-Type-Channel-DataSource)": { "[S3DataSource](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DataSource.html#sagemaker-Type-DataSource-S3DataSource)": { "[S3DataDistributionType](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3DataDistributionType)": "FullyReplicated", "[S3DataType](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3DataType)": "S3Prefix", "[S3Uri](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3Uri)": "s3:///" } }, "[InputMode](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html#sagemaker-Type-Channel-InputMode)": "File", }, ...] } ``` 次に、 AWS CLI コマンドを実行して、次のように JSON ファイルからトレーニングジョブを起動します。 ``` aws sagemaker create-training-job --cli-input-json file://run-my-training-job.json ``` #### を使用して入力データチャネル AWS CLI を直接設定する JSON ファイルなしで入力データチャネルを設定するには、次の AWS CLI コード構造を使用します。 ``` aws --region sagemaker create-training-job \ --training-job-name \ --role-arn \ --algorithm-specification '{ \ "TrainingInputMode": "File", \ "TrainingImage": "", \ "ContainerEntrypoint": ["/bin/sh"], \ "ContainerArguments": ["/opt/ml/input/data//custom_entrypoint.sh"]}' \ --input-data-config '[{ \ "ChannelName":"", \ "DataSource":{ \ "S3DataSource":{ \ "S3DataType":"S3Prefix", \ "S3Uri":"s3:///", \ "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}' ``` # Amazon SageMaker AI がトレーニング情報を提供する方法 このセクションでは、SageMaker AI がトレーニングデータ、ハイパーパラメータ、その他の設定情報などのトレーニング情報を Docker コンテナで利用できるようにする方法について説明します。 モデルトレーニングを開始する [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) リクエストを SageMaker AI に送信する際、トレーニングアルゴリズムが格納されている Docker イメージの Amazon Elastic Container Registry (Amazon ECR) パスを指定します。トレーニングデータが保存される Amazon Simple Storage Service (Amazon S3) の場所とアルゴリズム固有のパラメータも指定します。SageMaker AI はこの情報を Docker コンテナが利用できるようにするため、トレーニングアルゴリズムで使用できます。このセクションでは、この情報を Docker コンテナで利用できるようにする方法を説明します。トレーニングジョブの作成方法については、「`CreateTrainingJob`」を参照してください。SageMaker AI コンテナで情報を整理する方法の詳細については、「[SageMaker トレーニングおよび推論ツールキット](amazon-sagemaker-toolkits.md)」を参照してください。 **Topics** + [ハイパーパラメータ](#your-algorithms-training-algo-running-container-hyperparameters) + [環境可変](#your-algorithms-training-algo-running-container-environment-variables) + [入力データ設定](#your-algorithms-training-algo-running-container-inputdataconfig) + [トレーニングデータ](#your-algorithms-training-algo-running-container-trainingdata) + [分散型トレーニング設定](#your-algorithms-training-algo-running-container-dist-training) ## ハイパーパラメータ SageMaker AI は、`CreateTrainingJob` リクエスト内のハイパーパラメータを `/opt/ml/input/config/hyperparameters.json` ファイル内の Docker コンテナで利用できるようにします。 以下は、[XGBoost](https://docs.aws.amazon.com/sagemaker/latest/dg/xgboost.html) の `CreateTrainingJob` 操作で `num_round` と `eta` ハイパーパラメータを指定するための `hyperparameters.json` のハイパーパラメータ設定の例です。 ``` { "num_round": "128", "eta": "0.001" } ``` SageMaker AI のビルトイン XGBoost アルゴリズムに使用できるハイパーパラメータの完全なリストについては、「[XGBoost Hyperparameters](https://docs.aws.amazon.com/sagemaker/latest/dg/xgboost_hyperparameters.html)」を参照してください。 調整できるハイパーパラメータは、トレーニングするアルゴリズムによって異なります。SageMaker AI 組み込みアルゴリズムで使用できるハイパーパラメータのリストについては、「[Use Amazon SageMaker AI Built-in Algorithms or Pre-trained Models](https://docs.aws.amazon.com/sagemaker/latest/dg/algos.html)」のアルゴリズムリンクの下にある「**Hyperparameters**」にリストされているものを参照してください。 ## 環境可変 SageMaker AI では次の環境変数がコンテナ内で設定されます。 + TRAINING\$1JOB\$1NAME - `CreateTrainingJob` リクエストの `TrainingJobName` パラメータで指定します。 + TRAINING\$1JOB\$1ARN - `CreateTrainingJob` レスポンスの `TrainingJobArn` として返されるトレーニングジョブの Amazon リソースネーム (ARN)。 + `CreateTrainingJob` リクエストの [Environment](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html#sagemaker-CreateTrainingJob-request-Environment) パラメータで指定されるすべての環境変数。 ## 入力データ設定 SageMaker AI は、`CreateTrainingJob` リクエストの `InputDataConfig` パラメータでデータチャネル情報を指定します。この情報を Docker コンテナの `/opt/ml/input/config/inputdataconfig.json` ファイルで利用できるようにします。 例えば、3 つのデータチャネル (`train`、`evaluation`、`validation`) をリクエストで指定するとします。SageMaker AI は以下の JSON を提供します。 ``` { "train" : {"ContentType": "trainingContentType", "TrainingInputMode": "File", "S3DistributionType": "FullyReplicated", "RecordWrapperType": "None"}, "evaluation" : {"ContentType": "evalContentType", "TrainingInputMode": "File", "S3DistributionType": "FullyReplicated", "RecordWrapperType": "None"}, "validation" : {"TrainingInputMode": "File", "S3DistributionType": "FullyReplicated", "RecordWrapperType": "None"} } ``` **注記** SageMaker AI は、前の例で示されているように各データチャネルに関連する情報 (チャネル名やコンテンツタイプなど) のみをコンテナに提供します。EFS または FSxLustre を入力データソースとして指定した場合、`S3DistributionType` は `FullyReplicated` に設定されます。 ## トレーニングデータ [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) リクエストの `AlgorithmSpecification` にある `TrainingInputMode` パラメータでトレーニングのデータセットを使用可能にする方法を指定します。次の入力モードを使用できます。 + **`File` モード** `TrainingInputMode` 値として `File` mode を使用する場合、SageMaker AI はコンテナに以下のパラメータを設定します。 + `TrainingInputMode` パラメータは `inputdataconfig.json` に「File」として書き込まれます。 + `/opt/ml/input/data/channel_name` にデータチャネルディレクトリが書き込まれます。 `File` mode を使用する場合、SageMaker AI はチャネルごとにディレクトリを作成します。例えば、`training`、`validation`、`testing` という名前の 3 つのチャネルがある場合、SageMaker AI は Docker コンテナに次の 3 つのディレクトリを作成します。 + `/opt/ml/input/data/training` + `/opt/ml/input/data/validation` + `/opt/ml/input/data/testing` `File` モードでは、次のデータソースがサポートされています。 + Amazon Simple Storage Service (Amazon S3) + Amazon Elastic File System (Amazon EFS) + Amazon FSx for Lustre **注記** Amazon EFS や Amazon FSx などのファイルシステムのデータソースを使用するチャネルでは、`File` モードを使用する必要があります。この場合、チャネルで提供されるディレクトリパスは `/opt/ml/input/data/channel_name` にマウントされます。 + **`FastFile` モード** `FastFile` mode を `TrainingInputNodeParameter` として使用する場合、SageMaker AI はコンテナに以下のパラメータを設定します。 + `File` mode と同様に、`FastFile` mode では `TrainingInputMode` パラメータは `inputdataconfig.json` に「File」として書き込まれます。 + `/opt/ml/input/data/channel_name` にデータチャネルディレクトリが書き込まれます。 `FastFile` モードでは、次のデータソースがサポートされています。 + Amazon S3 `FastFile` モードを使用すると、チャネルディレクトリは読み取り専用権限でマウントされます。 歴史的に、`File` mode は `FastFile` mode よりも優先されていました。下位互換性を確保するため、`TrainingInputMode` パラメータが `inputdataconfig.json.` で `File` に設定されている限り、`File` mode をサポートするアルゴリズムは `FastFile` mode とシームレスに連携できます。 **注記** `FastFile` モードを使用するチャネルは、「S3Prefix」の `S3DataType` を使用する必要があります。 `FastFile` モードは、スラッシュ (`/`) を Amazon S3 オブジェクトをフォルダにグループ化するための区切り文字として使用するフォルダビューを示します。`S3Uri` のプレフィックスは、部分的なフォルダ名に対応させることはできません。例えば、Amazon S3 データセットに `s3://amzn-s3-demo-bucket/train-01/data.csv` がある場合、`s3://amzn-s3-demo-bucket/train` または `s3://amzn-s3-demo-bucket/train-01` のどちらも `S3Uri` のプレフィックスとしては許可されません。 フォルダに対応するチャネルを定義するには、末尾にスラッシュを使用することをお勧めします。例えば、`train-01` フォルダには `s3://amzn-s3-demo-bucket/train-01/` チャネルです。末尾のスラッシュがないと、別のフォルダ `s3://amzn-s3-demo-bucket/train-011/` またはファイル `s3://amzn-s3-demo-bucket/train-01.txt/` が存在する場合、チャネルがあいまいになります。 + **`Pipe` モード** + `inputdataconfig.json` に書き込まれる `TrainingInputMode` パラメータ: "Pipe" + Docker コンテナ内のデータチャネルディレクトリ: `/opt/ml/input/data/channel_name_epoch_number` + サポートされているデータソース: Amazon S3 チャネルごとに別のパイプから読む必要があります。例えば、`training`、`validation`、`testing` という名前の 3 つのチャネルがある場合は、次のパイプから読み取る必要があります。 + `/opt/ml/input/data/training_0, /opt/ml/input/data/training_1, ...` + `/opt/ml/input/data/validation_0, /opt/ml/input/data/validation_1, ...` + `/opt/ml/input/data/testing_0, /opt/ml/input/data/testing_1, ...` パイプを順番に読み取ります。たとえば、`training` というチャネルがある場合は、パイプを次の順序で読み取ります。 1. `/opt/ml/input/data/training_0` を読み取りモードで開き、end-of-file (EOF) まで読み取ります。または最初のエポックで終了した場合は、パイプファイルを早期に閉じます。 1. 最初のパイプファイルを閉じた後に、`/opt/ml/input/data/training_1` を探し、2 番目のエポックを実行します。同様に続けます。 指定されたエポックのファイルがまだ存在しない場合は、パイプが作成されるまでコードを再試行する必要があります。チャネルタイプ間にシーケンスの制限はありません。例えば、`training` チャネルの複数のエポックを読み取ることができ、準備ができたら `validation` チャネルの読み取りを開始するだけです。または、アルゴリズムで必要な場合はそれらを同時に読み取ることができます。 独自のコンテナを持ち込む際にパイプモードを使用する方法を示す Jupyter Notebook の例については、「[Bring your own pipe-mode algorithm to Amazon SageMaker AI](https://github.com/aws/amazon-sagemaker-examples/blob/main/advanced_functionality/pipe_bring_your_own/pipe_bring_your_own.ipynb)」を参照してください。 SageMaker AI モデルトレーニングは、ファイルモード、高速ファイルモード、パイプモードのデータ入力場所として、高性能の S3 Express One Zone ディレクトリバケットをサポートしています。S3 Express One Zone を使用するには、Amazon S3 汎用バケットの代わりに、S3 Express One Zone ディレクトリバケットの場所を入力します。IAM ロールの ARN に、必要なアクセスコントロールとアクセス許可ポリシーを指定します。詳細については、「[AmazonSageMakerFullAccesspolicy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonSageMakerFullAccess.html)」を参照してください。SageMaker AI 出力データは、Amazon S3 マネージドキー (SSE-S3) を使用するサーバー側の暗号化でのみディレクトリバケットで暗号化できます。 AWS KMS キーによるサーバー側の暗号化 (SSE-KMS) は現在、SageMaker AI 出力データをディレクトリバケットに保存するためにサポートされていません。詳細については、「[S3 Express One Zone](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone.html)」を参照してください。 ## 分散型トレーニング設定 複数コンテナで分散型トレーニングを実行する場合、SageMaker AI はすべてのコンテナに関する情報を `/opt/ml/input/config/resourceconfig.json` ファイル内で利用できるようにします。 コンテナ間通信を有効にするために、この JSON ファイルにはすべてのコンテナに関する情報が含まれます。SageMaker AI は、このファイルを `File` モードと `Pipe` モードの両方のアルゴリズムで利用できるようにします。ファイルは以下の情報を提供します。 + `current_host` - コンテナネットワーク上の現在のコンテナの名前。例えば、`algo-1`。ホスト値はいつでも変更できます。この変数に特定の値を指定したコードは記述しないでください。 + `hosts` - 辞書順にソートされた、コンテナネットワーク上のすべてのコンテナの名前のリスト。たとえば、3 ノードクラスターの場合は `["algo-1", "algo-2", "algo-3"]` です。コンテナでは、これらの名前を使用して、コンテナネットワーク上の他のコンテナをアドレス指定できます。ホスト値はいつでも変更できます。これらの変数に特定の値を指定したコードは記述しないでください。 + `network_interface_name` - コンテナに対して公開されているネットワークインターフェイスの名前。たとえば、Message Passing Interface (MPI) を実行しているコンテナは、この情報を使用してネットワークインターフェイス名を設定できます。 + この情報は正確ではない可能性があるため、`/etc/hostname` または `/etc/hosts` では使用しないでください。 + ホスト名情報は、アルゴリズムコンテナですぐには利用できない場合があります。ノードがクラスター内で使用可能になった時点で、ホスト名解決操作に再試行ポリシーを追加することをお勧めします。 3 ノードクラスターのノード 1 のファイル例を次に示します。 ``` { "current_host": "algo-1", "hosts": ["algo-1","algo-2","algo-3"], "network_interface_name":"eth1" } ``` # EFA でトレーニングを実行する SageMaker AI は、[EFA](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa.html) デバイスと統合でき、ハイパフォーマンスコンピューティング (HPC) および機械学習アプリケーションを高速化します。この統合により、分散トレーニングジョブを実行する場合に EFA デバイスを活用できます。SageMaker AI に取り込む既存の Docker コンテナに EFA 統合を追加できます。次の情報では、分散トレーニングジョブに EFA デバイスを使用するように独自のコンテナを設定する方法について説明します。 ## 前提条件 コンテナは [SageMaker トレーニングコンテナ仕様](https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-training-algo-dockerfile.html)を満たしている必要があります。  ## EFA および必要なパッケージをインストールする コンテナは、[EFA ソフトウェア](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa-start.html)をダウンロードしてインストールする必要があります。これにより、コンテナが EFA デバイスを認識し、Libfabric と Open MPI の互換性のあるバージョンが提供されます。 MPI や NCCL などのツールは、EFA 対応のトレーニングジョブの一部として使用するには、コンテナ内にインストールおよび管理する必要があります。使用可能なすべての EFA バージョンのリストについては、[「チェックサムを使用した EFA インストーラの検証](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa-verify.html)」を参照してください。次の例は、EFA 対応コンテナの Dockerfile を変更して EFA、MPI、OFI、NCCL、NCCL-TEST をインストールする方法を示しています。 **注記** コンテナで PyTorch を EFA とともに使用する場合、コンテナの NCCL バージョンは PyTorch インストールの NCCL バージョンと一致する必要があります。PyTorch NCCL のバージョンを検証するには、次のコマンドを使用します。 ``` torch.cuda.nccl.version() ``` ``` ARG OPEN_MPI_PATH=/opt/amazon/openmpi/ ENV NCCL_VERSION=2.7.8 ENV EFA_VERSION=1.30.0 ENV BRANCH_OFI=1.1.1 ################################################# ## EFA and MPI SETUP RUN cd $HOME \ && curl -O https://s3-us-west-2.amazonaws.com/aws-efa-installer/aws-efa-installer-${EFA_VERSION}.tar.gz \ && tar -xf aws-efa-installer-${EFA_VERSION}.tar.gz \ && cd aws-efa-installer \ && ./efa_installer.sh -y --skip-kmod -g \ ENV PATH="$OPEN_MPI_PATH/bin:$PATH" ENV LD_LIBRARY_PATH="$OPEN_MPI_PATH/lib/:$LD_LIBRARY_PATH" ################################################# ## NCCL, OFI, NCCL-TEST SETUP RUN cd $HOME \ && git clone https://github.com/NVIDIA/nccl.git -b v${NCCL_VERSION}-1 \ && cd nccl \ && make -j64 src.build BUILDDIR=/usr/local RUN apt-get update && apt-get install -y autoconf RUN cd $HOME \ && git clone https://github.com/aws/aws-ofi-nccl.git -b v${BRANCH_OFI} \ && cd aws-ofi-nccl \ && ./autogen.sh \ && ./configure --with-libfabric=/opt/amazon/efa \ --with-mpi=/opt/amazon/openmpi \ --with-cuda=/usr/local/cuda \ --with-nccl=/usr/local --prefix=/usr/local \ && make && make install RUN cd $HOME \ && git clone https://github.com/NVIDIA/nccl-tests \ && cd nccl-tests \ && make MPI=1 MPI_HOME=/opt/amazon/openmpi CUDA_HOME=/usr/local/cuda NCCL_HOME=/usr/local ``` ## コンテナを作成する場合の考慮事項 EFA デバイスは、コンテナからアクセス可能なデバイスのリストで `/dev/infiniband/uverbs0` としてコンテナにマウントされます。P4d インスタンスでは、コンテナは 4 つの EFA デバイスにアクセスできます。EFA デバイスは、次のようにコンテナからアクセス可能なデバイスのリストに表示されます。 + `/dev/infiniband/uverbs0` + `/dev/infiniband/uverbs1` + `/dev/infiniband/uverbs2` + `/dev/infiniband/uverbs3` 各コンテナインスタンスに提供される `resourceconfig.json` ファイルからホスト名、ピアホスト名、およびネットワークインターフェイス (MPI 用) に関する情報を取得するには、「[分散型トレーニング設定](https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-training-algo-running-container.html#your-algorithms-training-algo-running-container-dist-training)」を参照してください。コンテナは、デフォルトの Elastic Network Interface (ENI) を介してピア間の通常の TCP トラフィックを処理し、EFA デバイスを経由する OFI (カーネルバイパス) トラフィックを処理します。 ## EFA デバイスが認識されることを確認する  EFA デバイスが認識されていることを確認するには、コンテナ内から次のコマンドを実行します。 ``` /opt/amazon/efa/bin/fi_info -p efa ``` 出力は以下のようになります。 ``` provider: efa fabric: EFA-fe80::e5:56ff:fe34:56a8 domain: efa_0-rdm version: 2.0 type: FI_EP_RDM protocol: FI_PROTO_EFA provider: efa fabric: EFA-fe80::e5:56ff:fe34:56a8 domain: efa_0-dgrm version: 2.0 type: FI_EP_DGRAM protocol: FI_PROTO_EFA provider: efa;ofi_rxd fabric: EFA-fe80::e5:56ff:fe34:56a8 domain: efa_0-dgrm version: 1.0 type: FI_EP_RDM protocol: FI_PROTO_RXD ``` ## EFA でトレーニングジョブを実行する EFA 対応コンテナを作成したら、他の Docker イメージの場合と同じ方法で SageMaker AI 推定器を使用して EFA でトレーニングジョブを実行できます。コンテナを登録し、トレーニングに使用する方法の詳細については、「[独自のトレーニングコンテナを適応させる](https://docs.aws.amazon.com/sagemaker/latest/dg/adapt-training-container.html#byoc-training-step5)」を参照してください。 # Amazon SageMaker AI がアルゴリズムの成功と失敗を通知する方法 トレーニングアルゴリズムは、プロセスの終了コードを使用して、成功したか失敗したかを示します。 成功したトレーニング実行は終了コード 0 で終了する必要があり、成功しなかったトレーニング実行は 0 以外の終了コードで終了する必要があります。これらは、`DescribeTrainingJob` によって返される `TrainingJobStatus` で `Completed` および `Failed` に変換されます。この終了コード規則は標準であり、すべての言語で簡単に実装できます。例えば Python では、`sys.exit(1)` を使用して失敗終了を通知でき、単純にメインルーチンの最後まで実行すると Python はコード 0 で終了します。 失敗の場合、アルゴリズムは失敗の説明を失敗ファイルに書き込むことができます。詳細については、次のセクションを参照してください。 # Amazon SageMaker AI がトレーニングの出力を処理する方法 アルゴリズムはコンテナ内で実行されるため、トレーニングジョブとモデルのステータスおよび出力アーティファクトを含む出力が生成されます。アルゴリズムは、コンテナの `/output` ディレクトリにある次のファイルにこの情報を書き込む必要があります。Amazon SageMaker AI はこのディレクトリに含まれる情報を次のように処理します。 + `/opt/ml/model` - アルゴリズムは、すべての最終モデルアーティファクトをこのディレクトリに書き込む必要があります。SageMaker AI は、このデータを `CreateTrainingJob` のリクエストで指定した S3 の場所に圧縮された tar 形式の単一オブジェクトとしてコピーします。単一トレーニングジョブの複数のコンテナがこのディレクトリに書き込む場合、それらのコンテナに `file/directory` 名の競合がないことを確認する必要があります。SageMaker AI は TAR ファイルに結果を集約し、トレーニングジョブの最後に S3 にアップロードします。 + `/opt/ml/output/data` – アルゴリズムは、最終モデル以外に保存したいアーティファクトをこのディレクトリに書き込む必要があります。SageMaker AI は、このデータを `CreateTrainingJob` のリクエストで指定した S3 の場所に圧縮された tar 形式の単一オブジェクトとしてコピーします。単一トレーニングジョブの複数のコンテナがこのディレクトリに書き込む場合、それらのコンテナに `file/directory` 名の競合がないことを確認する必要があります。SageMaker AI は TAR ファイルに結果を集約し、トレーニングジョブの最後に S3 にアップロードします。 + `/opt/ml/output/failure` – トレーニングに失敗した場合、すべてのアルゴリズムの出力 (ログ記録など) の完了後に、アルゴリズムは失敗の説明をこのファイルに書き込む必要があります。`DescribeTrainingJob` レスポンスで、SageMaker AI はこのファイルの最初の 1024 文字を `FailureReason` として返します。 S3 汎用バケットまたは S3 ディレクトリバケットを指定して、トレーニング出力を保存できます。ディレクトリバケットは、Amazon S3 Express One Zone ストレージクラスのみを使用します。これは、一貫して 1 桁ミリ秒のレイテンシーに維持する必要があるワークロードまたはパフォーマンス重視のアプリケーション向けに設計されています。アプリケーションとパフォーマンス要件に最適なバケットタイプを選択します。S3 ディレクトリバケットの詳細については、*Amazon Simple Storage Service ユーザーガイド*の「[ディレクトリバケットの概要](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html)」を参照してください。 **注記** SageMaker AI 出力データは、Amazon S3 マネージドキー (SSE-S3) を使用するサーバー側の暗号化でのみ S3 ディレクトリバケットで暗号化できます。 AWS KMS キーによるサーバー側の暗号化 (SSE-KMS) は現在、SageMaker AI 出力データをディレクトリバケットに保存するためにサポートされていません。 # カスタム推論コードを持つコンテナ Amazon SageMaker AI を使用すると、Docker コンテナを操作し、以下のいずれかの方法で独自の推論コードを実行できます。 + 永続エンドポイントで独自の推論コードを使用して一度に 1 つの予測を取得するには、SageMaker AI ホスティングサービスを使用します。 + 独自の推論コードを使用してデータセット全体の予測を取得するには、SageMaker AI バッチ変換を使用します。 **Topics** + [ホスティングサービスでのカスタム推論コードの使用](your-algorithms-inference-code.md) + [バッチ変換でのカスタム推論コード](your-algorithms-batch-code.md) # ホスティングサービスでのカスタム推論コードの使用 このセクションでは、Amazon SageMaker AI がホスティングサービス用の独自の推論コードを実行する Docker コンテナとやり取りする方法について説明します。この情報を使用して、推論コードを書き込み、Docker イメージを作成します。 **Topics** + [SageMaker AI が推論イメージを実行する方法](#your-algorithms-inference-code-run-image) + [SageMaker AI がモデルアーティファクトをロードする方法](#your-algorithms-inference-code-load-artifacts) + [コンテナが推論リクエストに応答する方法](#your-algorithms-inference-code-container-response) + [コンテナがヘルスチェック (Ping) リクエストに応答する方法](#your-algorithms-inference-algo-ping-requests) + [双方向ストリーミング機能をサポートするコンテナ契約](#your-algorithms-inference-algo-bidi) + [リアルタイム推論コンテナにプライベート Docker レジストリを使用する](your-algorithms-containers-inference-private.md) ## SageMaker AI が推論イメージを実行する方法 コンテナを実行可能ファイルとして実行するように設定するには、Dockerfile で `ENTRYPOINT` 命令を使用します。次の点に注意してください。 + モデル推論の場合、SageMaker AI はコンテナを次のように実行します。 ``` docker run image serve ``` SageMaker AI はイメージ名の後に `serve` 引数を指定して、コンテナ内のデフォルトの `CMD` ステートメントを上書きします。`serve` 引数は、Dockerfile の `CMD` コマンドで指定した引数よりも優先されます。   + SageMaker AI では、すべてのコンテナがルートユーザーで実行されることを想定しています。ルートユーザーのみを使用するようにコンテナを作成します。SageMaker AI がコンテナを実行する際、ルートレベルのアクセス権を持たないユーザーによって権限の問題が発生する場合があります。   + `exec` 命令の `ENTRYPOINT` フォームを使用することをお勧めします。 ``` ENTRYPOINT ["executable", "param1", "param2"] ``` 例: ``` ENTRYPOINT ["python", "k_means_inference.py"] ``` `exec` 命令の `ENTRYPOINT` フォームは、`/bin/sh` の子としてではなく、直接実行ファイルを開始します。これにより、SageMaker API オペレーションから `SIGTERM` や `SIGKILL` のようなシグナルを受信できます。これは要件です。   例えば、エンドポイントを作成する [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) API を使用する場合に、SageMaker AI はリクエストで指定するエンドポイント設定で必要な ML コンピューティングインスタンスの数をプロビジョニングします。SageMaker AI はそれらのインスタンスで Docker コンテナを実行します。   エンドポイントをバックアップするインスタンスの数を減らす場合 ([https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html) API の呼び出しによって)、SageMaker AI は終了するインスタンスの Docker コンテナを停止するコマンドを実行します。コマンドは、`SIGTERM` シグナルを送信し、30 秒後に `SIGKILL` シグナルを送信します。   エンドポイントを更新する場合 ([https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html) API の呼び出しによって)、SageMaker AI は別の一連の ML コンピューティングインスタンスを起動して、推論コードを含む Docker コンテナを実行します。次に、前の Docker コンテナを停止するコマンドを実行します。Docker コンテナを停止するために、コマンドは、`SIGTERM` シグナルを送信し、30 秒後に `SIGKILL` シグナルを送信します。   + SageMaker AI は [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) リクエストで指定したコンテナ定義を使用してコンテナの環境変数と DNS ホスト名を次のように設定します。   + `ContainerDefinition.Environment` 文字列間マップを使用して環境変数を設定します。 + `ContainerDefinition.ContainerHostname` を使用して DNS ホスト名を設定します。   + モデル推論に GPU デバイスを使用 (`CreateEndpointConfig` リクエストで GPU ベースの ML コンピューティングインスタンスを指定) する予定の場合は、コンテナが `nvidia-docker` 互換であることを確認してください。NVIDIA ドライバーをイメージにバンドルしないでください。`nvidia-docker` の詳細については、[NVIDIA/nvidia-docker](https://github.com/NVIDIA/nvidia-docker) を参照してください。   + `tini` 引数と `train` 引数で混乱が生じるため、SageMaker AI コンテナでは、`serve` イニシャライザをエントリポイントとして使用することはできません。 ## SageMaker AI がモデルアーティファクトをロードする方法 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) API リクエストでは、`ModelDataUrl` または `S3DataSource` パラメータを使用して、モデルアーティファクトが保存されている S3 の場所を特定することができます。SageMaker AI は、推論コードで使用するために、モデルアーティファクトを S3 の場所から `/opt/ml/model` ディレクトリにコピーします。コンテナは `/opt/ml/model` に読み取り専用でアクセスできます。このディレクトリには書き込まないでください。 `ModelDataUrl` は tar.gz ファイルを指す必要があります。この情報がないと、SageMaker AI はファイルをダウンロードできません。 モデルを SageMaker AI でトレーニングした場合、モデルアーティファクトは Amazon S3 の単一の圧縮 tar ファイルとして保存されます。SageMaker AI の外部でモデルをトレーニングした場合は、この単一の圧縮 tar ファイルを作成して S3 の場所に保存する必要があります。コンテナが起動する前に、SageMaker AI は、この tar ファイルを /opt/ml/model ディレクトリに解凍します。 大規模なモデルをデプロイする場合は、[非圧縮モデルのデプロイ](large-model-inference-uncompressed.md) の配置に従うことをお勧めします。 ## コンテナが推論リクエストに応答する方法 推論を取得するため、クライアントアプリケーションは POST リクエストを SageMaker AI エンドポイントに送信します。SageMaker AI はリクエストをコンテナに渡し、推論結果をコンテナからクライアントに返します。 コンテナが受け取る推論リクエストの詳細については、*Amazon SageMaker AI API リファレンス*の以下のアクションを参照してください。 + [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) + [InvokeEndpointAsync](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpointAsync.html) + [InvokeEndpointWithResponseStream](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html) + [InvokeEndpointWithResponseStream](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithBidirectionalStream.html) **推論コンテナの要件** 推論リクエストに応答するには、コンテナが次の要件を満たしている必要があります。 + `InvokeEndpoint` でサポートされているものを除き、SageMaker AI はすべての `POST` ヘッダーを削除します。SageMaker AI は追加のヘッダーを追加する場合があります。推論コンテナはこれらの追加ヘッダーを安全に無視できる必要があります。 + 推論リクエストを受信するには、コンテナにポート 8080 でリッスンするウェブサーバーが必要であり、`/invocations` および `/ping` エンドポイントへの `POST` リクエストを受け入れる必要があります。 + 顧客のモデルコンテナは、250 ミリ秒以内にソケット接続リクエストを受け入れる必要があります。 + 顧客のモデルコンテナは、60 秒以内にリクエストに応答する必要があります。モデル自体は、`/invocations` に応答するまで 60 秒の最大処理時間をかけることができます。モデルの処理時間が 50 ～ 60 秒かかる場合は、SDK ソケットタイムアウトを 70 秒に設定する必要があります。 + 双方向ストリーミングをサポートする顧客のモデルコンテナは、以下を行う必要があります。 + は、デフォルトでポート 8080 から /invocations-bidirectional-stream への WebSockets 接続をサポートします。 invocations-bidirectional-stream + ポート 8080 でリッスンしているウェブサーバーがあり、/ping エンドポイントへの POST リクエストを受け入れる必要があります。 + HTTP 経由のコンテナヘルスチェックに加えて、コンテナは送信される WebSocket Ping Frame の ([RFC6455](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)) に従って Pong Frame で応答する必要があります。 **Example 呼び出し関数** 以下の例は、コンテナ内のコードで推論リクエストを処理する方法を示しています。これらの例は、InvokeEndpoint アクションを使用してクライアントアプリケーションが送信するリクエストを処理します。 FastAPI は Python を使用して API を構築するためのウェブフレームワークです。 ``` from fastapi import FastAPI, status, Request, Response . . . app = FastAPI() . . . @app.post('/invocations') async def invocations(request: Request): # model() is a hypothetical function that gets the inference output: model_resp = await model(Request) response = Response( content=model_resp, status_code=status.HTTP_200_OK, media_type="text/plain", ) return response . . . ``` この例では、`invocations` 関数は SageMaker AI が `/invocations` エンドポイントに送信する推論リクエストを処理します。 Flask は、Python を使用してウェブアプリケーションを開発するためのフレームワークです。 ``` import flask . . . app = flask.Flask(__name__) . . . @app.route('/invocations', methods=["POST"]) def invoke(request): # model() is a hypothetical function that gets the inference output: resp_body = model(request) return flask.Response(resp_body, mimetype='text/plain') ``` この例では、`invoke` 関数は SageMaker AI が `/invocations` エンドポイントに送信する推論リクエストを処理します。 **Example ストリーミングリクエストの呼び出し関数** 以下の例は、推論コンテナ内のコードで推論リクエストを処理する方法を示しています。これらの例は、InvokeEndpointWithResponseStream アクションを使用してクライアントアプリケーションが送信するリクエストを処理します。 コンテナがストリーミング推論リクエストを処理すると、モデルが推論を生成する際に、モデルの推論は一連のパーツとして段階的に返されます。レスポンスが利用可能になると、クライアントアプリケーションはすぐに受信し始めます。クライアントアプリケーションは、モデルがレスポンス全体を生成するのを待つ必要はありません。ストリーミングを実装し、チャットボット、仮想アシスタント、ミュージックジェネレーターなどの高速でインタラクティブな体験をサポートできます。 FastAPI は Python を使用して API を構築するためのウェブフレームワークです。 ``` from starlette.responses import StreamingResponse from fastapi import FastAPI, status, Request . . . app = FastAPI() . . . @app.post('/invocations') async def invocations(request: Request): # Streams inference response using HTTP chunked encoding async def generate(): # model() is a hypothetical function that gets the inference output: yield await model(Request) yield "\n" response = StreamingResponse( content=generate(), status_code=status.HTTP_200_OK, media_type="text/plain", ) return response . . . ``` この例では、`invocations` 関数は SageMaker AI が `/invocations` エンドポイントに送信する推論リクエストを処理します。この例ではレスポンスをストリーミングするために、Starlette フレームワークの `StreamingResponse` クラスを使用しています。 Flask は、Python を使用してウェブアプリケーションを開発するためのフレームワークです。 ``` import flask . . . app = flask.Flask(__name__) . . . @app.route('/invocations', methods=["POST"]) def invocations(request): # Streams inference response using HTTP chunked encoding def generate(): # model() is a hypothetical function that gets the inference output: yield model(request) yield "\n" return flask.Response( flask.stream_with_context(generate()), mimetype='text/plain') . . . ``` この例では、`invocations` 関数は SageMaker AI が `/invocations` エンドポイントに送信する推論リクエストを処理します。この例ではレスポンスをストリーミングするために、Flask フレームワークの `flask.stream_with_context` 関数を使用しています。 **Example 双方向ストリーミングの呼び出し関数の例** 次の例は、コンテナ内のコードがストリーミング推論リクエストとレスポンスを処理する方法を示しています。これらの例では、InvokeEndpointWithBidirectionalStream アクションを使用してクライアントアプリケーションが送信するストリーミングリクエストを処理します。 双方向ストリーミング機能を備えたコンテナは、パートがクライアントで段階的に生成され、コンテナにストリーミングされるストリーミング推論リクエストを処理します。モデルの推論は、モデルが生成する一連のパートとしてクライアントに返されます。レスポンスが利用可能になると、クライアントアプリケーションはすぐに受信し始めます。クライアントで完全に生成された へのリクエストや、モデルがレスポンス全体を生成するのを待つ必要はありません。双方向ストリーミングを実装して、チャットボット、インタラクティブな音声 AI アシスタント、リアルタイム翻訳などの高速なインタラクティブエクスペリエンスをサポートし、よりリアルタイムのエクスペリエンスを実現できます。 FastAPI は Python を使用して API を構築するためのウェブフレームワークです。 ``` import sys import asyncio import json from fastapi import FastAPI, WebSocket, WebSocketDisconnect from fastapi.responses import JSONResponse import uvicorn app = FastAPI() ... @app.websocket("/invocations-bidirectional-stream") async def websocket_invoke(websocket: WebSocket): """ WebSocket endpoint with RFC 6455 ping/pong and fragmentation support Handles: - Text messages (JSON) - including fragmented frames - Binary messages - including fragmented frames - Ping frames (automatically responds with pong) - Pong frames (logs receipt) - Fragmented frames per RFC 6455 Section 5.4 """ await manager.connect(websocket) # Fragment reassembly buffers per RFC 6455 Section 5.4 text_fragments = [] binary_fragments = [] while True: # Use receive() to handle all WebSocket frame types message = await websocket.receive() print(f"Received message: {message}") if message["type"] == "websocket.receive": if "text" in message: # Handle text frames (including fragments) text_data = message["text"] more_body = message.get("more_body", False) if more_body: # This is a fragment, accumulate it text_fragments.append(text_data) print(f"Received text fragment: {len(text_data)} chars (more coming)") else: # This is the final frame or a complete message if text_fragments: # Reassemble fragmented message text_fragments.append(text_data) complete_text = "".join(text_fragments) text_fragments.clear() print(f"Reassembled fragmented text message: {len(complete_text)} chars total") await handle_text_message(websocket, complete_text) else: # Complete message in single frame await handle_text_message(websocket, text_data) elif "bytes" in message: # Handle binary frames (including fragments) binary_data = message["bytes"] more_body = message.get("more_body", False) if more_body: # This is a fragment, accumulate it binary_fragments.append(binary_data) print(f"Received binary fragment: {len(binary_data)} bytes (more coming)") else: # This is the final frame or a complete message if binary_fragments: # Reassemble fragmented message binary_fragments.append(binary_data) complete_binary = b"".join(binary_fragments) binary_fragments.clear() print(f"Reassembled fragmented binary message: {len(complete_binary)} bytes total") await handle_binary_message(websocket, complete_binary) else: # Complete message in single frame await handle_binary_message(websocket, binary_data) elif message["type"] == "websocket.ping": # Handle ping frames - RFC 6455 Section 5.5.2 ping_data = message.get("bytes", b"") print(f"Received PING frame with payload: {ping_data}") # FastAPI automatically sends pong response elif message["type"] == "websocket.pong": # Handle pong frames pong_data = message.get("bytes", b"") print(f"Received PONG frame with payload: {pong_data}") elif message["type"] == "websocket.close": # Handle close frames - RFC 6455 Section 5.5.1 close_code = message.get("code", 1000) close_reason = message.get("reason", "") print(f"Received CLOSE frame - Code: {close_code}, Reason: '{close_reason}'") # Send close frame response if not already closing try: await websocket.close(code=close_code, reason=close_reason) print(f"Sent CLOSE frame response - Code: {close_code}") except Exception as e: print(f"Error sending close frame: {e}") break elif message["type"] == "websocket.disconnect": print("Client initiated disconnect") break else: print(f"Received unknown message type: {message['type']}") break async def handle_binary_message(websocket: WebSocket, binary_data: bytes): """Handle incoming binary messages (complete or reassembled from fragments)""" print(f"Processing complete binary message: {len(binary_data)} bytes") try: # Echo back the binary data await websocket.send_bytes(binary_data) except Exception as e: print(f"Error handling binary message: {e}") async def handle_text_message(websocket: WebSocket, data: str): """Handle incoming text messages""" try: # Send response back to the same client await manager.send_personal_message(data, websocket) except Exception as e: print(f"Error handling text message: {e}") def main(): if len(sys.argv) > 1 and sys.argv[1] == "serve": print("Starting server on port 8080...") uvicorn.run(app, host="0.0.0.0", port=8080) else: print("Usage: python app.py serve") sys.exit(1) if __name__ == "__main__": main() ``` この例では、`websocket_invoke` 関数は SageMaker AI が `/invocations-bidirectional-stream` エンドポイントに送信する推論リクエストを処理します。ストリームリクエストとストリームレスポンスの処理がクライアントに返されます。 ## コンテナがヘルスチェック (Ping) リクエストに応答する方法 SageMaker AI は、以下の状況で新しい推論コンテナを起動します。 + `CreateEndpoint`、`UpdateEndpoint`、および `UpdateEndpointWeightsAndCapacities` API 呼び出しへの応答 + セキュリティパッチ + 異常のあるインスタンスの置き換え コンテナの起動直後に、SageMaker AI は定期的に GET リクエストを `/ping` エンドポイントに送信し始めます。 コンテナの最も単純な要件は、HTTP 200 のステータスコードと空の本文で応答することです。これにより SageMaker AI に対し、コンテナが `/invocations` エンドポイントでの推論リクエストを受け入れる準備ができていることを示されます。 コンテナがスタートアップ後 8 分間に、常に 200 秒で応答しヘルスチェックを通過しない場合、新しいインスタンスの起動は失敗します。これにより `CreateEndpoint` は失敗し、エンドポイントは障害状態のままになります。`UpdateEndpoint` によって要求された更新は完了せず、セキュリティパッチは適用されず、異常のあるインスタンスは置き換えられません。 コンテナが静的な 200 を返す最小限のバーがありますが、コンテナ開発者はこの機能を使用してより深いチェックを実行できます。`/ping` 試行のリクエストのタイムアウトは 2 秒です。 さらに、双方向ストリーミングリクエストを処理できるコンテナは、Pong フレーム (WebSocket プロトコル [RFC6455](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3) に準拠) で Ping フレームに応答する必要があります。Pong Frame が 5 回連続して受信されない場合、コンテナへの接続は SageMaker AI プラットフォームによって閉じられます。SageMaker AI プラットフォームは、Pong Frames を持つモデルコンテナから Ping Frames にも応答します。 ## 双方向ストリーミング機能をサポートするコンテナ契約 双方向ストリーミング機能をサポートする SageMaker AI エンドポイントとしてモデルコンテナをホストする場合は、モデルコンテナが以下の契約をサポートしている必要があります。 **1. 双方向 Docker ラベル ** モデルコンテナには、このコンテナで双方向ストリーミング機能がサポートされていることを SageMaker AI プラットフォームに示す Docker ラベルが必要です。 ``` com.amazonaws.sagemaker.capabilities.bidirectional-streaming=true ``` **2. 呼び出しの WebSocket 接続のサポート** 双方向ストリーミングをサポートするお客様のモデルコンテナは、`/invocations-bidirectional-stream`デフォルトでポート 8080 から への WebSockets 接続をサポートする必要があります。 このパスは、InvokeEndpointWithBidirectionalStream API を呼び出すときに X-Amzn-SageMaker-Model-Invocation-Path ヘッダーを渡すことで上書きできます。 InvokeEndpointWithBidirectionalStream さらに、InvokeEndpointWithBidirectionalStream API を呼び出すときに X-Amzn-SageMaker-Model-Query-String ヘッダーを渡すことで、このパスに追加するクエリ文字列を指定できます。 **3. リクエストストリームの処理** InvokeEndpointWithBidirectionalStream API 入力ペイロードは、バイナリチャンク (「バイト」: ) のラッパーにすぎない一連の PayloadParts として にストリーミングされます。 ****** ``` { "PayloadPart": { "Bytes": , "DataType": , "CompletionState": "P": } } ``` **3.1。データフレーム** SageMaker AI が入力 PayloadParts をモデルコンテナに WebSocket データフレームとして渡す ([RFC6455-Section-5.6](https://datatracker.ietf.org/doc/html/rfc6455#section-5.6)) 1. SageMaker AI はバイナリチャンクを検査しません。 1. 入力 PayloadPart の受信時 + SageMaker AI は、 から WebSocket データフレームを 1 つだけ作成し`PayloadPart.Bytes`、それをモデルコンテナに渡します。 + の場合`PayloadPart.DataType = UTF8`、SageMaker AI はテキストデータフレームを作成します + `PayloadPart.DataType` に または が存在しない場合`PayloadPart.DataType = BINARY`、SageMaker AI はバイナリデータフレームを作成します。 1. を使用した一連の PayloadParts で`PayloadPart.CompletionState = PARTIAL`、 を使用した PayloadPart によって終了された場合`PayloadPart.CompletionState = COMPLETE`、SageMaker AI はそれらを WebSocket フラグメント化されたメッセージ [RFC6455-Section-5.4: Fragmentation](https://datatracker.ietf.org/doc/html/rfc6455#section-5.4) に変換します。 + を使用した最初の PayloadPart は、FIN ビットがクリアされた WebSocket データフレームに変換`PayloadPart.CompletionState = PARTIAL`されます。 + を使用した後続の PayloadParts は、FIN ビットクリアの WebSocket 継続フレームに変換`PayloadPart.CompletionState = PARTIAL`されます。 + を使用した最終的な PayloadPart は、FIN ビットが設定された WebSocket 継続フレームに変換`PayloadPart.CompletionState = COMPLETE`されます。 1. SageMaker AI は入力 PayloadPart からバイナリチャンクをエンコードまたはデコードせず、バイトはそのままモデルコンテナに渡されます。 1. SageMaker AI は、複数の入力 PayloadParts を 1 つの BinaryDataFrame に結合しません。 1. SageMaker AI は、1 つの入力 PayloadPart を複数の BinaryDataFrames にチャンクしません。 **例: フラグメント化されたメッセージフロー** ``` Client sends: PayloadPart 1: {Bytes: "Hello ", DataType: "UTF8", CompletionState: "PARTIAL"} PayloadPart 2: {Bytes: "World", DataType: "UTF8", CompletionState: "COMPLETE"} Container receives: Frame 1: Text Data Frame with "Hello " (FIN=0) Frame 2: Continuation Frame with "World" (FIN=1) ``` **3.2。コントロールフレーム** データフレームに加えて、SageMaker AI はコントロールフレームをモデルコンテナ ([RFC6455-Section-5.5](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5)) に送信します。 1. Close Frame: 何らかの理由で接続が閉じられた場合、SageMaker AI は Close Frame ([RFC6455-Section-5.5.1](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.1)) をモデルコンテナに送信することがあります。 1. Ping フレーム: SageMaker AI は 60 秒に 1 回 Ping フレーム ([RFC6455-Section-5.5.2](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2)) を送信します。モデルコンテナは Pong フレームで応答する必要があります。Pong フレーム ([RFC6455-Section-5.5.3](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)) が 5 回連続して受信されない場合、接続は SageMaker AI によって閉じられます。 1. Pong Frame: SageMaker AI は、Pong Frames を持つモデルコンテナから Ping Frames に応答します。 **4. レスポンスストリームの処理** 出力は、一連の PayloadParts、ModelStreamErrors、または InternalStreamFailures としてストリーミングされます。 ``` { "PayloadPart": { "Bytes": , "DataType": , "CompletionState": , }, "ModelStreamError": { "ErrorCode": , "Message": }, "InternalStreamFailure": { "Message": } } ``` **4.1。データフレーム** SageMaker AI は、モデルコンテナから受信したデータフレームを出力 PayloadParts に変換します。 1. モデルコンテナから WebSocket Text Data Frame を受信すると、SageMaker AI は Text Data Frame から raw バイトを取得し、それをレスポンス PayloadPart にラップし、同時に を設定します`PayloadPart.DataType = UTF8`。 1. モデルコンテナから WebSocket バイナリデータフレームを受信すると、SageMaker AI はデータフレームからのバイトをレスポンス PayloadPart に直接ラップし、同時に を設定します`PayloadPart.DataType = BINARY`。 1. [RFC6455-Section-5.4: Fragmentation](https://datatracker.ietf.org/doc/html/rfc6455#section-5.4) で定義されているフラグメント化されたメッセージの場合: + FIN ビットがクリアされた最初のデータフレームは、 の PayloadPart に変換されます`PayloadPart.CompletionState = PARTIAL`。 + FIN ビットがクリアされた後続の継続フレームは、 を使用して PayloadParts に変換されます`PayloadPart.CompletionState = PARTIAL`。 + FIN ビットが設定された最後の継続フレームは、 を使用して PayloadPart に変換されます`PayloadPart.CompletionState = COMPLETE`。 1. SageMaker AI はモデルコンテナから受信したバイトをエンコードまたはデコードせず、バイトはそのままモデルコンテナに渡されます。 1. SageMaker AI は、モデルコンテナから受信した複数のデータフレームを 1 つのレスポンス PayloadPart に結合しません。 1. SageMaker AI は、モデルコンテナから受信したデータフレームを複数のレスポンス PayloadParts にチャンクしません。 **例: ストリーミングレスポンスフロー** ``` Container sends: Frame 1: Text Data Frame with "Generating" (FIN=0) Frame 2: Continuation Frame with " response..." (FIN=1) Client receives: PayloadPart 1: {Bytes: "Generating", DataType: "UTF8", CompletionState: "PARTIAL"} PayloadPart 2: {Bytes: " response...", DataType: "UTF8", CompletionState: "COMPLETE"} ``` **4.2。コントロールフレーム** SageMaker AI は、モデルコンテナから次のコントロールフレームに応答します。 1. モデルコンテナからクローズフレーム ([RFC6455-Section-5.5.1](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.1)) を受信すると、SageMaker AI はステータスコード ([RFC6455-Section-7.4](https://datatracker.ietf.org/doc/html/rfc6455#section-7.4)) と失敗メッセージを ModelStreamError にラップし、エンドユーザーにストリーミングします。 1. モデルコンテナから Ping フレーム ([RFC6455-Section-5.5.2](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2)) を受信すると、SageMaker AI は Pong Frame で応答します。 1. Pong Frame([RFC6455-Section-5.5.3](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)): Pong Frame が 5 回連続して受信されない場合、接続は SageMaker AI によって閉じられます。 # リアルタイム推論コンテナにプライベート Docker レジストリを使用する Amazon SageMaker AI ホスティングでは、Amazon ECR に保存されているイメージを使用して、デフォルトでリアルタイム推論のためのコンテナを構築できます。オプションで、プライベート Docker レジストリ内のイメージからリアルタイム推論用のコンテナを構築できます。プライベートレジストリは、アカウント内の Amazon VPC からアクセスできることが必要です。プライベート Docker レジストリに格納されているイメージに基づいて作成するモデルは、プライベート Docker レジストリがアクセスできる同じ VPC に接続するように設定する必要があります。モデルの VPC への接続の詳細については、「[Amazon VPC のリソースへのアクセス権を SageMaker AI のホストされたエンドポイントに付与する](host-vpc.md)」を参照してください。 Docker レジストリは、既知の公開認証機関 (CA) からの TLS 証明書で保護されている必要があります。 **注記** SageMaker AI ホスティングがレジストリからモデルイメージをプルできるように、プライベート Docker レジストリは、モデルの VPC 設定で指定したセキュリティグループからのインバウンドトラフィックを許可する必要があります。 SageMaker AI は、VPC 内にオープンインターネットへのパスがある場合、DockerHub からモデルイメージをプルできます。 **Topics** + [Amazon Elastic コンテナレジストリ以外のプライベート Docker レジストリにイメージを保存する](#your-algorithms-containers-inference-private-registry) + [リアルタイム推論にプライベート Docker レジストリのイメージを使用する](#your-algorithms-containers-inference-private-use) + [SageMaker AI がプライベート Docker レジストリに対して認証できるようにする](#inference-private-docker-authenticate) + [Lambda 関数を作成する](#inference-private-docker-lambda) + [実行ロールに Lambda へのアクセス許可を付与する](#inference-private-docker-perms) + [Lambda のインターフェイス VPC エンドポイントを作成する](#inference-private-docker-vpc-interface) ## Amazon Elastic コンテナレジストリ以外のプライベート Docker レジストリにイメージを保存する プライベートの Docker レジストリを使用して SageMaker AI リアルタイム推論用にイメージを保存するには、Amazon VPC からアクセスできるプライベートレジストリを作成します。Docker レジストリの作成の詳細については、Docker ドキュメントの「[レジストリサーバーをデプロイする](https://docs.docker.com/registry/deploying/)」を参照してください。Docker レジストリは、以下を満たす必要があります。 + レジストリは [Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/) レジストリであることが必要です。 + Docker レジストリは、モデルの作成時に指定する `VpcConfig` パラメータで指定する同じ VPC からアクセスできる必要があります。 ## リアルタイム推論にプライベート Docker レジストリのイメージを使用する モデルを作成し、SageMaker AI ホスティングにデプロイする場合に、プライベート Docker レジストリのイメージを使用して推論コンテナを構築するように指定できます。[create\$1model](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model) 関数の呼び出しに渡す `PrimaryContainer` パラメータの `ImageConfig` オブジェクトでこれを指定します。 **プライベート Docker レジストリに保存されているイメージを推論コンテナに使用するには** 1. イメージ設定オブジェクトを作成し、`RepositoryAccessMode` フィールドに `Vpc` の値を指定します。 ``` image_config = { 'RepositoryAccessMode': 'Vpc' } ``` 1. プライベートの Docker レジストリに認証が必要な場合は、`RepositoryAuthConfig` オブジェクトを、イメージ設定オブジェクトに追加します。`RepositoryAuthConfig` オブジェクトの `RepositoryCredentialsProviderArn`フィールドで、SageMaker AI がプライベート Docker レジストリに対して認証できるようにする認証情報を提供する AWS Lambda 関数の Amazon リソースネーム (ARN) を指定します。認証を提供するために Lambda 関数を作成する方法については、「[SageMaker AI がプライベート Docker レジストリに対して認証できるようにする](#inference-private-docker-authenticate)」を参照してください。 ``` image_config = { 'RepositoryAccessMode': 'Vpc', 'RepositoryAuthConfig': { 'RepositoryCredentialsProviderArn': 'arn:aws:lambda:Region:Acct:function:FunctionName' } } ``` 1. 前のステップで作成したイメージ設定オブジェクトを使用し、`create_model` に渡すプライマリコンテナオブジェクトを作成します。 [ダイジェスト](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier)フォームでイメージを提供します。`:latest` タグを使用してイメージを提供する場合、SageMaker AI が意図したよりも新しいバージョンのイメージをプルするリスクがあります。ダイジェストフォームを使用すると、意図したイメージバージョンを確実に SageMaker AI がプルするようになります。 ``` primary_container = { 'ContainerHostname': 'ModelContainer', 'Image': 'myteam.myorg.com/docker-local/my-inference-image:', 'ImageConfig': image_config } ``` 1. `create_model` に渡すモデル名と実行ロールを指定します。 ``` model_name = 'vpc-model' execution_role_arn = 'arn:aws:iam::123456789012:role/SageMakerExecutionRole' ``` 1. 1 つ以上のセキュリティグループとサブネットをモデルの VPC 設定に指定します。プライベート Docker レジストリは、指定したセキュリティグループからのインバウンドトラフィックを許可する必要があります。指定するサブネットは、プライベート Docker レジストリと同じ VPC 内にある必要があります。 ``` vpc_config = { 'SecurityGroupIds': ['sg-0123456789abcdef0'], 'Subnets': ['subnet-0123456789abcdef0','subnet-0123456789abcdef1'] } ``` 1. Boto3 SageMaker AI クライアントを入手します。 ``` import boto3 sm = boto3.client('sagemaker') ``` 1. `PrimaryContainer` および `VpcConfig` パラメータに前の手順で指定した値を使用して `create_model` を呼び出し、モデルを作成します。 ``` try: resp = sm.create_model( ModelName=model_name, PrimaryContainer=primary_container, ExecutionRoleArn=execution_role_arn, VpcConfig=vpc_config, ) except Exception as e: print(f'error calling CreateModel operation: {e}') else: print(resp) ``` 1. 最後に、前のステップで作成したモデルを使用し、[create\$1endpoint\$1config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config) および [create\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint) を呼び出してホスティングエンドポイントを作成します。 ``` endpoint_config_name = 'my-endpoint-config' sm.create_endpoint_config( EndpointConfigName=endpoint_config_name, ProductionVariants=[ { 'VariantName': 'MyVariant', 'ModelName': model_name, 'InitialInstanceCount': 1, 'InstanceType': 'ml.t2.medium' }, ], ) endpoint_name = 'my-endpoint' sm.create_endpoint( EndpointName=endpoint_name, EndpointConfigName=endpoint_config_name, ) sm.describe_endpoint(EndpointName=endpoint_name) ``` ## SageMaker AI がプライベート Docker レジストリに対して認証できるようにする 認証を必要とするプライベート Docker レジストリから推論イメージをプルするには、認証情報を提供する AWS Lambda 関数を作成し、[create\$1model](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model) を呼び出すときに Lambda 関数の Amazon リソースネーム (ARN) を指定します。SageMaker AI が `create_model` を実行する場合、指定した Lambda 関数を呼び出して Docker レジストリに認証するための認証情報を取得します。 ## Lambda 関数を作成する 次の形式でレスポンスを返す AWS Lambda 関数を作成します。 ``` def handler(event, context): response = { "Credentials": {"Username": "username", "Password": "password"} } return response ``` プライベート Docker レジストリの認証の設定方法に応じて、Lambda 関数が返す認証情報は、次のいずれかを意味する可能性があります。 + 基本認証を使用するようにプライベート Docker レジストリを設定した場合、レジストリに対して認証するためのサインイン認証情報を提供します。 + ベアラトークン認証を使用するようにプライベート Docker レジストリを設定すると、サインイン認証情報が認可サーバーに送信され、ベアラトークンが返され、これをプライベートの Docker レジストリへの認証に使用できます。 ## 実行ロールに Lambda へのアクセス許可を付与する 呼び出しに使用する実行ロールには、 AWS Lambda 関数を呼び出すアクセス許可`create_model`が必要です。実行ロールのアクセス許可ポリシーに以下を追加します。 ``` { "Effect": "Allow", "Action": [ "lambda:InvokeFunction" ], "Resource": [ "arn:aws:lambda:*:*:function:*myLambdaFunction*" ] } ``` ここで、*mylambdaFunction* は Lambda 関数の名前です。ロールのアクセス許可ポリシーの編集の詳細については、AWS Identity and Access Management ユーザーガイドの「[ロールのアクセス許可ポリシーの変更 (コンソール)](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-modify_permissions-policy)」を参照してください。** **注記** `AmazonSageMakerFullAccess` マネージドポリシーがアタッチされた実行ロールには、名前に **SageMaker** がある任意の Lambda 関数を呼び出せるアクセス許可があります。 ## Lambda のインターフェイス VPC エンドポイントを作成する Amazon VPC がインターネット経由でトラフィックを送信せずに AWS Lambda 関数と通信できるようにインターフェイスエンドポイントを作成します。詳細については、AWS Lambda デベロッパーガイドの「[Lambda のインターフェイス VPC エンドポイントの設定](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc-endpoints.html)」を参照してください。** SageMaker AI ホスティングは VPC 経由で `lambda.region.amazonaws.com` にリクエストを送信し、Lambda 関数を呼び出します。インターフェイスエンドポイントの作成時にプライベート DNS 名を選択すると、Amazon Route 53 は呼び出しを Lambda インターフェイスエンドポイントにルーティングします。別の DNS プロバイダーを使用する場合は、必ず `lambda.region.amazonaws.com` を Lambda インターフェイスエンドポイントに対応付けてください。 # バッチ変換でのカスタム推論コード このセクションでは、Amazon SageMaker AI がバッチ変換用の独自の推論コードを実行する Docker コンテナとやり取りする方法について説明します。この情報を使用して、推論コードを書き込み、Docker イメージを作成します。 **Topics** + [SageMaker AI が推論イメージを実行する方法](#your-algorithms-batch-code-run-image) + [SageMaker AI がモデルアーティファクトをロードする方法](#your-algorithms-batch-code-load-artifacts) + [コンテナがリクエストを提供する方法](#your-algorithms-batch-code-how-containe-serves-requests) + [コンテナが推論リクエストに応答する方法](#your-algorithms-batch-code-how-containers-should-respond-to-inferences) + [コンテナがヘルスチェック (Ping) リクエストに応答する方法](#your-algorithms-batch-algo-ping-requests) ## SageMaker AI が推論イメージを実行する方法 コンテナを実行可能ファイルとして実行するように設定するには、Dockerfile で `ENTRYPOINT` 命令を使用します。次の点に注意してください。 + バッチ変換の場合、SageMaker AI はユーザーに代わってモデルを呼び出します。SageMaker AI はコンテナを次のように実行します。 ``` docker run image serve ``` バッチ変換への入力は、小さなファイルに分割して並列に処理できる形式である必要があります。これらの形式には、CSV、[JSON](https://www.json.org/json-en.html)、[JSON Lines](https://jsonlines.org/)、[TFRecord](https://www.tensorflow.org/tutorials/load_data/tfrecord)、[RecordIO](https://mesos.apache.org/documentation/latest/recordio/) が含まれます。 SageMaker AI はイメージ名の後に `serve` 引数を指定して、コンテナ内のデフォルトの `CMD` ステートメントを上書きします。`serve` 引数は、Dockerfile の `CMD` コマンドで指定した引数よりも優先されます。   + `exec` 命令の `ENTRYPOINT` フォームを使用することをお勧めします。 ``` ENTRYPOINT ["executable", "param1", "param2"] ``` 例えば、次のようになります。 ``` ENTRYPOINT ["python", "k_means_inference.py"] ```   + SageMaker AI は、コンテナに対して、[https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) および [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html) で指定された環境変数を設定します。さらに、以下の環境変数が設定されます。 + コンテナがバッチ変換で実行される場合、`SAGEMAKER_BATCH` は `true` に設定されます。 + `SAGEMAKER_MAX_PAYLOAD_IN_MB` は、HTTP 経由でコンテナに送信される最大サイズのペイロードに設定されます。 + `SAGEMAKER_BATCH_STRATEGY` は、呼び出しを行うごとにコンテナが単一レコードを送信する場合は `SINGLE_RECORD` に設定され、コンテナがペイロードに収まるだけのレコードを取得する場合は `MULTI_RECORD` に設定されます。 + `SAGEMAKER_MAX_CONCURRENT_TRANSFORMS` は、同時に開くことができる `/invocations` リクエストの最大数に設定されます。 **注記** 最後の 3 つの環境変数は、ユーザーが実行する API コールから取得されます。ユーザーがそれらの値を設定していない場合は、値が渡されません。その場合は、デフォルト値または (`/execution-parameters` へのレスポンスで) アルゴリズムによって要求された値のどちらかが使用されます。 + モデル推論に GPU デバイスを使用 (`CreateTransformJob` リクエストで GPU ベースの ML コンピューティングインスタンスを指定) する予定の場合は、コンテナが nvidia-docker 互換であることを確認してください。NVIDIA ドライバーをイメージにバンドルしないでください。nvidia-docker の詳細については、[NVIDIA/nvidia-docker](https://github.com/NVIDIA/nvidia-docker) を参照してください。   + train 引数と serve 引数で混乱が生じるため、SageMaker AI コンテナでは、`init` イニシャライザをエントリポイントとして使用することはできません。 ## SageMaker AI がモデルアーティファクトをロードする方法 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) リクエストでは、Amazon S3 でモデルアーティファクトを保存する場所を指定する `ModelDataUrl` パラメータがコンテナの定義に含まれます。SageMaker AI を使用して推論を実行すると、SageMaker AI はこの情報を使用して、モデルアーティファクトをどこからコピーするかを決定します。また、推論コードで使用するために、アーティファクトを Docker コンテナの `/opt/ml/model` ディレクトリにコピーします。 `ModelDataUrl` パラメータは tar.gz ファイルを指す必要があります。そうしない場合、SageMaker AI はファイルをダウンロードできません。モデルを SageMaker AI でトレーニングする場合、アーティファクトは Amazon S3 の単一の圧縮 tar ファイルとして保存されます。別のフレームワークでモデルをトレーニングする場合は、モデルのアーティファクトを圧縮 tar ファイルとして Amazon S3 に保存する必要があります。SageMaker AI はこの tar ファイルを解凍し、バッチ変換ジョブが開始される前にコンテナ内の `/opt/ml/model` ディレクトリにそれを保存します。 ## コンテナがリクエストを提供する方法 コンテナにはポート 8080 の呼び出しと ping リクエストに応答するウェブサーバーを実装する必要があります。バッチ変換の場合は、アルゴリズムを設定して、動的ランタイムを SageMaker AI に設定するように execution-parameters リクエストを実装するオプションがあります。SageMaker AI は次のエンドポイントを使用します。 + `ping` - コンテナの健全性を定期的にチェックするために使用します。SageMaker AI は、ping リクエスト成功の HTTP `200` ステータスコードと空の本文を待ってから呼び出しリクエストを送信します。呼び出しリクエストが送信される際に推論を生成するには、ping リクエストを使用して、モデルをメモリにロードする場合があります。 + (オプション) `execution-parameters` - ランタイム時に、アルゴリズムでジョブに最適な調整パラメータが渡されるようにします。コンテナで使用できるメモリと CPU に基づき、アルゴリズムによって、ジョブに適切な `MaxConcurrentTransforms`、`BatchStrategy`、および `MaxPayloadInMB` の値が選択されます。 呼び出しリクエストを呼び出す前に、SageMaker AI は、execution-parameters リクエストの呼び出しを試みます。バッチ変換ジョブを作成する場合は、`MaxConcurrentTransforms`、`BatchStrategy`、`MaxPayloadInMB` の各パラメータに値を提供できます。SageMaker AI は、次の優先順位を使用して、これらのパラメータの値を決定します。 1. `CreateTransformJob` リクエストを作成するときに指定するパラメータ値。 1. SageMaker AI で execution-parameters エンドポイントが呼び出されるとモデルコンテナから返される値。 1. デフォルトのパラメータ値 (以下のテーブルを参照)。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/your-algorithms-batch-code.html) `GET` execution-parameters リクエストのレスポンスは、`MaxConcurrentTransforms`、`BatchStrategy`、および `MaxPayloadInMB` パラメータのキーを持つ JSON オブジェクトです。有効なレスポンスの例を以下に示します。 ``` { “MaxConcurrentTransforms”: 8, “BatchStrategy": "MULTI_RECORD", "MaxPayloadInMB": 6 } ``` ## コンテナが推論リクエストに応答する方法 推論を得るために、Amazon SageMaker AI は推論コンテナに POST リクエストを送信します。POST リクエストボディには Amazon S3 からのデータが含まれています。Amazon SageMaker AI はリクエストをコンテナに渡し、コンテナから推論結果を返し、レスポンスのデータを Amazon S3 に保存します。 推論リクエストを受信するには、コンテナにポート 8080 でリッスンするウェブサーバーが必要であり、`/invocations` エンドポイントへの POST リクエストを受け入れる必要があります。推論リクエストのタイムアウトと最大リトライ回数は `[ModelClientConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelClientConfig.html)` によって設定できます。 ## コンテナがヘルスチェック (Ping) リクエストに応答する方法 コンテナの最も単純な要件は、HTTP 200 のステータスコードと空の本文で応答することです。これにより SageMaker AI に対し、コンテナが `/invocations` エンドポイントでの推論リクエストを受け入れる準備ができていることを示されます。 コンテナが静的な 200 を返す最小限のバーがありますが、コンテナ開発者はこの機能を使用してより深いチェックを実行できます。`/ping` 試行のリクエストのタイムアウトは 2 秒です。