Guide pratique pour déployer un pipeline afin d’effectuer un scoring par lots avec prétraitement

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 un pipeline d’inférence (ou de scoring) sous un point de terminaison par lots. Le pipeline effectue le scoring sur un modèle inscrit tout en réutilisant un composant de prétraitement à partir du moment où le modèle a été entraîné. La réutilisation du même composant de prétraitement garantit que le même prétraitement est appliqué pendant le scoring.

Vous allez apprendre à :

• Créer un pipeline qui réutilise des composants existants à partir de l’espace de travail
• Déployer le pipeline sur un point de terminaison
• Utiliser les prédictions générées par le pipeline

À propos de cet exemple

Cet exemple vous montre comment réutiliser le code de prétraitement et les paramètres appris pendant le prétraitement avant d’utiliser votre modèle pour l’inférence. En réutilisant le code de prétraitement et les paramètres appris, nous pouvons nous assurer que les mêmes transformations (telles que la normalisation et l’encodage des fonctionnalités) qui ont été appliquées aux données d’entrée pendant l’entraînement sont également appliquées lors de l’inférence. Le modèle utilisé pour l’inférence effectue des prédictions sur les données tabulaires du jeu de données UCI sur les maladies cardiaques.

Voici une visualisation du pipeline :

L’exemple de cet article est basé sur des extraits de code contenus dans le référentiel azureml-examples. Pour exécuter les commandes localement sans avoir à copier/coller le fichier YAML et d’autres fichiers, clonez d’abord le référentiel, puis modifiez les répertoires dans le dossier :

Azure CLI

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

Python

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

Les fichiers de cet exemple se situent dans :

cd endpoints/batch/deploy-pipelines/batch-scoring-with-preprocessing

Suivre avec les notebooks Jupyter

Vous pouvez suivre la version du Kit de développement logiciel (SDK) Python de cet exemple en ouvrant le notebook sdk-deploy-and-test.ipynb dans le référentiel cloné.

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.

• Un espace de travail Azure Machine Learning. Si vous n’en avez pas, suivez les étapes décrites dans l’article Gérer des espaces de travail Azure Machine Learning pour en créer un.

• Vérifiez que vous disposez des autorisations suivantes dans l’espace de travail :

  • Créez ou gérez des points de terminaison et des déploiements par lots : utilisez un rôle propriétaire, contributeur ou personnalisé autorisant Microsoft.MachineLearningServices/workspaces/batchEndpoints/*.

  • Créez des déploiements ARM dans le groupe de ressources de l’espace de travail : utilisez un rôle propriétaire, contributeur ou personnalisé autorisant Microsoft.Resources/deployments/write dans le groupe de ressources où l’espace de travail est déployé.

• Vous devez installer le logiciel suivant pour utiliser Azure Machine Learning :

  Azure CLI

  L’interface Azure CLI et l’mlextension pour Azure Machine Learning.

  az extension add -n ml
  

  Notes

  Les déploiements de composants de pipeline pour des points de terminaison Batch ont été introduits dans la version 2.7 de l’extension ml pour Azure CLI. Utilisez az extension update --name ml pour en obtenir la dernière version.

  Python

  Le kit de développement logiciel (SDK) Azure Machine Learning pour Python.

  pip install azure-ai-ml
  

  Notes

  Les classes ModelBatchDeployment et PipelineComponentBatchDeployment ont été introduites dans la version 1.7.0 du kit de développement logiciel (SDK). Utilisez pip install -U azure-ai-ml pour en obtenir la dernière version.

Se connecter à un espace de travail

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.

Azure CLI

Transmettez les valeurs de votre ID d’abonnement, de votre espace de travail, de votre emplacement et de votre groupe de ressources dans le code suivant :

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

Python

1. Importez les bibliothèques nécessaires :

   from azure.ai.ml import MLClient, Input, load_component
   from azure.ai.ml.entities import BatchEndpoint, ModelBatchDeployment, ModelBatchDeploymentSettings, PipelineComponentBatchDeployment, Model, AmlCompute, Data, BatchRetrySettings, CodeConfiguration, Environment, Data
   from azure.ai.ml.constants import AssetTypes, BatchDeploymentOutputAction
   from azure.ai.ml.dsl import pipeline
   from azure.identity import DefaultAzureCredential
   

2. Configurez les détails de l’espace de travail et obtenez un descripteur de l’espace de travail :

   Transmettez les valeurs de votre ID d’abonnement, de votre espace de travail et de votre groupe de ressources dans le code suivant :

   subscription_id = "<subscription>"
   resource_group = "<resource-group>"
   workspace = "<workspace>"
   
   ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)
   

Créer le pipeline d’inférence

Dans cette section, nous allons créer toutes les ressources requises pour notre pipeline d’inférence. Nous allons commencer par créer un environnement qui inclut les bibliothèques nécessaires pour les composants du pipeline. Ensuite, nous allons créer un cluster de calcul sur lequel le déploiement par lots s’exécutera. Après cela, nous allons inscrire les composants, les modèles et les transformations dont nous avons besoin pour générer notre pipeline d’inférence. Enfin, nous allons générer et tester le pipeline.

Créer l’environnement

Les composants de cet exemple utilisent un environnement avec les bibliothèques XGBoost et scikit-learn. Le fichier environment/conda.yml contient la configuration de l’environnement :

environment/conda.yml

channels:
- conda-forge
dependencies:
- python=3.8.5
- pip
- pip:
  - mlflow
  - azureml-mlflow
  - datasets
  - jobtools
  - cloudpickle==1.6.0
  - dask==2023.2.0
  - scikit-learn==1.1.2
  - xgboost==1.3.3
name: mlflow-env

Créez l’environnement ainsi :

1. Définissez l’environnement :

   Azure CLI

   environment/xgboost-sklearn-py38.yml

   $schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
   name: xgboost-sklearn-py38
   image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
   conda_file: conda.yml
   description: An environment for models built with XGBoost and Scikit-learn.
   

   Python

   environment = Environment(
       name="xgboost-sklearn-py38",
       description="An environment for models built with XGBoost and Scikit-learn.",
       image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest",
       conda_file="environment/conda.yml",
   )

2. Créez l’environnement :

   Azure CLI

   az ml environment create -f environment/xgboost-sklearn-py38.yml
   

   Python

   try:
       ml_client.environments.create_or_update(environment)
   except ResourceExistsError:
       pass

Créer un cluster de calcul

Les points de terminaison et les déploiements par lots s’exécutent sur des clusters de calcul. Ils peuvent s’exécuter sur n’importe quel cluster de calcul Azure Machine Learning qui existe déjà dans l’espace de travail. Par conséquent, plusieurs déploiements par lots peuvent partager la même infrastructure de calcul. Dans cet exemple, nous allons travailler sur un cluster de calcul Azure Machine Learning appelé batch-cluster. Nous allons vérifier que le calcul existe sur l’espace de travail ou le créer dans le cas contraire.

Azure CLI

az ml compute create -n batch-cluster --type amlcompute --min-instances 0 --max-instances 5

Python

compute_name = "batch-cluster"
if not any(filter(lambda m: m.name == compute_name, ml_client.compute.list())):
    compute_cluster = AmlCompute(
        name=compute_name,
        description="Batch endpoints compute cluster",
        min_instances=0,
        max_instances=5,
    )
    ml_client.begin_create_or_update(compute_cluster).result()

Inscrire des composants et des modèles

Nous allons inscrire les composants, les modèles et les transformations dont nous avons besoin pour générer notre pipeline d’inférence. Nous pouvons réutiliser certaines de ces ressources pour les routines d’entraînement.

Conseil

Dans ce didacticiel, nous allons réutiliser le modèle et le composant de prétraitement d’un pipeline d’entraînement antérieur. Vous pouvez voir comment ils ont été créés en suivant l’exemple Comment déployer un pipeline d’entraînement avec des points de terminaison par lots.

1. Inscrivez le modèle à utiliser pour la prédiction :

   Azure CLI

   az ml model create --name heart-classifier --type mlflow_model --path model
   

   Python

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

2. Le modèle inscrit n’a pas été entraîné directement sur les données d’entrée. Au lieu de cela, les données d’entrée ont été prétraitées (ou transformées) avant l’entraînement, à l’aide d’un composant de préparation. Nous devrons également inscrire ce composant. Inscrivez le composant de préparation :

   Azure CLI

   az ml component create -f components/prepare/prepare.yml
   

   Python

   prepare_data = load_component(source="components/prepare/prepare.yml")
   
   ml_client.components.create_or_update(prepare_data)

   Conseil

   Après avoir inscrit le composant de préparation, vous pouvez le référencer à partir de l’espace de travail. Par exemple, azureml:uci_heart_prepare@latest obtient la dernière version du composant de préparation.

3. Dans le cadre des transformations de données dans le composant de préparation, les données d’entrée ont été normalisées pour centrer les prédicteurs et limiter leurs valeurs dans la plage de [-1, 1]. Les paramètres de transformation ont été capturés dans une transformation scikit-learn que nous pouvons également inscrire pour l’appliquer ultérieurement lorsque nous avons de nouvelles données. Inscrivez la transformation ainsi :

   Azure CLI

   az ml model create --name heart-classifier-transforms --type custom_model --path transformations
   

   Python

   transformation_name = "heart-classifier-transforms"
   transformation_local_path = "transformations"
   
   transformations = ml_client.models.create_or_update(
       Model(
           name=transformation_name,
           path=transformation_local_path,
           type=AssetTypes.CUSTOM_MODEL,
       )
   )

4. Nous allons effectuer l’inférence pour le modèle inscrit, à l’aide d’un autre composant nommé score qui calcule les prédictions pour un modèle donné. Nous allons référencer le composant directement à partir de sa définition.

   Conseil

   Il est recommandé d’inscrire le composant et de le référencer à partir du pipeline. Toutefois, dans cet exemple, nous allons référencer le composant directement à partir de sa définition pour vous aider à voir quels composants sont réutilisés à partir du pipeline d’entraînement et lesquels sont nouveaux.

Générer le pipeline

Il est maintenant temps de relier tous les éléments ensemble. Le pipeline d’inférence que nous allons déployer comporte deux composants (ou étapes) :

• preprocess_job : cette étape lit les données d’entrée et retourne les données préparées et les transformations appliquées. L’étape reçoit deux entrées :
  • data : dossier contenant les données d’entrée à noter
  • transformations : (facultatif) chemin des transformations qui seront appliquées, le cas échéant. Lorsqu’elles sont fournies, les transformations sont lues à partir du modèle indiqué au niveau du chemin d’accès. Cependant, si le chemin d’accès n’est pas fourni, les transformations seront apprises à partir des données d’entrée. Toutefois, pour l’inférence, vous ne pouvez pas apprendre les paramètres de transformation (dans cet exemple, les coefficients de normalisation) depuis des données d’entrée, car vous devez utiliser les mêmes valeurs de paramètre que celles apprises pendant l’entraînement. Étant donné que cette entrée est facultative, le composant preprocess_job peut être utilisé pendant l’entraînement et l’évaluation.
• score_job : cette étape effectue l’inférence sur les données transformées à l’aide du modèle d’entrée. Notez que le composant utilise un modèle MLflow pour effectuer l’inférence. Enfin, les scores sont réécrits dans le même format que lors de leur lecture.

Azure CLI

La configuration du pipeline est définie dans le fichier pipeline.yml :

pipeline.yml

$schema: https://azuremlschemas.azureedge.net/latest/pipelineComponent.schema.json
type: pipeline

name: batch_scoring_uci_heart
display_name: Batch Scoring for UCI heart
description: This pipeline demonstrates how to make batch inference using a model from the Heart Disease Data Set problem, where pre and post processing is required as steps. The pre and post processing steps can be components reusable from the training pipeline.

inputs:
  input_data:
    type: uri_folder
  score_mode:
    type: string
    default: append

outputs: 
  scores:
    type: uri_folder
    mode: upload

jobs:
  preprocess_job:
    type: command
    component: azureml:uci_heart_prepare@latest
    inputs:
      data: ${{parent.inputs.input_data}}
      transformations: 
        path: azureml:heart-classifier-transforms@latest
        type: custom_model
    outputs:
      prepared_data:
  
  score_job:
    type: command
    component: components/score/score.yml
    inputs:
      data: ${{parent.jobs.preprocess_job.outputs.prepared_data}}
      model:
        path: azureml:heart-classifier@latest
        type: mlflow_model
      score_mode: ${{parent.inputs.score_mode}}
    outputs:
      scores: 
        mode: upload
        path: ${{parent.outputs.scores}}

Python

prepare_data = ml_client.components.get("uci_heart_prepare", label="latest")
score_data = load_component(source="components/score/score.yml")

Créons le pipeline dans une fonction :

@pipeline()
def uci_heart_classifier_scorer(
    input_data: Input(type=AssetTypes.URI_FOLDER), score_mode: str
):
    """This pipeline demonstrates how to make batch inference using a model from the Heart Disease Data Set problem, where pre and post processing is required as steps. The pre and post processing steps can be components reusable from the training pipeline."""
    prepared_data = prepare_data(
        data=input_data,
        transformations=Input(type=AssetTypes.CUSTOM_MODEL, path=transformations.id),
    )
    scored_data = score_data(
        data=prepared_data.outputs.prepared_data,
        model=Input(type=AssetTypes.MLFLOW_MODEL, path=model.id),
        score_mode=score_mode,
    )

    return {"scores": scored_data.outputs.scores}

Voici une visualisation du pipeline :

Tester le pipeline

Testons le pipeline avec des exemples de données. Pour ce faire, nous allons créer un travail à l’aide du pipeline et du cluster de calcul batch-cluster créés précédemment.

Azure CLI

Le fichier pipeline-job.yml suivant contient la configuration du travail de pipeline :

pipeline-job.yml

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline

display_name: uci-classifier-score-job
description: |-
  This pipeline demonstrate how to make batch inference using a model from the Heart \
  Disease Data Set problem, where pre and post processing is required as steps. The \
  pre and post processing steps can be components reused from the training pipeline.

compute: batch-cluster
component: pipeline.yml
inputs:
  input_data:
    type: uri_folder
  score_mode: append
outputs: 
  scores:
    mode: upload

Python

pipeline_job = uci_heart_classifier_scorer(
    input_data=Input(type="uri_folder", path="data/unlabeled/"), score_mode="append"
)

À présent, nous allons configurer certains paramètres d’exécution pour exécuter le test :

pipeline_job.settings.default_datastore = "workspaceblobstore"
pipeline_job.settings.default_compute = "batch-cluster"

Créez le travail de test :

Azure CLI

az ml job create -f pipeline-job.yml --set inputs.input_data.path=data/unlabeled

Python

pipeline_job_run = ml_client.jobs.create_or_update(
    pipeline_job, experiment_name="uci-heart-score-pipeline"
)
pipeline_job_run

Créer un point de terminaison de traitement de lots

1. Entrez un nom pour le point de terminaison. Le nom d’un point de terminaison de lot doit être unique dans chaque région, car le nom est utilisé pour construire l’URI d’appel. Pour garantir son originalité, ajoutez des caractères de fin au nom spécifié dans le code suivant.

   Azure CLI

   ENDPOINT_NAME="uci-classifier-score"
   

   Python

   endpoint_name = "uci-classifier-score"

2. Configurer le point de terminaison :

   Azure CLI

   Le fichier endpoint.yml contient la configuration du point de terminaison.

   endpoint.yml

   $schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
   name: uci-classifier-score
   description: Batch scoring endpoint of the Heart Disease Data Set prediction task.
   auth_mode: aad_token
   

   Python

   endpoint = BatchEndpoint(
       name=endpoint_name,
       description="Batch scoring endpoint of the Heart Disease Data Set prediction task",
   )

3. Créez le point de terminaison :

   Azure CLI

   az ml batch-endpoint create --name $ENDPOINT_NAME -f endpoint.yml
   

   Python

   ml_client.batch_endpoints.begin_create_or_update(endpoint).result()

4. Interrogez l’URI du point de terminaison :

   Azure CLI

   az ml batch-endpoint show --name $ENDPOINT_NAME
   

   Python

   endpoint = ml_client.batch_endpoints.get(name=endpoint_name)
   print(endpoint)

Déployer le composant de pipeline

Pour déployer le composant de pipeline, nous devons créer un déploiement par lots. Un déploiement est un ensemble de ressources nécessaires à l’hébergement de la ressource qui effectue le travail réel.

1. Configurer le déploiement

   Azure CLI

   Le fichier deployment.yml contient la configuration du déploiement. Pour obtenir des propriétés supplémentaires, vous pouvez vérifier le schéma YAML du point de terminaison de lot complet.

   deployment.yml

   $schema: https://azuremlschemas.azureedge.net/latest/pipelineComponentBatchDeployment.schema.json
   name: uci-classifier-prepros-xgb
   endpoint_name: uci-classifier-batch
   type: pipeline
   component: pipeline.yml
   settings:
       continue_on_step_failure: false
       default_compute: batch-cluster
   

   Python

   Notre pipeline est défini dans une fonction. Pour le transformer en composant, vous utiliserez sa propriété component. Les composants de pipeline sont des graphiques de calcul réutilisables qui peuvent être inclus dans des déploiements par lots ou utilisés pour composer des pipelines plus complexes.

   pipeline_component = ml_client.components.create_or_update(
       uci_heart_classifier_scorer().component
   )

   Nous pouvons maintenant définir le déploiement :

   deployment = PipelineComponentBatchDeployment(
       name="uci-classifier-prepros-xgb",
       description="A sample deployment with pre and post processing done before and after inference.",
       endpoint_name=endpoint.name,
       component=pipeline_component,
       settings={"continue_on_step_failure": False, "default_compute": compute_name},
   )

2. Créer le déploiement

   Azure CLI

   Exécutez le code suivant pour créer un déploiement par lots sous le point de terminaison de traitement par lots et le définir comme déploiement par défaut.

   az ml batch-deployment create --endpoint $ENDPOINT_NAME -f deployment.yml --set-default
   

   Conseil

   Notez l’utilisation de l’indicateur --set-default pour indiquer que ce nouveau déploiement est désormais la valeur par défaut.

   Python

   Cette commande initie la création du déploiement et renvoie un réponse de confirmation tandis que la création du déploiement se poursuit.

   ml_client.batch_deployments.begin_create_or_update(deployment).result()

   Une fois créé, nous allons configurer ce nouveau déploiement comme déploiement par défaut :

   endpoint = ml_client.batch_endpoints.get(endpoint_name)
   endpoint.defaults.deployment_name = deployment.name
   ml_client.batch_endpoints.begin_create_or_update(endpoint).result()

3. Votre déploiement est prêt à être utilisé.

test du déploiement

Une fois le déploiement créé, il est prêt à recevoir des travaux. Suivez ces étapes pour le tester :

1. Notre déploiement demande à ce que nous indiquions une entrée de données et une entrée littérale.

   Azure CLI

   Le fichier inputs.yml contient la définition de la ressource de données d’entrée :

   inputs.yml

   inputs:
     input_data:
       type: uri_folder
       path: data/unlabeled
     score_mode:
       type: string
       default: append
   outputs:
     scores:
       type: uri_folder
       mode: upload
   

   Python

   Définition de la ressource de données d’entrée :

   input_data = Input(type="uri_folder", path="data/unlabeled/")
   score_mode = Input(type="string", default="append")

   Conseil

   Pour en savoir plus sur la façon d’indiquer des entrées, consultez Créer des travaux et des données d’entrée pour les points de terminaison par lots.

2. Vous pouvez appeler le déploiement par défaut ainsi :

   Azure CLI

   JOB_NAME=$(az ml batch-endpoint invoke -n $ENDPOINT_NAME --f inputs.yml --query name -o tsv)
   

   Python

   Conseil

   Quelle est la différence entre inputs et input lorsque vous appelez un point de terminaison ?

   En général, vous pouvez utiliser un dictionnaire inputs = {} avec la méthode invoke pour fournir un nombre arbitraire d’entrées nécessaires à un point de terminaison par lots contenant un modèle de déploiement ou un déploiement de pipelines.

   Pour un déploiement de modèle, vous pouvez utiliser input comme moyen plus court de spécifier l’emplacement des données d’entrée pour le déploiement, car un déploiement de modèle ne prend toujours qu’une seule entrée de données.

   job = ml_client.batch_endpoints.invoke(
       endpoint_name=endpoint.name,
       inputs={"input_data": input_data, "score_mode": score_mode},
   )

3. Vous pouvez surveiller la progression de l’affichage et diffuser les journaux en continu à l’aide de :

   Azure CLI

   az ml job stream -n $JOB_NAME
   

   Python

   ml_client.jobs.get(job.name)

   Pour attendre la fin du travail, exécutez le code suivant :

   ml_client.jobs.stream(name=job.name)

Accéder à la sortie du travail

Une fois le travail terminé, nous pouvons accéder à sa sortie. Ce travail ne contient qu’une seule sortie nommée scores :

Azure CLI

Vous pouvez télécharger les résultats associés à l’aide de az ml job download.

az ml job download --name $JOB_NAME --output-name scores

Python

Téléchargez le résultat :

ml_client.jobs.download(name=job.name, download_path=".", output_name="scores")

Lisez les données notées :

import pandas as pd
import glob

output_files = glob.glob("named-outputs/scores/*.csv")
score = pd.concat((pd.read_csv(f) for f in output_files))
score

La sortie se présente comme suit :

age	sexe	...	thal	prediction
0.9338	1	...	2	0
1.3782	1	...	3	1
1.3782	1	...	4	0
-1.954	1	...	3	0

La sortie contient les prédictions ainsi que les données fournies au composant de score, qui a été prétraité. Par exemple, la colonne age a été normalisée et la colonne thal contient des valeurs d’encodage d’origine. Dans la pratique, vous souhaiterez probablement générer uniquement la prédiction, puis la concaténer avec les valeurs d’origine. Ce travail a été laissé au lecteur.

Nettoyer les ressources

Une fois que vous avez terminé, supprimez les ressources associées de l’espace de travail :

Azure CLI

Exécutez le code suivant pour supprimer le point de terminaison de lot et ses déploiements sous-jacents. Utilisez --yes pour confirmer la suppression.

az ml batch-endpoint delete -n $ENDPOINT_NAME --yes

Python

Supprimez le point de terminaison :

ml_client.batch_endpoints.begin_delete(endpoint_name)

(Facultatif) Supprimez le calcul, sauf si vous comptez réutiliser votre cluster de calcul dans des déploiements ultérieurs.

Azure CLI

az ml compute delete -n batch-cluster

Python

ml_client.compute.begin_delete(name="batch-cluster")

Étapes suivantes

• Créer des points de terminaison par lots à partir de travaux de pipeline
• Accès aux données à partir de travaux de points de terminaison de traitement par lots
• Résolution des problèmes de points de terminaison de traitement de lots