Déployer et évaluer un modèle de Machine Learning à l’aide d’un point de terminaison en ligne

  • Article

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

Dans cet article, vous allez apprendre à déployer votre modèle sur un point de terminaison en ligne pour une utilisation dans l’inférence en temps réel. Vous allez commencer par déployer un modèle sur votre ordinateur local pour déboguer les erreurs éventuelles. Ensuite, vous allez déployer et tester le modèle dans Azure. Vous allez également apprendre à afficher le déploiement des journaux et à surveiller le contrat de niveau de service (SLA). À la fin de cet article, vous disposerez d’un point de terminaison HTTPS/REST évolutif que vous pourrez utiliser pour l’inférence en temps réel.

Les points de terminaison en ligne sont des points de terminaison utilisés pour l’inférence en temps réel. Il existe deux types de points de terminaison en ligne : les points de terminaison en ligne managés et les points de terminaison en ligne Kubernetes. Pour plus d’informations sur les points de terminaison et les différences entre les points de terminaison en ligne managés et les points de terminaison en ligne Kubernetes, consultez Que sont les points de terminaison Azure Machine Learning ?.

Les points de terminaison en ligne managés vous aident à déployer vos modèles de ML dans un mode clé en main. Les points de terminaison en ligne managés fonctionnent avec des ordinateurs de processeur et GPU puissants dans Azure de manière évolutive et entièrement gérée. Les points de terminaison en ligne gérés prennent en charge la fourniture, la mise à l’échelle et le monitoring de vos modèles, ce qui vous évite la surcharge liée à la configuration et à la gestion de l’infrastructure sous-jacente.

L’exemple principal de ce document utilise des points de terminaison en ligne managés pour le déploiement. Pour utiliser Kubernetes à la place, consultez les notes dans ce document qui sont incluses avec la discussion sur les points de terminaison en ligne managés.

Prérequis

S’APPLIQUE À :Extension Azure ML CLI v2 (actuelle)

Avant de suivre les étapes décrites dans cet article, vérifiez que vous disposez des composants requis suivants :

  • Les contrôles d’accès en fonction du rôle Azure (Azure RBAC) sont utilisés pour accorder l’accès aux opérations dans Azure Machine Learning. Pour effectuer les étapes décrites dans cet article, votre compte d’utilisateur doit avoir le rôle Propriétaire ou Contributeur sur l’espace de travail Azure Machine Learning, ou un rôle personnalisé autorisant Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*. Si vous utilisez Studio pour créer/gérer des points de terminaison/déploiements en ligne, le propriétaire du groupe de ressources doit vous assigner une autorisation « Microsoft.Resources/deployments/write » supplémentaire. Pour plus d’informations, consultez Gérer l’accès à un espace de travail Azure Machine Learning.

  • (Facultatif) Pour déployer localement, vous devez installer Moteur Docker sur votre ordinateur local. Nous recommandons fortement cette option pour déboguer les problèmes plus facilement.

Allocation de quota du nombre de machines virtuelles pour le déploiement

Azure Machine Learning réserve 20 % de vos ressources de calcul pour les points de terminaison en ligne managés afin d’exécuter des mises à niveau sur certaines références SKU de machine virtuelle. Si vous demandez un nombre donné d’instances dans un déploiement, vous devez disposer d’un quota de ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU pour éviter d’obtenir une erreur. Par exemple, si vous demandez 10 instances d’une machine virtuelle Standard_DS3_v2 (fournie avec 4 cœurs) dans un déploiement, vous devez disposer d’un quota de 48 cœurs (12 instances * 4 cores). Pour afficher votre utilisation et demander des augmentations de quota, consultez Afficher votre utilisation et vos quotas dans le Portail Azure.

Certaines références SKU de machine virtuelle sont exemptées d’une réservation de quota supplémentaire. Pour afficher la liste complète, consultez la liste des références SKU de points de terminaison en ligne managés.

Azure Machine Learning fournit un pool de quotas partagé à partir duquel tous les utilisateurs peuvent accéder au quota pour effectuer des tests pendant une période limitée. Lorsque vous utilisez le studio pour déployer des modèles Llama (à partir du catalogue de modèles) vers un point de terminaison en ligne managé, Azure Machine Learning vous permet d’accéder à ce quota partagé pendant une courte période.

Toutefois, pour déployer un modèle Llama-2-70b ou Llama-2-70b-chat vous devez disposer d’un abonnement Accord Entreprise avant de pouvoir déployer à l’aide du quota partagé. Pour plus d’informations sur l’utilisation du quota partagé pour le déploiement de points de terminaison en ligne, consultez le Guide pratique pour déployer des modèles de base à l’aide du studio.

Préparer votre système

Définir des variables d’environnement

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, exécutez le code suivant :

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

Cloner le référentiel d’exemples

Pour suivre cet article, commencez par cloner le dépôt d’exemples (azureml-examples). Ensuite, exécutez le code suivant pour accéder au répertoire cli/ du dépôt :

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

Conseil

Utilisez --depth 1 pour cloner uniquement le dernier commit dans le dépôt, ce qui réduit le temps nécessaire à l’exécution de l’opération.

Les commandes de ce tutoriel se trouvent dans les fichiers deploy-local-endpoint.sh et deploy-managed-online-endpoint.sh du répertoire cli, tandis que les fichiers de configuration YAML se trouvent dans le sous-répertoire endpoints/online/managed/sample/.

Notes

Les fichiers de configuration YAML pour les points de terminaison en ligne Kubernetes se trouvent dans le sous-répertoire endpoints/online/kubernetes/.

Définir le point de terminaison

Pour définir un point de terminaison, vous devez spécifier :

  • Nom du point de terminaison : Nom du point de terminaison. Il doit être unique au sein de la région Azure. Pour plus d’informations sur les règles de nommage, consultez limites de point de terminaison.
  • Mode d’authentification : méthode d’authentification pour le point de terminaison. Choisissez entre l’authentification basée sur une clé et celle basée sur un jeton Azure Machine Learning. Une clé n’expire pas, mais un jeton expire bien. Pour plus d’informations sur l’authentification, consultez S’authentifier auprès d’un point de terminaison en ligne.
  • Vous pouvez éventuellement ajouter une description et des étiquettes à votre point de terminaison.

Définir un nom d’un point de terminaison

Pour définir un nom de point de terminaison, exécutez la commande suivante (remplacez YOUR_ENDPOINT_NAME par un nom unique).

Pour Linux, exécutez cette commande :

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

Configurer le point de terminaison

L’extrait de code suivant montre le fichier endpoints/online/managed/sample/endpoint.yml :

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

La référence pour le format YAML du point de terminaison est décrite dans le tableau suivant. Pour savoir comment spécifier ces attributs, consultez la référence YAML du point de terminaison en ligne. Pour plus d’informations sur les limites liées aux points de terminaison gérés, consultez les limites pour les points de terminaison en ligne.

Clé Description
$schema (Facultatif) Schéma YAML. Pour voir toutes les options disponibles dans le fichier YAML, vous pouvez consulter le schéma dans l’extrait de code précédent avec un navigateur.
name Nom du point de terminaison.
auth_mode Utilisez key pour l’authentification basée sur les clés. Utilisez aml_token pour l’authentification Azure Machine Learning basée sur les jetons. Utilisez la commande az ml online-endpoint get-credentials pour récupérer le jeton le plus récent.

Définir le déploiement

Un déploiement est un ensemble de ressources nécessaires pour héberger le modèle qui effectue l’inférence réelle. Pour déployer un modèle, vous devez disposer des éléments suivants :

  • Fichiers de modèle (ou le nom et la version d’un modèle déjà inscrit dans votre espace de travail). Dans l’exemple, nous avons un modèle scikit-learn qui effectue une régression.
  • Un script de scoring, c’est-à-dire du code qui exécute le modèle sur une demande d’entrée donnée. Le script de scoring reçoit les données envoyées à un service web déployé et les passe au modèle. Le script exécute ensuite le modèle et retourne sa réponse au client. Le script de scoring est spécifique à votre modèle. Il doit comprendre les données que le modèle attend en tant qu’entrée et retourne en tant que sortie. Dans cet exemple, nous disposons d’un fichier score.py.
  • Environnement dans lequel votre modèle s’exécute. L’environnement peut être une image Docker avec des dépendances Conda ou un Dockerfile.
  • Paramètres pour spécifier le type d’instance et la capacité de mise à l’échelle.

Le tableau suivant décrit les attributs clés d’un déploiement :

Attribut Description
Nom Le nom du déploiement.
Nom du point de terminaison Nom du point de terminaison sous lequel créer le déploiement.
Modèle Modèle à utiliser pour le déploiement. Cette valeur peut être une référence à un modèle versionné existant dans l’espace de travail ou une spécification de modèle inline.
Chemin du code Le chemin d’accès du répertoire dans l’environnement de développement local qui contient tout le code source Python pour le scoring du modèle. Vous pouvez utiliser des répertoires et des packages imbriqués.
Script de scoring Le chemin relatif du fichier de scoring dans le répertoire de code source. Ce code Python doit avoir une fonction init() et une fonction run(). La fonction init() sera appelée une fois le modèle créé ou mis à jour (vous pouvez l’utiliser pour mettre en cache le modèle dans la mémoire, par exemple). La fonction run() est appelée à chaque appel du point de terminaison pour effectuer la notation et la prédiction réelles.
Environnement L’environnement pour héberger le modèle et le code. Cette valeur peut être une référence à un environnement versionné existant dans l’espace de travail ou une spécification d’environnement inline.
Type d’instance Taille de machine virtuelle à utiliser pour le déploiement. Pour obtenir la liste des tailles prises en charge, consultez la liste des références SKU des points de terminaison en ligne managés.
Nombre d’instances Nombre d’instances à utiliser pour le déploiement. Basez la valeur sur la charge de travail que vous attendez. Pour une haute disponibilité, nous vous recommandons de définir la valeur sur au moins 3. Nous réservons 20 % en plus pour effectuer des mises à niveau. Pour plus d’informations, consultez allocation de quota du nombre de machines virtuelles pour les déploiements.

Remarque

  • Le modèle et l’image conteneur (tels que définis dans Environnement) peuvent être référencés à nouveau à tout moment par le déploiement lorsque les instances derrière le déploiement passent par des correctifs de sécurité et/ou d’autres opérations de récupération. Si vous avez utilisé un modèle inscrit ou une image conteneur dans Azure Container Registry pour un déploiement et que vous avez supprimé le modèle ou l’image conteneur, les déploiements qui s’appuient sur ces ressources peuvent échouer lors de la nouvelle imagerie. Si vous avez supprimé le modèle ou l’image conteneur, assurez-vous que les déploiements dépendants sont recréés ou mis à jour avec un autre modèle ou image conteneur.
  • Le registre de conteneurs auquel l’environnement fait référence ne peut être privé que si l’identité du point de terminaison a l’autorisation d’y accéder via l’authentification Microsoft Entra et Azure RBAC. Pour la même raison, les registres Docker privés autres que Azure Container Registry ne sont pas pris en charge.

Configurer un déploiement

L’extrait de code suivant montre le fichier endpoints/online/managed/sample/blue-deployment.yml avec toutes les entrées nécessaires pour configurer un déploiement :

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

Notes

Dans le fichier blue-deployment.yml, nous avons spécifié les attributs de déploiement suivants :

  • model - Dans cet exemple, nous spécifions les propriétés de modèle inline avec path. Les fichiers de modèle sont automatiquement téléchargés et enregistrés avec un nom généré automatiquement.
  • environment - Dans cet exemple, nous avons des définitions inline qui incluent path. Nous utiliserons environment.docker.image pour l’image. Les dépendances conda_file seront installées au-dessus de l’image.

Pendant le déploiement, les fichiers locaux comme la source Python du modèle de scoring sont chargés à partir de l’environnement de développement.

Pour plus d’informations sur le schéma YAML, consultez le document Référence YAML sur les points de terminaison en ligne.

Notes

Pour utiliser Kubernetes comme cible de calcul à la place des points de terminaison gérés :

  1. Créez et attachez votre cluster Kubernetes comme cible de calcul à votre espace de travail Azure Machine Learning avec Azure Machine Learning Studio.
  2. Utilisez le code YAML de point de terminaison pour cibler Kubernetes à la place du code YAML de point de terminaison géré. Vous devrez modifier le code YAML pour remplacer la valeur de target par le nom de votre cible de calcul inscrite. Vous pouvez utiliser ce fichier deployment.yaml qui a des propriétés supplémentaires applicables au déploiement Kubernetes.

Toutes les commandes utilisées dans cet article (à l’exception de la surveillance du contrat SLA facultative et de l’intégration d’Azure Log Analytics) peuvent être utilisées avec des points de terminaison gérés ou avec des points de terminaison Kubernetes.

Enregistrement séparé de votre modèle et de votre environnement

Dans cet exemple, nous spécifions le path (l’emplacement à partir duquel charger les fichiers) inline. L’interface CLI charge automatiquement les fichiers et inscrit le modèle et l’environnement. En guise de bonne pratique pour la production, vous devez inscrire le modèle et l’environnement et spécifier séparément le nom et la version inscrits dans le code YAML. Utilisez le formulaire model: azureml:my-model:1 ou environment: azureml:my-env:1.

Pour effectuer l’inscription, vous pouvez extraire les définitions YAML de model et environment dans des fichiers YAML distincts et utiliser les commandes az ml model create et az ml environment create. Pour en savoir plus sur ces commandes, exécutez az ml model create -h et az ml environment create -h.

Pour plus d’informations sur l’enregistrement de votre modèle en tant que ressource, consultez Enregistrer votre modèle en tant que ressource dans Machine Learning à l’aide de la CLI. Pour plus d’informations sur la création d’un environnement, consultez Gérer les environnements Azure Machine Learning avec la CLI & SDK (v2).

Utilisation de différents types d’images et d’instances de processeur et GPU

La définition précédente dans le fichier blue-deployment.yml utilise une instance de type Standard_DS3_v2 à usage général et une image Docker non-GPU mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest. Pour le calcul GPU, choisissez une référence SKU de type de calcul GPU et une image Docker GPU.

Pour connaître les types d’instances à usage général et GPU pris en charge, consultez les SKU de machine virtuelle prises en charge par des points de terminaison en ligne managés. Pour obtenir la liste des images de base de processeur et GPU d’Azure ML, consultez Images de base Azure Machine Learning.

Notes

Pour utiliser Kubernetes au lieu de points de terminaison managés comme cible de calcul, consultez Présentation de la cible de calcul Kubernetes.

Identifier le chemin d’accès du modèle par rapport à AZUREML_MODEL_DIR

Lors du déploiement de votre modèle sur Azure Machine Learning, vous devez spécifier l’emplacement du modèle que vous souhaitez déployer dans le cadre de votre configuration de déploiement. Dans Azure Machine Learning, utilisez la variable d’environnement AZUREML_MODEL_DIR pour suivre le chemin d’accès à votre modèle. En identifiant le chemin d’accès du modèle par rapport à AZUREML_MODEL_DIR, vous pouvez déployer un ou plusieurs modèles stockés localement sur votre ordinateur ou déployer un modèle inscrit dans votre espace de travail Azure Machine Learning.

À titre d’illustration, nous faisons référence à la structure de dossiers locale suivante pour les deux premiers cas où vous déployez un modèle unique ou plusieurs modèles stockés localement :

A screenshot showing a folder structure containing multiple models.

Utiliser un modèle local unique dans un déploiement

Pour utiliser un modèle unique qui se trouve sur votre ordinateur local dans un déploiement, spécifiez le path au model dans votre fichier YAML de déploiement. Voici un exemple de fichier YAML de déploiement avec le chemin d’accès /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl :

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1

Une fois votre déploiement créé, la variable d’environnement AZUREML_MODEL_DIR pointe vers l’emplacement de stockage Azure où votre modèle est stocké. Par exemple, /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 contient le modèle sample_m1.pkl.

Dans votre script de scoring (score.py), vous pouvez charger votre modèle (ici, sample_m1.pkl) dans la fonction init() :

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "sample_m1.pkl") 
    model = joblib.load(model_path)

Utiliser plusieurs modèles locaux dans un déploiement

Même si Azure CLI, le Kit de développement logiciel (SDK) Python et d’autres outils clients ne vous laissent spécifier qu’un seul modèle par déploiement dans la définition du déploiement, vous pouvez toujours utiliser plusieurs modèles dans un déploiement en inscrivant un dossier de modèles contenant tous les modèles en tant que fichiers ou sous-répertoires.

Dans l’exemple de structure de dossiers précédent, notez la présence de plusieurs modèles dans le dossier models. Dans votre fichier YAML de déploiement, vous pouvez spécifier le chemin d’accès au dossier models comme suit :

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/ 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1

Une fois votre déploiement créé, la variable d’environnement AZUREML_MODEL_DIR pointe vers l’emplacement de stockage Azure où vos modèles sont stockés. Par exemple, /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 contient les modèles et la structure de fichiers.

Pour cet exemple, le contenu du dossier AZUREML_MODEL_DIR se présente comme suit :

A screenshot of the folder structure of the storage location for multiple models.

Dans votre script de scoring (score.py), vous pouvez charger vos modèles dans la fonction init(). Le code suivant charge le modèle sample_m1.pkl :

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "models","model_1","v1", "sample_m1.pkl ") 
    model = joblib.load(model_path)

Pour obtenir un exemple de déploiement de plusieurs modèles dans un même déploiement, consultez Déployer plusieurs modèles dans un même déploiement (exemple CLI) et Déployer plusieurs modèles dans un même déploiement (exemple SDK).

Conseil

Si vous avez plus de 1 500 fichiers à inscrire, envisagez de compresser les fichiers ou sous-répertoires au format .tar.gz lors de l’inscription des modèles. Pour consommer les modèles, vous pouvez décompresser les fichiers ou sous-répertoires dans la fonction init() du script de scoring. Sinon, quand vous inscrivez les modèles, définissez la propriété azureml.unpack sur True pour décompresser automatiquement les fichiers ou sous-répertoires. Dans les deux cas, la décompression se produit une fois dans l’étape d’initialisation.

Utiliser des modèles inscrits dans votre espace de travail Azure Machine Learning dans un déploiement

Pour utiliser un ou plusieurs modèles inscrits dans votre espace de travail Azure Machine Learning, spécifiez dans votre déploiement le nom du ou des modèles inscrits dans votre fichier YAML de déploiement. Par exemple, la configuration YAML de déploiement suivante spécifie azureml:local-multimodel:3 comme nom de model inscrit :

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: azureml:local-multimodel:3 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1

Pour cet exemple, considérez que local-multimodel:3 contient les artefacts de modèle suivants, que vous pouvez voir sous l’onglet Modèles dans Azure Machine Learning studio :

A screenshot of the folder structure showing the model artifacts of the registered model.

Une fois votre déploiement créé, la variable d’environnement AZUREML_MODEL_DIR pointe vers l’emplacement de stockage Azure où vos modèles sont stockés. Par exemple, /var/azureml-app/azureml-models/local-multimodel/3 contient les modèles et la structure de fichiers. AZUREML_MODEL_DIR pointe vers le dossier contenant la racine des artefacts de modèle. Dans cet exemple, le contenu du dossier AZUREML_MODEL_DIR se présente comme suit :

A screenshot of the folder structure showing multiple models.

Dans votre script de scoring (score.py), vous pouvez charger vos modèles dans la fonction init(). Par exemple, chargez le modèle diabetes.sav :

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR"), "models", "diabetes", "1", "diabetes.sav") 
    model = joblib.load(model_path)

Comprendre le script de scoring

Conseil

Le format du script de scoring pour les points de terminaison en ligne est le même que celui utilisé dans la version précédente de l’interface CLI et dans le SDK Python.

Comme indiqué précédemment, le script de scoring spécifié dans code_configuration.scoring_script doit avoir une fonction init() et une fonction run().

Cet exemple utilise le fichier score.py :score.py

import os
import logging
import json
import numpy
import joblib


def init():
    """
    This function is called when the container is initialized/started, typically after create/update of the deployment.
    You can write the logic here to perform init operations like caching the model in memory
    """
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Init complete")


def run(raw_data):
    """
    This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
    In the example we extract the data from the json input and call the scikit-learn model's predict()
    method and return the result back
    """
    logging.info("model 1: request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

La fonction init() est appelée lorsque le conteneur est initialisé ou démarré. Cette initialisation se produit généralement peu après la création ou la mise à jour du déploiement. Vous utilisez la fonction init pour écrire la logique des opérations d’initialisation globales telles que la mise en cache du modèle en mémoire (comme dans cet exemple).

La fonction run() est appelée à chaque appel du point de terminaison et effectue les opérations de scoring et de prédiction réelles. Dans cet exemple, nous allons extraire des données d’une entrée JSON, appeler la méthode predict() du modèle scikit-learn, puis retourner le résultat.

Déployer et déboguer localement à l’aide de points de terminaison locaux

Nous vous recommandons vivement de tester et d’exécuter votre point de terminaison localement en validant et en déboguant votre code et votre configuration avant de procéder au déploiement sur Azure. L’interface Azure CLI et le SDK Python prennent en charge les points de terminaison et les déploiements locaux, contrairement à Azure Machine Learning studio et au modèle ARM.

Pour effectuer un déploiement local, le moteur Docker doit être installé et en cours d’exécution. Le moteur Docker démarre généralement au démarrage de l’ordinateur. Si ce n’est pas le cas, vous pouvez dépanner le Moteur Docker.

Conseil

Vous pouvez utiliser le package Python du serveur HTTP d’inférence Azure Machine Learning pour déboguer votre script de scoring localement sans moteur Docker. Le débogage avec le serveur d’inférence vous aide à déboguer le script de scoring avant le déploiement sur des points de terminaison locaux afin de pouvoir déboguer sans être affecté par les configurations de conteneur de déploiement.

Remarque

Les points de terminaison locaux présentent les limitations suivantes :

  • Ils ne prennent pas en charge les règles de trafic, l’authentification et les paramètres de sonde.
  • Ils ne prennent en charge qu’un seul déploiement par point de terminaison.
  • Ils prennent uniquement en charge les fichiers de modèle local et l’environnement avec un fichier conda local. Si vous souhaitez tester des modèles inscrits, commencez par les télécharger à l’aide de l’interface CLI ou du SDK, puis utilisez path dans la définition de déploiement pour faire référence au dossier parent. Si vous voulez tester des environnements inscrits, vérifiez le contexte de l’environnement dans Azure Machine Learning Studio et préparez le fichier conda local à utiliser. L’exemple dans cet article illustre l’utilisation du modèle local et de l’environnement avec un fichier conda local, qui prend en charge le déploiement local.

Pour plus d’informations sur le débogage local des points de terminaison en ligne avant le déploiement sur Azure, consultez Déboguer les points de terminaison en ligne localement dans Visual Studio Code.

Déployer le modèle localement

Tout d’abord, créez un point de terminaison. Si vous le souhaitez, pour un point de terminaison local, vous pouvez ignorer cette étape et créer directement le déploiement (étape suivante), qui créera ensuite les métadonnées requises. Le déploiement de modèles localement est utile à des fins de développement et de test.

az ml online-endpoint create --local -n $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

À présent, créez un déploiement nommé blue sous le point de terminaison.

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

L’indicateur --local oriente l’interface CLI pour déployer le point de terminaison dans l’environnement Docker.

Conseil

Utilisez Visual Studio Code pour tester et déboguer vos points de terminaison localement. Pour plus d’informations, consultez Déboguer les points de terminaison en ligne localement dans Visual Studio Code.

Vérifier si le déploiement local a réussi

Vérifiez l’état pour voir si le modèle a été déployé sans erreur :

az ml online-endpoint show -n $ENDPOINT_NAME --local

Le résultat doit ressembler au JSON suivant. Le provisioning_state est Succeeded.

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

Le tableau suivant contient les valeurs possibles de provisioning_state :

State Description
Creating La ressource est en cours de création.
Mise à jour La ressource est en cours de mise à jour.
Suppression en cours La ressource est en cours de suppression.
Réussi L’opération de création/mise à jour a réussi.
Échec L’opération de création/mise à jour/suppression a échoué.

Appeler le point de terminaison local pour effectuer la notation des données avec votre modèle

Appelez le point de terminaison pour effectuer la notation du modèle à l’aide de la commande pratique invoke et en transmettant les paramètres de requête stockés dans un fichier JSON :

az ml online-endpoint invoke --local --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

Si vous souhaitez utiliser un client REST (par exemple, une boucle), vous devez disposer de l’URI de notation. Pour récupérer l’URI de notation, exécutez az ml online-endpoint show --local -n $ENDPOINT_NAME. Dans les données retournées, recherchez l’attribut scoring_uri. Des exemples de commandes curl sont disponibles plus loin dans ce document.

Rechercher dans les journaux la sortie de l’opération d’appel

Dans l’exemple fichier score.py, la méthode run() journalise une sortie dans la console.

Vous pouvez afficher cette sortie en utilisant la commande get-logs :

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

Déployer votre point de terminaison en ligne dans Azure

Ensuite, déployez votre point de terminaison en ligne dans Azure.

Déployer sur Azure

Pour créer le point de terminaison dans le cloud, exécutez le code suivant :

az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

Pour créer le déploiement nommé blue sous le point de terminaison, exécutez le code suivant :

az ml online-deployment create --name blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic

Ce déploiement peut prendre jusqu’à 15 minutes selon que l’environnement ou l’image sous-jacent(e) est généré(e) pour la première fois ou non. Les déploiements suivants qui utilisent le même environnement termineront le traitement plus rapidement.

Conseil

  • Si vous préférez ne pas bloquer votre console CLI, vous pouvez ajouter l’indicateur --no-wait à la commande. Toutefois, cela arrêtera l’affichage interactif de l’état du déploiement.

Important

L’indicateur --all-traffic dans la commande az ml online-deployment create ci-dessus alloue 100 % du trafic du point de terminaison au déploiement bleu nouvellement créé. Bien que cela soit utile à des fins de développement et de test, pour la production, vous souhaiterez peut-être ouvrir le trafic vers le nouveau déploiement via une commande explicite. Par exemple : az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100".

Conseil

Vérifiez l’état du point de terminaison

La commande show contient des informations dans provisioning_state pour le point de terminaison et le déploiement :

az ml online-endpoint show -n $ENDPOINT_NAME

Vous pouvez répertorier tous les points de terminaison dans l’espace de travail sous la forme d’un tableau à l’aide de la commande list :

az ml online-endpoint list --output table

Vérifier l’état du déploiement en ligne

Vérifiez les journaux pour voir si le modèle a été déployé sans erreur.

Pour voir la sortie de journal d’un conteneur, utilisez la commande CLI suivante :

az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

Par défaut, les journaux sont extraits du conteneur du serveur d’inférence. Pour voir les journaux du conteneur de l’initialiseur de stockage, ajoutez l’indicateur --container storage-initializer. Pour plus d’informations sur les journaux de déploiement, consultez Obtenir des journaux de conteneur.

Appeler le point de terminaison pour effectuer la notation des données avec votre modèle

Vous pouvez utiliser la commande invoke ou un client REST de votre choix pour appeler le point de terminaison et effectuer le scoring de certaines données :

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

L’exemple suivant montre comment récupérer la clé utilisée pour l’authentification auprès du point de terminaison :

Conseil

Vous pouvez contrôler quels principaux de sécurité Microsoft Entra peuvent obtenir la clé d’authentification en leur attribuant un rôle personnalisé qui autorise Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action et Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action. Pour plus d’informations, consultez Gérer l’accès à un espace de travail Azure Machine Learning.

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

Ensuite, utilisez la boucle pour noter les données.

SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

Notez que nous utilisons les commandes show et get-credentials pour récupérer les informations d’authentification. Notez également que nous utilisons l’indicateur --query pour filtrer les attributs sur les attributs nécessaires uniquement. Pour en apprendre davantage sur --query consultez Interroger la sortie de commande Azure CLI.

Pour visualiser les journaux d’appel, exécutez get-logs de nouveau.

Pour plus d’informations sur l’authentification avec un jeton, consultez S’authentifier sur des points de terminaison en ligne.

(Facultatif) Mettre à jour le déploiement

Si vous souhaitez mettre à jour le code, le modèle ou l’environnement, mettez à jour le fichier YAML et exécutez la commande az ml online-endpoint update.

Notes

Si vous mettez à jour le nombre d’instances (pour mettre à l’échelle votre déploiement) avec d’autres paramètres de modèle (comme le code, le modèle ou l’environnement) dans une même commande update, l’opération de mise à l’échelle est effectuée en premier, puis les autres mises à jour sont appliquées. Il est conseillé d’effectuer ces opérations séparément dans un environnement de production.

Pour comprendre comment update fonctionne :

  1. Ouvrez le fichier online/model-1/onlinescoring/score.py.

  2. Modifiez la dernière ligne de la fonction init() : après logging.info("Init complete"), ajoutez logging.info("Updated successfully").

  3. Enregistrez le fichier .

  4. Exécutez cette commande :

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

    Notes

    La mise à jour à l’aide de YAML est déclarative. Autrement dit, les modifications apportées dans le fichier YAML seront reflétées dans les ressources du Gestionnaire de ressource Azure sous-jacentes (points de terminaison et déploiements). Une approche déclarative facilite les GitOps : Toutes les modifications apportées aux points de terminaison et déploiements passent (même instance_count) par le fichier YAML.

    Conseil

    • Vous pouvez utiliser des paramètres de mise à jour génériques, tels que le paramètre --set, avec la commande CLI update pour remplacer les attributs dans votre YAML ou pour définir des attributs spécifiques sans les passer dans le fichier YAML. L’utilisation de --set pour les attributs uniques est particulièrement importante dans les scénarios de développement et de test. Par exemple, pour effectuer un scale-up de la valeur instance_count pour le premier déploiement, vous pouvez utiliser l’indicateur --set instance_count=2. Toutefois, étant donné que le code YAML n’est pas mis à jour, cette technique ne facilite pas les GitOps.
    • La spécification du fichier YAML n’est PAS obligatoire. Si vous souhaitez par exemple tester différents paramètres d’accès concurrentiel pour un déploiement donné, vous pouvez essayer quelque chose comme az ml online-deployment update -n blue -e my-endpoint --set request_settings.max_concurrent_requests_per_instance=4 environment_variables.WORKER_COUNT=4. Cela conserve toute la configuration existante, mais met uniquement à jour les paramètres spécifiés.

  5. Comme vous avez modifié la fonction init() qui s’exécute lors de la création ou de la mise à jour du point de terminaison, le message Updated successfully figure dans les journaux. Récupérez les journaux en exécutant :

    az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

La commande update fonctionne également avec les déploiements locaux. Utilisez la même commande az ml online-deployment update avec l’indicateur --local.

Notes

La mise à jour précédente du déploiement est un exemple de mise à jour propagée sur place.

  • Pour un point de terminaison en ligne managé, le déploiement est mis à jour vers la nouvelle configuration avec 20 % de nœuds à la fois. Autrement dit, si le déploiement compte 10 nœuds, 2 nœuds sont mis à jour à la fois.
  • Pour un point de terminaison en ligne Kubernetes, le système crée de manière itérative une instance de déploiement avec la nouvelle configuration et supprime l’ancienne.
  • Pour une utilisation en production, envisagez le déploiement bleu-vert qui offre une alternative plus sûre pour la mise à jour d’un service web.

(Facultatif) Configurer la mise à l’échelle automatique

La mise à l’échelle automatique exécute automatiquement la quantité appropriée de ressources pour gérer la charge sur votre application. Les points de terminaison en ligne managés prennent en charge la mise à l’échelle automatique via l’intégration à la fonctionnalité de mise à l’échelle automatique d’Azure Monitor. Pour configurer la mise à l’échelle automatique, consultez Mise à l’échelle automatique des points de terminaison en ligne.

(Facultatif) Surveiller le contrat SLA à l’aide d’Azure Monitor

Pour afficher les mesures et définir des alertes en fonction de votre contrat SLA, suivez les étapes décrites dans Analyser les points de terminaison en ligne.

(Facultatif) Intégrer à Log Analytics

La commande get-logs pour CLI ou la méthode get_logs pour SDK ne fournit que les quelques dernières centaines de lignes de journaux d’une instance sélectionnée automatiquement. Toutefois, Log Analytics offre un moyen de stocker et d’analyser durablement les journaux. Pour plus d’informations sur l’utilisation de la journalisation, consultez Monitorer les points de terminaison en ligne.

Supprimez le point de terminaison et le déploiement

Si vous n’envisagez pas d’utiliser le déploiement, vous devez le supprimer en exécutant le code suivant (cela supprime le point de terminaison et tous les déploiements sous-jacents) :

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait

Contenu connexe