Depurar pontos de extremidade online localmente no Visual Studio Code

Artigo
04/07/2024

APLICA-SE A:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

Saiba como usar o depurador de código do Microsoft Visual Studio para testar e depurar pontos de extremidade online localmente antes de implantá-los no Azure.

Os pontos de extremidade locais do Aprendizado de Máquina do Azure ajudam você a testar e depurar seu script de pontuação, configuração de ambiente, configuração de código e modelo de aprendizado de máquina localmente.

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.

Depurar pontos de extremidade localmente antes de implantá-los na nuvem pode ajudá-lo a detetar erros em seu código e configuração anteriormente. Você tem diferentes opções para depurar pontos de extremidade localmente com o Visual Studio Code.

Servidor HTTP de inferência do Azure Machine Learning
Ponto final local

Este guia se concentra em pontos de extremidade locais.

A tabela a seguir fornece uma visão geral dos cenários para ajudá-lo a escolher o que funciona melhor para você.

Cenário	Servidor HTTP de inferência	Ponto final local
Atualize o ambiente Python local, sem a reconstrução da imagem do Docker	Sim	No
Atualizar script de pontuação	Sim	Sim
Atualizar configurações de implantação (implantação, ambiente, código, modelo)	Não	Sim
Integração do depurador de código do Visual Studio	Sim	Sim

Este guia pressupõe que você tenha os seguintes itens instalados localmente no seu PC.

Para obter mais informações, consulte o guia sobre como preparar seu sistema para implantar pontos de extremidade online.

Os exemplos neste artigo são baseados em exemplos de código contidos no repositório GitHub azureml-examples . Para executar os comandos localmente sem ter que copiar/colar YAML e outros arquivos, clone o repositório e altere os diretórios para azureml-examples/cli:

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

Se você ainda não definiu os padrões para a CLI do Azure, salve suas configurações padrão. Para evitar passar os valores da sua assinatura, espaço de trabalho e grupo de recursos várias vezes, use os comandos a seguir. Substitua os seguintes parâmetros por valores para sua configuração específica:

Substitua <subscription> pelo seu ID da subscrição do Azure.
Substitua <workspace> pelo nome do espaço de trabalho do Azure Machine Learning.
Substitua <resource-group> pelo grupo de recursos do Azure que contém seu espaço de trabalho.
Substitua <location> pela região do Azure que contém seu espaço de trabalho.

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

Gorjeta

Você pode ver quais são seus padrões atuais usando o az configure -l comando.

APLICA-SE A: Python SDK azure-ai-ml v2 (atual)

Este guia pressupõe que você tenha os seguintes itens instalados localmente no seu PC.

Para obter mais informações, consulte o guia sobre como preparar seu sistema para implantar pontos de extremidade online.

Os exemplos neste artigo podem ser encontrados no bloco de anotações Jupyter chamado Debug online endpoints localmente no Visual Studio Code dentro do repositório azureml-examples . Para executar o código localmente, clone o repositório e altere os diretórios para o diretório pai do bloco de anotações sdk/endpoints/online/managed.

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples
cd sdk/python/endpoints/online/managed

Abra o bloco de anotações Jupyter e importe os módulos necessários:

from azure.ai.ml import MLClient
from azure.ai.ml.entities import (
    ManagedOnlineEndpoint,
    ManagedOnlineDeployment,
    Model,
    CodeConfiguration,
    Environment,
)
from azure.identity import DefaultAzureCredential

Configure variáveis para o espaço de trabalho e o ponto de extremidade:

subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace_name = "<AML_WORKSPACE_NAME>"

endpoint_name = "<ENDPOINT_NAME>"

Lançar contêiner de desenvolvimento

CLI do Azure
Python

Os pontos de extremidade locais do Aprendizado de Máquina do Azure usam contêineres de desenvolvimento do Docker e do Visual Studio Code (contêineres de desenvolvimento) para criar e configurar um ambiente de depuração local. Com contêineres de desenvolvimento, você pode aproveitar os recursos do Visual Studio Code de dentro de um contêiner do Docker. Para obter mais informações sobre contêineres de desenvolvimento, consulte Criar um contêiner de desenvolvimento.

Para depurar pontos de extremidade online localmente no Visual Studio Code, use o --vscode-debug sinalizador ao criar ou atualizar a implantação online do Azure Machine Learning. O comando a seguir usa um exemplo de implantação do repositório de exemplos:

az ml online-deployment create --file endpoints/online/managed/sample/blue-deployment.yml --local --vscode-debug

Importante

No Subsistema Windows para Linux (WSL), você precisará atualizar sua variável de ambiente PATH para incluir o caminho para o executável do Visual Studio Code ou usar a interoperabilidade WSL. Para obter mais informações, consulte Interoperabilidade do Windows com Linux.

Uma imagem do Docker é criada localmente. Qualquer configuração de ambiente ou erros de arquivo de modelo são apresentados nesta etapa do processo.

Nota

A primeira vez que você inicia um contêiner de desenvolvimento novo ou atualizado, isso pode levar vários minutos.

Depois que a imagem for compilada com êxito, seu contêiner de desenvolvimento será aberto em uma janela do Visual Studio Code.

Você usará algumas extensões do Visual Studio Code para depurar suas implantações no contêiner de desenvolvimento. O Azure Machine Learning instala automaticamente essas extensões em seu contêiner de desenvolvimento.

Depuração de inferência
Pylance
Jupyter
Python

Importante

Antes de iniciar sua sessão de depuração, certifique-se de que as extensões de código do Visual Studio terminaram de instalar em seu contêiner de desenvolvimento.

Obtenha um identificador para o espaço de trabalho:

credential = DefaultAzureCredential()
ml_client = MLClient(
    credential,
    subscription_id=subscription_id,
    resource_group_name=resource_group,
    workspace_name=workspace_name,
)

Para depurar pontos de extremidade online localmente no Visual Studio Code, defina os sinalizadores e local ao criar ou atualizar uma implantação online do vscode-debug Azure Machine Learning. O código a seguir espelha um exemplo de implantação do repositório de exemplos:

deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=endpoint_name,
    model=Model(path="../model-1/model/sklearn_regression_model.pkl"),
    code_configuration=CodeConfiguration(
        code="../model-1/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-1/environment/conda.yaml",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    ),
    instance_type="Standard_DS3_v2",
    instance_count=1,
)

deployment = ml_client.online_deployments.begin_create_or_update(
    deployment, local=True, vscode_debug=True
).result()

Importante

Uma imagem do Docker é criada localmente. Qualquer configuração de ambiente ou erros de arquivo de modelo são apresentados nesta etapa do processo.

Nota

Pode levar vários minutos para iniciar um contêiner de desenvolvimento novo ou atualizado pela primeira vez.

Depois que a imagem for compilada com êxito, seu contêiner de desenvolvimento será aberto em uma janela do Visual Studio Code.

Depuração de inferência
Pylance
Jupyter
Python

Importante

Antes de iniciar sua sessão de depuração, certifique-se de que as extensões de código do Visual Studio terminaram de instalar em seu contêiner de desenvolvimento.

Iniciar sessão de depuração

Depois que seu ambiente estiver configurado, use o depurador de código do Visual Studio para testar e depurar sua implantação localmente.

Abra o script de pontuação no Visual Studio Code.

Gorjeta

O script score.py usado pelo ponto de extremidade implantado anteriormente está localizado em azureml-samples/cli/endpoints/online/managed/sample/score.py no repositório clonado. No entanto, as etapas neste guia funcionam com qualquer script de pontuação.
Defina um ponto de interrupção em qualquer lugar do seu script de pontuação.
- Para depurar o comportamento de inicialização, coloque o(s) seu(s) ponto(s) de interrupção dentro da init função.
- Para depurar o comportamento de pontuação, coloque o(s) seu(s) ponto(s) de interrupção dentro da run função.
Selecione o modo de exibição Trabalho de código do Visual Studio.
No menu suspenso Executar e Depurar, selecione AzureML: Depurar Ponto de Extremidade Local para começar a depurar seu ponto de extremidade localmente.

Na seção Pontos de interrupção do modo de exibição Executar, verifique se:
- Exceções geradas está desmarcada
- Exceções não capturadas é verificada
Selecione o ícone de reprodução ao lado da lista suspensa Executar e Depurar para iniciar sua sessão de depuração.

Neste ponto, todos os pontos de interrupção em sua init função são detetados. Use as ações de depuração para percorrer seu código. Para obter mais informações sobre ações de depuração, consulte o guia de ações de depuração.

Para obter mais informações sobre o depurador de código do Visual Studio, consulte Depuração.

Depurar seu endpoint

CLI do Azure
Python

Agora que seu aplicativo está sendo executado no depurador, tente fazer uma previsão para depurar seu script de pontuação.

Use o ml comando extension invoke para fazer uma solicitação ao seu ponto de extremidade local.

az ml online-endpoint invoke --name <ENDPOINT-NAME> --request-file <REQUEST-FILE> --local

Nesse caso, <REQUEST-FILE> é um arquivo JSON que contém amostras de dados de entrada para o modelo fazer previsões semelhantes ao seguinte JSON:

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

Gorjeta

O URI de pontuação é o endereço onde seu ponto de extremidade escuta as solicitações. Use a ml extensão para obter o URI de pontuação.

az ml online-endpoint show --name <ENDPOINT-NAME> --local

O resultado deve ser algo semelhante ao seguinte:

{
 "auth_mode": "aml_token",
 "location": "local",
 "name": "my-new-endpoint",
 "properties": {},
 "provisioning_state": "Succeeded",
 "scoring_uri": "http://localhost:5001/score",
 "tags": {},
 "traffic": {},
 "type": "online"
}

O URI de pontuação pode ser encontrado na scoring_uri propriedade.

Neste ponto, todos os pontos de interrupção em sua run função são detetados. Use as ações de depuração para percorrer seu código. Para obter mais informações sobre ações de depuração, consulte o guia de ações de depuração.

Agora que seu aplicativo está sendo executado no depurador, tente fazer uma previsão para depurar seu script de pontuação.

Use o invoke método em seu MLClient objeto para fazer uma solicitação ao seu ponto de extremidade local.

endpoint = ml_client.online_endpoints.get(name=endpoint_name, local=True)

request_file_path = "../model-1/sample-request.json"

ml_client.online_endpoints.invoke(endpoint_name, request_file_path, local=True)

Nesse caso, <REQUEST-FILE> é um arquivo JSON que contém amostras de dados de entrada para o modelo fazer previsões semelhantes ao seguinte JSON:

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

Gorjeta

O URI de pontuação é o endereço onde seu ponto de extremidade escuta as solicitações. O as_dict método de objetos de ponto de extremidade retorna informações semelhantes às show da CLI do Azure. O objeto endpoint pode ser obtido através do .get.

print(endpoint)

O resultado deve ser algo semelhante ao seguinte:

{
 "auth_mode": "aml_token",
 "location": "local",
 "name": "my-new-endpoint",
 "properties": {},
 "provisioning_state": "Succeeded",
 "scoring_uri": "http://localhost:5001/score",
 "tags": {},
 "traffic": {},
 "type": "online"
}

O URI de scoring_uri pontuação pode ser encontrado na chave.

Editar seu ponto de extremidade

CLI do Azure
Python

À medida que você depura e soluciona problemas em seu aplicativo, há cenários em que você precisa atualizar seu script de pontuação e configurações.

Para aplicar alterações ao seu código:

Atualize o seu código.
Reinicie a sessão de depuração usando o Developer: Reload Window comando na paleta de comandos. Para obter mais informações, consulte a documentação da paleta de comandos.

Nota

Como o diretório que contém seu código e ativos de ponto de extremidade é montado no contêiner de desenvolvimento, todas as alterações feitas no contêiner de desenvolvimento são sincronizadas com o sistema de arquivos local.

Para alterações mais extensas envolvendo atualizações no ambiente e na configuração do ponto de extremidade, use o ml comando extension update . Isso aciona uma reconstrução completa da imagem com suas alterações.

az ml online-deployment update --file <DEPLOYMENT-YAML-SPECIFICATION-FILE> --local --vscode-debug

Depois que a imagem atualizada for criada e seu contêiner de desenvolvimento for iniciado, use o depurador de código do Visual Studio para testar e solucionar problemas do ponto de extremidade atualizado.

À medida que você depura e soluciona problemas em seu aplicativo, há cenários em que você precisa atualizar seu script de pontuação e configurações.

Para aplicar alterações ao seu código:

Atualize o seu código.
Reinicie a sessão de depuração usando o Developer: Reload Window comando na paleta de comandos. Para obter mais informações, consulte a documentação da paleta de comandos.

Nota

Para alterações mais extensas envolvendo atualizações no seu ambiente e configuração de ponto final, use o online_deployments.update módulo/método do .MLClient Isso aciona uma reconstrução completa da imagem com suas alterações.

new_deployment = ManagedOnlineDeployment(
    name="green",
    endpoint_name=endpoint_name,
    model=Model(path="../model-2/model/sklearn_regression_model.pkl"),
    code_configuration=CodeConfiguration(
        code="../model-2/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-2/environment/conda.yaml",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    ),
    instance_type="Standard_DS3_v2",
    instance_count=2,
)

deployment = ml_client.online_deployments.begin_create_or_update(
    new_deployment, local=True, vscode_debug=True
).result()

Depurar pontos de extremidade online localmente no Visual Studio Code

Pré-requisitos

Lançar contêiner de desenvolvimento

Iniciar sessão de depuração

Depurar seu endpoint

Editar seu ponto de extremidade

Conteúdos relacionados

Recursos adicionais