Depuração interativa com o Visual Studio Code
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
Extensão vs Code do Azure Machine Learning (pré-visualização). Para obter mais informações, veja Configurar a extensão do VS Code do Azure Machine Learning.
Importante
Por predefinição, a extensão do VS Code do Azure Machine Learning utiliza a CLI (v2). As instruções neste guia utilizam a CLI 1.0. Para mudar para a CLI 1.0, defina a
azureML.CLI Compatibility Mode
definição no Visual Studio Code como1.0
. Para obter mais informações sobre como modificar as suas definições no Visual Studio Code, veja a documentação das definições do utilizador e da área 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 Desktop para Mac e Windows
Docker Engine para Linux.
Nota
No Windows, certifique-se de que configura o Docker para utilizar contentores linux.
Dica
Para o Windows, embora não seja necessário, é altamente recomendado utilizar o Docker com o Subsistema Windows para Linux (WSL) 2.
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á definida1.0
como especificada nos pré-requisitos
No VS Code, abra a vista de extensão do Azure Machine Learning.
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.
Expanda o nó da área de trabalho.
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.
Expanda o nó Experimentações , clique com o botão direito do rato na experimentação que pretende executar e selecione Executar Experimentação.
Na lista de opções, selecione Localmente.
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.
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.
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.
- Escolha o seu ambiente. Pode escolher entre qualquer um dos Azure Machine Learning organizados ou criar o seu próprio.
- Indique o nome do script que pretende executar. O caminho é relativo ao diretório aberto no VS Code.
- 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.
- 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.
- É 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.
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.
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:
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.
Inicie o componente de depuração de depuração e aguarde que um depurador se ligue.
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.
Diga ao VS Code o endereço IP ao qual ligar o depurador através de um
launch.json
ficheiro.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:
Adicione as seguintes instruções de importação:
import argparse import os import debugpy import socket from azureml.core import Run
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')
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()
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 osHOST
valores ePORT
é alisten
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
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.
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:
No VS Code, selecione o menu Depurar e, em seguida, selecione Abrir configurações. É aberto um ficheiro com o nome launch.json .
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.
Guarde o ficheiro launch.json .
Ligar o depurador
Abra o VS Code e abra uma cópia local do script.
Defina pontos de interrupção onde pretende que o script pare depois de anexar.
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 aTimeout 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
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.
Para configurar o VS Code para comunicar com a imagem do Docker, crie uma nova configuração de depuração:
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 .
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.
Guarde o ficheiro launch.json .
Criar uma imagem que inclua depuração
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())
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...")
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 quemodel
está a ser implementado. Omyenv.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>
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.py
interrupçã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.
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 contentorPara 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çãodebug: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.Dentro do contentor, execute o seguinte comando na shell
runsvdir /var/runit
Em seguida, pode ver o seguinte resultado na shell dentro do contentor:
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.
Depois de selecionar a seta verde e anexar o depurador, na interface do VS Code do contentor, pode ver algumas informações novas:
Além disso, na interface principal do VS Code, o que pode ver é o seguinte:
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: