トレーニングジョブを作成するトレーニングジョブを更新するデータ処理ジョブを作成するエンドポイントの作成エンドポイントを更新します。例外処理に関するガイダンス

SageMaker Python SDK トラブルシューティングガイド

SageMaker Python SDK を使用して、Python スクリプトまたは Jupyter Notebook 内で Amazon SageMaker AI とやり取りできます。SDK はワークフローを簡素化していますが、さまざまな例外やエラーが発生する可能性があります。このトラブルシューティングガイドは、SageMaker Python SDK を使用する際に発生する可能性のある一般的な問題を理解し、解決することを目的としています。ここでは、トレーニングジョブの作成、ジョブとエンドポイントの処理、一般的な例外処理に関するシナリオについて説明します。以下のセクションで説明するガイダンスに従うことで、一般的な問題を効果的に診断して、対処できます。

SageMaker Python SDK は、低レベルの SageMaker API オペレーションのラッパーとして機能します。SDK へのアクセスに使用する IAM ロールは、基盤となるオペレーションにアクセスできる必要があります。SageMaker AI フルアクセスポリシーを IAM ロールに追加するのは、SageMaker Python SDK を使用するアクセス許可があることを確認するための最も簡単な方法です。SageMaker AI フルアクセスポリシーの詳細については、Amazon SageMaker AI フルアクセス」を参照してください。

利便性は低いものの、よりきめ細かいアクセス許可を提供することが、SDK を使用するための安全なアプローチです。以下の各セクションには、必要なアクセス許可に関する情報が記載されています。

トレーニングジョブを作成する

重要

SageMaker AI フルアクセスポリシーを IAM ロールに追加しない場合は、CreateTrainingJob および DescribeTrainingJob オペレーションを呼び出すためのアクセス許可が必要です。

また、以下のアクセス許可も必要です。

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

このエラーは、無効な入力チャネルを指定すると発生します。入力チャネルは、モデルが期待するデータソースまたはパラメータです。

アルゴリズムのタイプページで、モデルに移動して、モデルの入力チャネルに関する情報を検索できます。

アルゴリズムの AWS Marketplace ページの Usage セクションで、入力チャネルに関する情報を確認することもできます。

アルゴリズムの入力チャネルに関する情報を取得するには、次の手順を使用します。
アルゴリズムの入力チャネルに関する情報を取得するには
1. SageMaker AI コンソールに移動します。
2. 左側のナビゲーションで、[トレーニング] を選択します。
3. [アルゴリズム] を選択します。
4. [アルゴリズムを探す] をクリックします。
5. 結果のリストでアルゴリズムを検索します。
6. [使用状況] タブをクリックします。
7. [チャネル仕様] のヘッダーに移動します。

botocore.exceptions.ClientError

botocore.exceptions.ClientError 例外は、基盤となる AWS サービスが例外をスローしたときに発生します。この場合、不適切なパラメータ、アクセス許可の問題、リソースの制約など、さまざまな原因が考えられます。botocore.exceptions.ClientError 例外のコンテキストと、例外の修正方法については、次のリストを参照してください。

ResourceLimitExceeded – AWS アカウントは、トレーニングジョブの実行に必要な Amazon EC2 インスタンスにアクセスできません。アクセスを取得するには、クォータの引き上げをリクエストします。クォータの引き上げの詳細については、「 Service Quotas」を参照してください。botocore.exceptions.ClientError 例外については、次のリストを参照してください。
ValidationException – 検証例外は、トレーニングジョブに適切でない Amazon EC2 インスタンスタイプを使用した場合に発生します。使用している IAM ロールにトレーニングジョブに対するアクセス許可がない場合にも表示されます。

トレーニングジョブを更新する

重要

SageMaker AI 管理ポリシーを IAM ロールに追加しない場合は、ロールに次のアクセス許可へのアクセスを許可する必要があります。

s3:GetObject — Amazon S3 バケットからモデルアーティファクトを読み取るアクセス許可を付与します
s3:PutObject – 該当する場合、モデルアーティファクトに更新を書き込むアクセス許可を付与します
iam:GetRole – トレーニングジョブの実行に必要な IAM ロールに関する情報を取得するアクセス許可を提供します。
sagemaker:UpdateTrainingJob – UpdateTrainingJob オペレーションを使用してトレーニングジョブを変更するアクセス許可を提供します。
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: <class 'dict'>, valid types: <class 'list'>, <class 'tuple'>

この例外は、update_training_job 関数が期待する形式でパラメータが指定されていない場合に発生する可能性があります。例えば、profiler_rule_configs パラメータがリストであることを想定しているとします。代わりにパラメータをディクショナリとして渡すと、エラーが発生します。

データ処理ジョブを作成する

重要

SageMaker AI 管理ポリシーを 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」を参照してください。

処理ジョブを作成する際に、ValueError、UnexpectedStatusException または botocore.exceptions.ClientError が発生する場合があります。

ValueError

次は、ValueError の例です。



ValueError: code preprocess.py wasn't found. Please make sure that the file exists.

指定したパスが正しくありません。スクリプトファイルへの相対パスまたは絶対パスのいずれかを指定できます。ファイルへのパスの指定の詳細については、「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 <module>
    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 ジョブを作成しようとすると発生します。このセキュリティ機能により、ロールとアクセス許可が各アカウント内で管理されます。この問題を解決するには、以下の手順を実行します。

IAM ロールが処理ジョブと同じアカウントにあることを検証します。クロスアカウントロールには明示的な許可が必要です
別のアカウントのロールを使用する場合は、そのロールの信頼ポリシーを更新して、処理ジョブを作成するアカウントがロールを引き受けられるようにします。
ロールに sagemaker:CreateProcessingJobや iam:PassRole などのジョブを処理するために必要なアクセス許可があることを確認します。

エンドポイントの作成

重要

SageMaker AI 管理ポリシーを 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 のログを確認するには

Amazon SageMaker AI コンソールに移動します。
左のナビゲーションペインで [エンドポイント] を選択します。
失敗したエンドポイントを選択します。
分析するには、[エンドポイントの詳細] タブで、[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 AI 管理ポリシーを IAM ロールに追加しない場合は、ロールに次のアクセス許可へのアクセスを許可する必要があります。

sagemaker:UpdateEndpoint – エンドポイントのインスタンスタイプや数の変更など、既存のエンドポイントを更新するアクセス許可を提供します。
sagemaker:UpdateEndpointWeightsAndCapacities – インスタンスタイプやカウントなど、エンドポイントの動作を定義するエンドポイント設定を作成するアクセス許可を提供します。
sagemaker:DescribeEndpoint – 更新前に必要となることが多いエンドポイントの現在の設定を記述するアクセス許可を提供します。

さらに、エンドポイントとエンドポイント設定を記述して一覧表示するためのアクセス許可が必要になる場合があります。

ValueError は、次のような状況で発生する可能性があります。



ValueError: Endpoint with name 'abc' does not exist; please use an existing endpoint name

エラーは、指定されたエンドポイント名が AWS アカウント内の既存のエンドポイントと一致していないことを示します。次の手順を使用して、問題のトラブルシューティングを行います。

値エラーをトラブルシューティングするには

次のコードを使用して、すべてのエンドポイントを一覧表示します。


import sagemaker
sagemaker_session = sagemaker.Session()
# List all endpoints
endpoints = sagemaker_session.sagemaker_client.list_endpoints()
print(endpoints)

update_endpoint 関数に指定したエンドポイントがリストにあることを確認します。
正しい AWS リージョンで動作していることを確認します。SageMaker AI エンドポイントはリージョン固有です。
使用している 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 のサービス」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

SageMaker AI ドキュメント履歴

SageMaker Python SDK トラブルシューティングガイド

トレーニングジョブを作成する

重要

アルゴリズムの入力チャネルに関する情報を取得するには

トレーニングジョブを更新する

重要

データ処理ジョブを作成する

重要

エンドポイントの作成

重要

CloudWatch のログを確認するには

エンドポイントを更新します。

重要

値エラーをトラブルシューティングするには

例外処理に関するガイダンス