Lancement progressif de modèles MLflow sur des points de terminaison en ligne

Article
09/03/2024

Dans cet article, vous allez découvrir comment mettre à jour, puis déployer progressivement des modèles MLflow sur des points de terminaison en ligne sans perturber le service. Vous allez utiliser le déploiement bleu-vert, également appelé stratégie de lancement sécurisé, pour introduire une nouvelle version d’un service web en production. Cette stratégie vous permettra de déployer votre nouvelle version du service web sur un petit sous-ensemble d’utilisateurs ou de demandes avant de le déployer complètement.

À propos de cet exemple

Les points de terminaison en ligne suivent le concept de point de terminaison et de déploiement. Un point de terminaison représente l’API que les clients utilisent pour consommer le modèle, tandis que le déploiement indique l’implémentation spécifique de cette API. Cette distinction permet aux utilisateurs de dissocier l’API de l’implémentation et de modifier l’implémentation sous-jacente sans affecter le consommateur. Cet exemple utilise ces concepts pour mettre à jour le modèle déployé dans les points de terminaison sans interrompre le service.

Le modèle que nous allons déployer est basé sur le jeu de données UCI Heart Disease. La base de données contient 76 attributs, mais nous utilisons un sous-ensemble de 14 d’entre eux. Le modèle tente de prédire la présence de maladie cardiaque chez un patient. Il est entier compris entre 0 (aucune présence de maladie) et 1 (présence de maladie). Il a été entraîné à l’aide d’un classifieur XGBBoost et tout le prétraitement requis a été empaqueté en tant que pipeline scikit-learn, ce qui fait de ce modèle un pipeline de bout en bout qui passe des données brutes aux prédictions.

Les informations de cet article sont basées sur des exemples de code contenus dans le référentiel azureml-examples. Pour exécuter les commandes localement sans avoir à copier/coller les fichiers, clonez le dépôt, puis remplacez les répertoires par sdk/using-mlflow/deploy.

Suivre dans les notebooks Jupyter

Vous pouvez suivre cet exemple dans les notebooks suivants. Dans le dépôt cloné, ouvrez le notebook : mlflow_sdk_online_endpoints_progresive.ipynb.

Prérequis

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

Un abonnement Azure. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer. Essayez la version gratuite ou payante d’Azure Machine Learning.
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 que vous puissiez 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/*. Pour plus d’informations, consultez Gérer l’accès à un espace de travail Azure Machine Learning.

En outre, vous devez :

Installer l’interface Azure CLI et l’extension ml pour l’interface Azure CLI. Pour plus d’informations, consultez Installer, configurer et utiliser l’interface CLI (v2).

Installez le package mlflow du Kit de développement logiciel (SDK) Mlflow et le plug-in Azure Machine Learning pour MLflow azureml-mlflow.
```
pip install mlflow azureml-mlflow
```
En cas d’exécution en dehors de la capacité de calcul Azure Machine Learning, configurez l’URI de suivi MLflow ou l’URI de registre de MLflow pour qu’il pointe vers l’espace de travail sur lequel vous travaillez. Découvrez comment configurer MLflow pour Azure Machine Learning.

Se connecter à un espace de travail

Tout d’abord, nous allons nous connecter à l’espace de travail Azure Machine Learning sur lequel nous allons travailler.

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

L’espace de travail est la ressource de niveau supérieur pour Azure Machine Learning. Il fournit un emplacement centralisé dans lequel exploiter tous les artefacts que vous créez lorsque vous utilisez Azure Machine Learning. Dans cette section, nous allons nous connecter à l’espace de travail dans lequel vous allez effectuer des tâches de déploiement.

Importez les bibliothèques nécessaires :

from azure.ai.ml import MLClient, Input
from azure.ai.ml.entities import ManagedOnlineEndpoint, ManagedOnlineDeployment, Model
from azure.ai.ml.constants import AssetTypes
from azure.identity import DefaultAzureCredential

Configurez les détails de l’espace de travail et obtenez un handle pour l’espace de travail :

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)

Importer les bibliothèques nécessaires

import json
import mlflow
import requests
import pandas as pd
from mlflow.deployments import get_deploy_client

Configurez le client MLflow et le client de déploiement :

mlflow_client = mlflow.MLflowClient()
deployment_client = get_deploy_client(mlflow.get_tracking_uri())

Inscription du modèle dans le registre

Vérifiez que votre modèle est inscrit dans le registre Azure Machine Learning. Le déploiement de modèles non inscrits n’est pas pris en charge dans Azure Machine Learning. Vous pouvez inscrire un nouveau modèle à l’aide du kit de développement logiciel (SDK) MLflow :

MODEL_NAME='heart-classifier'
az ml model create --name $MODEL_NAME --type "mlflow_model" --path "model"

model_name = 'heart-classifier'
model_local_path = "model"

model = ml_client.models.create_or_update(
     Model(name=model_name, path=model_local_path, type=AssetTypes.MLFLOW_MODEL)
)

model_name = 'heart-classifier'
model_local_path = "model"

registered_model = mlflow_client.create_model_version(
    name=model_name, source=f"file://{model_local_path}"
)
version = registered_model.version

Créez un point de terminaison en ligne

Les points de terminaison en ligne sont des points de terminaison utilisés pour l’inférence en ligne (en temps réel). Les points de terminaison en ligne contiennent des déploiements prêts à recevoir des données des clients et pouvant renvoyer des réponses en temps réel.

Nous allons exploiter cette fonctionnalité en déployant plusieurs versions du même modèle sous le même point de terminaison. Mais le nouveau déploiement recevra 0 % du trafic pour commencer. Une fois que nous sommes sûrs que le nouveau modèle fonctionne correctement, nous allons déplacer progressivement le trafic d’un déploiement à l’autre.

Les points de terminaison nécessitent un nom, qui doit être unique dans la même région. Assurons-nous d’en créer un qui n’existe pas :

ENDPOINT_SUFIX=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w ${1:-5} | head -n 1)
ENDPOINT_NAME="heart-classifier-$ENDPOINT_SUFIX"

import random
import string

# Creating a unique endpoint name by including a random suffix
allowed_chars = string.ascii_lowercase + string.digits
endpoint_suffix = "".join(random.choice(allowed_chars) for x in range(5))
endpoint_name = "heart-classifier-" + endpoint_suffix

print(f"Endpoint name: {endpoint_name}")

import random
import string

# Creating a unique endpoint name by including a random suffix
allowed_chars = string.ascii_lowercase + string.digits
endpoint_suffix = "".join(random.choice(allowed_chars) for x in range(5))
endpoint_name = "heart-classifier-" + endpoint_suffix

print(f"Endpoint name: {endpoint_name}")

Configurer le point de terminaison

endpoint.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: heart-classifier-edp
auth_mode: key

endpoint = ManagedOnlineEndpoint(
    name=endpoint_name,
    description="An endpoint to serve predictions of the UCI heart disease problem",
    auth_mode="key",
)

Nous pouvons configurer les propriétés de ce point de terminaison à l’aide d’un fichier de configuration. Nous configurons le mode d’authentification du point de terminaison pour en faire une « clé » dans l’exemple suivant :

endpoint_config = {
    "auth_mode": "key",
    "identity": {
        "type": "system_assigned"
    }
}

Écrivons cette configuration dans un fichier JSON :

endpoint_config_path = "endpoint_config.json"
with open(endpoint_config_path, "w") as outfile:
    outfile.write(json.dumps(endpoint_config))

Créez le point de terminaison :

az ml online-endpoint create -n $ENDPOINT_NAME -f endpoint.yml

ml_client.online_endpoints.begin_create_or_update(endpoint).result()

endpoint = deployment_client.create_endpoint(
    name=endpoint_name,
    config={"endpoint-config-file": endpoint_config_path},
)

Obtention du secret d’authentification pour le point de terminaison.
```
ENDPOINT_SECRET_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME | jq -r ".accessToken")
```
```
endpoint_secret_key = ml_client.online_endpoints.list_keys(
    name=endpoint_name
).access_token
```
Cette fonctionnalité n’est pas disponible dans le Kit de développement logiciel (SDK) MLflow. Accédez à Azure Machine Learning studio, puis au point de terminaison pour y récupérer la clé secrète.

Créer un déploiement bleu

À ce stade, le point de terminaison est vide. Il ne contient aucun déploiement. Créons le premier déploiement en déployant le même modèle que celui sur lequel nous travaillions auparavant. Nous appellerons ce déploiement « par défaut », représentant notre « déploiement bleu ».

Configurer le déploiement

blue-deployment.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: default
endpoint_name: heart-classifier-edp
model: azureml:heart-classifier@latest
instance_type: Standard_DS2_v2
instance_count: 1

blue_deployment_name = "default"

Configurez la configuration matérielle requise de votre déploiement :

blue_deployment = ManagedOnlineDeployment(
    name=blue_deployment_name,
    endpoint_name=endpoint_name,
    model=model,
    instance_type="Standard_DS2_v2",
    instance_count=1,
)

Si votre point de terminaison n’a pas de connectivité de sortie, utilisez l’empaquetage de modèle (préversion) en incluant l’argument with_package=True :

blue_deployment = ManagedOnlineDeployment(
    name=blue_deployment_name,
    endpoint_name=endpoint_name,
    model=model,
    instance_type="Standard_DS2_v2",
    instance_count=1,
    with_package=True,
)

blue_deployment_name = "default"

Pour spécifier la configuration matérielle requise de votre déploiement, vous devez créer un fichier JSON avec la configuration souhaitée :

deploy_config = {
    "instance_type": "Standard_DS2_v2",
    "instance_count": 1,
}

Notes

Pour obtenir la spécification complète de cette configuration, consultez Schéma de déploiement en ligne managé (v2).

Écrivez la configuration dans un fichier :

deployment_config_path = "deployment_config.json"
with open(deployment_config_path, "w") as outfile:
    outfile.write(json.dumps(deploy_config))

Créer le déploiement

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

Si votre point de terminaison n’a pas de connectivité de sortie, utilisez l’empaquetage de modèle (préversion) en incluant l’indicateur --with-package :

az ml online-deployment create --with-package --endpoint-name $ENDPOINT_NAME -f blue-deployment.yml --all-traffic

Conseil

Nous définissons l’indicateur --all-traffic dans la commande create, qui affectera tout le trafic au nouveau déploiement.

ml_client.online_deployments.begin_create_or_update(blue_deployment).result()

blue_deployment = deployment_client.create_deployment(
    name=blue_deployment_name,
    endpoint=endpoint_name,
    model_uri=f"models:/{model_name}/{version}",
    config={"deploy-config-file": deployment_config_path},
)

Attribuer tout le trafic au déploiement

Jusqu’à présent, le point de terminaison a un déploiement, mais aucun trafic ne lui est attribué. Nous allons le lui attribuer maintenant.
Cette étape n’est pas nécessaire avec l’interface Azure CLI, car nous avons utilisé --all-traffic au moment de la création.
```
endpoint.traffic = { blue_deployment_name: 100 }
```
```
traffic_config = {"traffic": {blue_deployment_name: 100}}
```
Écrivez la configuration dans un fichier :
```
traffic_config_path = "traffic_config.json"
with open(traffic_config_path, "w") as outfile:
    outfile.write(json.dumps(traffic_config))
```
Mettez à jour la configuration du point de terminaison :
Cette étape n’est pas nécessaire avec l’interface Azure CLI, car nous avons utilisé --all-traffic au moment de la création.
```
ml_client.begin_create_or_update(endpoint).result()
```
```
deployment_client.update_endpoint(
    endpoint=endpoint_name,
    config={"endpoint-config-file": traffic_config_path},
)
```

Créer un exemple d’entrée pour tester le déploiement

sample.yml

{
    "input_data": {
        "columns": [
            "age",
            "sex",
            "cp",
            "trestbps",
            "chol",
            "fbs",
            "restecg",
            "thalach",
            "exang",
            "oldpeak",
            "slope",
            "ca",
            "thal"
        ],
        "data": [
            [ 48, 0, 3, 130, 275, 0, 0, 139, 0, 0.2, 1, 0, "normal" ]
        ]
    }
}

Le code suivant échantillonne 5 observations du jeu de données d’apprentissage, supprime la colonne target (comme le modèle va le prédire), puis crée une requête dans le fichier sample.json qui peut être utilisée avec le déploiement du modèle.

samples = (
    pd.read_csv("data/heart.csv")
    .sample(n=5)
    .drop(columns=["target"])
    .reset_index(drop=True)
)

with open("sample.json", "w") as f:
    f.write(
        json.dumps(
            {"input_data": json.loads(samples.to_json(orient="split", index=False))}
        )
    )

Le code suivant échantillonne 5 observations du jeu de données d’apprentissage, supprime la colonne target (comme le modèle va le prédire) et crée une requête.

samples = (
    pd.read_csv("data/heart.csv")
    .sample(n=5)
    .drop(columns=["target"])
    .reset_index(drop=True)
)

test du déploiement

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file sample.json

ml_client.online_endpoints.invoke(
    endpoint_name=endpoint_name,
    request_file="sample.json",
)

deployment_client.predict(
    endpoint=endpoint_name, 
    df=samples
)

Créer un déploiement vert sous le point de terminaison en ligne

Imaginons qu’il existe une nouvelle version du modèle créée par l’équipe de développement et qu’il soit prêt à être mis en production. Nous pouvons d’abord tester ce modèle et une fois que nous sommes confiants, nous pouvons mettre à jour le point de terminaison pour acheminer le trafic vers celui-ci.

Inscrire une nouvelle version du modèle

MODEL_NAME='heart-classifier'
az ml model create --name $MODEL_NAME --type "mlflow_model" --path "model"

Obtenons le numéro de version du nouveau modèle :

VERSION=$(az ml model show -n heart-classifier --label latest | jq -r ".version")

model_name = 'heart-classifier'
model_local_path = "model"

model = ml_client.models.create_or_update(
     Model(name=model_name, path=model_local_path, type=AssetTypes.MLFLOW_MODEL)
)
version = model.version

model_name = 'heart-classifier'
model_local_path = "model"

registered_model = mlflow_client.create_model_version(
    name=model_name, source=f"file://{model_local_path}"
)
version = registered_model.version

Configurer un nouveau déploiement

green-deployment.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: xgboost-model
endpoint_name: heart-classifier-edp
model: azureml:heart-classifier@latest
instance_type: Standard_DS2_v2
instance_count: 1

Nous allons nommer le déploiement comme suit :

GREEN_DEPLOYMENT_NAME="xgboost-model-$VERSION"

green_deployment_name = f"xgboost-model-{version}"

Configurez la configuration matérielle requise de votre déploiement :

green_deployment = ManagedOnlineDeployment(
    name=green_deployment_name,
    endpoint_name=endpoint_name,
    model=model,
    instance_type="Standard_DS2_v2",
    instance_count=1,
)

Si votre point de terminaison n’a pas de connectivité de sortie, utilisez l’empaquetage de modèle (préversion) en incluant l’argument with_package=True :

green_deployment = ManagedOnlineDeployment(
    name=green_deployment_name,
    endpoint_name=endpoint_name,
    model=model,
    instance_type="Standard_DS2_v2",
    instance_count=1,
    with_package=True,
)

green_deployment_name = f"xgboost-model-{version}"

Pour spécifier la configuration matérielle requise de votre déploiement, vous devez créer un fichier JSON avec la configuration souhaitée :

deploy_config = {
    "instance_type": "Standard_DS2_v2",
    "instance_count": 1,
}

Conseil

Nous utilisons la même confirmation matérielle que celle indiquée dans deployment-config-file. Mais il n’est pas obligatoire d’avoir la même configuration. Vous pouvez configurer différents matériels pour différents modèles selon la configuration requise.

Écrivez la configuration dans un fichier :

deployment_config_path = "deployment_config.json"
with open(deployment_config_path, "w") as outfile:
    outfile.write(json.dumps(deploy_config))

Créer le nouveau déploiement

az ml online-deployment create -n $GREEN_DEPLOYMENT_NAME --endpoint-name $ENDPOINT_NAME -f green-deployment.yml

Si votre point de terminaison n’a pas de connectivité de sortie, utilisez l’empaquetage de modèle (préversion) en incluant l’indicateur --with-package :

az ml online-deployment create --with-package -n $GREEN_DEPLOYMENT_NAME --endpoint-name $ENDPOINT_NAME -f green-deployment.yml

ml_client.online_deployments.begin_create_or_update(green_deployment).result()

new_deployment = deployment_client.create_deployment(
    name=green_deployment_name,
    endpoint=endpoint_name,
    model_uri=f"models:/{model_name}/{version}",
    config={"deploy-config-file": deployment_config_path},
)

Tester le déploiement sans modifier le trafic

az ml online-endpoint invoke --name $ENDPOINT_NAME --deployment-name $GREEN_DEPLOYMENT_NAME --request-file sample.json

ml_client.online_endpoints.invoke(
    endpoint_name=endpoint_name,
    deployment_name=green_deployment_name
    request_file="sample.json",
)

deployment_client.predict(
    endpoint=endpoint_name, 
    deployment_name=green_deployment_name, 
    df=samples
)

Conseil

Notez comment nous indiquons maintenant le nom du déploiement que nous voulons appeler.

Mettre à jour progressivement le trafic

Une fois que nous sommes confiants concernant le nouveau déploiement, nous pouvons mettre à jour le trafic pour acheminer une partie de celui-ci vers le nouveau déploiement. Le trafic est configuré au niveau du point de terminaison :

Configurez le trafic :

Cette étape n’est pas obligatoire dans l’interface CLI Azure

endpoint.traffic = {blue_deployment_name: 90, green_deployment_name: 10}

traffic_config = {"traffic": {blue_deployment_name: 90, green_deployment_name: 10}}

Écrivez la configuration dans un fichier :

traffic_config_path = "traffic_config.json"
with open(traffic_config_path, "w") as outfile:
    outfile.write(json.dumps(traffic_config))

Mettre à jour le point de terminaison

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "default=90 $GREEN_DEPLOYMENT_NAME=10"

ml_client.begin_create_or_update(endpoint).result()

deployment_client.update_endpoint(
    endpoint=endpoint_name,
    config={"endpoint-config-file": traffic_config_path},
)

Si vous décidez de basculer l’ensemble du trafic vers le nouveau déploiement, mettez à jour tout le trafic :

Cette étape n’est pas obligatoire dans l’interface CLI Azure

endpoint.traffic = {blue_deployment_name: 0, green_deployment_name: 100}

traffic_config = {"traffic": {blue_deployment_name: 0, green_deployment_name: 100}}

Écrivez la configuration dans un fichier :

traffic_config_path = "traffic_config.json"
with open(traffic_config_path, "w") as outfile:
    outfile.write(json.dumps(traffic_config))

Mettre à jour le point de terminaison

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "default=0 $GREEN_DEPLOYMENT_NAME=100"

ml_client.begin_create_or_update(endpoint).result()

deployment_client.update_endpoint(
    endpoint=endpoint_name,
    config={"endpoint-config-file": traffic_config_path},
)

Comme l’ancien déploiement ne reçoit aucun trafic, vous pouvez le supprimer en toute sécurité :
```
az ml online-deployment delete --endpoint-name $ENDPOINT_NAME --name default
```
```
ml_client.online_deployments.begin_delete(
    name=blue_deployment_name, 
    endpoint_name=endpoint_name
)
```
```
deployment_client.delete_deployment(
    blue_deployment_name, 
    endpoint=endpoint_name
)
```
Conseil

Notez qu’à ce stade, l’ancien « déploiement bleu » a été supprimé et le nouveau « déploiement vert » a pris la place du « déploiement bleu ».

Nettoyer les ressources

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

ml_client.online_endpoints.begin_delete(name=endpoint_name)

deployment_client.delete_endpoint(endpoint_name)

Important

Notez que la suppression d’un point de terminaison supprime également tous les déploiements qu’il contient.

Partager via

Lancement progressif de modèles MLflow sur des points de terminaison en ligne

À propos de cet exemple

Suivre dans les notebooks Jupyter

Prérequis

Se connecter à un espace de travail

Inscription du modèle dans le registre

Créez un point de terminaison en ligne

Créer un déploiement bleu

Créer un déploiement vert sous le point de terminaison en ligne

Mettre à jour progressivement le trafic

Nettoyer les ressources

Étapes suivantes

Commentaires

Ressources supplémentaires