Depuração interativa com o Visual Studio Code

APLICA-SE A: Python SDK azureml v1

Saiba como depurar interativamente experimentos, pipelines e implantações do Azure Machine Learning usando o Visual Studio Code (VS Code) e a depuração.

Executar e depurar experimentos localmente

Use a extensão do Azure Machine Learning para validar, executar e depurar seus experimentos de aprendizado de máquina antes de enviá-los para a nuvem.

Pré-requisitos

• Extensão VS Code do Azure Machine Learning (visualização). Para obter mais informações, consulte Configurar a extensão VS Code do Azure Machine Learning.

  Importante

  A extensão VS Code do Azure Machine Learning usa a CLI (v2) por padrão. As instruções neste guia usam CLI 1.0. Para alternar para a CLI 1.0, defina a azureML.CLI Compatibility Mode configuração no Visual Studio Code como 1.0. Para obter mais informações sobre como modificar suas configurações no Visual Studio Code, consulte a documentação de configurações de usuário e espaço de trabalho.

  Importante

  Esta funcionalidade está atualmente em pré-visualização pública. Esta versão de pré-visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas.

  Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

• Docker

  • Docker Desktop para Mac e Windows

  • Docker Engine para Linux.

    Nota

    No Windows, certifique-se de configurar o Docker para usar contêineres Linux.

    Gorjeta

    Para Windows, embora não seja necessário, é altamente recomendável usar o Docker com o Windows Subsystem for Linux (WSL) 2.

• Python 3

Experiência de depuração local

1. No VS Code, abra a exibição da extensão do Azure Machine Learning.

2. Expanda o nó de assinatura que contém seu espaço de trabalho. Se você ainda não tiver um, poderá criar um espaço de trabalho do Azure Machine Learning usando a extensão.

3. Expanda o nó do espaço de trabalho.

4. Clique com o botão direito do mouse no nó Experimentos e selecione Criar experimento. Quando o prompt aparecer, forneça um nome para seu experimento.

5. Expanda o nó Experimentos, clique com o botão direito do mouse no experimento que deseja executar e selecione Executar experimento.

6. Na lista de opções, selecione Localmente.

7. Primeira utilização apenas no Windows. Quando solicitado a permitir o Compartilhamento de Arquivos, selecione Sim. Quando você habilita o compartilhamento de arquivos, ele permite que o Docker monte o diretório que contém seu script no contêiner. Além disso, ele também permite que o Docker armazene os logs e saídas de sua execução em um diretório temporário em seu sistema.

8. Selecione Sim para depurar seu experimento. Se não, selecione Não. Selecionar não executará seu experimento localmente sem anexar ao depurador.

9. Selecione Create new Run Configuration (Criar nova configuração de execução) para criar sua configuração de execução. A configuração de execução define o script que você deseja executar, as dependências e os conjuntos de dados usados. Como alternativa, se você já tiver um, selecione-o na lista suspensa.

   1. Escolha o seu ambiente. Você pode escolher entre qualquer um dos selecionados do Azure Machine Learning ou criar o seu próprio.
   2. Forneça o nome do script que você deseja executar. O caminho é relativo ao diretório aberto no VS Code.
   3. Escolha se deseja usar um conjunto de dados do Azure Machine Learning ou não. Você pode criar conjuntos de dados do Azure Machine Learning usando a extensão.
   4. A depuração é necessária para anexar o depurador ao contêiner que executa o experimento. Para adicionar depuração como uma dependência, selecione Adicionar depuração. Caso contrário, selecione Ignorar. Não adicionar depuração como uma dependência executa seu experimento sem anexar ao depurador.
   5. Um arquivo de configuração contendo suas definições de configuração de execução é aberto no editor. Se estiver satisfeito com as configurações, selecione Enviar experiência. Como alternativa, abra a paleta de comandos (Exibir paleta de comandos) na barra de menus e insira o AzureML: Submit experiment comando na > caixa de texto.

10. Depois que o experimento for enviado, uma imagem do Docker contendo o script e as configurações especificadas na configuração de execução será criada.

    Quando o processo de compilação da imagem do Docker começa, o conteúdo do arquivo é transmitido para o console de 60_control_log.txt saída no VS Code.

    Nota

    A primeira vez que a imagem do Docker é criada pode levar vários minutos.

11. Uma vez que a imagem é construída, um prompt aparece para iniciar o depurador. Defina seus pontos de interrupção no script e selecione Iniciar depurador quando estiver pronto para iniciar a depuração. Isso anexa o depurador do VS Code ao contêiner que executa o experimento. Como alternativa, na extensão do Azure Machine Learning, passe o mouse sobre o nó da sua execução atual e selecione o ícone de reprodução para iniciar o depurador.

    Importante

    Não é possível ter várias sessões de depuração para um único experimento. No entanto, você pode depurar dois ou mais experimentos usando várias instâncias do VS Code.

Neste ponto, você deve ser capaz de passo a passo e depurar seu código usando o VS Code.

Se, em algum momento, você quiser cancelar sua execução, clique com o botão direito do mouse no nó de execução e selecione Cancelar execução.

Semelhante às execuções de experimentos remotos, você pode expandir o nó de execução para inspecionar os logs e as saídas.

Depurar e resolver problemas de pipelines de machine learning

Em alguns casos, talvez seja necessário depurar interativamente o código Python usado no pipeline de ML. Usando o VS Code e a depuração, você pode anexar ao código à medida que ele é executado no ambiente de treinamento.

Pré-requisitos

• Um espaço de trabalho do Azure Machine Learning configurado para usar uma Rede Virtual do Azure.

• Um pipeline do Azure Machine Learning que usa scripts Python como parte das etapas do pipeline. Por exemplo, um PythonScriptStep.

• Um cluster de computação do Azure Machine Learning, que está na rede virtual e é usado pelo pipeline para treinamento.

• Um ambiente de desenvolvimento que está na rede virtual. O ambiente de desenvolvimento pode ser um dos seguintes:

  • Uma Máquina Virtual do Azure na rede virtual
  • Uma instância de computação da VM do Notebook na rede virtual
  • Uma máquina cliente que tem conectividade de rede privada com a rede virtual, seja por VPN ou via ExpressRoute.

Para obter mais informações sobre como usar uma Rede Virtual do Azure com o Azure Machine Learning, consulte Visão geral de privacidade e isolamento de rede virtual.

Como funciona

As etapas do pipeline de ML executam scripts Python. Esses scripts são modificados para executar as seguintes ações:

1. Registre o endereço IP do host em que eles estão sendo executados. Use o endereço IP para conectar o depurador ao script.

2. Inicie o componente de depuração e aguarde até que um depurador se conecte.

3. A partir do seu ambiente de desenvolvimento, você monitora os logs criados pelo processo de treinamento para encontrar o endereço IP onde o script está sendo executado.

4. Você informa ao VS Code o endereço IP ao qual conectar o depurador usando um launch.json arquivo.

5. Você anexa o depurador e percorre interativamente o script.

Configurar scripts Python

Para habilitar a depuração, faça as seguintes alterações no(s) script(s) Python usado(s) pelas etapas em seu pipeline de ML:

1. Adicione as seguintes instruções de importação:

   import argparse
   import os
   import debugpy
   import socket
   from azureml.core import Run
   

2. Adicione os seguintes argumentos. Esses argumentos permitem que você habilite o depurador conforme necessário e defina o tempo limite para anexar o depurador:

   parser.add_argument('--remote_debug', action='store_true')
   parser.add_argument('--remote_debug_connection_timeout', type=int,
                       default=300,
                       help=f'Defines how much time the Azure Machine Learning compute target '
                       f'will await a connection from a debugger client (VSCODE).')
   parser.add_argument('--remote_debug_client_ip', type=str,
                       help=f'Defines IP Address of VS Code client')
   parser.add_argument('--remote_debug_port', type=int,
                       default=5678,
                       help=f'Defines Port of VS Code client')
   

3. Adicione as seguintes instruções . Essas instruções carregam o contexto de execução atual para que você possa registrar o endereço IP do nó em que o código está sendo executado:

   global run
   run = Run.get_context()
   

4. Adicione uma if instrução que inicia a depuração e aguarda a anexação de um depurador. Se nenhum depurador for anexado antes do tempo limite, o script continuará normalmente. Certifique-se de substituir o HOST e PORT valores é a função com o listen seu próprio.

   if args.remote_debug:
       print(f'Timeout for debug connection: {args.remote_debug_connection_timeout}')
       # Log the IP and port
       try:
           ip = args.remote_debug_client_ip
       except:
           print("Need to supply IP address for VS Code client")
       print(f'ip_address: {ip}')
       debugpy.listen(address=(ip, args.remote_debug_port))
       # Wait for the timeout for debugger to attach
       debugpy.wait_for_client()
       print(f'Debugger attached = {debugpy.is_client_connected()}')
   

O exemplo Python a seguir mostra um arquivo simples train.py que permite a depuração:

# Copyright (c) Microsoft. All rights reserved.
# Licensed under the MIT license.

import argparse
import os
import debugpy
import socket
from azureml.core import Run

print("In train.py")
print("As a data scientist, this is where I use my training code.")

parser = argparse.ArgumentParser("train")

parser.add_argument("--input_data", type=str, help="input data")
parser.add_argument("--output_train", type=str, help="output_train directory")

# Argument check for remote debugging
parser.add_argument('--remote_debug', action='store_true')
parser.add_argument('--remote_debug_connection_timeout', type=int,
                    default=300,
                    help=f'Defines how much time the Azure Machine Learning compute target '
                    f'will await a connection from a debugger client (VSCODE).')
parser.add_argument('--remote_debug_client_ip', type=str,
                    help=f'Defines IP Address of VS Code client')
parser.add_argument('--remote_debug_port', type=int,
                    default=5678,
                    help=f'Defines Port of VS Code client')

# Get run object, so we can find and log the IP of the host instance
global run
run = Run.get_context()

args = parser.parse_args()

# Start debugger if remote_debug is enabled
if args.remote_debug:
    print(f'Timeout for debug connection: {args.remote_debug_connection_timeout}')
    # Log the IP and port
    ip = socket.gethostbyname(socket.gethostname())
    # try:
    #     ip = args.remote_debug_client_ip
    # except:
    #     print("Need to supply IP address for VS Code client")
    print(f'ip_address: {ip}')
    debugpy.listen(address=(ip, args.remote_debug_port))
    # Wait for the timeout for debugger to attach
    debugpy.wait_for_client()
    print(f'Debugger attached = {debugpy.is_client_connected()}')

print("Argument 1: %s" % args.input_data)
print("Argument 2: %s" % args.output_train)

if not (args.output_train is None):
    os.makedirs(args.output_train, exist_ok=True)
    print("%s created" % args.output_train)

Configurar pipeline de ML

Para fornecer os pacotes Python necessários para iniciar a depuração e obter o contexto de execução, crie um ambiente e defina pip_packages=['debugpy', 'azureml-sdk==<SDK-VERSION>']. Altere a versão do SDK para corresponder à que você está usando. O trecho de código a seguir demonstra como criar um ambiente:

# Use a RunConfiguration to specify some additional requirements for this step.
from azureml.core.runconfig import RunConfiguration
from azureml.core.conda_dependencies import CondaDependencies
from azureml.core.runconfig import DEFAULT_CPU_IMAGE

# create a new runconfig object
run_config = RunConfiguration()

# enable Docker 
run_config.environment.docker.enabled = True

# set Docker base image to the default CPU-based image
run_config.environment.docker.base_image = DEFAULT_CPU_IMAGE

# use conda_dependencies.yml to create a conda environment in the Docker image for execution
run_config.environment.python.user_managed_dependencies = False

# specify CondaDependencies obj
run_config.environment.python.conda_dependencies = CondaDependencies.create(conda_packages=['scikit-learn'],
                                                                           pip_packages=['debugpy', 'azureml-sdk==<SDK-VERSION>'])

Na seção Configurar scripts Python, novos argumentos foram adicionados aos scripts usados pelas etapas do pipeline de ML. O trecho de código a seguir demonstra como usar esses argumentos para habilitar a depuração para o componente e definir um tempo limite. Ele também demonstra como usar o ambiente criado anteriormente, definindo runconfig=run_config:

# Use RunConfig from a pipeline step
step1 = PythonScriptStep(name="train_step",
                         script_name="train.py",
                         arguments=['--remote_debug', '--remote_debug_connection_timeout', 300,'--remote_debug_client_ip','<VS-CODE-CLIENT-IP>','--remote_debug_port',5678],
                         compute_target=aml_compute,
                         source_directory=source_directory,
                         runconfig=run_config,
                         allow_reuse=False)

Quando o pipeline é executado, cada etapa cria uma execução filho. Se a depuração estiver habilitada, o script modificado registrará informações semelhantes ao seguinte texto na 70_driver_log.txt execução do filho:

Timeout for debug connection: 300
ip_address: 10.3.0.5

Salve o ip_address valor. Ele é usado na próxima seção.

Configurar o ambiente de desenvolvimento

1. Para instalar o debugpy em seu ambiente de desenvolvimento do VS Code, use o seguinte comando:

   python -m pip install --upgrade debugpy
   

   Para obter mais informações sobre como usar a depuração com o VS Code, consulte Depuração remota.

2. Para configurar o VS Code para se comunicar com a computação do Azure Machine Learning que está executando o depurador, crie uma nova configuração de depuração:

   1. No VS Code, selecione o menu Depurar e, em seguida, selecione Abrir configurações. Um arquivo chamado launch.json é aberto.

   2. No arquivo launch.json, localize a linha que contém "configurations": [e insira o seguinte texto depois dela. Altere a "host": "<IP-ADDRESS>" entrada para o endereço IP retornado em seus logs da seção anterior. Altere a "localRoot": "${workspaceFolder}/code/step" entrada para um diretório local que contém uma cópia do script que está sendo depurado:

      {
          "name": "Azure Machine Learning Compute: remote debug",
          "type": "python",
          "request": "attach",
          "port": 5678,
          "host": "<IP-ADDRESS>",
          "redirectOutput": true,
          "pathMappings": [
              {
                  "localRoot": "${workspaceFolder}/code/step1",
                  "remoteRoot": "."
              }
          ]
      }
      

      Importante

      Se já houver outras entradas na seção de configurações, adicione uma vírgula (,) após o código inserido.

      Gorjeta

      A prática recomendada, especialmente para pipelines, é manter os recursos para scripts em diretórios separados para que o código seja relevante apenas para cada uma das etapas. Neste exemplo, o valor de localRoot exemplo faz referência /code/step1.

      Se você estiver depurando vários scripts, em diretórios diferentes, crie uma seção de configuração separada para cada script.

   3. Salve o arquivo launch.json .

Conecte o depurador

1. Abra o VS Code e abra uma cópia local do script.

2. Defina pontos de interrupção onde você deseja que o script pare depois de anexado.

3. Enquanto o processo filho estiver executando o script e o Timeout for debug connection for exibido nos logs, use a tecla F5 ou selecione Depurar. Quando solicitado, selecione Azure Machine Learning Compute: configuração de depuração remota. Você também pode selecionar o ícone de depuração na barra lateral, a entrada de depuração remota do Azure Machine Learning: no menu suspenso Depurar e, em seguida, usar a seta verde para anexar o depurador.

   Neste ponto, o VS Code se conecta à depuração no nó de computação e para no ponto de interrupção definido anteriormente. Agora você pode percorrer o código enquanto ele é executado, visualizar variáveis, etc.

   Nota

   Se o log exibir uma entrada informando Debugger attached = False, o tempo limite expirou e o script continuou sem o depurador. Envie o pipeline novamente e conecte o depurador após a Timeout for debug connection mensagem e antes que o tempo limite expire.

Depurar e solucionar problemas de implantações

Em alguns casos, talvez seja necessário depurar interativamente o código Python contido na implantação do modelo. Por exemplo, se o script de entrada estiver falhando e o motivo não puder ser determinado pelo registro em log extra. Usando o VS Code e a depuração, você pode anexar ao código em execução dentro do contêiner do Docker.

As implantações de serviços Web locais exigem uma instalação funcional do Docker em seu sistema local. Para obter mais informações sobre como usar o Docker, consulte a Documentação do Docker. Ao trabalhar com instâncias de computação, o Docker já está instalado.

Configurar o ambiente de desenvolvimento

1. Para instalar o debugpy em seu ambiente de desenvolvimento local do VS Code, use o seguinte comando:

   python -m pip install --upgrade debugpy
   

   Para obter mais informações sobre como usar a depuração com o VS Code, consulte Depuração remota.

2. Para configurar o VS Code para se comunicar com a imagem do Docker, crie uma nova configuração de depuração:

   1. No VS Code, selecione o menu Depurar na extensão Executar e, em seguida, selecione Abrir configurações. Um arquivo chamado launch.json é aberto.

   2. No arquivo launch.json, localize o item "configurações" (a linha que contém "configurations": [) e insira o seguinte texto depois dele.

      {
          "name": "Azure Machine Learning Deployment: Docker Debug",
          "type": "python",
          "request": "attach",
          "connect": {
              "port": 5678,
              "host": "0.0.0.0",
          },
          "pathMappings": [
              {
                  "localRoot": "${workspaceFolder}",
                  "remoteRoot": "/var/azureml-app"
              }
          ]
      }
      

      Após a inserção, o arquivo launch.json deve ser semelhante ao seguinte:

      {
      // Use IntelliSense to learn about possible attributes.
      // Hover to view descriptions of existing attributes.
      // For more information, visit: https://go.microsoft.com/fwlink/linkid=830387
      "version": "0.2.0",
      "configurations": [
          {
              "name": "Python: Current File",
              "type": "python",
              "request": "launch",
              "program": "${file}",
              "console": "integratedTerminal"
          },
          {
              "name": "Azure Machine Learning Deployment: Docker Debug",
              "type": "python",
              "request": "attach",
              "connect": {
                  "port": 5678,
                  "host": "0.0.0.0"
                  },
              "pathMappings": [
                  {
                      "localRoot": "${workspaceFolder}",
                      "remoteRoot": "/var/azureml-app"
                  }
              ]
          }
          ]
      }
      

      Importante

      Se já houver outras entradas na seção de configurações, adicione uma vírgula ( , ) após o código inserido.

      Esta seção é anexada ao contêiner do Docker usando a porta 5678.

   3. Salve o arquivo launch.json .

Criar uma imagem que inclua depuração

1. Modifique o ambiente conda para sua implantação para que ele inclua depuração. O exemplo a seguir demonstra como adicioná-lo usando o pip_packages parâmetro:

   from azureml.core.conda_dependencies import CondaDependencies 
   
   
   # Usually a good idea to choose specific version numbers
   # so training is made on same packages as scoring
   myenv = CondaDependencies.create(conda_packages=['numpy==1.15.4',
                               'scikit-learn==0.19.1', 'pandas==0.23.4'],
                                pip_packages = ['azureml-defaults==1.0.83', 'debugpy'])
   
   with open("myenv.yml","w") as f:
       f.write(myenv.serialize_to_string())
   

2. Para iniciar a depuração e aguardar uma conexão quando o serviço for iniciado, adicione o seguinte à parte superior do score.py arquivo:

   import debugpy
   # Allows other computers to attach to debugpy on this IP address and port.
   debugpy.listen(('0.0.0.0', 5678))
   # Wait 30 seconds for a debugger to attach. If none attaches, the script continues as normal.
   debugpy.wait_for_client()
   print("Debugger attached...")
   

3. Crie uma imagem com base na definição do ambiente e puxe a imagem para o registro local.

   Nota

   Este exemplo pressupõe que ws aponta para seu espaço de trabalho do Azure Machine Learning e esse model é o modelo que está sendo implantado. O myenv.yml arquivo contém as dependências conda criadas na etapa 1.

   from azureml.core.conda_dependencies import CondaDependencies
   from azureml.core.model import InferenceConfig
   from azureml.core.environment import Environment
   
   
   myenv = Environment.from_conda_specification(name="env", file_path="myenv.yml")
   myenv.docker.base_image = None
   myenv.docker.base_dockerfile = "FROM mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:latest"
   inference_config = InferenceConfig(entry_script="score.py", environment=myenv)
   package = Model.package(ws, [model], inference_config)
   package.wait_for_creation(show_output=True)  # Or show_output=False to hide the Docker build logs.
   package.pull()
   

   Uma vez que a imagem tenha sido criada e baixada (esse processo pode levar mais de 10 minutos), o caminho da imagem (inclui repositório, nome e tag, que neste caso também é seu resumo) é finalmente exibido em uma mensagem semelhante à seguinte:

   Status: Downloaded newer image for myregistry.azurecr.io/package@sha256:<image-digest>
   

4. Para facilitar o trabalho com a imagem localmente, você pode usar o comando a seguir para adicionar uma tag para essa imagem. Substitua myimagepath no comando a seguir pelo valor de local da etapa anterior.

   docker tag myimagepath debug:1
   

   Para o restante das etapas, você pode se referir à imagem local como debug:1 em vez do valor do caminho de imagem completo.

Depurar o serviço

1. Para iniciar um contêiner do Docker usando a imagem, use o seguinte comando:

   docker run -it --name debug -p 8000:5001 -p 5678:5678 -v <my_local_path_to_score.py>:/var/azureml-app/score.py debug:1 /bin/bash
   

   Este comando anexa seu score.py local ao do contêiner. Portanto, todas as alterações feitas no editor são refletidas automaticamente no contêiner

2. Para uma melhor experiência, você pode entrar no contêiner com uma nova interface VS Code. Selecione a Docker extensão na barra lateral do VS Code, encontre seu contêiner local criado, nesta documentação seu debug:1. Clique com o botão direito do mouse neste contêiner e selecione "Attach Visual Studio Code", em seguida, uma nova interface VS Code será aberta automaticamente e essa interface mostra o interior do contêiner criado.

   

3. Dentro do contêiner, execute o seguinte comando no shell

   runsvdir /var/runit
   

   Então você pode ver a seguinte saída no shell dentro do seu contêiner:

   

4. Para anexar o VS Code à depuração dentro do contêiner, abra o VS Code e use a tecla F5 ou selecione Depurar. Quando solicitado, selecione Implantação do Azure Machine Learning: configuração de depuração do Docker. Você também pode selecionar o ícone Executar extensão na barra lateral, a entrada Implantação do Azure Machine Learning: Depuração do Docker no menu suspenso Depurar e, em seguida, usar a seta verde para anexar o depurador.

   

   Depois de selecionar a seta verde e anexar o depurador, na interface do contêiner VS Code você pode ver algumas novas informações:

   

   Além disso, na sua interface principal do VS Code, o que você pode ver é o seguinte:

   

E agora, o local score.py que está anexado ao contêiner já parou nos pontos de interrupção onde você definiu. Neste ponto, o VS Code se conecta à depuração dentro do contêiner do Docker e para o contêiner do Docker no ponto de interrupção definido anteriormente. Agora você pode percorrer o código enquanto ele é executado, visualizar variáveis, etc.

Para obter mais informações sobre como usar o VS Code para depurar o Python, consulte Depurar seu código Python.

Parar o contentor

Para parar o contêiner, use o seguinte comando:

docker stop debug

Próximos passos

Agora que você configurou o VS Code Remote, pode usar uma instância de computação como computação remota do VS Code para depurar seu código interativamente.

Saiba mais sobre a resolução de problemas:

• Implantação de modelo local
• Implantação remota de modelo
• Pipelines de aprendizado de máquina
• ParallelRunStep