Depurar scripts de avaliação usando o servidor HTTP de inferência do Azure Machine Learning

O servidor HTTP de inferência do Azure Machine Learning é um pacote Python que expõe sua função de pontuação como um ponto de extremidade HTTP e encapsula o código e as dependências do servidor Flask em um pacote singular. O servidor de inferência é incluído nas imagens pré-criadas do Docker para inferência que são usadas quando você implanta um modelo no Aprendizado de Máquina do Azure. Quando você usa o pacote sozinho, pode implantar o modelo localmente para produção. Você também pode validar facilmente seu script de pontuação (entrada) em um ambiente de desenvolvimento local. Se houver um problema com o script de pontuação, o servidor de inferência retornará um erro e o local do erro.

Você também pode usar o servidor de inferência para criar portas de validação em um pipeline contínuo de integração e implantação. Por exemplo, você pode iniciar o servidor de inferência com o script candidato e executar o conjunto de testes no ponto de extremidade local.

Este artigo oferece suporte a desenvolvedores que desejam usar o servidor de inferência para depurar localmente. Neste artigo, irá ver como usar o servidor de inferência com endpoints online.

Pré-requisitos

• Python 3.8 ou posterior
• Anaconda

O servidor de inferência é executado em sistemas operacionais baseados em Windows e Linux.

Explore as opções de depuração local para endpoints online

Ao depurar endpoints localmente antes de implantar na nuvem, pode detetar erros no seu código e configuração desde o início. Para depurar pontos de extremidade localmente, você tem várias opções, incluindo:

• O servidor HTTP de inferência do Azure Machine Learning.
• Um ponto de extremidade local.

A tabela a seguir fornece uma visão geral do suporte que cada opção oferece para vários cenários de depuração:

Este artigo descreve como usar o servidor de inferência.

Ao executar o servidor de inferência localmente, você pode se concentrar em depurar seu script de pontuação sem se preocupar com as configurações do contêiner de implantação.

Depurar seu script de pontuação localmente

Para depurar seu script de pontuação localmente, você tem várias opções para testar o comportamento do servidor de inferência:

• Use um script de pontuação fictício.
• Utilize o VS Code para depurar com o pacote azureml-inference-server-http.
• Execute um script de pontuação real, um arquivo de modelo e um arquivo de ambiente a partir do repositório de exemplos.

As seções a seguir fornecem informações sobre cada opção.

Usar um script de pontuação fictícia para testar o comportamento do servidor de inferência

1. Crie um diretório chamado server_quickstart para armazenar seus arquivos:

   mkdir server_quickstart
   cd server_quickstart
   

2. Para evitar conflitos de pacotes, crie um ambiente virtual, como myenvo , e ative-o:

   python -m virtualenv myenv
   

   Nota

   No Linux, execute o source myenv/bin/activate comando para ativar o ambiente virtual.

   Depois de testar o servidor de inferência, você pode executar o deactivate comando para desativar o ambiente virtual Python.

3. Instale o azureml-inference-server-http pacote a partir do feed Python Package Index (PyPI):

   python -m pip install azureml-inference-server-http
   

4. Crie seu script de entrada. O exemplo a seguir cria um script de entrada básico e o salva em um arquivo chamado score.py:

   echo -e 'import time\ndef init(): \n\ttime.sleep(1) \n\ndef run(input_data): \n\treturn {"message":"Hello, World!"}' > score.py
   

5. Use o azmlinfsrv comando para iniciar o servidor de inferência e definir o arquivo score.py como o script de entrada:

   azmlinfsrv --entry_script score.py
   

   Nota

   O servidor de inferência é hospedado em 0.0.0.0, o que significa que ele ouve todos os endereços IP da máquina de hospedagem.

6. Use o curl utilitário para enviar uma solicitação de pontuação para o servidor de inferência:

   curl -p 127.0.0.1:5001/score
   

   O servidor de inferência publica a seguinte resposta:

   {"message": "Hello, World!"}
   

7. Quando terminar o teste, selecione Ctrl+C para parar o servidor de inferência.

Você pode modificar o arquivo de script de pontuação score.py. Em seguida, você pode testar suas alterações usando o azmlinfsrv --entry_script score.py comando para executar o servidor de inferência novamente.

Integração com o VS Code

No VS Code, você pode usar a extensão Python para depuração com o pacote azureml-inference-server-http . O VS Code oferece dois modos de depuração: iniciar e anexar.

Antes de usar qualquer um dos modos, instale o azureml-inference-server-http pacote executando o seguinte comando:

python -m pip install azureml-inference-server-http

Modo de inicialização

Para o modo de inicialização, execute as seguintes etapas para configurar o VS Code launch.json arquivo de configuração e iniciar o servidor de inferência dentro do VS Code:

1. Inicie o VS Code e abra a pasta que contém o script score.py.

2. Para esse espaço de trabalho no VS Code, adicione a seguinte configuração ao arquivo launch.json:

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Debug score.py",
               "type": "debugpy",
               "request": "launch",
               "module": "azureml_inference_server_http.amlserver",
               "args": [
                   "--entry_script",
                   "score.py"
               ]
           }
       ]
     }
   

3. Inicie a sessão de depuração no VS Code selecionando Executar>Iniciar Depuração ou selecionando F5.

Modo de anexação

Para o modo de anexação, execute as seguintes etapas para usar o VS Code com a extensão Python para anexar ao processo do servidor de inferência:

1. Inicie o VS Code e abra a pasta que contém o script score.py.

2. Para esse espaço de trabalho no VS Code, adicione a seguinte configuração ao arquivo launch.json:

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Python: Attach using Process ID",
               "type": "debugpy",
               "request": "attach",
               "processId": "${command:pickProcess}",
               "justMyCode": true
           }
       ]
     }
   

3. Em uma janela de comando, inicie o servidor de inferência executando o azmlinfsrv --entry_script score.py comando.

4. Execute as seguintes etapas para iniciar a sessão de depuração no VS Code:

   1. Selecione Executar>Iniciar Depuração ou selecione F5.

   2. Na janela de comando, pesquise os logs do servidor de inferência para localizar a ID de processo do azmlinfsrv processo.

      

      Certifique-se de localizar o ID do azmlinfsrv processo, não o gunicorn processo.

   3. No depurador VS Code, insira o ID do processo azmlinfsrv.

      Se não conseguir ver o selector de processos do VS Code, insira manualmente o ID do processo no campo processId do arquivo launch.json do espaço de trabalho.

Para os modos de inicialização e anexação, você pode definir pontos de interrupção e depurar o script passo a passo.

Use um exemplo de ponta a ponta

O procedimento a seguir executa o servidor de inferência localmente com arquivos de exemplo do repositório de exemplo do Azure Machine Learning. Os arquivos de exemplo incluem um script de pontuação, um arquivo de modelo e um arquivo de ambiente. Para obter mais exemplos de como usar esses arquivos de exemplo, consulte Implantar e pontuar um modelo de aprendizado de máquina usando um ponto de extremidade online.

1. Clone o repositório de exemplo e vá para a pasta que contém os arquivos de exemplo relevantes:

   git clone --depth 1 https://github.com/Azure/azureml-examples
   cd azureml-examples/cli/endpoints/online/model-1/
   

2. Use conda para criar e ativar um ambiente virtual:

   Neste exemplo, o azureml-inference-server-http pacote é instalado automaticamente. O pacote está incluído como uma biblioteca dependente do azureml-defaults pacote, que está listado no arquivo conda.yaml.

   # Create the environment from the YAML file.
   conda env create --name model-env -f ./environment/conda.yaml
   # Activate the new environment.
   conda activate model-env
   

3. Reveja o script de pontuação, onlinescoring/score.py:

   import os
   import logging
   import json
   import numpy
   import joblib
   
   
   def init():
       """
       This function is called when the container is initialized/started, typically after create/update of the deployment.
       You can write the logic here to perform init operations like caching the model in memory
       """
       global model
       # AZUREML_MODEL_DIR is an environment variable created during deployment.
       # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
       # Please provide your model's folder name if there is one
       model_path = os.path.join(
           os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
       )
       # deserialize the model file back into a sklearn model
       model = joblib.load(model_path)
       logging.info("Init complete")
   
   
   def run(raw_data):
       """
       This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
       In the example we extract the data from the json input and call the scikit-learn model's predict()
       method and return the result back
       """
       logging.info("model 1: request received")
       data = json.loads(raw_data)["data"]
       data = numpy.array(data)
       result = model.predict(data)
       logging.info("Request processed")
       return result.tolist()
   

4. Execute o servidor de inferência especificando o script de pontuação e o caminho para a pasta modelo.

   Durante a implantação, a AZUREML_MODEL_DIR variável é definida para armazenar o caminho para a pasta modelo. Você especifica esse valor no model_dir parâmetro. Quando o script de pontuação é executado, ele recupera o valor da AZUREML_MODEL_DIR variável.

   Nesse caso, use o diretório atual, ./, como o model_dir valor, porque o script de pontuação especifica o subdiretório como model/sklearn_regression_model.pkl.

   azmlinfsrv --entry_script ./onlinescoring/score.py --model_dir ./
   

   Quando o servidor de inferência é iniciado com sucesso e invoca o script de pontuação, abre-se o log de inicialização de exemplo. Caso contrário, o log mostra mensagens de erro.

5. Teste o script de pontuação com dados de exemplo executando as seguintes etapas:

   1. Abra outra janela de comando e vá para o mesmo diretório de trabalho em que você executou o azmlinfsrv comando.

   2. Use o seguinte curl utilitário para enviar uma solicitação de exemplo para o servidor de inferência e receber um resultado de pontuação:

      curl --request POST "127.0.0.1:5001/score" --header "Content-Type:application/json" --data @sample-request.json
      

      Quando não há problemas no seu script de pontuação, o script retorna o resultado da pontuação. Se ocorrerem problemas, você pode atualizar o script de pontuação e, em seguida, iniciar o servidor de inferência novamente para testar o script atualizado.

Revisar rotas do servidor de inferência

O servidor de inferência escuta na porta 5001 por padrão nas seguintes rotas:

Revisar os parâmetros do servidor de inferência

O servidor de inferência aceita os seguintes parâmetros:

Explore o processamento de solicitações do servidor de inferência

As etapas a seguir demonstram como o servidor de inferência, azmlinfsrv, lida com solicitações de entrada:

1. Um wrapper de CLI Python fica ao redor da pilha de rede do servidor de inferência e é usado para iniciar o servidor de inferência.

2. Um cliente envia uma solicitação para o servidor de inferência.

3. O servidor de inferência envia a solicitação por meio do servidor WSGI (Web Server Gateway Interface ), que despacha a solicitação para um dos seguintes aplicativos de trabalho do Flask:

   • On Windows: Waitress
   • No Linux: gunicorn

4. O aplicativo Flask worker lida com a solicitação, o que inclui o carregamento do script de entrada e quaisquer dependências.

5. Seu script de entrada recebe a solicitação. O script de entrada faz uma chamada de inferência para o modelo carregado e retorna uma resposta.

Explorar os registos do servidor de inferência

Há duas maneiras de obter dados de log para o teste do servidor de inferência:

• Execute o azureml-inference-server-http pacote localmente e visualize a saída do log.
• Use pontos de extremidade online e visualize os logs de contêiner. O log do servidor de inferência é chamado Versão do servidor <>HTTP de Inferência do Azure Machine Learning.

Ver registos de arranque

Quando o servidor de inferência é iniciado, os logs mostram as seguintes configurações iniciais do servidor:

Azure ML Inferencing HTTP server <version>


Server Settings
---------------
Entry Script Name: <entry-script>
Model Directory: <model-directory>
Config File: <configuration-file>
Worker Count: <worker-count>
Worker Timeout (seconds): None
Server Port: <port>
Health Port: <port>
Application Insights Enabled: false
Application Insights Key: <Application-Insights-instrumentation-key>
Inferencing HTTP server version: azmlinfsrv/<version>
CORS for the specified origins: <access-control-allow-origins>
Create dedicated endpoint for health: <health-check-endpoint>


Server Routes
---------------
Liveness Probe: GET   127.0.0.1:<port>/
Score:          POST  127.0.0.1:<port>/score

<logs>

Por exemplo, quando você executa o servidor de inferência executando as etapas de exemplo de ponta a ponta , os logs contêm as seguintes informações:

Azure ML Inferencing HTTP server v1.2.2


Server Settings
---------------
Entry Script Name: /home/user-name/azureml-examples/cli/endpoints/online/model-1/onlinescoring/score.py
Model Directory: ./
Config File: None
Worker Count: 1
Worker Timeout (seconds): None
Server Port: 5001
Health Port: 5001
Application Insights Enabled: false
Application Insights Key: None
Inferencing HTTP server version: azmlinfsrv/1.2.2
CORS for the specified origins: None
Create dedicated endpoint for health: None

Server Routes
---------------
Liveness Probe: GET   127.0.0.1:5001/
Score:          POST  127.0.0.1:5001/score

2022-12-24 07:37:53,318 I [32726] gunicorn.error - Starting gunicorn 20.1.0
2022-12-24 07:37:53,319 I [32726] gunicorn.error - Listening at: http://0.0.0.0:5001 (32726)
2022-12-24 07:37:53,319 I [32726] gunicorn.error - Using worker: sync
2022-12-24 07:37:53,322 I [32756] gunicorn.error - Booting worker with pid: 32756
Initializing logger
2022-12-24 07:37:53,779 I [32756] azmlinfsrv - Starting up app insights client
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - Found user script at /home/user-name/azureml-examples/cli/endpoints/online/model-1/onlinescoring/score.py
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - run() is not decorated. Server will invoke it with the input in JSON string.
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - Invoking user's init function
2022-12-24 07:37:55,974 I [32756] azmlinfsrv.user_script - Users's init has completed successfully
2022-12-24 07:37:55,976 I [32756] azmlinfsrv.swagger - Swaggers are prepared for the following versions: [2, 3, 3.1].
2022-12-24 07:37:55,976 I [32756] azmlinfsrv - Scoring timeout is set to 3600000
2022-12-24 07:37:55,976 I [32756] azmlinfsrv - Worker with pid 32756 ready for serving traffic

Compreender o formato dos dados de registo

Todos os logs do servidor de inferência, exceto o script iniciador, apresentam dados no seguinte formato:

<UTC-time> <level> [<process-ID>] <logger-name> - <message>

Cada entrada é composta pelos seguintes componentes:

• <UTC-time>: A hora em que a entrada é inserida no log
• <level>: O primeiro caractere do nível de log para a entrada, como E para ERROR, I para INFO, e assim por diante
• <process-ID>: O ID do processo associado à entrada
• <logger-name>: O nome do recurso associado à entrada de log
• <message>: O conteúdo da mensagem de log

Há seis níveis de logging em Python. Cada nível tem um valor numérico atribuído de acordo com a sua gravidade:

Solucionar problemas do servidor de inferência

As seções a seguir fornecem dicas básicas de solução de problemas para o servidor de inferência. Para solucionar problemas de pontos de extremidade online, consulte Solucionar problemas de implantação e pontuação de pontos de extremidade online.

Verifique os pacotes instalados

Siga estas etapas para resolver problemas com pacotes instalados:

1. Reúna informações sobre pacotes instalados e versões para seu ambiente Python.

2. No arquivo de ambiente, verifique a versão do pacote Python azureml-inference-server-http especificada. Nos logs de inicialização do servidor HTTP de inferência do Azure Machine Learning, verifique a versão do servidor de inferência exibida. Confirme se as duas versões coincidem.

   Em alguns casos, o resolvedor de dependência pip instala versões de pacote inesperadas. Talvez seja necessário executar pip para corrigir os pacotes e versões instalados.

3. Se especificares o Flask ou as suas dependências no teu ambiente, remove estes itens.

   • Os pacotes dependentes incluem flask, jinja2, itsdangerous, werkzeug, markupsafee click.
   • O flask pacote é listado como uma dependência no pacote do servidor de inferência. A melhor abordagem é permitir que o servidor de inferência instale o flask pacote.
   • Quando o servidor de inferência é configurado para suportar novas versões do Flask, o servidor de inferência recebe automaticamente as atualizações do pacote à medida que ficam disponíveis.

Verifique a versão do servidor de inferência

O azureml-inference-server-http pacote do servidor é publicado no PyPI. A página PyPI lista o changelog e todas as versões do pacote.

Se você usar uma versão inicial do pacote, atualize sua configuração para a versão mais recente. A tabela a seguir resume versões estáveis, problemas comuns e ajustes recomendados:

Verificar dependências do pacote

Os pacotes dependentes mais relevantes para o pacote de azureml-inference-server-http servidor incluem:

• flask
• opencensus-ext-azure
• inference-schema

Se você especificar o azureml-defaults pacote em seu ambiente Python, o azureml-inference-server-http pacote será um pacote dependente. A dependência é instalada automaticamente.

TypeError durante a inicialização do servidor de inferência

Você pode encontrar o seguinte TypeError durante a inicialização do servidor de inferência:

TypeError: register() takes 3 positional arguments but 4 were given

  File "/var/azureml-server/aml_blueprint.py", line 251, in register

    super(AMLBlueprint, self).register(app, options, first_registration)

TypeError: register() takes 3 positional arguments but 4 were given

Este erro ocorre quando você tem o Flask 2 instalado em seu ambiente Python, mas sua azureml-inference-server-http versão do pacote não suporta o Flask 2. O suporte para o Flask 2 está disponível no azureml-inference-server-http pacote 0.7.0 e versões posteriores, e no azureml-defaults pacote 1.44 e versões posteriores.

• Se você não usar o pacote Flask 2 em uma imagem do Docker do Azure Machine Learning, use a versão mais recente do azureml-inference-server-http pacote ou azureml-defaults .

• Se você usar o pacote Flask 2 em uma imagem do Docker do Azure Machine Learning, confirme se a versão de compilação da imagem é July 2022 ou posterior.

  Você pode encontrar a versão da imagem nos logs do contêiner. Por exemplo, consulte as seguintes declarações de registo:

  2022-08-22T17:05:02,147738763+00:00 | gunicorn/run | AzureML Container Runtime Information
  2022-08-22T17:05:02,161963207+00:00 | gunicorn/run | ###############################################
  2022-08-22T17:05:02,168970479+00:00 | gunicorn/run | 
  2022-08-22T17:05:02,174364834+00:00 | gunicorn/run | 
  2022-08-22T17:05:02,187280665+00:00 | gunicorn/run | AzureML image information: openmpi4.1.0-ubuntu20.04, Materialization Build:20220708.v2
  2022-08-22T17:05:02,188930082+00:00 | gunicorn/run | 
  2022-08-22T17:05:02,190557998+00:00 | gunicorn/run | 
  

  A data de compilação da imagem aparece após a Materialization Build notação. No exemplo anterior, a versão da imagem é 20220708, ou 8 de julho de 2022. A imagem neste exemplo é compatível com o Flask 2.

  Se você não vir uma mensagem semelhante no log do contêiner, sua imagem está desatualizada e deve ser atualizada. Se você usar uma imagem CUDA (Compute Unified Device Architecture) e não conseguir encontrar uma imagem mais recente, verifique o repositório AzureML-Containers para ver se sua imagem foi preterida. Você pode encontrar substitutos designados para imagens obsoletas.

  Se utilizar o servidor de inferência com um endpoint online, também poderá encontrar os logs no Azure Machine Learning Studio. Na página do seu ponto de extremidade, selecione a guia Logs .

Se você implantar com o SDK v1 e não especificar explicitamente uma imagem em sua configuração de implantação, o servidor de inferência aplicará o pacote com uma versão que corresponda ao openmpi4.1.0-ubuntu20.04 conjunto de ferramentas SDK local. No entanto, a versão instalada pode não ser a versão mais recente disponível da imagem.

Para o SDK versão 1.43, o servidor de inferência instala a versão do pacote por padrão, mas essa versão do pacote não é compatível com o openmpi4.1.0-ubuntu20.04:20220616 SDK 1.43. Certifique-se de usar o SDK mais recente para sua implantação.

Se não for possível atualizar a imagem, você poderá evitar temporariamente o problema fixando as azureml-defaults==1.43 entradas ou azureml-inference-server-http~=0.4.13 no arquivo de ambiente. Essas entradas direcionam o servidor de inferência para instalar a versão mais antiga com flask 1.0.x.

ImportError ou ModuleNotFoundError durante a inicialização do servidor de inferência

Você pode encontrar um ImportError ou ModuleNotFoundError em módulos específicos, como opencensus, jinja2, markupsafe, ou click, durante a inicialização do servidor de inferência. O exemplo a seguir mostra a mensagem de erro:

ImportError: cannot import name 'Markup' from 'jinja2'

Os erros de importação e módulo ocorrem quando você usa a versão 0.4.10 ou versões anteriores do servidor de inferência que não fixam a dependência do Flask em uma versão compatível. Para evitar o problema, instale uma versão posterior do servidor de inferência.

Conteúdos relacionados

• Desenvolver e avaliar um modelo de aprendizagem automática usando um endpoint online
• Imagens pré-construídas do Docker para inferência