Depurar pontos de extremidade online localmente Visual Studio Code

Artigo
04/15/2024

APLICA-SE A:Extensão de ML da CLI do Azure v2 (atual)SDK do Python azure-ai-ml v2 (atual)

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

Pontos de extremidade locais do Azure Machine Learning ajudam você a testar e depurar o script de pontuação, a configuração do ambiente, a configuração de código e o modelo de machine learning localmente.

Importante

Esse recurso está atualmente em visualização pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos.

Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

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

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

Este guia se concentra nos pontos de extremidade locais.

A tabela a seguir fornece uma visão geral dos cenários para ajudar você a escolher o mais adequado.

Cenário	Servidor HTTP de inferência	Ponto de extremidade local
Atualizar o ambiente Python local, sem a recomposição de imagem do Docker	Sim	Não
Criar 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 do Visual Studio Code	Sim	Sim

Este guia pressupõe que você tenha os itens a seguir instalados localmente em seu computador.

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

Os exemplos neste artigo baseiam-se em exemplos de código contidos no repositório do GitHub azureml-examples. Para executar os comandos localmente sem precisar copiar/colar o 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 da CLI do Azure, salve as configurações padrão. Para evitar passar os valores para sua assinatura, espaço de trabalho e grupo de recursos várias vezes, use os seguintes comandos. Substitua os seguintes parâmetros por valores para a sua configuração específica:

Substitua <subscription> por sua ID da assinatura do Azure.
Substitua <workspace> pelo nome do workspace do Azure Machine Learning.
Substitua <resource-group> pelo grupo de recursos do Azure que contém o workspace.
Substitua <location> pela região do Azure que contém o workspace.

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

Dica

Para ver quais são seus padrões atuais, use o comando az configure -l.

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

Este guia pressupõe que você tenha os itens a seguir instalados localmente em seu computador.

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

É possível encontrar os exemplos deste artigo no notebook Jupyter Depurar pontos de extremidade online localmente no Visual Studio Code, que está no 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 notebook 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 notebook 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

Configurar variáveis para o workspace e o ponto de extremidade:

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

endpoint_name = "<ENDPOINT_NAME>"

Iniciar contêiner de desenvolvimento

CLI do Azure
Python

Os pontos de extremidade locais do Azure Machine Learning usam contêineres de desenvolvimento do Docker e do Visual Studio Code para criar e configurar um ambiente de depuração local. Com contêineres de desenvolvimento, é possível aproveitar os recursos do Visual Studio Code 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, utilize o sinalizador --vscode-debug ao criar ou atualizar uma 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 WSL (Subsistema do Windows para Linux), é necessário atualizar a variável de ambiente PATH para incluir o caminho para o executável do Visual Studio Code ou usar a interoperabilidade do WSL. Para obter mais informações, consulte a interoperabilidade do Windows com Linux.

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

Observação

Pode levar muitos minutos ao iniciar um contêiner de desenvolvimento novo ou atualizado pela primeira vez.

Depois que a imagem for criada, o contêiner de desenvolvimento será aberto em uma janela do Visual Studio Code.

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

Depuração de inferência
Pylance
Jupyter
Python

Importante

Antes de iniciar a sessão de depuração, verifique se as extensões do Visual Studio Code foram instaladas no contêiner de desenvolvimento.

Obtenha um identificador para o workspace:

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 vscode-debug e local ao criar ou atualizar uma implantação online do Azure Machine Learning. O comando 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 aparecem nesta fase do processo.

Observação

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

Depois que a imagem for criada, o 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 a sessão de depuração, verifique se as extensões do Visual Studio Code foram instaladas no contêiner de desenvolvimento.

Iniciar a sessão de depuração

Depois que o ambiente estiver configurado, use o depurador do Visual Studio Code para testar e depurar a implantação localmente.

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

Dica

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 script de pontuação.
- Para depurar o comportamento de inicialização, coloque seus pontos de interrupção dentro da função init.
- Para depurar o comportamento da pontuação, coloque seus pontos de interrupção dentro da função run.
Selecione a exibição “Trabalho do Visual Studio Code”.
No menu suspenso Executar e depurar, selecione AzureML: depurar ponto de extremidade local para começar a depurar o ponto de extremidade localmente.

Na seção Pontos de Interrupção da exibição Executar, verifique se:
- Exceções Ativas está desmarcada
- Exceções Não Capturadas está desmarcada
Selecione o ícone de reprodução próximo ao menu suspenso Executar e depurar para iniciar a sessão de depuração.

Neste ponto, todos os pontos de interrupção na função init são capturados. Use as ações de depuração para passar pelo código. Para obter mais informações sobre ações de depuração, consulte o guia de ações de depuração.

Para saber mais sobre o depurador do Visual Studio Code, confira Depuração.

Depurar o ponto de extremidade

CLI do Azure
Python

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

Use o comando ml de extensão invoke para fazer uma solicitação ao 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 exemplos 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]
]}

Dica

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

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

O resultado deve ser 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 propriedade scoring_uri.

Neste ponto, todos os pontos de interrupção na função run são capturados. Use as ações de depuração para passar pelo 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á em execução no depurador, tente fazer uma previsão para depurar o script de pontuação.

Use método invoke no seu objeto MLClient para fazer uma solicitação ao 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 exemplos 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]
]}

Dica

O URI de pontuação é o endereço em que o ponto de extremidade escuta solicitações. O método as_dict de objetos de ponto de extremidade retorna informações semelhantes a show na CLI do Azure. O objeto de ponto de extremidade pode ser obtido por meio de .get.

print(endpoint)

O resultado deve ser 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 chave scoring_uri.

Editar o ponto de extremidade

CLI do Azure
Python

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

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

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

Observação

Como o diretório que contém o código e os ativos do 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 abrangentes que envolvem atualizações em seu ambiente e configuração de ponto de extremidade, use o comando ml da extensão update. Isso aciona uma recompilaçã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 o contêiner de desenvolvimento for iniciado, use o depurador do Visual Studio Code para testar e solucionar problemas do ponto de extremidade atualizado.

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

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

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

Observação

Para alterações mais abrangentes que envolvem atualizações em seu ambiente e configuração de ponto de extremidade, use o módulo/método MLClient da extensão online_deployments.update. Isso aciona uma recompilaçã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()

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

Depurar pontos de extremidade online localmente Visual Studio Code

Pré-requisitos

Iniciar contêiner de desenvolvimento

Iniciar a sessão de depuração

Depurar o ponto de extremidade

Editar o ponto de extremidade

Conteúdo relacionado

Recursos adicionais