Depuração interativa com o Visual Studio Code

  • Artigo

APLICA-SE A:Python SDK azureml v1

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

Executar e depurar experimentações localmente

Utilize a extensão do Azure Machine Learning para validar, executar e depurar as suas experimentações de machine learning antes de as submeter para a cloud.

Pré-requisitos

Depurar experimentação localmente

Importante

Antes de executar a experimentação localmente, certifique-se de que:

  • O Docker está em execução.
  • A azureML.CLI Compatibility Mode definição no Visual Studio Code está definida 1.0 como especificada nos pré-requisitos

  1. No VS Code, abra a vista de extensão do Azure Machine Learning.

  2. Expanda o nó de subscrição que contém a área de trabalho. Se ainda não tiver uma, pode criar uma área de trabalho do Azure Machine Learning com a extensão.

  3. Expanda o nó da área de trabalho.

  4. Clique com o botão direito do rato no nó Experimentações e selecione Criar experimentação. Quando o pedido for apresentado, forneça um nome para a sua experimentação.

  5. Expanda o nó Experimentações , clique com o botão direito do rato na experimentação que pretende executar e selecione Executar Experimentação.

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

  7. Utilização pela primeira vez apenas no Windows. Quando lhe for pedido para permitir a Partilha de Ficheiros, selecione Sim. Quando ativa a partilha de ficheiros, permite ao Docker montar o diretório que contém o script no contentor. Além disso, também permite ao Docker armazenar os registos e saídas da sua execução num diretório temporário no seu sistema.

  8. Selecione Sim para depurar a experimentação. Caso contrário, selecione Não. Selecionar não irá executar a experimentação localmente sem anexar ao depurador.

  9. Selecione Criar nova Configuração de Execução para criar a configuração de execução. A configuração de execução define o script que pretende executar, as dependências e os conjuntos de dados utilizados. Em alternativa, se já tiver uma, selecione-a na lista pendente.

    1. Escolha o seu ambiente. Pode escolher entre qualquer um dos Azure Machine Learning organizados ou criar o seu próprio.
    2. Indique o nome do script que pretende executar. O caminho é relativo ao diretório aberto no VS Code.
    3. Escolha se quer ou não utilizar um conjunto de dados do Azure Machine Learning. Pode criar conjuntos de dados do Azure Machine Learning com a extensão.
    4. A depuração é necessária para anexar o depurador ao contentor que está a executar a experimentação. Para adicionar a depuração como uma dependência, selecione Adicionar Depuração. Caso contrário, selecione Ignorar. Não adicionar a depuração como uma dependência executa a experimentação sem anexar ao depurador.
    5. É aberto um ficheiro de configuração que contém as definições de configuração de execução no editor. Se estiver satisfeito com as definições, selecione Submeter experimentação. Em alternativa, abra a paleta de comandos (Ver > Paleta de Comandos) a partir da barra de menus e introduza o AzureML: Submit experiment comando na caixa de texto.

  10. Assim que a experimentação for submetida, é criada uma imagem do Docker que contém o script e as configurações especificadas na configuração de execução.

    Quando o processo de compilação de imagens do Docker é iniciado, os conteúdos do fluxo de 60_control_log.txt ficheiros são transmitidos para a consola de saída no VS Code.

    Nota

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

  11. Assim que a imagem for criada, é apresentado um pedido para iniciar o depurador. Defina os pontos de interrupção no script e selecione Iniciar depurador quando estiver pronto para começar a depurar. Ao fazê-lo, anexa o depurador do VS Code ao contentor que está a executar a experimentação. Em alternativa, na extensão do Azure Machine Learning, paire o cursor sobre o nó da execução atual e selecione o ícone de reprodução para iniciar o depurador.

    Importante

    Não pode ter várias sessões de depuração para uma única experimentação. No entanto, pode depurar duas ou mais experimentações com várias instâncias do VS Code.

Neste momento, deverá conseguir avançar e depurar o código com o VS Code.

Se, em algum momento, pretender cancelar a execução, clique com o botão direito do rato no nó de execução e selecione Cancelar execução.

À semelhança das execuções de experimentação remotas, pode expandir o nó de execução para inspecionar os registos e saídas.

Dica

As imagens do Docker que utilizam as mesmas dependências definidas no seu ambiente são reutilizadas entre execuções. No entanto, se executar uma experimentação com um ambiente novo ou diferente, será criada uma nova imagem. Uma vez que estas imagens são guardadas no seu armazenamento local, é recomendado remover imagens antigas ou não utilizadas do Docker. Para remover imagens do seu sistema, utilize a CLI do Docker ou a extensão do Docker do VS Code.

Depurar e resolver problemas de pipelines de machine learning

Em determinados casos, poderá ter de depurar interativamente o código do Python utilizado no pipeline do ML. Ao utilizar o VS Code e a depuração, pode anexar ao código à medida que é executado no ambiente de preparação.

Pré-requisitos

  • Uma área de trabalho do Azure Machine Learning configurada para utilizar um Rede Virtual do Azure.

  • Um pipeline do Azure Machine Learning que utiliza scripts python como parte dos passos do pipeline. Por exemplo, um PythonScriptStep.

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

  • Um ambiente de desenvolvimento que se encontra 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 Bloco de Notas na rede virtual
    • Uma máquina cliente que tenha conectividade de rede privada à rede virtual, seja por VPN ou através do ExpressRoute.

Para obter mais informações sobre como utilizar um Rede Virtual do Azure com o Azure Machine Learning, veja Descrição geral do isolamento e privacidade da rede virtual.

Dica

Embora possa trabalhar com recursos do Azure Machine Learning que não estão por detrás de uma rede virtual, recomenda-se a utilização de uma rede virtual.

Como funciona

Os passos do pipeline de ML executam scripts python. Estes scripts são modificados para efetuar as seguintes ações:

  1. Registe o endereço IP do anfitrião no qual está a ser executado. Utilize o endereço IP para ligar o depurador ao script.

  2. Inicie o componente de depuração de depuração e aguarde que um depurador se ligue.

  3. A partir do seu ambiente de desenvolvimento, monitoriza os registos criados pelo processo de preparação para encontrar o endereço IP onde o script está em execução.

  4. Diga ao VS Code o endereço IP ao qual ligar o depurador através de um launch.json ficheiro.

  5. Pode anexar o depurador e percorrer interativamente o script.

Configurar scripts python

Para ativar a depuração, faça as seguintes alterações aos scripts python utilizados pelos passos no 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. Estes argumentos permitem-lhe ativar o depurador conforme necessário e definir 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. Estas instruções carregam o contexto de execução atual para que possa registar o endereço IP do nó no qual o código está a ser executado:

    global run
run = Run.get_context()

  4. Adicione uma instrução if que inicia a depuração e aguarda a anexação de um depurador. Se nenhum depurador se anexar antes do tempo limite, o script continua normalmente. Certifique-se de que substitui os HOST valores e PORT é a listen função pela sua.

    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 de Python seguinte mostra um ficheiro 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 o 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 está a utilizar. O fragmento de código seguinte 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 secção Configurar scripts python , foram adicionados novos argumentos aos scripts utilizados pelos passos do pipeline de ML. O fragmento de código seguinte demonstra como utilizar estes argumentos para ativar a depuração do componente e definir um tempo limite. Também demonstra como utilizar o ambiente criado anteriormente ao definir 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 passo cria uma execução subordinada. Se a depuração estiver ativada, o script modificado regista informações semelhantes ao seguinte texto na 70_driver_log.txt execução subordinada:

Timeout for debug connection: 300
ip_address: 10.3.0.5

Guarde o ip_address valor. É utilizado na secção seguinte.

Dica

Também pode encontrar o endereço IP dos registos de execução da execução subordinada para este passo de pipeline. Para obter mais informações sobre como ver estas informações, veja Monitorizar as execuções e as métricas da experimentação do Azure Machine Learning.

Configurar o ambiente de desenvolvimento

  1. Para instalar a depuração no seu ambiente de desenvolvimento do VS Code, utilize o seguinte comando:

    python -m pip install --upgrade debugpy

    Para obter mais informações sobre como utilizar a depuração com o VS Code, veja Depuração Remota.

  2. Para configurar o VS Code para comunicar com a computação do Azure Machine Learning que está a executar 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. É aberto um ficheiro com o nome launch.json .

    2. No ficheiro launch.json , localize a linha que contém e insira "configurations": [o seguinte texto a seguir. Altere a "host": "<IP-ADDRESS>" entrada para o endereço IP devolvido nos registos da secção anterior. Altere a "localRoot": "${workspaceFolder}/code/step" entrada para um diretório local que contenha uma cópia do script que está a ser 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á existirem outras entradas na secção de configurações, adicione uma vírgula (,) após o código que inseriu.

      Dica

      A melhor prática, especialmente para pipelines, é manter os recursos para scripts em diretórios separados para que o código seja relevante apenas para cada um dos passos. Neste exemplo, o localRoot valor de exemplo referencia /code/step1.

      Se estiver a depurar vários scripts, em diretórios diferentes, crie uma secção de configuração separada para cada script.

    3. Guarde o ficheiro launch.json .

Ligar o depurador

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

  2. Defina pontos de interrupção onde pretende que o script pare depois de anexar.

  3. Enquanto o processo subordinado está a executar o script e o Timeout for debug connection é apresentado nos registos, utilize a tecla F5 ou selecione Depurar. Quando lhe for pedido, selecione a Computação do Azure Machine Learning: configuração de depuração remota . Também pode selecionar o ícone de depuração na barra lateral, a entrada Azure Machine Learning: depuração remota no menu pendente Depurar e, em seguida, utilizar a seta verde para anexar o depurador.

    Neste momento, o VS Code liga-se à depuração no nó de computação e para no ponto de interrupção que definiu anteriormente. Agora pode percorrer o código à medida que é executado, ver variáveis, etc.

    Nota

    Se o registo apresentar uma entrada a indicar Debugger attached = False, o tempo limite expirou e o script continuou sem o depurador. Submeta o pipeline novamente e ligue o depurador após a Timeout for debug connection mensagem e antes que o tempo limite expire.

Depurar e resolver problemas de implementações

Em alguns casos, poderá ter de depurar interativamente o código Python contido na implementação do modelo. Por exemplo, se o script de entrada estiver a falhar e o motivo não puder ser determinado pelo registo extra. Ao utilizar o VS Code e a depuração, pode anexar ao código em execução no contentor do Docker.

Dica

Se estiver a utilizar pontos finais e implementações online geridos localmente, veja Depurar pontos finais online geridos localmente no Visual Studio Code (pré-visualização).

Importante

Este método de depuração não funciona ao utilizar Model.deploy() e LocalWebservice.deploy_configuration implementar um modelo localmente. Em vez disso, tem de criar uma imagem com o método Model.package( ).

As implementações de serviços Web locais requerem uma instalação funcional do Docker no seu sistema local. Para obter mais informações sobre como utilizar 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 a depuração no ambiente de desenvolvimento do VS Code local, utilize o seguinte comando:

    python -m pip install --upgrade debugpy

    Para obter mais informações sobre como utilizar a depuração com o VS Code, veja Depuração Remota.

  2. Para configurar o VS Code para 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. É aberto um ficheiro com o nome launch.json .

    2. No ficheiro launch.json , localize o item "configurations" (a linha que contém ) e insira "configurations": [o seguinte texto após o mesmo.

      {
    "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 ficheiro 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á existirem outras entradas na secção de configurações, adicione uma vírgula ( , ) após o código que inseriu.

      Esta secção anexa ao contentor do Docker com a porta 5678.

    3. Guarde o ficheiro launch.json .

Criar uma imagem que inclua depuração

  1. Modifique o ambiente conda para a sua implementação para que inclua depuração. O exemplo seguinte demonstra como adicioná-lo com 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 ligação quando o serviço for iniciado, adicione o seguinte à parte superior do ficheiro score.py :

    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 de ambiente e puxe a imagem para o registo local.

    Nota

    Este exemplo pressupõe que ws aponta para a sua área de trabalho do Azure Machine Learning e que é esse o modelo que model está a ser implementado. O myenv.yml ficheiro contém as dependências conda criadas no passo 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()

    Depois de a imagem ter sido criada e transferida (este processo pode demorar mais de 10 minutos), o caminho da imagem (inclui o repositório, o nome e a etiqueta, que neste caso também é o seu resumo) é finalmente apresentado numa mensagem semelhante à seguinte:

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

  4. Para facilitar o trabalho com a imagem localmente, pode utilizar o seguinte comando para adicionar uma etiqueta para esta imagem. Substitua myimagepath no seguinte comando pelo valor de localização do passo anterior.

    docker tag myimagepath debug:1

    Para os restantes passos, pode referir-se à imagem local como debug:1 em vez do valor completo do caminho da imagem.

Depurar o serviço

Dica

Se definir um tempo limite para a ligação de depuração no ficheiro, tem de ligar o score.py VS Code à sessão de depuração antes de o tempo limite expirar. Inicie o VS Code, abra a cópia local de , defina um ponto de score.pyinterrupção e prepare-o antes de utilizar os passos nesta secção.

Para obter mais informações sobre como depurar e definir pontos de interrupção, veja Depuração.

  1. Para iniciar um contentor do Docker com a imagem, utilize 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 o localmente score.py ao que se encontra no contentor. Por conseguinte, todas as alterações efetuadas no editor são refletidas automaticamente no contentor

  2. Para uma melhor experiência, pode aceder ao contentor com uma nova interface do VS Code. Selecione a Docker extensão na barra lateral do VS Code e localize o contentor local criado. Nesta documentação debug:1, é . Clique com o botão direito do rato neste contentor e selecione "Attach Visual Studio Code"e, em seguida, será aberta automaticamente uma nova interface do VS Code e esta interface mostra o interior do contentor criado.

    A interface do VS Code do contentor

  3. Dentro do contentor, execute o seguinte comando na shell

    runsvdir /var/runit

    Em seguida, pode ver o seguinte resultado na shell dentro do contentor:

    O resultado da consola de execução do contentor

  4. Para anexar o VS Code à depuração no contentor, abra o VS Code e utilize a chave F5 ou selecione Depurar. Quando lhe for pedido, selecione a Implementação do Azure Machine Learning: Configuração de Depuração do Docker . Também pode selecionar o ícone Depurar extensão na barra lateral, a entrada Implementação do Azure Machine Learning: Depuração do Docker no menu pendente Depurar e, em seguida, utilizar a seta verde para anexar o depurador.

    O ícone de depuração, o botão iniciar a depuração e o seletor de configuração

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

    As informações anexadas do depurador de contentor

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

    O ponto de interrupção do VS Code no score.py

E agora, o local score.py que está anexado ao contentor já parou nos pontos de interrupção onde definiu. Neste momento, o VS Code liga-se à depuração no contentor do Docker e para o contentor do Docker no ponto de interrupção que definiu anteriormente. Agora pode percorrer o código à medida que é executado, ver variáveis, etc.

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

Parar o contentor

Para parar o contentor, utilize o seguinte comando:

docker stop debug

Passos seguintes

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

Saiba mais sobre a resolução de problemas: