Depurar pontos de extremidade online localmente Visual Studio Code

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

• Docker
• Visual Studio Code
• CLI do Azure
• Extensão de ML da CLI do Azure (v2)

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>

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.

• Docker
• Visual Studio Code
• CLI do Azure
• Extensão de ML da CLI do Azure (v2)
• SDK do Python para o Azure Machine Learning (v2)
• WSL (Subsistema do Windows para Linux)

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>"

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

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

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

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.

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()

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

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

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]
]}

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

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

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]
]}

print(endpoint)

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

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.

À 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:

1. Atualize o código.
2. 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.

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:

1. Atualize o código.
2. 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.

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.