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

Articolo
10/16/2024

SI APPLICA A:Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)Python SDK azure-ai-ml v2 (corrente)

Informazioni su come usare il debugger di Microsoft Visual Studio Code per testare e sottoporre a debug gli endpoint online in locale prima di distribuirli in Azure.

Gli endpoint locali di Azure Machine Learning consentono di testare e sottoporre a debug lo script di assegnazione dei punteggi, la configurazione dell'ambiente, la configurazione del codice e il modello di Machine Learning in locale.

Importante

Questa funzionalità è attualmente in anteprima pubblica. Questa versione di anteprima viene fornita senza contratto di servizio, pertanto se ne sconsiglia l’uso per i carichi di lavoro in ambienti di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate.

Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Il debug degli endpoint in locale prima di distribuirli nel cloud consente di rilevare gli errori nel codice e nella configurazione con largo anticipo. Sono disponibili differenti opzioni per eseguire il debug degli endpoint in locale con Visual Studio Code.

Server HTTP di inferenza di Azure Machine Learning
Endpoint locale

Questa guida è incentrata sugli endpoint locali.

La tabella seguente offre una panoramica degli scenari che consentono di scegliere le opzioni più adatte.

Scenario	Server HTTP di inferenza	Endpoint locale
Aggiornare l'ambiente Python locale, senza ricompilare l'immagine Docker	Sì	No
Aggiornare lo script di assegnazione dei punteggi	Sì	Sì
Aggiornare le configurazioni di distribuzione (distribuzione, ambiente, codice, modello)	No	Sì
Integrazione del debugger di Visual Studio Code	Sì	Sì

Prerequisiti

Interfaccia della riga di comando di Azure
Python

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

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>

Suggerimento

È possibile visualizzare le impostazioni predefinite correnti usando il comando az configure -l.

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

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

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

Avviare il contenitore di sviluppo

Interfaccia della riga di comando di Azure
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.

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

Importante

In sottosistema Windows per Linux (WSL) è necessario aggiornare la variabile di ambiente PATH in modo da includere il percorso dell'eseguibile di Visual Studio Code o usare l'interoperabilità di WSL. Per altre informazioni, vedere Interoperabilità di Windows con Linux.

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.

Nota

La prima volta che si avvia un contenitore di sviluppo nuovo o aggiornato, possono essere necessari diversi minuti.

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

Importante

Prima di avviare la sessione di debug, assicurarsi che l'installazione delle estensioni di Visual Studio Code sia stata completata nel 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()

Importante

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.

Nota

La prima volta che si avvia un contenitore di sviluppo nuovo o aggiornato, possono essere necessari diversi minuti.

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

Debug dell'inferenza
Pylance
Jupyter
Python

Importante

Prima di avviare la sessione di debug, assicurarsi che l'installazione delle estensioni di Visual Studio Code sia stata completata nel contenitore di sviluppo.

Avviare la sessione di debug

Dopo aver configurato l'ambiente, usare il debugger di Visual Studio Code per testare e sottoporre a debug la distribuzione in locale.

Aprire lo script di assegnazione dei punteggi in Visual Studio Code.

Suggerimento

Lo script score.py usato dall'endpoint distribuito in precedenza si trova in azureml-samples/cli/endpoints/online/managed/sample/score.py nel repository clonato. Tuttavia, i passaggi descritti in questa guida funzionano con qualsiasi script di assegnazione dei punteggi.
Impostare un punto di interruzione in qualsiasi posizione all'interno dello script di assegnazione dei punteggi.
- Per eseguire il debug del comportamento di avvio, posizionare i punti di interruzione all'interno della funzione init.
- Per eseguire il debug del comportamento di assegnazione dei punteggi, posizionare i punti di interruzione all'interno della funzione run.
Selezionare la visualizzazione Processo di Visual Studio Code.
Nell'elenco a discesa Esegui con debug selezionare AzureML: Debug endpoint locale per avviare il debug dell'endpoint in locale.

Nella sezione Punti di interruzione della visualizzazione Esegui verificare che:
- L'opzione Eccezioni generate sia deselezionata
- L'opzione Eccezioni non rilevate sia selezionata
Selezionare l'icona di riproduzione accanto all'elenco a discesa Esegui con debug per avviare la sessione di debug.

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

Per altre informazioni sul debugger di Visual Studio Code, vedere Debug.

Eseguire il debug dell'endpoint

Interfaccia della riga di comando di Azure
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]
]}

Suggerimento

L'URI di assegnazione dei punteggi è l'indirizzo in cui l'endpoint resta in ascolto delle richieste. Usare l'estensione ml per ottenere l'URI di assegnazione dei punteggi.

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

L'output dovrebbe essere simile al seguente:

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

L'URI di assegnazione dei punteggi è reperibile nella proprietà scoring_uri.

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

Suggerimento

L'URI di assegnazione dei punteggi è l'indirizzo in cui l'endpoint resta in ascolto delle richieste. Il metodo as_dict degli oggetti endpoint restituisce informazioni simili a show nell'interfaccia della riga di comando di Azure. L'oggetto endpoint può essere ottenuto tramite .get.

print(endpoint)

L'output dovrebbe essere simile al seguente:

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

L'URI di assegnazione dei punteggi è reperibile nella chiave scoring_uri.

Modificare l'endpoint

Interfaccia della riga di comando di Azure
Python

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:

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

Nota

Poiché la directory contenente il codice e gli asset dell'endpoint viene montata nel contenitore di sviluppo, tutte le modifiche apportate nel contenitore di sviluppo vengono sincronizzate con il file system locale.

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:

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

Nota

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.

Condividi tramite

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

Prerequisiti

Avviare il contenitore di sviluppo

Avviare la sessione di debug

Eseguire il debug dell'endpoint

Modificare l'endpoint

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

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

Prerequisiti

Avviare il contenitore di sviluppo

Avviare la sessione di debug

Eseguire il debug dell'endpoint

Modificare l'endpoint

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive