Utiliser un conteneur personnalisé pour déployer un modèle sur un point de terminaison en ligne

APPLIES TO:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

Dans Azure Machine Learning, vous pouvez utiliser un conteneur personnalisé pour déployer un modèle sur un point de terminaison en ligne. Les déploiements de conteneurs personnalisés peuvent utiliser des serveurs web autres que le serveur Python Flask par défaut utilisé par Azure Machine Learning.

Lorsque vous utilisez un déploiement personnalisé, vous pouvez :

• Utilisez différents outils et technologies, tels que TensorFlow Serve (TF Serve), TorchServe, Triton Inference Server, le package Plumber R et l’image d’inférence Minimale d’Azure Machine Learning.
• Tirez toujours parti de la surveillance intégrée, de la mise à l’échelle, des alertes et de l’authentification proposées par Azure Machine Learning.

Cet article explique comment utiliser une image TF Service pour servir un modèle TensorFlow.

Prerequisites

• Un espace de travail Azure Machine Learning. Pour obtenir des instructions sur la création d’un espace de travail, consultez Créer l’espace de travail.

• Azure CLI et l’extension ml ou le Kit de développement logiciel (SDK) Python Azure Machine Learning v2 :

  Azure CLI

  Pour installer Azure CLI et l’extension ml , consultez Installer et configurer l’interface CLI (v2).

  Les exemples de cet article supposent que vous utilisez un interpréteur de commandes Bash ou un interpréteur de commandes compatible. Par exemple, vous pouvez utiliser un interpréteur de commandes sur un système Linux ou un sous-système Windows pour Linux.

  Python SDK

  Pour installer le kit SDK Python v2, utilisez la commande suivante :

  pip install azure-ai-ml azure-identity
  

  Pour mettre à jour une installation existante du Kit de développement logiciel (SDK) vers la version la plus récente, utilisez la commande suivante :

  pip install --upgrade azure-ai-ml azure-identity
  

  Pour plus d’informations, consultez la bibliothèque de client du package Azure Machine Learning pour Python.

• Un groupe de ressources Azure qui contient votre espace de travail et auquel vous ou votre principal de service disposez d’un accès Contributeur. Si vous utilisez les étapes décrites dans Créer l’espace de travail pour configurer votre espace de travail, vous répondez à cette exigence.

• Docker Engine, installed and running locally. This prerequisite is highly recommended. Vous devez l'utiliser pour déployer un modèle localement, et c'est utile pour le débogage.

Deployment examples

The following table lists deployment examples that use custom containers and take advantage of various tools and technologies.

Example	Script de l'Azure CLI	Description
minimal/multimodel	deploy-custom-container-minimal-multimodel	Déploie plusieurs modèles sur un seul déploiement en étendant l’image minimale d’inférence Azure Machine Learning.
minimal/single-model	deploy-custom-container-minimal-single-model	Déploie un modèle unique en étendant l’image minimale d’inférence Azure Machine Learning.
mlflow/multideployment-scikit	deploy-custom-container-mlflow-multideployment-scikit	Déploie deux modèles MLFlow avec des exigences Python différentes sur deux déploiements distincts derrière un seul point de terminaison. Utilise l'image minimale d'inférence d'Azure Machine Learning.
r/multimodel-plumber	deploy-custom-container-r-multimodel-plumber	Déploie trois modèles de régression sur un point de terminaison. Utilise le package Plumber R.
tfserving/half-plus-two	deploy-custom-container-tfserving-half-plus-two	Déploie un modèle Half Plus Two à l’aide d’un conteneur personnalisé TF Service. Utilise le processus d'enregistrement du modèle standard.
tfserving/half-plus-two-integrated	deploy-custom-container-tfserving-half-plus-two-integrated	Déploie un modèle Half Plus Two à l’aide d’un conteneur personnalisé TF Service avec le modèle intégré à l’image.
torchserve/densenet	deploy-custom-container-torchserve-densenet	Déploie un modèle unique à l’aide d’un conteneur personnalisé TorchServe.
triton/single-model	deploy-custom-container-triton-single-model	Déploie un modèle Triton à l’aide d’un conteneur personnalisé.

Cet article vous montre comment utiliser l’exemple tfserving/half-plus-two.

Warning

Les équipes de support Microsoft peuvent ne pas être en mesure de résoudre les problèmes causés par une image personnalisée. Si vous rencontrez des problèmes, vous pouvez être invité à utiliser l’image par défaut ou l’une des images que Microsoft fournit pour déterminer si le problème est spécifique à votre image.

Télécharger le code source

The steps in this article use code samples from the azureml-examples repository. Utilisez les commandes suivantes pour cloner le référentiel :

Azure CLI

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

Python SDK

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

Dans le référentiel d’exemples, la plupart des exemples Python se trouvent sous le dossier sdk/python. Pour cet article, accédez plutôt au dossier cli. La structure de dossiers sous le dossier cli est légèrement différente de la structure sdk/python dans ce cas. La plupart des étapes décrites dans cet article nécessitent la structure cli.

Pour suivre les exemples d’étapes, consultez un notebook Jupyter dans le référentiel d’exemples. Toutefois, dans les sections suivantes de ce notebook, les étapes s’exécutent à partir du dossier azureml-examples/sdk/python au lieu du dossier cli :

• 3. Test locally
• 5. Tester le point de terminaison avec des exemples de données

Initialiser des variables d’environnement

Pour utiliser un modèle TensorFlow, vous avez besoin de plusieurs variables d’environnement. Exécutez les commandes suivantes pour définir ces variables :

BASE_PATH=endpoints/online/custom-container/tfserving/half-plus-two
AML_MODEL_NAME=tfserving-mounted
MODEL_NAME=half_plus_two
MODEL_BASE_PATH=/var/azureml-app/azureml-models/$AML_MODEL_NAME/1

Télécharger un modèle TensorFlow

Téléchargez et décompressez un modèle qui divise une valeur d’entrée par deux et ajoute deux au résultat :

wget https://aka.ms/half_plus_two-model -O $BASE_PATH/half_plus_two.tar.gz
tar -xvf $BASE_PATH/half_plus_two.tar.gz -C $BASE_PATH

Tester une image de service TF localement

Utilisez Docker pour exécuter votre image localement pour les tests :

docker run --rm -d -v $PWD/$BASE_PATH:$MODEL_BASE_PATH -p 8501:8501 \
 -e MODEL_BASE_PATH=$MODEL_BASE_PATH -e MODEL_NAME=$MODEL_NAME \
 --name="tfserving-test" docker.io/tensorflow/serving:latest
sleep 10

Envoyer des demandes de liveness et de scoring à l’image

Envoyez une demande liveness pour vérifier que le processus à l’intérieur du conteneur est en cours d’exécution. Vous devez obtenir un code d’état de réponse de 200 OK.

curl -v http://localhost:8501/v1/models/$MODEL_NAME

Envoyez une demande de scoring pour vérifier que vous pouvez obtenir des prédictions sur les données non étiquetées :

curl --header "Content-Type: application/json" \
  --request POST \
  --data @$BASE_PATH/sample_request.json \
  http://localhost:8501/v1/models/$MODEL_NAME:predict

Arrêter l’image

Lorsque vous terminez le test localement, arrêtez l’image :

docker stop tfserving-test

Déployer votre point de terminaison en ligne dans Azure

Pour déployer votre point de terminaison en ligne sur Azure, effectuez les étapes décrites dans les sections suivantes.

Azure CLI

Créer des fichiers YAML pour votre point de terminaison et votre déploiement

Vous pouvez configurer votre déploiement cloud à l’aide de YAML. Par exemple, pour configurer votre point de terminaison, vous pouvez créer un fichier YAML nommé tfserving-endpoint.yml qui contient les lignes suivantes :

$schema: https://azuremlsdk2.blob.core.windows.net/latest/managedOnlineEndpoint.schema.json
name: tfserving-endpoint
auth_mode: aml_token

Pour configurer votre déploiement, vous pouvez créer un fichier YAML nommé tfserving-deployment.yml qui contient les lignes suivantes :

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: tfserving-deployment
endpoint_name: tfserving-endpoint
model:
  name: tfserving-mounted
  version: <model-version>
  path: ./half_plus_two
environment_variables:
  MODEL_BASE_PATH: /var/azureml-app/azureml-models/tfserving-mounted/<model-version>
  MODEL_NAME: half_plus_two
environment:
  #name: tfserving
  #version: 1
  image: docker.io/tensorflow/serving:latest
  inference_config:
    liveness_route:
      port: 8501
      path: /v1/models/half_plus_two
    readiness_route:
      port: 8501
      path: /v1/models/half_plus_two
    scoring_route:
      port: 8501
      path: /v1/models/half_plus_two:predict
instance_type: Standard_DS3_v2
instance_count: 1

Python SDK

Se connecter à votre espace de travail Azure Machine Learning

Pour configurer votre espace de travail Azure Machine Learning, procédez comme suit :

1. Importez les bibliothèques nécessaires :

   # Import the required libraries.
   from azure.ai.ml import MLClient
   from azure.ai.ml.entities import (
      ManagedOnlineEndpoint,
      ManagedOnlineDeployment,
      Model,
      Environment,
      CodeConfiguration,
   )
   from azure.identity import DefaultAzureCredential
   

2. Configurez les paramètres de l’espace de travail et obtenez un handle pour l’espace de travail :

   # Enter information about your Azure Machine Learning workspace.
   subscription_id = "<subscription-ID>"
   resource_group = "<resource-group-name>"
   workspace = "<Azure-Machine-Learning-workspace-name>"
   
   # Get a handle to the workspace.
   ml_client = MLClient(
     DefaultAzureCredential(), subscription_id, resource_group, workspace
   )
   

Pour plus d’informations, consultez Déployer et scorer un modèle Machine Learning en utilisant un point de terminaison en ligne.

Configurer un point de terminaison en ligne

Utilisez le code suivant pour configurer un point de terminaison en ligne. Gardez à l’esprit les points suivants :

• Le nom du point de terminaison doit être unique dans sa région Azure. En outre, un nom de point de terminaison doit commencer par une lettre et se compose uniquement de caractères alphanumériques et de traits d’union. Pour plus d’informations sur les règles de nommage, consultez les points de terminaison en ligne Azure Machine Learning et les points de terminaison par lots.
• Pour la valeur, utilisez-la auth_mode pour l’authentification key basée sur des clés. Utilisez aml_token pour l’authentification Azure Machine Learning basée sur les jetons. Une clé n’expire pas, mais un jeton expire bien. Pour plus d’informations sur l’authentification, consultez Authentifier les clients pour les points de terminaison en ligne.
• La description et les balises sont facultatives.

# To create a unique endpoint name, use a time stamp of the current date and time.
import datetime

online_endpoint_name = "endpoint-" + datetime.datetime.now().strftime("%m%d%H%M%f")

# Configure an online endpoint.
endpoint = ManagedOnlineEndpoint(
    name=online_endpoint_name,
    description="A sample online endpoint",
    auth_mode="key",
    tags={"env": "dev"},
)

Configurer un déploiement en ligne

Un déploiement est un ensemble de ressources requises pour héberger le modèle qui effectue l’inférence réelle. Vous pouvez utiliser la ManagedOnlineDeployment classe pour configurer un déploiement pour votre point de terminaison. Le constructeur de cette classe utilise les paramètres suivants :

• name : nom du déploiement.
• endpoint_name: nom du point de terminaison sous lequel créer le déploiement.
• model: 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.
• environment: environnement à utiliser pour le déploiement. Cette valeur peut être une référence à un environnement versionné existant dans l’espace de travail ou une spécification d’environnement inline.
• environment_variables: variables d’environnement définies pendant le déploiement.
  • MODEL_BASE_PATH: chemin d’accès au dossier parent qui contient un dossier pour votre modèle.
  • MODEL_NAME: nom de votre modèle.
• instance_type: 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.
• instance_count: nombre d’instances à utiliser pour le déploiement.

Utilisez le code suivant pour configurer un déploiement pour votre point de terminaison :

# create a blue deployment
model = Model(name="tfserving-mounted", version="1", path="half_plus_two")

env = Environment(
    image="docker.io/tensorflow/serving:latest",
    inference_config={
        "liveness_route": {"port": 8501, "path": "/v1/models/half_plus_two"},
        "readiness_route": {"port": 8501, "path": "/v1/models/half_plus_two"},
        "scoring_route": {"port": 8501, "path": "/v1/models/half_plus_two:predict"},
    },
)

blue_deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=online_endpoint_name,
    model=model,
    environment=env,
    environment_variables={
        "MODEL_BASE_PATH": "/var/azureml-app/azureml-models/tfserving-mounted/1",
        "MODEL_NAME": "half_plus_two",
    },
    instance_type="Standard_DS2_v2",
    instance_count=1,
)

Les sections suivantes décrivent les concepts importants relatifs aux paramètres YAML et Python.

Base image

Dans la environment section YAML ou le Environment constructeur en Python, vous spécifiez l’image de base comme paramètre. Cet exemple utilise docker.io/tensorflow/serving:latest comme image valeur.

Si vous inspectez votre conteneur, vous pouvez voir que ce serveur utilise ENTRYPOINT des commandes pour démarrer un script de point d’entrée. Ce script prend des variables d’environnement telles que MODEL_BASE_PATH et MODEL_NAME, et expose des ports tels que 8501. Ces détails concernent tous ce serveur et vous pouvez utiliser ces informations pour déterminer comment définir votre déploiement. Par exemple, si vous définissez les variables d'environnement MODEL_BASE_PATH et MODEL_NAME dans votre définition de déploiement, TF Serving utilise ces valeurs pour lancer le serveur. De même, si vous définissez le port de chaque itinéraire dans la définition de déploiement vers 8501, les demandes utilisateur adressées à ces itinéraires sont correctement routées vers le serveur de service TF.

Cet exemple est basé sur l'application TF Serving. Toutefois, vous pouvez utiliser n’importe quel conteneur qui reste à jour et répond aux demandes qui vont à la vie, à la préparation et aux itinéraires de scoring. Pour savoir comment former un fichier Dockerfile pour créer un conteneur, vous pouvez vous référer à d’autres exemples. Certains serveurs utilisent des instructions CMD au lieu des instructions ENTRYPOINT.

Paramètre inference_config

Dans la section ou la environmentEnvironment classe, inference_config est un paramètre. Il spécifie le port et le chemin d’accès pour trois types d’itinéraires : liveness, readiness et scoring routes. Le inference_config paramètre est requis si vous souhaitez exécuter votre propre conteneur avec un point de terminaison en ligne managé.

Itinéraires de préparation et itinéraires liveness

Certains serveurs d’API permettent de vérifier l’état du serveur. Il existe deux types d’itinéraires que vous pouvez spécifier pour vérifier l’état :

• Liveness routes: To check whether a server is running, you use a liveness route.
• Readiness routes: To check whether a server is ready to do work, you use a readiness route.

Dans le contexte de l’inférence de Machine Learning, un serveur peut répondre avec un code d’état de 200 OK à une demande liveness avant de charger un modèle. Le serveur peut répondre avec un code d’état de 200 OK à une demande de préparation uniquement après avoir chargé le modèle en mémoire.

Pour plus d’informations sur les sondes liveness et readiness, consultez Configurer Liveness, Readiness et Startup Probes.

Le serveur d’API que vous choisissez détermine les itinéraires liveness et readiness. Vous identifiez ce serveur à une étape antérieure lorsque vous testez le conteneur localement. Dans cet article, l’exemple de déploiement utilise le même chemin pour les itinéraires liveness et readiness, car TF Service définit uniquement un itinéraire liveness. Pour obtenir d’autres façons de définir les itinéraires, consultez d’autres exemples.

Scoring routes

Le serveur d'API que vous utilisez offre un moyen de recevoir les données sur lesquelles travailler. Dans le contexte de l’inférence de Machine Learning, un serveur reçoit les données d’entrée via un itinéraire spécifique. Identifiez cet itinéraire pour votre serveur d’API lorsque vous testez le conteneur localement dans une étape antérieure. Spécifiez cet itinéraire comme itinéraire de scoring lorsque vous définissez le déploiement à créer.

La création réussie du déploiement met également à jour le paramètre scoring_uri du point de terminaison. Vous pouvez vérifier ce fait en exécutant la commande suivante : az ml online-endpoint show -n <endpoint-name> --query scoring_uri.

Localiser le modèle monté

When you deploy a model as an online endpoint, Azure Machine Learning mounts your model to your endpoint. Lorsque le modèle est monté, vous pouvez déployer de nouvelles versions du modèle sans avoir à créer une image Docker. By default, a model registered with the name my-model and version 1 is located on the following path inside your deployed container: /var/azureml-app/azureml-models/my-model/1.

Par exemple, tenez compte de la configuration suivante :

• Structure de répertoires sur votre ordinateur local de /azureml-examples/cli/endpoints/online/custom-container
• Nom du modèle de half_plus_two

Azure CLI

Supposons que votre fichier tfserving-deployment.yml contient les lignes suivantes dans sa model section. Dans cette section, la name valeur fait référence au nom que vous utilisez pour inscrire le modèle dans Azure Machine Learning.

model:
    name: tfserving-mounted
    version: 1
    path: ./half_plus_two

Python SDK

Supposons que vous utilisez le code suivant pour créer une Model classe. Dans ce code, la name valeur fait référence au nom que vous utilisez pour inscrire le modèle dans Azure Machine Learning.

model = Model(name="tfserving-mounted", version="1", path="half_plus_two")

Dans ce cas, lorsque vous créez un déploiement, votre modèle se trouve sous le dossier suivant : /var/azureml-app/azureml-models/tfserving-mounted/1.

Vous pouvez éventuellement configurer votre model_mount_path valeur. En ajustant ce paramètre, vous pouvez modifier le chemin d’accès où le modèle est monté.

Important

La model_mount_path valeur doit être un chemin absolu valide dans Linux (dans le système d’exploitation invité de l’image conteneur).

Important

model_mount_path est utilisable uniquement dans le scénario BYOC (Apportez votre propre conteneur). Dans le scénario BYOC, l’environnement utilisé par le déploiement en ligne doit avoir inference_config un paramètre configuré. Vous pouvez utiliser Azure ML CLI ou le Kit de développement logiciel (SDK) Python pour spécifier un inference_config paramètre lors de la création de l’environnement. Actuellement, l’interface utilisateur de Studio ne prend pas en charge la spécification de ce paramètre.

Lorsque vous modifiez la valeur de model_mount_path, vous devez également mettre à jour la variable d’environnement MODEL_BASE_PATH . Définissez MODEL_BASE_PATH sur la même valeur que model_mount_path pour éviter un déploiement ayant échoué en raison d’une erreur concernant le chemin d’accès de base introuvable.

Azure CLI

Par exemple, vous pouvez ajouter le model_mount_path paramètre à votre fichier tfserving-deployment.yml. Vous pouvez également mettre à jour la MODEL_BASE_PATH valeur dans ce fichier :

name: tfserving-deployment
endpoint_name: tfserving-endpoint
model:
  name: tfserving-mounted
  version: 1
  path: ./half_plus_two
model_mount_path: /var/tfserving-model-mount
environment_variables:
  MODEL_BASE_PATH: /var/tfserving-model-mount
...

Python SDK

Par exemple, vous pouvez ajouter le model_mount_path paramètre à votre ManagedOnlineDeployment classe. Vous pouvez également mettre à jour la MODEL_BASE_PATH valeur dans ce code :

blue_deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=online_endpoint_name,
    model=model,
    environment=env,
    model_mount_path="/var/tfserving-model-mount",
    environment_variables={
        "MODEL_BASE_PATH": "/var/tfserving-model-mount",
    ...
)

Dans votre déploiement, votre modèle se trouve ensuite sur /var/tfserving-model-mount/tfserving-mounted/1. Il n’est plus sous azureml-app/azureml-models, mais sous le chemin de montage que vous spécifiez :

Créer votre point de terminaison et votre déploiement

Azure CLI

Après avoir construit votre fichier YAML, utilisez la commande suivante pour créer votre point de terminaison :

az ml online-endpoint create --name tfserving-endpoint -f endpoints/online/custom-container/tfserving/half-plus-two/tfserving-endpoint.yml

Utilisez la commande suivante pour créer votre déploiement. Cette étape peut durer quelques minutes.

az ml online-deployment create --name tfserving-deployment -f endpoints/online/custom-container/tfserving/half-plus-two/tfserving-deployment.yml --all-traffic

Python SDK

Utilisez le code suivant pour créer le point de terminaison dans l’espace de travail. Ce code utilise l'instance de MLClient que vous avez créée précédemment. La begin_create_or_update méthode démarre la création du point de terminaison. Elle retourne ensuite une réponse de confirmation pendant la création du point de terminaison.

ml_client.begin_create_or_update(endpoint)

Créez le déploiement en exécutant le code suivant :

ml_client.begin_create_or_update(blue_deployment)

Appeler le point de terminaison

Une fois votre déploiement terminé, effectuez une requête d'évaluation auprès du point de terminaison déployé.

Azure CLI

RESPONSE=$(az ml online-endpoint invoke -n $ENDPOINT_NAME --request-file $BASE_PATH/sample_request.json)

Python SDK

Utilisez l’instance de MLClient que vous avez créée précédemment pour obtenir un accès au point de terminaison. Utilisez ensuite la invoke méthode et les paramètres suivants pour appeler le point de terminaison :

• endpoint_name: nom du point de terminaison
• request_file: fichier qui contient les données de requête
• deployment_name: nom du déploiement à tester dans le point de terminaison

For the request data, you can use a sample JSON file from the example repository.

# Test the blue deployment by using some sample data.
response = ml_client.online_endpoints.invoke(
    endpoint_name=online_endpoint_name,
    deployment_name="blue",
    request_file="sample_request.json",
)

Supprimer le point de terminaison

Si vous n’avez plus besoin de votre point de terminaison, exécutez la commande suivante pour la supprimer :

Azure CLI

az ml online-endpoint delete --name tfserving-endpoint

Python SDK

ml_client.online_endpoints.begin_delete(name=online_endpoint_name)

Related content

• Effectuer un lancement sécurisé de nouveaux déploiements pour l’inférence en temps réel
• Résoudre les problèmes de déploiement et d'évaluation des points de terminaison en ligne
• Exemple de Torch serve