Partilhar via

Solucionar problemas de pontos de extremidade em lote

  • Artigo

APLICA-SE A:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

Este artigo fornece orientação para solucionar erros comuns ao usar pontos de extremidade em lote para pontuação em lote no Aprendizado de Máquina do Azure. As seções a seguir descrevem como analisar logs de pontuação em lote para identificar possíveis problemas e cenários sem suporte. Você também pode revisar as soluções recomendadas para resolver erros comuns.

Obter logs para trabalhos de pontuação em lote

Depois de invocar um ponto de extremidade em lote usando a CLI do Azure ou a API REST, o trabalho de pontuação em lote é executado de forma assíncrona. Há duas opções para obter os logs para um trabalho de pontuação em lote:

  • Opção 1: Transmitir logs de tarefas para um console local. Somente os logs na pasta azureml-logs são transmitidos.

    Execute o seguinte comando para transmitir os logs gerados pelo sistema para o console. Substitua o <job_name> parâmetro pelo nome do seu trabalho de pontuação em lote:

    az ml job stream --name <job_name>

  • Opção 2: Exibir logs de trabalho no estúdio do Azure Machine Learning.

    Execute o seguinte comando para obter o link de trabalho para usar no estúdio. Substitua o <job_name> parâmetro pelo nome do seu trabalho de pontuação em lote:

    az ml job show --name <job_name> --query services.Studio.endpoint -o tsv

    1. Abra o link de trabalho no estúdio.

    2. No gráfico do trabalho, selecione a etapa de pontuação em lote.

    3. Na guia Saídas + logs, selecione um ou mais logs para revisar.

Rever ficheiros de registo

O Azure Machine Learning fornece vários tipos de arquivos de log e outros arquivos de dados que você pode usar para ajudar a solucionar problemas de seu trabalho de pontuação em lote.

As duas pastas de nível superior para logs de pontuação em lote são azureml-logs e logs. As informações do controlador que inicia o script de pontuação são armazenadas no arquivo ~/azureml-logs/70_driver_log.txt .

Examinar informações de alto nível

A natureza distribuída dos trabalhos de pontuação em lote resulta em logs de fontes diferentes, mas dois arquivos combinados fornecem informações de alto nível:

Ficheiro Description
~/logs/job_progress_overview.txt Fornece informações de alto nível sobre o número atual de minilotes (também conhecidos como tarefas) criados e o número atual de minilotes processados. À medida que o processamento de minilotes chega ao fim, o log registra os resultados do trabalho. Se o trabalho falhar, o log mostrará a mensagem de erro e onde iniciar a solução de problemas.
~/logs/sys/master_role.txt Fornece a visualização do nó principal (também conhecido como orquestrador) do trabalho em execução. Esse log inclui informações sobre a criação da tarefa, o monitoramento do progresso e o resultado do trabalho.

Examinar dados de rastreamento de pilha em busca de erros

Outros arquivos fornecem informações sobre possíveis erros em seu script:

Ficheiro Description
~/logs/usuário/error.txt Fornece um resumo dos erros em seu script.
~/logs/usuário/erro/* Fornece os rastreamentos de pilha completa de exceções lançadas durante o carregamento e a execução do script de entrada.

Examinar logs de processo por nó

Para obter uma compreensão completa de como cada nó executa seu script de pontuação, examine os logs de processo individuais para cada nó. Os logs de processo são armazenados na pasta ~/logs/sys/node e agrupados por nós de trabalho.

A pasta contém uma <subpasta ip_address>/ que contém um <arquivo process_name>.txt com informações detalhadas sobre cada minilote. O conteúdo da pasta é atualizado quando um trabalhador seleciona ou conclui o minilote. Para cada minilote, o arquivo de log inclui:

  • O endereço IP e a ID do processo (PID) do processo de trabalho.
  • O número total de itens, o número de itens processados com êxito e o número de itens com falha.
  • A hora de início, duração, tempo do processo e tempo do método de execução.

Examinar verificações periódicas por nó

Você também pode exibir os resultados de verificações periódicas do uso de recursos para cada nó. Os arquivos de log e de instalação são armazenados na pasta ~/logs/perf .

Use o --resource_monitor_interval parâmetro para alterar o intervalo de verificação em segundos:

  • Usar padrão: o intervalo padrão é de 600 segundos (aproximadamente 10 minutos).
  • Parar verificações: defina o valor como 0 para parar de executar verificações no nó.

A pasta contém uma <subpasta ip_address>/ sobre cada minilote. O conteúdo da pasta é atualizado quando um trabalhador seleciona ou conclui o minilote. Para cada minilote, a pasta inclui os seguintes itens:

Ficheiro ou Pasta Description
OS/ Armazena informações sobre todos os processos em execução no nó. Uma verificação executa um comando do sistema operacional e salva o resultado em um arquivo. No Linux, o comando é ps. A pasta contém os seguintes itens:
- %Y%m%d%H: Subpasta que contém um ou mais arquivos de verificação de processo. O nome da subpasta é a data e hora de criação da verificação (Ano, Mês, Dia, Hora).
processes_%M: Arquivo dentro da subpasta. O arquivo mostra detalhes sobre a verificação do processo. O nome do arquivo termina com o tempo de verificação (Minuto) relativo ao tempo de criação do cheque.
node_disk_usage.csv Mostra o uso detalhado do disco do nó.
node_resource_usage.csv Fornece a visão geral do uso de recursos do nó.
processes_resource_usage.csv Fornece uma visão geral do uso de recursos de cada processo.

Adicionar registo ao script de pontuação

Você pode usar o log Python em seu script de pontuação. Esses logs são armazenados no arquivo logs/user/stdout/<node_id>/process<number>.stdout.txt arquivo.

O código a seguir demonstra como adicionar log em seu script:

import argparse
import logging

# Get logging_level
arg_parser = argparse.ArgumentParser(description="Argument parser.")
arg_parser.add_argument("--logging_level", type=str, help="logging level")
args, unknown_args = arg_parser.parse_known_args()
print(args.logging_level)

# Initialize Python logger
logger = logging.getLogger(__name__)
logger.setLevel(args.logging_level.upper())
logger.info("Info log statement")
logger.debug("Debug log statement")

Resolver erros comuns

As seções a seguir descrevem erros comuns que podem ocorrer durante o desenvolvimento e consumo de pontos finais em lote e etapas para resolução.

Nenhum módulo chamado azureml

A implantação em lote do Azure Machine Learning requer o pacote azureml-core na instalação.

Mensagem registrada: "Nenhum módulo nomeado azureml."

Motivo: O azureml-core pacote parece estar faltando na instalação.

Solução: Adicione o azureml-core pacote ao seu arquivo de dependências conda.

Nenhuma saída no arquivo de previsões

A implantação em lote espera que uma pasta vazia armazene o arquivo predictions.csv . Quando a implantação encontra um arquivo existente na pasta especificada, o processo não substitui o conteúdo do arquivo pela nova saída nem cria um novo arquivo com os resultados.

Mensagem registrada: Nenhuma mensagem registrada específica.

Motivo: a implantação em lote não pode substituir um arquivo de predictions.csv existente.

Solução: Se o processo especificar um local de pasta de saída para as previsões, verifique se a pasta não contém um arquivo predictions.csv existente.

Tempo limite do processo em lote

A implantação em lote usa um timeout valor para determinar quanto tempo a implantação deve aguardar para que cada processo em lote seja concluído. Quando a execução de um lote excede o tempo limite especificado, a implantação em lote aborta o processo.

Os processos anulados são repetidos até o número máximo de tentativas especificado no max_retries valor. Se o erro de tempo limite ocorrer em cada nova tentativa, o trabalho de implantação falhará.

Você pode configurar as timeout propriedades e max_retries para cada implantação com o retry_settings parâmetro.

Mensagem registrada: "Nenhuma atualização de progresso em [número] segundos. Nenhuma atualização de progresso nesta verificação. Aguarde [número] de segundos desde a última atualização."

Motivo: a execução em lote excede o tempo limite especificado e o número máximo de tentativas de repetição. Esta ação corresponde à falha da função no script de run() entrada.

Solução: aumente o valor da timeout sua implantação. Por padrão, o timeout valor é 30 e o max_retries valor é 3. Para determinar um valor adequado timeout para sua implantação, considere o número de arquivos a serem processados em cada lote e os tamanhos dos arquivos. Você pode diminuir o número de arquivos para processar e gerar minilotes de tamanho menor. Esta abordagem resulta numa execução mais rápida.

Exceção em ScriptExecution.StreamAccess.Authentication

Para que a implantação em lote seja bem-sucedida, a identidade gerenciada para o cluster de computação deve ter permissão para montar o armazenamento de ativos de dados. Quando a identidade gerenciada tem permissões insuficientes, o script causa uma exceção. Essa falha também pode fazer com que o armazenamento de ativos de dados não seja montado.

Mensagem registrada: "ScriptExecutionException foi causada por StreamAccessException. StreamAccessException foi causada por AuthenticationException."

Motivo: o cluster de computação onde a implantação está sendo executada não pode montar o armazenamento onde o ativo de dados está localizado. A identidade gerenciada da computação não tem permissões para executar a montagem.

Solução: certifique-se de que a identidade gerenciada associada ao cluster de computação em que sua implantação está sendo executada tenha pelo menos acesso do Storage Blob Data Reader à conta de armazenamento. Apenas os proprietários de contas de Armazenamento do Azure podem alterar o nível de acesso no portal do Azure.

Falha na inicialização do conjunto de dados, não é possível montar o conjunto de dados

O processo de implantação em lote requer armazenamento montado para o ativo de dados. Quando o armazenamento não é montado, o conjunto de dados não pode ser inicializado.

Mensagem registrada: "Falha na inicialização do conjunto de dados: UserErrorException: Mensagem: Não é possível montar o Dataset(ID='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', name='None', version=None). A fonte do conjunto de dados não está acessível ou não contém dados."

Motivo: o cluster de computação onde a implantação está sendo executada não pode montar o armazenamento onde o ativo de dados está localizado. A identidade gerenciada da computação não tem permissões para executar a montagem.

Solução: certifique-se de que a identidade gerenciada associada ao cluster de computação em que sua implantação está sendo executada tenha pelo menos acesso do Storage Blob Data Reader à conta de armazenamento. Apenas os proprietários de contas de Armazenamento do Azure podem alterar o nível de acesso no portal do Azure.

dataset_param não tem valor especificado ou valor padrão

Durante a implantação em lote, o nó do conjunto de dados faz referência ao dataset_param parâmetro. Para que a implantação prossiga, o parâmetro deve ter um valor atribuído ou um valor padrão especificado.

Mensagem registrada: "Data set node [code] references parameter dataset_param, que não tem um valor especificado ou um valor padrão."

Motivo: o ativo de dados de entrada fornecido ao ponto de extremidade em lote não é suportado.

Solução: verifique se o script de implantação fornece uma entrada de dados com suporte para pontos de extremidade em lote.

O programa do usuário falha, a execução falha

Durante a execução do script para implantação em lote, se a init() função ou encontrar um erro, o programa ou run() a execução do usuário poderá falhar. Você pode revisar os detalhes do erro em um arquivo de log gerado.

Mensagem registrada: "O programa do usuário falhou com exceção: falha na execução. Por favor, verifique os logs para obter detalhes. Você pode verificar logs/readme.txt para o layout dos logs."

Motivo: A init() função ou run() produz um erro durante a execução do script de pontuação.

Solução: Siga estas etapas para localizar detalhes sobre as falhas de função:

  1. No estúdio do Azure Machine Learning, vá para o trabalho de implantação em lote com falha executado e selecione a guia Saídas + logs .

  2. Abra o arquivo registra>erro<>do usuário>node_identifier>>número> do processo<.txt.

  3. Localize a mensagem de erro gerada pela init() função ou run() .

ValueError: Nenhum objeto para concatenar

Para que a implantação em lote seja bem-sucedida, cada arquivo em um minilote deve ser válido e implementar um tipo de arquivo suportado. Lembre-se de que os modelos MLflow suportam apenas um subconjunto de tipos de arquivo. Para obter mais informações, consulte Considerações ao implantar na inferência em lote.

Mensagem registrada: "ValueError: Nenhum objeto para concatenar."

Motivo: Todos os arquivos no minilote gerado são tipos de arquivos corrompidos ou não suportados.

Solução: Siga estas etapas para localizar detalhes sobre os arquivos com falha:

  1. No estúdio do Azure Machine Learning, vá para o trabalho de implantação em lote com falha executado e selecione a guia Saídas + logs .

  2. Abra o arquivo logs>usuário>stdout<>node_identifier>>número> do processo<.txt.

  3. Procure entradas que descrevam a falha de entrada do arquivo, como "ERROR:azureml:Error processing input file".

Se o tipo de ficheiro não for suportado, reveja a lista de ficheiros suportados. Talvez seja necessário alterar o tipo de arquivo dos dados de entrada ou personalizar a implantação fornecendo um script de pontuação. Para obter mais informações, veja Utilizar modelos do MLflow com um script de classificação.

Nenhum minilote bem-sucedido

O processo de implantação em lote requer pontos de extremidade em lote para fornecer dados no formato esperado pela run() função. Se os arquivos de entrada forem arquivos corrompidos ou incompatíveis com a assinatura do modelo, a run() função não retornará um minilote bem-sucedido.

Mensagem registrada: "Nenhum item de mini lote bem-sucedido retornado de run(). Por favor, marque 'response: run()' em https://aka.ms/batch-inference-documentation."

Motivo: O ponto de extremidade em lote não conseguiu fornecer dados no formato esperado para a run() função. Esse problema pode resultar de arquivos corrompidos sendo lidos ou incompatibilidade dos dados de entrada com a assinatura do modelo (MLflow).

Solução: Siga estas etapas para localizar detalhes sobre o minilote com falha:

  1. No estúdio do Azure Machine Learning, vá para o trabalho de implantação em lote com falha executado e selecione a guia Saídas + logs .

  2. Abra o arquivo logs>usuário>stdout<>node_identifier>>número> do processo<.txt.

  3. Procure entradas que descrevam a falha do arquivo de entrada para o minilote, como "Erro ao processar o arquivo de entrada". Os detalhes devem descrever por que o arquivo de entrada não pode ser lido corretamente.

Público ou serviço não permitido

Os tokens Microsoft Entra são emitidos para ações específicas que identificam os usuários permitidos (público), serviço e recursos. O token de autenticação para a API REST do ponto de extremidade em lote deve definir o resource parâmetro como https://ml.azure.com.

Mensagem registrada: Nenhuma mensagem registrada específica.

Motivo: você tenta invocar a API REST para o ponto de extremidade e a implantação em lote com um token emitido para um público ou serviço diferente.

Solução: Siga estes passos para resolver este problema de autenticação:

  1. Ao gerar um token de autenticação para a API REST do ponto de extremidade em lote, defina o resource parâmetro como https://ml.azure.com.

    Observe que esse recurso é diferente do recurso que você usa para gerenciar o ponto de extremidade a partir da API REST. Todos os recursos do Azure (incluindo pontos de extremidade em lote) usam o recurso https://management.azure.com para gerenciamento.

  2. Ao invocar a API REST para um ponto de extremidade e implantação em lote, tenha cuidado para usar o token emitido para a API REST do ponto de extremidade em lote e não um token emitido para um público ou serviço diferente. Em cada caso, confirme se você está usando o URI de recurso correto.

Se você quiser usar a API de gerenciamento e a API de invocação de trabalho ao mesmo tempo, precisará de dois tokens. Para obter mais informações, consulte Autenticação em pontos de extremidade em lote (REST).

Nenhuma implantação válida para rotear

Para que a implantação em lote seja bem-sucedida, o ponto de extremidade em lote deve ter pelo menos uma rota de implantação válida. O método padrão é definir a implantação em lote padrão usando o defaults.deployment_name parâmetro.

Mensagem registrada: "Nenhuma implantação válida para rota. Verifique se o ponto de extremidade tem pelo menos uma implantação com valores de peso positivos ou use um cabeçalho específico de implantação para rotear."

Motivo: a implantação em lote padrão não está definida corretamente.

Solução: Use um dos seguintes métodos para resolver o problema de roteamento:

  • Confirme se o defaults.deployment_name parâmetro define a implantação em lote padrão correta. Para obter mais informações, consulte Atualizar a implantação em lote padrão.

  • Defina a rota com um cabeçalho específico da implantação.

Limitações e cenários sem suporte

Ao projetar soluções de implantação de aprendizado de máquina que dependem de pontos de extremidade em lote, lembre-se de que algumas configurações e cenários não são suportados. As seções a seguir identificam espaços de trabalho e recursos de computação sem suporte e tipos inválidos para arquivos de entrada.

Configurações de espaço de trabalho sem suporte

As seguintes configurações de espaço de trabalho não são suportadas para implantação em lote:

  • Espaços de trabalho configurados com um recurso Registros de Contêiner do Azure com o recurso Quarentena habilitado
  • Espaços de trabalho com chaves gerenciadas pelo cliente

Configurações de computação não suportadas

As seguintes configurações de computação não são suportadas para implantação em lote:

  • Clusters Kubernetes do Azure ARC
  • Solicitação granular de recursos (memória, vCPU, GPU) para clusters Kubernetes do Azure (somente a contagem de instâncias pode ser solicitada)

Tipos de arquivo de entrada não suportados

Os seguintes tipos de arquivo de entrada não são suportados para implantação em lote:

  • Conjuntos de dados tabulares (V1)
  • Pastas e conjuntos de dados de arquivos (V1)
  • MLtable (V2)

Conteúdos relacionados