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

Articolo
04/07/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 ed eseguire il debug degli 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 non è consigliabile usarla per 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 diverse opzioni per 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 in questo articolo sono basati su esempi di codice contenuti nel repository GitHub azureml-examples . Per eseguire i comandi in locale senza dover copiare/incollare YAML e altri file, clonare il repository e quindi modificare 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 già state impostate, salvare le proprie impostazioni predefinite. Per evitare di passare più volte i valori per la sottoscrizione, l'area di lavoro e il gruppo di risorse, eseguire i comandi seguenti. Sostituire i parametri seguenti con i valori relativi alla 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 che contiene l'area di lavoro.
Sostituire <location> con l'area di Azure che contiene l'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 notebook di Jupyter denominato Eseguire il debug degli 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 passare 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 contenitori di sviluppo Docker e Visual Studio Code (contenitori di sviluppo) per compilare e configurare un ambiente di debug locale. Con i contenitori di sviluppo è possibile sfruttare le funzionalità di Visual Studio Code dall'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 durante la --vscode-debug creazione o l'aggiornamento e la 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 per includere il percorso dell'eseguibile di Visual Studio Code o usare l'interoperabilità 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 alcuni minuti.

Una volta compilata correttamente l'immagine, il contenitore di sviluppo viene aperto in una finestra di Visual Studio Code.

Per eseguire il debug delle distribuzioni nel contenitore di sviluppo si useranno alcune estensioni di Visual Studio Code. 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 le estensioni di Visual Studio Code siano state completate nell'installazione 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 Visual Studio Code, impostare i flag e local durante la creazione o l'aggiornamento vscode-debug 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

L'avvio di un contenitore di sviluppo nuovo o aggiornato può richiedere alcuni minuti per la prima volta.

Una volta compilata correttamente l'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 le estensioni di Visual Studio Code siano state completate nell'installazione nel contenitore di sviluppo.

Avviare la sessione di debug

Dopo aver configurato l'ambiente, usare il debugger di Visual Studio Code per testare ed eseguire il debug della 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 e 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 e 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 aver compilato l'immagine aggiornata e aver avviato il 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 aver compilato l'immagine aggiornata e aver avviato il contenitore di sviluppo, usare il debugger di Visual Studio Code per testare e risolvere i problemi dell'endpoint aggiornato.

Share via

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

Risorse aggiuntive

Share via

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

Risorse aggiuntive