SageMaker Guia de solução de problemas do SDK para Python

Você pode usar o SageMaker Python SDK para interagir com a Amazon SageMaker AI em seus scripts Python ou notebooks Jupyter. Apesar do SDK fornecer um fluxo de trabalho simplificado, você pode encontrar várias exceções ou erros. Este guia de solução de problemas tem como objetivo ajudar você a entender e resolver problemas comuns que podem surgir ao trabalhar com o SDK do SageMaker Python. Ele abrange cenários relacionados à criação de trabalhos de treinamento, trabalhos de processamento e endpoints, bem como práticas gerais de tratamento de exceções. Ao seguir as orientações fornecidas nas seções a seguir, você pode diagnosticar e resolver problemas comuns com eficácia.

O SDK do SageMaker Python atua como um invólucro para as operações de API de baixo nível. SageMaker O perfil do IAM que você está usando para acessar o SDK deve ser capaz de acessar as operações subjacentes. Adicionar a política de acesso total da SageMaker IA à sua função do IAM é a maneira mais simples de garantir que você tenha permissões para usar o SDK do Python SageMaker . Para obter mais informações sobre a política de acesso total à SageMaker IA, consulte Amazon SageMaker AI Full Access.

Embora menos conveniente, fornecer permissões menores é uma abordagem segura para usar o SDK. Cada uma das seções a seguir contém informações sobre as permissões necessárias.

Criar um trabalho de treinamento

Importante

Se você não estiver adicionando a política SageMaker AI Full Access à sua função do IAM, ela deve ter permissões para chamar as DescribeTrainingJoboperações CreateTrainingJobe.

Também requer permissões para:

• Acessar dados de entrada/saída no S3

• Execute EC2 instâncias da Amazon

• Registrar CloudWatch métricas

Se seu trabalho de SageMaker treinamento precisar acessar recursos em uma Amazon Virtual Private Cloud (Amazon VPC), certifique-se de definir as configurações de VPC e os grupos de segurança necessários ao criar o trabalho de processamento.

Ao criar um trabalho de treinamento, você pode se deparar com as exceções botocore.exceptions.ClientError ou ValueError.

ValueError

Exceções de ValueError ocorrem quando há um problema com os valores ou parâmetros que você está passando para uma função. Use a lista a seguir para ver exemplos de exceções de ValueError e como corrigi-las.

• ValueError: either image_uri or algorithm_arn is required. None was provided:

  • Se você estiver usando a função AlgorithmEstimator, forneça o algorithm_arn.

  • Se você estiver usando a função Estimator, forneça o estimator_arn.

• ValueError: Unknown input channel: train is not supported by: scikit-decision-trees-15423055-57b73412d2e93e9239e4e16f83298b8f

  Você recebe esse erro ao fornecer um canal de entrada inválido. Um canal de entrada é uma fonte de dados ou um parâmetro que o modelo espera.

  Na página Tipos de Algoritmos, você pode navegar até o modelo para encontrar informações sobre os canais de entrada dele.

  Você também pode encontrar informações sobre os canais de entrada na seção Uso na AWS Marketplace página do algoritmo.

  Use o procedimento a seguir para obter informações sobre os canais de entrada de um algoritmo.

  Para obter informações sobre os canais de entrada de um algoritmo

  1. Navegue até o console de SageMaker IA.

  2. No painel de navegação à esquerda, escolha Treinamento.

  3. Selecione Algoritmos.

  4. Escolha Encontrar algoritmo.

  5. Encontre seu algoritmo na lista de resultados.

  6. Selecione a guia Uso.

  7. Navegue até o cabeçalho de Especificação do canal.

botocore.exceptions.ClientError

botocore.exceptions.ClientErrorexceções ocorrem quando um AWS serviço subjacente lança uma exceção. Isso pode ser devido a vários motivos, como parâmetros incorretos, problemas de permissões ou restrições de recursos. Use a lista a seguir para obter contexto sobre exceções botocore.exceptions.ClientError e obter informações sobre como corrigi-las.

• ResourceLimitExceeded— Sua AWS conta não tem acesso às EC2 instâncias da Amazon necessárias para executar o trabalho de treinamento. Para obter acesso, solicite um aumento de cota. Para obter informações sobre aumentos de cotas, consulte Service Quotas. Use a lista a seguir para obter informações sobre exceções botocore.exceptions.ClientError.

• ValidationException— As exceções de validação surgem quando você usa o tipo errado de EC2 instância da Amazon para o trabalho de treinamento. Elas também podem surgir quando o perfil do IAM que você está usando não tem permissões para o trabalho de treinamento.

Atualizar um trabalho de treinamento

Importante

Se você não estiver adicionando a política gerenciada de SageMaker IA à sua função do IAM, você deve conceder à função acesso às seguintes permissões:

• s3:GetObject: fornece permissões para ler os artefatos de modelo a partir de buckets do Amazon S3

• s3:PutObject: se aplicável, fornece permissões para gravar atualizações nos artefatos do modelo

• iam:GetRole: fornece permissões para obter informações sobre o perfil do IAM necessário para executar o trabalho de treinamento

• sagemaker:UpdateTrainingJob— Fornece permissões para modificar os trabalhos de treinamento usando a UpdateTrainingJoboperação.

• logs:PutLogEvents— Fornece permissões para gravar registros nos CloudWatch registros da Amazon durante o processo de atualização.

Ao atualizar um trabalho de treinamento, você pode se deparar com um botocore.exceptions.ParamValidationError ou um botocore.exceptions.ClientError.

botocore.exceptions.ClientError

O ClientError tem a seguinte mensagem:

botocore.exceptions.ClientError: An error occurred (ValidationException) when calling the UpdateTrainingJob operation: Invalid UpdateTrainingJobRequest, the request cannot be empty            
        

Se você estiver enfrentando esse erro, deverá incluir um dos seguintes parâmetros junto com o nome do trabalho de treinamento:

• profiler_rule_configs (lista): uma lista de configurações de regras do profiler. Por padrão, não há configurações de regras de profiler.

• profiler_config(dict) — A configuração do SageMaker AI Profiler coleta métricas e as envia. Por padrão, não há configuração de profiler.

• resource_config (dicionário): a configuração dos recursos do trabalho de treinamento. Você pode atualizar o período de manutenção de atividade se o status do grupo de alta atividade for Available. Nenhum outro campo pode ser atualizado.

• remote_debug_config (dicionário): configuração para RemoteDebug. O dicionário pode conter EnableRemoteDebug (bool).

botocore.exceptions.ParamValidationError

O botocore.exceptions.ParamValidationError tem o seguinte erro:

botocore.exceptions.ParamValidationError: Parameter validation failed:
Invalid type for parameter ProfilerRuleConfigurations, value: {'DisableProfiler': False}, type: <class 'dict'>, valid types: <class 'list'>, <class 'tuple'>
        

Essa exceção pode ocorrer se o parâmetro não for fornecido no formato esperado pela função update_training_job. Por exemplo, ela espera que o parâmetro profiler_rule_configs seja uma lista. Se, em vez disso, o parâmetro for passado como um dicionário, acontecerá o erro.

Criar um trabalho de processamento

Importante

Se você não estiver adicionando a política gerenciada de SageMaker IA à sua função do IAM, você deve conceder à função acesso às seguintes permissões:

• sagemaker:CreateProcessingJob: fornece permissões para criar um trabalho de processamento

• sagemaker:DescribeProcessingJob: fornece permissões para obter informações sobre um trabalho de processamento

• s3:GetObject: fornece permissões para ler os artefatos de modelo a partir de buckets do Amazon S3

• s3:PutObject: se aplicável, fornece permissões para gravar atualizações nos artefatos do modelo

• logs:PutLogEvents— Fornece permissões para gravar registros nos CloudWatch registros da Amazon durante o processo de atualização.

Se seu trabalho de processamento precisar acessar recursos dentro de uma nuvem privada virtual da Amazon, você deverá especificar security_group_ids e subnets no estimador que você criar. Para ver um exemplo de como você pode acessar recursos em uma VPC da Amazon, consulte Treinamento e inferência seguros com a VPC.

Ao criar um trabalho de processamento, você pode se deparar com um ValueError, um UnexpectedStatusException ou um botocore.exceptions.ClientError.

ValueError

Veja a seguir um exemplo de um ValueError.

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

O caminho que você especificou não estava correto. Você pode especificar um caminho relativo ou absoluto para seu arquivo de script. Para obter mais informações sobre como especificar caminhos para seus arquivos, consulte sagemaker.processing. RunArgs.

UnexpectedStatusException

Veja a seguir um exemplo de um UnexpectedStatusException.

UnexpectedStatusException: Error for Processing job sagemaker-scikit-learn-2024-07-02-14-08-55-993: Failed. Reason: AlgorithmError: , exit code: 1           
        

O rastreamento que acompanha a exceção pode ajudá-lo a identificar a causa-raiz:

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'            
        

O erro "FileNotFoundError: [Errno 2] File b'/opt/ml/processing/input/census-income.csv' does not exist" indica que o arquivo census-income.csv de entrada não foi encontrado no caminho /opt/ml/processing/input/ especificado. Verifique se os dados de entrada foram fornecidos corretamente e se o script de pré-processamento está copiando os dados para o caminho esperado.

botocore.exceptions.ClientError

Veja a seguir um exemplo de um botocore.exceptions.ClientError.

botocore.exceptions.ClientError: An error occurred (ValidationException) when calling the CreateProcessingJob operation: RoleArn: Cross-account pass role is not allowed.
        

O "Cross-account pass role is not allowed in create processing job" erro ocorre quando você tenta criar um trabalho SageMaker de processamento usando uma função do IAM de uma AWS conta diferente. Esse atributo de segurança garante que funções e permissões sejam gerenciadas em cada conta. Para resolver o problema, faça o seguinte:

1. Verifique se o perfil do IAM está na mesma conta que o trabalho de processamento. As funções entre contas exigem permissão explícita

2. Se estiver usando uma função de outra conta, atualize sua política de confiança para permitir que a conta que está criando o trabalho de processamento assuma a função.

3. Certifique-se de que a função tenha as permissões necessárias para processar trabalhos, como sagemaker:CreateProcessingJob ou iam:PassRole.

Criar um endpoint

Importante

Se você não estiver adicionando a política gerenciada de SageMaker IA à sua função do IAM, você deve conceder à função acesso às seguintes permissões:

• sagemaker:CreateModel: fornece permissões para criar o modelo que você está implantando no endpoint

• sagemaker:CreateEndpointConfig: fornece permissões para criar uma configuração de endpoint que define o comportamento do endpoint, como o tipo e a contagem de instâncias

• sagemaker:CreateEndpoint: fornece permissões para criar a configuração do endpoint usando o endpoint que você especificou

Além disso, você precisa de permissões para descrever e listar os modelos, endpoints e configurações de endpoints.

Ao criar um endpoint, você pode se deparar com um UnexpectedStatusException ou um botocore.exceptions.ClientError.

Veja a seguir um exemplo de um 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            
        

A mensagem de erro solicita que você verifique os CloudWatch registros da Amazon. Use o procedimento a seguir para verificar os logs.

Para verificar os CloudWatch registros

1. Navegue até o console do Amazon SageMaker AI.

2. No painel de navegação à esquerda, selecione Endpoints.

3. Selecione o endpoint que falhou.

4. Na página de detalhes do Endpoint, escolha Exibir logins. CloudWatch

Depois de encontrar os logs, procure o problema específico. Veja a seguir um exemplo de um CloudWatch registro:

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            
        

Para obter informações sobre como resolver o botocore.exceptions.ClientError, consulte Orientações para lidar com exceções.

Atualizar um endpoint

Importante

Se você não estiver adicionando a política gerenciada de SageMaker IA à sua função do IAM, você deve conceder à função acesso às seguintes permissões:

• sagemaker:UpdateEndpoint: fornece permissões para atualizar um endpoint existente, como alterar o tipo ou a contagem de instâncias do endpoint

• sagemaker:UpdateEndpointWeightsAndCapacities: fornece permissões para criar uma configuração de endpoint que define o comportamento do endpoint, como o tipo e a contagem de instâncias

• sagemaker:DescribeEndpoint: fornece permissões para descrever a configuração atual do endpoint, que geralmente é necessária antes da atualização

Além disso, talvez você precise de permissões para descrever e listar os endpoints e as configurações dos endpoints.

Você pode se deparar com um ValueError, como o seguinte:

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

O erro indica que o nome do endpoint especificado não corresponde a nenhum endpoint existente na sua AWS conta. Use o seguinte procedimento para solucionar o erro:

Para solucionar um erro de valor

1. Use o código a seguir para listar todos os endpoints:

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

2. Verifique se o endpoint que você especificou para a função update_endpoint está na lista.

3. Verifique se você está operando na AWS região correta. SageMaker Os endpoints de IA são específicos da região.

4. Verifique se o perfil do IAM que você está usando tem permissões para listar, descrever ou atualizar os endpoints.

Orientações para lidar com exceções

Se você não conseguir encontrar informações para ajudá-lo a corrigir seu problema específico, os exemplos de código a seguir podem lhe dar inspiração sobre como lidar com exceções.

A seguir, há um exemplo genérico que você pode usar para resolver a maioria das exceções.

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  
        

Existem quatro categorias principais de erros:

• Erros específicos do SDK do SageMaker Python

• Erros específicos do AWS serviço subjacente

Erros específicos do AWS serviço subjacente são sempre botocore.exceptions.ClientError exceções. O botocore.exceptions.ClientError tem um objeto Error e um objeto ResponseMetadata. O seguinte exemplo mostra o modelo de um erro do cliente:

{
    '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
    }
}
            
        

A seguir, há um exemplo do tratamento específico que você pode repetir com o 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'])
            
        

Para obter mais informações sobre como lidar com ClientError exceções, consulte Análise de respostas de erro e captura de exceções de. Serviços da AWS