Eseguire il debug degli endpoint online in locale in Visual Studio Code

Questa guida presuppone che nel PC siano installati gli elementi seguenti in locale.

• Docker
• Visual Studio Code
• Interfaccia della riga di comando di Azure
• Estensione ml dell'interfaccia della riga di comando di Azure (v2)

Per altre informazioni, vedere la guida su come preparare il sistema per la distribuzione di endpoint online.

Gli esempi di questo articolo si basano sugli esempi di codice contenuti nel repository GitHub azureml-examples. Per eseguire i comandi in locale senza dover copiare o incollare il file YAML e altri file, clonare il repository quindi cambiare le directory in azureml-examples/cli:

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

Se le impostazioni predefinite per l'interfaccia della riga di comando di Azure non sono state ancora impostate, salvare le proprie impostazioni predefinite. Per evitare di passare più volte i valori per la propria sottoscrizione, area di lavoro e gruppo di risorse, usare i comandi seguenti. Sostituire i parametri seguenti con i valori della propria configurazione specifica:

• Sostituire <subscription> con l'ID della sottoscrizione di Azure.
• Sostituire <workspace> con il nome dell'area di lavoro di Azure Machine Learning.
• Sostituire <resource-group> con il gruppo di risorse di Azure contenente la propria area di lavoro.
• Sostituire <location> con l'area di Azure contenente la propria area di lavoro.

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

SI APPLICA A: Python SDK azure-ai-ml v2 (corrente)

Questa guida presuppone che nel PC siano installati gli elementi seguenti in locale.

• Docker
• Visual Studio Code
• Interfaccia della riga di comando di Azure
• Estensione ml dell'interfaccia della riga di comando di Azure (v2)
• Azure Machine Learning Python SDK (v2)
• Sottosistema di Windows per Linux (WSL)

Per altre informazioni, vedere la guida su come preparare il sistema per la distribuzione di endpoint online.

Gli esempi in questo articolo sono disponibili nel Jupyter Notebook Eseguire il debug di endpoint online in locale in Visual Studio Code all'interno del repository azureml-examples. Per eseguire il codice in locale, clonare il repository e quindi andare alla directory padre del notebook sdk/endpoints/online/managed.

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

Aprire il notebook di Jupyter e importare i moduli necessari:

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

Configurare le variabili per l'area di lavoro e l'endpoint:

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

endpoint_name = "<ENDPOINT_NAME>"

Gli endpoint locali di Azure Machine Learning usano i contenitori di sviluppo Docker e Visual Studio Code per creare e configurare un ambiente di debug locale. Con i contenitori di sviluppo è possibile sfruttare le funzionalità di Visual Studio Code all'interno di un contenitore Docker. Per altre informazioni sui contenitori di sviluppo, vedere Creare un contenitore di sviluppo.

Per eseguire il debug degli endpoint online in locale in Visual Studio Code, usare il flag --vscode-debug durante la creazione o l'aggiornamento di una distribuzione online di Azure Machine Learning. Il comando seguente usa un esempio di distribuzione del repository di esempi:

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

Viene creata un'immagine Docker in locale. In questa fase del processo vengono rilevati eventuali errori di configurazione dell'ambiente o di file del modello.

Dopo la compilazione dell'immagine, il contenitore di sviluppo viene aperto in una finestra di Visual Studio Code.

Si useranno alcune estensioni di Visual Studio Code per eseguire il debug delle distribuzioni nel contenitore di sviluppo. Azure Machine Learning installa automaticamente queste estensioni nel contenitore di sviluppo.

• Debug dell'inferenza
• Pylance
• Jupyter
• Python

Gli endpoint locali di Azure Machine Learning usano i contenitori di sviluppo Docker e Visual Studio Code per creare e configurare un ambiente di debug locale. Con i contenitori di sviluppo è possibile sfruttare le funzionalità di Visual Studio Code all'interno di un contenitore Docker. Per altre informazioni sui contenitori di sviluppo, vedere Creare un contenitore di sviluppo.

Ottenere un handle per l'area di lavoro:

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

Per eseguire il debug degli endpoint online in locale in VS Code, usare i flag vscode-debug e local durante la creazione o l'aggiornamento di una distribuzione online di Azure Machine Learning. Il codice seguente rispecchia un esempio di distribuzione del repository di esempi:

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

Viene creata un'immagine Docker in locale. In questa fase del processo vengono rilevati eventuali errori di configurazione dell'ambiente o di file del modello.

Dopo la compilazione dell'immagine, il contenitore di sviluppo viene aperto in una finestra di Visual Studio Code.

Si useranno alcune estensioni di Visual Studio Code per eseguire il debug delle distribuzioni nel contenitore di sviluppo. Azure Machine Learning installa automaticamente queste estensioni nel contenitore di sviluppo.

• Debug dell'inferenza
• Pylance
• Jupyter
• Python

Ora che l'applicazione è in esecuzione nel debugger, provare a fare una previsione per eseguire il debug dello script di assegnazione dei punteggi.

Usare il comando invoke dell'estensione ml per effettuare una richiesta all'endpoint locale.

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

In questo caso, <REQUEST-FILE> è un file JSON che contiene esempi di dati di input per il modello per fare previsioni in modo simile al codice JSON seguente:

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

A questo punto, vengono rilevati tutti i punti di interruzione nella funzione run. Usare le azioni di debug per scorrere il codice. Per altre informazioni sulle azioni di debug, vedere la guida alle azioni di debug.

Ora che l'applicazione è in esecuzione nel debugger, provare a fare una previsione per eseguire il debug dello script di assegnazione dei punteggi.

Usare il metodo invoke dell'oggetto MLClient per effettuare una richiesta all'endpoint locale.

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)

In questo caso, <REQUEST-FILE> è un file JSON che contiene esempi di dati di input per il modello per fare previsioni in modo simile al codice JSON seguente:

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

A questo punto, vengono rilevati tutti i punti di interruzione nella funzione run. Usare le azioni di debug per scorrere il codice. Per altre informazioni sulle azioni di debug, vedere la guida alle azioni di debug.

Durante il debug e la risoluzione dei problemi dell'applicazione, in alcuni scenari in cui è necessario aggiornare lo script di assegnazione dei punteggi e le configurazioni.

Per applicare le modifiche al codice:

1. Aggiornare il codice
2. Riavviare la sessione di debug usando il comando Developer: Reload Window nel riquadro comandi. Per altre informazioni, vedere la documentazione del riquadro comandi.

Per modifiche più estese che coinvolgono gli aggiornamenti dell'ambiente e della configurazione dell'endpoint, usare il comando update dell'estensione ml. In questo modo viene attivata una ricompilazione completa dell'immagine con le modifiche.

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

Dopo la compilazione dell'immagine aggiornata e l'avvio del contenitore di sviluppo, usare il debugger di Visual Studio Code per testare e risolvere i problemi dell'endpoint aggiornato.

Durante il debug e la risoluzione dei problemi dell'applicazione, in alcuni scenari in cui è necessario aggiornare lo script di assegnazione dei punteggi e le configurazioni.

Per applicare le modifiche al codice:

1. Aggiornare il codice
2. Riavviare la sessione di debug usando il comando Developer: Reload Window nel riquadro comandi. Per altre informazioni, vedere la documentazione del riquadro comandi.

Per modifiche più estese che coinvolgono gli aggiornamenti dell'ambiente e della configurazione dell'endpoint, usare il modulo/metodo online_deployments.update di MLClient. In questo modo viene attivata una ricompilazione completa dell'immagine con le modifiche.

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

Dopo la compilazione dell'immagine aggiornata e l'avvio del contenitore di sviluppo, usare il debugger di Visual Studio Code per testare e risolvere i problemi dell'endpoint aggiornato.