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

Article
04/11/2024

S’APPLIQUE À :Extension Azure CLI v2 (actuelle)Kit de développement logiciel (SDK) Python azure-ai-ml v2 (version actuelle)

Découvrez comment utiliser le débogueur Microsoft Visual Studio Code pour tester, puis déboguer des points de terminaison en ligne localement avant de les déployer sur Azure.

Les points de terminaison locaux Azure Machine Learning vous aident à tester et à déboguer votre script de scoring, la configuration de l’environnement, la configuration du code et le modèle Machine Learning localement.

Important

Cette fonctionnalité est actuellement disponible en préversion publique. Cette préversion est fournie sans contrat de niveau de service et n’est pas recommandée pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge.

Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Le débogage des points de terminaison localement avant le déploiement dans le cloud peut vous aider à détecter plus tôt les erreurs dans votre code et votre configuration. Vous disposez de différentes options pour déboguer les points de terminaison localement avec Visual Studio Code.

Serveur HTTP d’inférence Azure Machine Learning
Point de terminaison local

Ce guide se concentre sur les points de terminaison locaux.

Le tableau suivant fournit une vue d’ensemble des scénarios pour vous aider à choisir la solution la mieux adaptée.

Scénario	Serveur HTTP d’inférence	Point de terminaison local
Mettre à jour l’environnement Python local, sans regénération d’image Docker	Oui	Non
Mettre à jour le script de scoring	Oui	Oui
Mettre à jour les configurations de déploiement (déploiement, environnement, code, modèle)	Non	Oui
Intégration du débogueur Visual Studio Code	Oui	Oui

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

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>

Conseil

Vous pouvez afficher les valeurs par défaut actuelles à l’aide de la commande az configure -l.

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.

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

Lancer le conteneur de développement

Azure CLI
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.

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

Important

Sur un sous-système Windows pour Linux (WSL), vous devez mettre à jour votre variable d’environnement PATH pour inclure le chemin d’accès à l’exécutable Visual Studio Code ou utiliser WSL interop. Pour plus d’informations, consultez Interopérabilité Windows avec Linux.

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.

Remarque

La première fois que vous lancez un conteneur de développement nouveau ou mis à jour, cela peut prendre plusieurs minutes.

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

Important

Avant de démarrer votre session de débogage, vérifiez que les extensions VS Code ont terminé de s’installer dans votre 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()

Important

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.

Remarque

Le premier lancement d’un conteneur de développement nouveau ou mis à jour peut prendre plusieurs minutes.

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.

Débogage d’inférence
Pylance
Jupyter
Python

Important

Avant de démarrer votre session de débogage, vérifiez que les extensions VS Code ont terminé de s’installer dans votre conteneur de développement.

Démarrer la session de débogage

Une fois votre environnement configuré, utilisez le débogueur Visual Studio Code pour tester, puis déboguer votre déploiement localement.

Ouvrez votre script de scoring dans Visual Studio Code.

Conseil

Le script score.py utilisé par le point de terminaison déployé précédemment se trouve à l’emplacement azureml-samples/cli/endpoints/online/managed/sample/score.py dans le référentiel que vous avez cloné. Toutefois, les étapes de ce guide fonctionnent pour tout script de scoring.
Définissez un point d’arrêt n’importe où dans votre script de scoring.
- Pour déboguer le comportement de démarrage, placez votre ou vos points d’arrêt à l’intérieur de la fonction init.
- Pour déboguer le comportement de scoring, placez votre ou vos points d’arrêt à l’intérieur de la fonction run.
Sélectionnez la vue Travail Visual Studio Code.
Dans la liste déroulante Exécuter et déboguer, sélectionnez Azure ML : déboguer le point de terminaison local pour démarrer le débogage de votre point de terminaison localement.

Dans la section Points d’arrêt de la vue Exécuter, vérifiez les éléments suivants :
- Les Exceptions levées sont désactivées
- Les Exceptions interceptées sont activées
Sélectionnez l’icône de lecture à côté de la liste déroulante Exécuter et déboguer pour démarrer votre session de débogage.

À ce stade, tous les points d’arrêt de votre fonction init 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.

Si vous souhaitez en savoir plus sur le débogueur Visual Studio Code, veuillez consulter la rubrique Débogage.

Déboguer votre point de terminaison

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

Conseil

L’URI de scoring correspond à l’adresse où votre point de terminaison écoute les demandes. Utilisez l’extension ml pour récupérer l’URI de scoring.

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

Le résultat doit être semblable à ce qui suit :

{
 "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 de scoring se trouve dans la propriété scoring_uri.

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

Conseil

L’URI de scoring correspond à l’adresse où votre point de terminaison écoute les demandes. La méthode as_dict d’objets de point de terminaison retourne des informations similaires à show dans Azure CLI. L’objet de point de terminaison peut être obtenu via .get.

print(endpoint)

Le résultat doit être semblable à ce qui suit :

{
 "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 de notation se trouve dans la clé scoring_uri.

Modifier votre point de terminaison

Azure CLI
Python

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 :

Mettez à jour votre code.
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.

Notes

Étant donné que le répertoire contenant votre code et vos ressources de point de terminaison est monté sur le conteneur de développement, toutes les modifications que vous effectuez dans le conteneur de développement sont synchronisées avec votre système de fichiers local.

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 :

Mettez à jour votre code.
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.

Notes

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

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

Prérequis

Lancer le conteneur de développement

Démarrer la session de débogage

Déboguer votre point de terminaison

Modifier votre point de terminaison

Contenu connexe

Ressources supplémentaires