Déboguer les points de terminaison en ligne localement dans Visual Studio Code

Ce guide suppose que les éléments suivants sont installés localement sur votre PC.

• Docker
• Visual Studio Code
• Azure CLI
• Extension Azure CLI ml (v2)

Pour plus d’informations, consultez le guide expliquant comment préparer votre système pour déployer des points de terminaison en ligne.

Les exemples de cet article sont basés sur des exemples de code contenus dans le référentiel GitHub azureml-examples. Pour exécuter les commandes localement sans avoir à copier/coller le fichier YAML et d’autres fichiers, clonez le référentiel, puis modifiez les répertoires en azureml-examples/cli :

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

Si vous n’avez pas encore défini les paramètres par défaut pour l’interface CLI Azure, enregistrez vos paramètres par défaut. Pour éviter de transmettre plusieurs fois les valeurs de votre abonnement, de votre espace de travail et de votre groupe de ressources, utilisez les commandes suivantes. Remplacez les paramètres suivants par des valeurs pour votre configuration spécifique :

• Remplacez <subscription> par l’identifiant de votre abonnement Azure.
• Remplacez <workspace> par le nom de votre espace de travail Azure Machine Learning.
• Remplacez <resource-group> par le groupe de ressources Azure qui contient votre espace de travail.
• Remplacez <location> par la région Azure qui contient votre espace de travail.

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

S’APPLIQUE À : Kit de développement logiciel (SDK) Python azure-ai-mlv2 (préversion)

Ce guide suppose que les éléments suivants sont installés localement sur votre PC.

• Docker
• Visual Studio Code
• Azure CLI
• Extension Azure CLI ml (v2)
• Kit SDK Python Azure Machine Learning (v2)
• Sous-système Windows pour Linux (WSL)

Pour plus d’informations, consultez le guide expliquant comment préparer votre système pour déployer des points de terminaison en ligne.

Les exemples de cet article sont disponibles dans le notebook Jupyter appelé Déboguer des points de terminaison en ligne localement dans le notebook Visual Studio Code dans le référentiel azureml-examples. Pour exécuter le code localement, clonez le référentiel, puis remplacez les répertoires par le répertoire parent sdk/endpoints/online/managed du notebook.

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

Ouvrez le notebook Jupyter, puis importez les modules requis :

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

Configurez des variables pour l’espace de travail et le point de terminaison :

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

endpoint_name = "<ENDPOINT_NAME>"

Les points de terminaison locaux Azure Machine Learning utilisent les conteneurs de développement Docker et Visual Studio Code (conteneurs de développement) pour générer, puis configurer un environnement de débogage local. Avec les conteneurs de développement, vous pouvez tirer parti des fonctionnalités de Visual Studio Code au sein d’un conteneur Docker. Pour plus d’informations sur les conteneurs de développement, consultez Créer un conteneur de développement.

Pour déboguer des points de terminaison en ligne localement dans Visual Studio Code, utilisez l’indicateur --vscode-debug lors de la création ou de la mise à jour d’un déploiement en ligne Azure Machine Learning. La commande suivante utilise un exemple de déploiement issu du référentiel des exemples :

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

Une image Docker est générée localement. Toute erreur de configuration d’environnement ou de fichier de modèle est exposée à cette étape du processus.

Une fois que l’image est correctement générée, votre conteneur de développement s’ouvre dans une fenêtre Visual Studio Code.

Vous allez utiliser quelques extensions Visual Studio Code pour déboguer vos déploiements dans le conteneur de développement. Azure Machine Learning installe automatiquement ces extensions dans votre conteneur de développement.

• Débogage d’inférence
• Pylance
• Jupyter
• Python

Les points de terminaison locaux Azure Machine Learning utilisent les conteneurs de développement Docker et Visual Studio Code (conteneurs de développement) pour générer, puis configurer un environnement de débogage local. Avec les conteneurs de développement, vous pouvez tirer parti des fonctionnalités de Visual Studio Code au sein d’un conteneur Docker. Pour plus d’informations sur les conteneurs de développement, consultez Créer un conteneur de développement.

Obtenez une poignée dans l’espace de travail :

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

Pour déboguer les points de terminaison en ligne localement dans Visual Studio Code, définissez les indicateurs vscode-debug et local lors de la création ou de la mise à jour d'un déploiement en ligne d’Azure Machine Learning. Le code suivant reflète un exemple de déploiement du dépôt d'exemples :

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

Une image Docker est générée localement. Toute erreur de configuration d’environnement ou de fichier de modèle est exposée à cette étape du processus.

Une fois que l’image est correctement générée, votre conteneur de développement s’ouvre dans une fenêtre Visual Studio Code.

Vous allez utiliser quelques extensions Visual Studio Code pour déboguer vos déploiements dans le conteneur de développement. Azure Machine Learning installe automatiquement ces extensions dans votre conteneur de développement.

• Débogage d’inférence
• Pylance
• Jupyter
• Python

Maintenant que votre application s’exécute dans le débogueur, essayez d’effectuer une prédiction pour déboguer votre script de scoring.

Utilisez la commande invoke d’extension ml pour effectuer une requête à votre point de terminaison local.

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

Dans ce cas, <REQUEST-FILE> est un fichier JSON qui contient des exemples de données d’entrée pour que le modèle effectue des prédictions similaires au code JSON suivant :

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

À ce stade, tous les points d’arrêt de votre fonction run sont interceptés. Utilisez les actions de débogage pour parcourir votre code. Pour plus d’informations sur les actions de débogage, consultez le Guide des actions de débogage.

Maintenant que votre application s’exécute dans le débogueur, essayez d’effectuer une prédiction pour déboguer votre script de scoring.

Utilisez la méthode invoke sur votre objet MLClient pour faire une demande à votre point d'accès 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)

Dans ce cas, <REQUEST-FILE> est un fichier JSON qui contient des exemples de données d’entrée pour que le modèle effectue des prédictions similaires au code JSON suivant :

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

À ce stade, tous les points d’arrêt de votre fonction run sont interceptés. Utilisez les actions de débogage pour parcourir votre code. Pour plus d’informations sur les actions de débogage, consultez le Guide des actions de débogage.

Quand vous déboguez et dépannez votre application, il existe des scénarios dans lesquels vous devez mettre à jour votre script de scoring et vos configurations.

Pour appliquer les modifications à votre code :

1. Mettez à jour votre code.
2. Redémarrez votre session de débogage à l’aide de la commande Developer: Reload Window dans la palette de commandes. Pour plus d’informations, consultez la documentation sur la palette de commandes.

Pour effectuer des modifications plus approfondies concernant les mises à jour de la configuration de votre environnement et de vos points de terminaison, utilisez la commande update d’extension ml. Cette action déclenche une régénération d’image complète avec vos modifications.

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

Une fois que l’image mise à jour est générée et que votre conteneur de développement est lancé, utilisez le débogueur Visual Studio Code pour tester, puis résoudre les problèmes liés à votre point de terminaison mis à jour.

Quand vous déboguez et dépannez votre application, il existe des scénarios dans lesquels vous devez mettre à jour votre script de scoring et vos configurations.

Pour appliquer les modifications à votre code :

1. Mettez à jour votre code.
2. Redémarrez votre session de débogage à l’aide de la commande Developer: Reload Window dans la palette de commandes. Pour plus d’informations, consultez la documentation sur la palette de commandes.

Pour des changements plus importants impliquant des mises à jour de votre environnement et de la configuration des points d'accès, utilisez le module/méthode online_deployments.update de votre MLClient. Cette action déclenche une régénération d’image complète avec vos modifications.

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

Une fois que l’image mise à jour est générée et que votre conteneur de développement est lancé, utilisez le débogueur Visual Studio Code pour tester, puis résoudre les problèmes liés à votre point de terminaison mis à jour.