SageMaker Python SDK 故障排除指南 - Amazon SageMaker
创建 Training Job更新 Training Job创建处理 Job创建端点更新终端节点异常处理指南

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

SageMaker Python SDK 故障排除指南

你可以使用 SageMaker Python 在 Python SDK 脚本或 Jupyter 笔记本 SageMaker 中与亚马逊互动。尽管SDK提供了简化的工作流程，但您可能会遇到各种异常或错误。本疑难解答指南旨在帮助您了解和解决使用 SageMaker Python 时可能出现的常见问题SDK。它涵盖了与创建训练作业、处理作业和端点相关的场景，以及一般的异常处理实践。通过遵循以下各节中提供的指导，您可以有效地诊断和解决常见问题。

P SageMaker ython SDK 充当低级 SageMaker API操作的封装器。您用于访问的IAM角色SDK必须能够访问底层操作。为你的IAM角色添加 SageMaker 完全访问策略是确保你有权使用 SageMaker Python 的最直接方法SDK。有关 SageMaker 完全访问策略的更多信息，请参阅 Amazon SageMaker 完全访问权限。

虽然不太方便，但提供更精细的权限是一种安全的使用方法。SDK以下各节都包含有关所需权限的信息。

创建 Training Job

重要

如果您没有向IAM角色添加 SageMaker 完全访问权限策略，则该策略必须具有调用CreateTrainingJob和DescribeTrainingJob操作的权限。

它还需要以下权限：

  • 访问 S3 中的输入/输出数据

  • 运行 Amazon EC2 实例

  • 日志 CloudWatch 指标

如果您的 SageMaker 训练作业需要访问 Amazon Virtual Private Cloud (AmazonVPC) 中的资源，请务必在创建处理任务时配置必要的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 页面的 “使用情况” 部分中找到有关输入通道的信息。

    使用以下步骤获取有关算法输入通道的信息。

    获取有关算法输入通道的信息

    1. 导航到SageMaker 控制台。

    2. 在左侧导航栏中，选择训练。

    3. 选择算法。

    4. 选择 “查找算法”。

    5. 在结果列表中找到您的算法。

    6. 选择 “使用情况” 选项卡。

    7. 导航至渠道规格标题。

botocore.exceptions.ClientError

botocore.exceptions.ClientError底层 AWS 服务抛出异常时会发生异常。这可能是由于各种原因造成的，例如参数不正确、权限问题或资源限制。使用以下列表了解botocore.exceptions.ClientError异常的背景信息以及如何修复异常的信息。

  • ResourceLimitExceeded— 您的 AWS 账户无权访问运行训练任务所需的亚马逊EC2实例。要获得访问权限，请申请增加配额。有关增加配额的信息，请参阅 S ervice Quotas。使用以下列表了解有关botocore.exceptions.ClientError异常的信息。

  • ValidationException— 当您在训练作业中使用错误的 Amazon EC2 实例类型时，会出现验证异常。当你使用的IAM角色没有训练作业的权限时，它们也可能出现。

更新 Training Job

重要

如果您未向IAM角色添加 SageMaker 托管策略，则必须向该角色授予以下权限：

  • 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（列表）-探查器规则配置列表。默认情况下，没有探查器规则配置。

  • profiler_config（dict）— SageMaker 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参数是一个列表。如果将参数作为字典传递，则会引发错误。

创建处理 Job

重要

如果您未向IAM角色添加 SageMaker 托管策略，则必须向该角色授予以下权限：

  • sagemaker:CreateProcessingJob— 提供创建处理任务的权限

  • sagemaker:DescribeProcessingJob— 提供获取有关处理任务信息的权限

  • s3:GetObject— 提供从 Amazon S3 存储桶读取模型工件的权限

  • s3:PutObject— 如果适用，则提供写入模型构件更新的权限

  • logs:PutLogEvents— 提供在更新过程中向 Amazon CloudWatch 日志写入日志的权限。

如果您的处理任务需要访问 Amazon Virtual Private Cloud subnets 中的资源，则必须在您创建的估算器中指定其security_group_ids和。有关如何访问 Amazon 内部资源的示例VPC，请参阅使用进行安全训练和推理。VPC

当你创建处理任务时，你可能会遇到 a ValueError、a 或 a botocore.exceptions.ClientError。UnexpectedStatusException

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.

当您尝试使用其他 AWS 账户IAM中的角色创建 SageMaker 处理任务时，就会发生"Cross-account pass role is not allowed in create processing job"错误。此安全功能可确保管理每个账户中的角色和权限。要解决该问题，请执行以下操作：

  1. 验证该IAM角色与处理任务在同一个账户中。跨账户角色需要明确的津贴

  2. 如果使用其他账户的角色，请更新其信任策略以允许创建处理任务的账户代入该角色。

  3. 确保该角色具有处理任务所需的权限，例如sagemaker:CreateProcessingJob或iam:PassRole。

创建端点

重要

如果您未向IAM角色添加 SageMaker 托管策略，则必须向该角色授予以下权限：

  • 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 控制台。

  2. 在左侧导航栏中，选择终端节点。

  3. 选择出现故障的端点。

  4. 在终端节点详细信息页面上，选择查看登录信息 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，请参阅异常处理指南。

更新终端节点

重要

如果您未向IAM角色添加 SageMaker 托管策略，则必须向该角色授予以下权限：

  • 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)

  2. 验证您为update_endpoint函数指定的端点是否在列表中。

  3. 请确保您在正确的 AWS 地区开展业务。 SageMaker 终端节点是特定于区域的。

  4. 确保您使用的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

错误主要分为两类：

  • 特定于 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 服务捕获异常。