Solução de problemas de pontos de extremidade em lote
APLICA-SE A:
Extensão de ML da CLI do Azure v2 (atual)SDK do Python azure-ai-ml v2 (atual)
Este artigo fornece diretrizes para a solução de erros comuns ao usar pontos de extremidade em lote para pontuação em lote no Azure Machine Learning. As seções a seguir descrevem como analisar os logs de pontuação em lote para identificar possíveis problemas e cenários sem suporte. Você também pode analisar as soluções recomendadas para resolver erros comuns.
Obter logs para os trabalhos de pontuação em lote
Depois que você invocar um ponto de extremidade em lote usando a CLI do Azure ou a API REST, o trabalho de pontuação em lote será executado de forma assíncrona. Há duas opções para obter os logs de um trabalho de pontuação em lote:
Opção 1: Transmitir os logs do trabalho para um console local. Somente os registros na pasta azureml-logs são transmitidos.
Execute o seguinte comando para transmitir os logs gerados pelo sistema para seu console. Substitua o parâmetro
<job_name>pelo nome do seu trabalho de pontuação em lote:az ml job stream --name <job_name>Opção 2: Exibir os logs do trabalho no Estúdio do Azure Machine Learning.
Execute o seguinte comando para obter o link do trabalho a ser usado no estúdio. Substitua o parâmetro
<job_name>pelo nome do seu trabalho de pontuação em lote:az ml job show --name <job_name> --query services.Studio.endpoint -o tsvAbra o link do trabalho no estúdio.
No gráfico do trabalho, selecione a etapa batchscoring.
Na guia Saídas + logs, selecione um ou mais logs para revisar.
Revisar os arquivos de log
O Azure Machine Learning fornece vários tipos de arquivos de log e outros arquivos de dados que podem ser usados para ajudar a solucionar problemas do trabalho de pontuação em lote.
As duas pastas de nível superior para os logs de pontuação em lote são azureml-logs e logs. As informações do controlador que inicia o script de avaliação são armazenadas no arquivo ~/azureml-logs/70_driver_log.txt.
Examinar as informações de alto nível
A natureza distribuída dos trabalhos de pontuação em lote resulta em logs de diferentes fontes, mas dois arquivos combinados fornecem informações de alto nível:
| Arquivo | Descrição |
|---|---|
| ~/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 dos 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 exibição do nó principal (também conhecido como orquestrador) do trabalho em execução. Esse registro inclui informações sobre a criação da tarefa, o monitoramento do progresso e o resultado do trabalho. |
Examinar os dados de rastreamento de pilha em busca de erros
Outros arquivos fornecem informações sobre possíveis erros em seu script:
| Arquivo | Descrição |
|---|---|
| ~/logs/user/error.txt | Fornece um resumo dos erros no seu script. |
| ~/logs/user/error/* | Fornece os rastreamentos de pilha completos das exceções geradas durante o carregamento e a execução do script de entrada. |
Examinar os logs de processo por nó
Para ter uma compreensão completa de como cada nó executa seu script de pontuação, examine os logs de processo individuais de 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 registro 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, a duração, o tempo de processamento e o tempo do método de execução.
Examinar as verificações periódicas por nó
Você também pode ver os resultados de verificações periódicas do uso de recursos para cada nó. Os arquivos de log e os arquivos de configuração são armazenados na pasta ~/logs/perf.
Use o parâmetro --resource_monitor_interval para alterar o intervalo de verificação em segundos:
- Use o padrão: O intervalo padrão é de 600 segundos (aproximadamente 10 minutos).
- Parar verificações: Defina o valor como 0 para interromper a execução de 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:
| Arquivo ou Pasta | Descrição |
|---|---|
| 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 processos. O nome da subpasta é a data e a hora de criação da verificação (Ano, Mês, Dia, Hora). processos_%M: Arquivo dentro da subpasta. O arquivo mostra detalhes sobre a verificação do processo. O nome do arquivo termina com a hora da verificação (Minuto) em relação à hora de criação da verificação. |
| node_disk_usage.csv | Mostra a utilização detalhada 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 o registro em log ao script de pontuação
Use o log do Python no script de pontuação. Esses registros são armazenados no arquivo logs/user/stdout/<node_id>/process<number>.stdout.txt.
O código a seguir demonstra como adicionar o registro em log ao 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 o consumo de pontos de extremidade em lote e as 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 chamado azureml."
Motivo: O pacote azureml-core parece estar ausente na instalação.
Solução: Adicionar o pacote azureml-core ao seu arquivo de dependências do Conda.
Nenhuma saída no arquivo de previsões
A implantação em lote espera uma pasta vazia para armazenar 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 arquivo com os resultados.
Mensagem registrada: Nenhuma mensagem específica registrada.
Motivo: A implantação em lote não pode sobrescrever um arquivo predictions.csv existente.
Solução: Se o processo especificar um local de pasta de saída para as previsões, certifique-se de que a pasta não contenha um arquivo predictions.csv existente.
O processo em lote atinge o tempo limite
A implantação em lote usa um valor timeout para determinar quanto tempo a implantação deve esperar 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 tentados novamente até o número máximo de tentativas especificado no valor max_retries. Se o erro de tempo limite ocorrer em cada tentativa de repetição, o trabalho de implantação falhará.
Você pode configurar as propriedades timeout e max_retries para cada implantação com o parâmetro retry_settings.
Mensagem registrada: "Nenhuma atualização de progresso em [número] segundos. Nenhuma atualização de progresso nesta verificação. "Aguarde [número] segundos desde a última atualização."
Reason: A execução do lote excede o tempo limite especificado e o número máximo de tentativas de repetição. Essa ação corresponde à falha da função run() no script de entrada.
Solução: Aumentar o valor de timeout para sua implantação. Por padrão, o valor timeout é 30 e o valor max_retries é 3. Para determinar um valor timeout adequado à sua implantação, considere o número de arquivos a serem processados em cada lote e o tamanho dos arquivos. Você pode diminuir o número de arquivos a serem processados e gerar minilotes de tamanho menor. Essa abordagem resulta em uma execução mais rápida.
Exceção em ScriptExecution.StreamAccess.Authentication
Para que a implantação em lote seja bem-sucedida, a identidade gerenciada do cluster de computação deve ter permissão para montar o armazenamento de ativos de dados. Quando a identidade gerenciada não tem permissões suficientes, o script gera 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 causado por StreamAccessException. StreamAccessException foi causada por AuthenticationException."
Motivo: o cluster de computação em que a implantação está sendo executada não pode montar o armazenamento em que o ativo de dados está localizado. A identidade gerenciada do computador 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 o Leitor de Dados de Blobs de Armazenamento acesso à conta de armazenamento. Somente os proprietários de contas de Armazenamento do Microsoft 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: Message: Não é possível montar o Dataset(ID='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', name='None', version=None). A origem do conjunto de dados não está acessível ou não contém dados."
Motivo: o cluster de computação em que a implantação está sendo executada não pode montar o armazenamento em que o ativo de dados está localizado. A identidade gerenciada do computador 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 o Leitor de Dados de Blobs de Armazenamento acesso à conta de armazenamento. Somente os proprietários de contas de Armazenamento do Microsoft 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 parâmetro dataset_param. Para que a implantação prossiga, o parâmetro deve ter um valor atribuído ou um valor padrão especificado.
Mensagem registrada: "O nó do conjunto de dados [código] faz referência ao parâmetro dataset_param, que não tem um valor especificado ou um valor padrão."
Motivo: não há suporte para o ativo de dados de entrada fornecido para o ponto de extremidade em lote.
Solução: Certificar-se de que o script de implantação forneça uma entrada de dados compatível com os pontos de extremidade em lote.
Falha no programa do usuário, falha na execução
Durante a execução do script para implantação em lote, se a função init() ou run() encontrar um erro, o programa do usuário ou a execução poderá falhar. É possível analisar 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. Verifique os detalhes nos logs. Você pode verificar logs/readme.txt para ver o layout dos registros."
Motivo: A função init() 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:
No Estúdio do Azure Machine Learning, vá para a execução do trabalho de implantação em lote com falha e selecione a guia Saídas + logs.
Abra o arquivo logs>user>error><node_identifier>>process<number>.txt.
Localize a mensagem de erro gerada pela função
init()ourun().
ValueError: nenhum objeto a ser concatenado
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 com suporte. Lembre-se de que os modelos do MLflow dão suporte para apenas um subconjunto de tipos de arquivo. Para obter mais informações, consulte Considerações ao implantar a inferência em lote.
Mensagem registrada: "ValueError: Nenhum objeto para concatenar."
Motivo: Todos os arquivos no minilote gerado estão corrompidos ou são de tipos sem suporte.
Solução: Seguir estas etapas para localizar detalhes sobre os arquivos com falha:
No Estúdio do Azure Machine Learning, vá para a execução do trabalho de implantação em lote com falha e selecione a guia Saídas + logs.
Abra o arquivo logs>user>stdout><node_identifier>>process<number>.txt.
Procure entradas que descrevam a falha na entrada do arquivo, como "ERROR:azureml:Erro ao processar o arquivo de entrada."
Se o tipo de arquivo não for compatível, revise a lista de arquivos compatíveis. 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, confira Usar modelos do MLflow com um script de pontuação.
Nenhum minilote bem-sucedido
O processo de implantação em lote exige que os pontos de extremidade em lote forneçam dados no formato esperado pela função run(). Se os arquivos de entrada estiverem corrompidos ou forem incompatíveis com a assinatura do modelo, a função run() não retornará um minilote bem-sucedido.
Mensagem registrada: "Nenhum item de minilote bem-sucedido retornado de run()". Verifique 'response: run()' em https://aka.ms/batch-inference-documentation."
Motivo: O ponto de extremidade em lote não conseguiu fornecer os dados no formato esperado para a função run(). Esse problema pode resultar da leitura de arquivos corrompidos ou da incompatibilidade dos dados de entrada com a assinatura do modelo (MLflow).
Solução: Seguir estas etapas para localizar os detalhes sobre o minilote com falha:
No Estúdio do Azure Machine Learning, vá para a execução do trabalho de implantação em lote com falha e selecione a guia Saídas + logs.
Abra o arquivo logs>user>stdout><node_identifier>>process<number>.txt.
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-alvo ou serviço não permitido
Os tokens do Microsoft Entra são emitidos para ações específicas que identificam os usuários (público-alvo), serviços e recursos permitidos. O token de autenticação para a API REST do ponto de extremidade em lote deve definir o parâmetro resource como https://ml.azure.com.
Mensagem registrada: Nenhuma mensagem específica registrada.
Motivo: Tentar invocar a API REST para o ponto de extremidade em lote e implantação com um token emitido para um público-alvo ou serviço diferente.
Solução: Seguir estas etapas para resolver esse problema de autenticação:
Quando você gerar um token de autenticação para a API REST do ponto de extremidade em lote, defina o parâmetro
resourcecomohttps://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.compara gerenciamento.Quando você invocar a API REST para um ponto de extremidade em lote e implantação, 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-alvo ou serviço diferente. Em cada caso, confirme se 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 parâmetro defaults.deployment_name.
Mensagem registrada: "Nenhuma implantação válida para a qual rotear. 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: Usar um dos métodos a seguir para resolver o problema de roteamento:
Confirme se o parâmetro
defaults.deployment_namedefine 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 têm suporte. As seções a seguir identificam espaços de trabalho e recursos de computação sem suporte e tipos inválidos de arquivos de entrada.
Configurações do espaço de trabalho sem suporte
Não há suporte para as seguintes configurações de espaço de trabalho para implantação em lote:
- Espaços de trabalho configurados com Registros de Contêineres do Azure com recurso de Quarentena habilitado
- Espaços de trabalho com chaves gerenciadas pelo cliente
Configurações da computação sem suporte
Não há suporte para as seguintes configurações de computação para implantação em lote:
- Clusters do Kubernetes do Azure ARC
- Solicitação de recursos granulares (memória, vCPU, GPU) para clusters do Azure Kubernetes (somente a contagem de instâncias pode ser solicitada)
Tipos de arquivos de entrada sem suporte
Não há suporte para os seguintes tipos de arquivos de entrada para implantação em lote:
- Conjuntos de dados tabulares (V1)
- Conjuntos de dados de Pastas e Arquivos (V1)
- MLtable (V2)