翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# SageMaker Python SDK トラブルシューティングガイド
SageMaker Python SDK を使用して、Python スクリプトまたは Jupyter ノートブック内で Amazon SageMaker AI を操作できます。SDK はワークフローを簡素化していますが、さまざまな例外やエラーが発生する可能性があります。このトラブルシューティングガイドは、SageMaker Python SDK を使用する際に発生する可能性のある一般的な問題を理解し、解決することを目的としています。ここでは、トレーニングジョブの作成、ジョブとエンドポイントの処理、一般的な例外処理に関するシナリオについて説明します。以下のセクションで説明するガイダンスに従うことで、一般的な問題を効果的に診断して、対処できます。
SageMaker Python SDK は、低レベルの SageMaker API オペレーションのラッパーとして機能します。SDK へのアクセスに使用する IAM ロールは、基盤となるオペレーションにアクセスできる必要があります。SageMaker AI フルアクセスポリシーを IAM ロールに追加することが、SageMaker Python SDK を使用するアクセス許可があることを確認する最も簡単な方法です。SageMaker AI のフルアクセスポリシーの詳細については、「[Amazon SageMaker のフルアクセス](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonSageMakerFullAccess.html)」を参照してください。
利便性は低いものの、よりきめ細かいアクセス許可を提供することが、SDK を使用するための安全なアプローチです。以下の各セクションには、必要なアクセス許可に関する情報が記載されています。
## トレーニングジョブを作成する
**重要**
SageMaker AI フルアクセスポリシーを IAM ロールに追加しない場合は、[CreateTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) オペレーションと [DescribeTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingJob.html) オペレーションを呼び出すアクセス許可が必要です。
また、以下のアクセス許可も必要です。
S3 の入力/出力データにアクセスする
Amazon EC2 instances を実行する
Log CloudWatch メトリクス
SageMaker トレーニングジョブが Amazon Virtual Private Cloud (Amazon VPC) 内のリソースにアクセスする必要がある場合は、処理ジョブを作成する際に必要な VPC 設定とセキュリティグループを設定する必要があります。
トレーニングジョブを作成する際、`botocore.exceptions.ClientError` 例外または `ValueError` 例外が発生する場合があります。
------
#### [ ValueError ]
`ValueError` 例外は、関数に渡される値またはパラメータに問題がある場合に発生します。次のリストを使用して、`ValueError` 例外の例と修正方法を確認します。
+ `ValueError: either image_uri or algorithm_arn is required. None was provided`:
+ `AlgorithmEstimator` 関数を使用している場合は、`algorithm_arn` を指定します。
+ `Estimator` 関数を使用している場合は、`estimator_arn` を指定します。
+ `ValueError: Unknown input channel: train is not supported by: scikit-decision-trees-15423055-57b73412d2e93e9239e4e16f83298b8f`
このエラーは、無効な入力チャネルを指定すると発生します。入力チャネルは、モデルが期待するデータソースまたはパラメータです。
[アルゴリズムのタイプ](algorithms-choose.md) ページで、モデルに移動して、モデルの入力チャネルに関する情報を検索できます。
入力チャネルに関する情報は、アルゴリズムの AWS Marketplace ページの **Usage** セクションでも確認できます。
アルゴリズムの入力チャネルに関する情報を取得するには、次の手順を使用します。
**アルゴリズムの入力チャネルに関する情報を取得するには**
1. [SageMaker AI コンソール](https://console.aws.amazon.com/sagemaker)に移動します。
1. 左側のナビゲーションで、**[トレーニング]** を選択します。
1. **[アルゴリズム]** を選択します。
1. **[アルゴリズムを探す]** をクリックします。
1. 結果のリストでアルゴリズムを検索します。
1. **[使用状況]** タブをクリックします。
1. **[チャネル仕様]** のヘッダーに移動します。
------
#### [ botocore.exceptions.ClientError ]
`botocore.exceptions.ClientError` 例外は、基盤となる AWS サービスが例外をスローしたときに発生します。この場合、不適切なパラメータ、アクセス許可の問題、リソースの制約など、さまざまな原因が考えられます。`botocore.exceptions.ClientError` 例外のコンテキストと、例外の修正方法については、次のリストを参照してください。
+ `ResourceLimitExceeded` – AWS アカウントは、トレーニングジョブの実行に必要な Amazon EC2 インスタンスにアクセスできません。アクセスを取得するには、クォータの引き上げをリクエストします。クォータの引き上げの詳細については、「[ Service Quotas](https://docs.aws.amazon.com/general/latest/gr/sagemaker.html#limits_sagemaker)」を参照してください。`botocore.exceptions.ClientError` 例外については、次のリストを参照してください。
+ `ValidationException` – 検証例外は、トレーニングジョブに適切でない Amazon EC2 インスタンスタイプを使用した場合に発生します。使用している IAM ロールにトレーニングジョブに対するアクセス許可がない場合にも表示されます。
------
## トレーニングジョブを更新する
**重要**
SageMaker マネージドポリシーを IAM ロールに追加しない場合は、ロールに次のアクセス許可へのアクセス権を付与する必要があります。
`s3:GetObject` — Amazon S3 バケットからモデルアーティファクトを読み取るアクセス許可を付与します
`s3:PutObject` – 該当する場合、モデルアーティファクトに更新を書き込むアクセス許可を付与します
`iam:GetRole` – トレーニングジョブの実行に必要な IAM ロールに関する情報を取得するアクセス許可を提供します。
`sagemaker:UpdateTrainingJob` – [UpdateTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateTrainingJob.html) オペレーションを使用してトレーニングジョブを変更するアクセス許可を提供します。
`logs:PutLogEvents` – 更新プロセス中に Amazon CloudWatch ログにログを書き込むアクセス許可を提供します。
トレーニングジョブを更新すると、`botocore.exceptions.ParamValidationError` または `botocore.exceptions.ClientError` が発生する場合があります。
------
#### [ botocore.exceptions.ClientError ]
`ClientError` のメッセージは、次のとおりです。
```
botocore.exceptions.ClientError: An error occurred (ValidationException) when calling the UpdateTrainingJob operation: Invalid UpdateTrainingJobRequest, the request cannot be empty
```
このエラーが発生した場合は、トレーニングジョブの名前とともに、次のいずれかのパラメータを含める必要があります。
+ `profiler_rule_configs` (list) – Profiler ルール設定のリスト。デフォルトでは、Profiler ルール設定はありません。
+ `profiler_config` (dict) – SageMaker AI Profiler がメトリクスを収集して送信するための設定です。デフォルトでは、Profiler 設定はありません。
+ `resource_config` (dict) – トレーニングジョブリソースの設定。ウォームプールのステータスが `Available` の場合、キープアライブ期間を更新できます。その他のフィールドは更新できません。
+ `remote_debug_config` (dict) – `RemoteDebug` の設定。ディクショナリには `EnableRemoteDebug`(bool) を含めることができます。
------
#### [ botocore.exceptions.ParamValidationError ]
`botocore.exceptions.ParamValidationError` の形式は次のとおりです。
```
botocore.exceptions.ParamValidationError: Parameter validation failed:
Invalid type for parameter ProfilerRuleConfigurations, value: {'DisableProfiler': False}, type: , valid types: ,
```
この例外は、`update_training_job` 関数が期待する形式でパラメータが指定されていない場合に発生する可能性があります。例えば、`profiler_rule_configs` パラメータがリストであることを想定しているとします。代わりにパラメータをディクショナリとして渡すと、エラーが発生します。
------
## データ処理ジョブを作成する
**重要**
SageMaker マネージドポリシーを IAM ロールに追加しない場合は、ロールに次のアクセス許可へのアクセス権を付与する必要があります。
`sagemaker:CreateProcessingJob` – 処理ジョブを作成するアクセス許可を付与します。
`sagemaker:DescribeProcessingJob` – 処理ジョブに関する情報を取得するアクセス許可を提供します。
`s3:GetObject` — Amazon S3 バケットからモデルアーティファクトを読み取るアクセス許可を付与します
`s3:PutObject` – 該当する場合、モデルアーティファクトに更新を書き込むアクセス許可を付与します
`logs:PutLogEvents` – 更新プロセス中に Amazon CloudWatch ログにログを書き込むアクセス許可を提供します。
処理ジョブが Amazon Virtual Private Cloud 内のリソースにアクセスする必要がある場合は、作成する推定ツール内で `security_group_ids` と `subnets` を指定する必要があります。Amazon VPC 内のリソースにアクセスする方法の例については、「[Secure Training and Inference with VPC](https://sagemaker.readthedocs.io/en/stable/overview.html#secure-training-and-inference-with-vpc)」を参照してください。
処理ジョブを作成する際に、`ValueError`、`UnexpectedStatusException` または `botocore.exceptions.ClientError` が発生する場合があります。
------
#### [ ValueError ]
次は、`ValueError` の例です。
```
ValueError: code preprocess.py wasn't found. Please make sure that the file exists.
```
指定したパスが正しくありません。スクリプトファイルへの相対パスまたは絶対パスのいずれかを指定できます。ファイルへのパスの指定の詳細については、「[sagemaker.processing.RunArgs](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.processing.RunArgs)」を参照してください。
------
#### [ UnexpectedStatusException ]
以下は、`UnexpectedStatusException` の例です。
```
UnexpectedStatusException: Error for Processing job sagemaker-scikit-learn-2024-07-02-14-08-55-993: Failed. Reason: AlgorithmError: , exit code: 1
```
例外に伴うトレースバックは、根本原因の特定に役立ちます。
```
Traceback (most recent call last):
File "/opt/ml/processing/input/code/preprocessing.py", line 51, in
df = pd.read_csv(input_data_path)
.
.
.
File "pandas/_libs/parsers.pyx", line 689, in pandas._libs.parsers.TextReader._setup_parser_source
FileNotFoundError: [Errno 2] File b'/opt/ml/processing/input/census-income.csv' does not exist: b'/opt/ml/processing/input/census-income.csv'
```
エラー `"FileNotFoundError: [Errno 2] File b'/opt/ml/processing/input/census-income.csv' does not exist"` は、入力ファイル `census-income.csv` が指定されたパス `/opt/ml/processing/input/` に見つからないことを示します。入力データが適切に提供され、前処理スクリプトが想定されたパスにデータをコピーしていることを検証します。
------
#### [ botocore.exceptions.ClientError ]
次は、`botocore.exceptions.ClientError` の例です。
```
botocore.exceptions.ClientError: An error occurred (ValidationException) when calling the CreateProcessingJob operation: RoleArn: Cross-account pass role is not allowed.
```
`"Cross-account pass role is not allowed in create processing job"` エラーは、別の AWS アカウントの IAM ロールを使用して SageMaker Processing ジョブを作成しようとすると発生します。このセキュリティ機能により、ロールとアクセス許可が各アカウント内で管理されます。この問題を解決するには、以下の手順を実行します。
1. IAM ロールが処理ジョブと同じアカウントにあることを検証します。クロスアカウントロールには明示的な許可が必要です
1. 別のアカウントのロールを使用する場合は、そのロールの信頼ポリシーを更新して、処理ジョブを作成するアカウントがロールを引き受けられるようにします。
1. ロールに `sagemaker:CreateProcessingJob`や `iam:PassRole` などのジョブを処理するために必要なアクセス許可があることを確認します。
------
## エンドポイントの作成
**重要**
SageMaker マネージドポリシーを IAM ロールに追加しない場合は、ロールに次のアクセス許可へのアクセス権を付与する必要があります。
`sagemaker:CreateModel` – エンドポイントにデプロイするモデルを作成するアクセス許可を提供します。
`sagemaker:CreateEndpointConfig` – インスタンスタイプやカウントなど、エンドポイントの動作を定義するエンドポイント設定を作成するアクセス許可を提供します。
`sagemaker:CreateEndpoint` – 指定したエンドポイントを使用してエンドポイント設定を作成するアクセス許可を提供します。
さらに、モデル、エンドポイント、エンドポイント設定を記述して一覧表示するためのアクセス許可が必要です。
エンドポイントを作成する際に、`UnexpectedStatusException` または `botocore.exceptions.ClientError` に直面する場合があります。
以下は、`UnexpectedStatusException` の例です。
```
UnexpectedStatusException: Error hosting endpoint gpt2-large-2024-07-03-15-28-20-448: Failed. Reason: The primary container for production variant AllTraffic did not pass the ping health check. Please check CloudWatch logs for this endpoint.. Try changing the instance type or reference the troubleshooting page https://docs.aws.amazon.com/sagemaker/latest/dg/async-inference-troubleshooting.html
```
このエラーメッセージは、Amazon CloudWatch ログを確認するように指示しています。ログを確認するには、次の手順を使用します。
**CloudWatch のログを確認するには**
1. [Amazon SageMaker AI コンソール](https://console.aws.amazon.com/sagemaker)に移動します。
1. 左のナビゲーションペインで **[エンドポイント]** を選択します。
1. 失敗したエンドポイントを選択します。
1. 分析するには、**[エンドポイントの詳細]** タブで、**[CloudWatch ログを表示]** をクリックします。
ログが見つかったら、特定の問題を探します。以下は、CloudWatch ログに送信されるログイベントの例です。
```
NotImplementedError: gptq quantization is not supported for AutoModel, you can try to quantize it with text-generation-server quantize ORIGINAL_MODEL_ID NEW_MODEL_ID
```
`botocore.exceptions.ClientError` の問題の解決の詳細については、「[例外処理に関するガイダンス](#sagemaker-python-sdk-troubleshooting-exception-handling)」を参照してください。
## エンドポイントを更新します。
**重要**
SageMaker マネージドポリシーを IAM ロールに追加しない場合は、ロールに次のアクセス許可へのアクセス権を付与する必要があります。
`sagemaker:UpdateEndpoint` – エンドポイントのインスタンスタイプや数の変更など、既存のエンドポイントを更新するアクセス許可を提供します。
`sagemaker:UpdateEndpointWeightsAndCapacities` – インスタンスタイプやカウントなど、エンドポイントの動作を定義するエンドポイント設定を作成するアクセス許可を提供します。
`sagemaker:DescribeEndpoint` – 更新前に必要となることが多いエンドポイントの現在の設定を記述するアクセス許可を提供します。
さらに、エンドポイントとエンドポイント設定を記述して一覧表示するためのアクセス許可が必要になる場合があります。
`ValueError` は、次のような状況で発生する可能性があります。
```
ValueError: Endpoint with name 'abc' does not exist; please use an existing endpoint name
```
エラーは、指定されたエンドポイント名が AWS アカウント内の既存のエンドポイントと一致していないことを示します。次の手順を使用して、問題のトラブルシューティングを行います。
**値エラーをトラブルシューティングするには**
1. 次のコードを使用して、すべてのエンドポイントを一覧表示します。
```
import sagemaker
sagemaker_session = sagemaker.Session()
# List all endpoints
endpoints = sagemaker_session.sagemaker_client.list_endpoints()
print(endpoints)
```
1. `update_endpoint` 関数に指定したエンドポイントがリストにあることを確認します。
1. 正しい AWS リージョンで動作していることを確認します。SageMaker AI エンドポイントはリージョンによって異なります。
1. 使用している IAM ロールに、エンドポイントを一覧表示、説明、または更新するアクセス許可があることを確認してください。
## 例外処理に関するガイダンス
特定の問題を修正するのに役立つ情報が見つからない場合は、次のコード例を参考にして、例外の処理方法を確認してください。
以下は、ほとんどの例外をキャッチするために使用できる一般的な例です。
```
import sagemaker
from botocore.exceptions import ParamValidationError, ClientError
try:
sagemaker.some_api_call(SomeParam='some_param')
except ClientError as error:
# Put your error handling logic here
raise error
except ParamValidationError as error:
raise ValueError('The parameters you provided are incorrect: {}'.format(error))
except ValueError as error:
# Catch generic ValueError exceptions
```
エラーには次の主な 2 つのカテゴリがあります。
+ SageMaker Python SDK 固有のエラー
+ 基盤となる AWS サービスに固有のエラー
基盤となる AWS サービスに固有のエラーは常に`botocore.exceptions.ClientError`例外です。`botocore.exceptions.ClientError` には `Error` オブジェクトと `ResponseMetadata` オブジェクトがあります。クライアントエラーのテンプレートは、以下のとおりです。
```
{
'Error': {
'Code': 'SomeServiceException',
'Message': 'Details/context around the exception or error'
},
'ResponseMetadata': {
'RequestId': '1234567890ABCDEF',
'HostId': 'host ID data will appear here as a hash',
'HTTPStatusCode': 400,
'HTTPHeaders': {'header metadata key/values will appear here'},
'RetryAttempts': 0
}
}
```
以下は、`botocore.exceptions.ClientError` で実行できる特定のエラー処理の例です。
```
try:
sagemaker.some_api_call(SomeParam='some_param')
except botocore.exceptions.ClientError as err:
if err.response['Error']['Code'] == 'InternalError': # Generic error
# We grab the message, request ID, and HTTP code to give to customer support
print('Error Message: {}'.format(err.response['Error']['Message']))
print('Request ID: {}'.format(err.response['ResponseMetadata']['RequestId']))
print('Http code: {}'.format(err.response['ResponseMetadata']['HTTPStatusCode']))
raise err
else if err.response['Error']['Code'] == 'ValidationException':
raise ValueError(err.response['Error']['Message'])
```
`ClientError` 例外の処理方法の詳細については、[「エラーレスポンスの解析と例外のキャッチ AWS のサービス](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/error-handling.html#parsing-error-responses-and-catching-exceptions-from-aws-services)」を参照してください。