Partage via

Personnaliser les sorties dans les déploiements par lots

  • Article

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

Ce guide explique comment créer des déploiements qui génèrent des sorties et des fichiers personnalisés. Parfois, vous avez besoin d’un meilleur contrôle sur le contenu écrit en tant que sortie des travaux d’inférence par lots. Ces cas incluent les situations suivantes :

  • Vous devez contrôler l’écriture des prédictions dans la sortie. Par exemple, vous souhaitez ajouter la prédiction aux données d’origine si les données sont tabulaires.
  • Vous devez écrire vos prédictions dans un format de fichier différent de celui pris en charge prêt à l’emploi par des déploiements par lots.
  • Votre modèle est un modèle génératif qui ne peut pas écrire la sortie dans un format tabulaire. Par exemple, les modèles qui produisent des images en tant que sorties.
  • Votre modèle produit plusieurs fichiers tabulaires au lieu d’un seul. L’on peut citer par exemple les modèles qui effectuent des prévisions en tenant compte de plusieurs scénarios.

Les déploiements par lots vous permettent de contrôler la sortie des travaux par l’écriture directe dans la sortie du travail de déploiement par lots. Dans ce tutoriel, vous allez apprendre à déployer un modèle pour effectuer une inférence par lots et écrire les sorties au format parquet en ajoutant les prédictions aux données d’entrée d’origine.

À propos de cet exemple

Cet exemple montre comment déployer un modèle pour effectuer une inférence par lots et personnaliser la façon dont vos prédictions sont écrites dans la sortie. Le modèle est basé sur le jeu de données UCI Heart Disease. La base de données contient 76 attributs, mais cet exemple utilise un sous-ensemble de 14 d’entre eux. Le modèle tente de prédire la présence de maladie cardiaque chez un patient. C’est un entier compris entre 0 (aucune présence) et 1 (présence).

Le modèle 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.

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 :

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

Les fichiers de cet exemple se situent dans :

cd endpoints/batch/deploy-models/custom-outputs-parquet

Suivre dans un notebook Jupyter

Un notebook Jupyter vous permet de suivre cet exemple. Dans le référentiel cloné, ouvrez le notebook appelé custom-output-batch.ipynb.

Prérequis

  • 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. Pour créer un espace de travail, consultez Gérer les espaces de travail Azure Machine Learning.

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

    • 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éer des déploiements Azure Resource Manager dans le groupe de ressources de l’espace de travail : utilisez un rôle Propriétaire, Contributeur ou un rôle personnalisé autorisant Microsoft.Resources/deployments/write dans le groupe de ressources où l’espace de travail est déployé.

  • Installez le logiciel suivant pour utiliser Machine Learning :

    Exécutez la commande suivante pour installer l’interface de ligne de commande Azure et l’extension pour Azure Machine Learning ml :

    az extension add -n ml

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

Se connecter à un espace de travail

L’espace de travail est la ressource de niveau supérieur pour le Machine Learning. Il fournit un emplacement centralisé pour travailler avec tous les artefacts que vous créez lorsque vous utilisez Machine Learning. Dans cette section, vous vous connectez à l’espace de travail dans lequel vous effectuez vos tâches de déploiement.

Dans la commande suivante, entrez les valeurs de votre ID d’abonnement, de votre espace de travail, de votre emplacement et de votre groupe de ressources :

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

Créer un déploiement par lots avec une sortie personnalisée

Dans cet exemple, vous créez un déploiement qui peut écrire directement dans le dossier de sortie du travail de déploiement par lots. Le déploiement utilise cette fonctionnalité pour écrire des fichiers parquet personnalisés.

Inscrire le modèle

Vous pouvez uniquement déployer des modèles inscrits avec un point de terminaison par lots. Dans ce cas, vous avez déjà une copie locale du modèle dans le référentiel. Vous devez donc uniquement publier le modèle dans le registre dans l’espace de travail. Vous pouvez ignorer cette étape si le modèle que vous essayez de déployer est déjà inscrit.

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

Créer un script de scoring

Vous devez créer un script de scoring qui peut lire les données d’entrée fournies par le déploiement par lots, puis retourner les scores du modèle. Vous allez également écrire directement dans le dossier de sortie du travail. En résumé, le script de scoring proposé effectue les opérations suivantes :

  1. Lit les données d’entrée en tant que fichiers CSV.
  2. Exécute une fonction predict de modèle MLflow sur les données d’entrée.
  3. Ajoute les prédictions à un pandas.DataFrame avec les données d’entrée.
  4. Écrit les données dans un fichier nommé fichier d’entrée, mais au format parquet.

code/batch_driver.py

import os
import pickle
import glob
import pandas as pd
from pathlib import Path
from typing import List


def init():
    global model
    global output_path

    # AZUREML_MODEL_DIR is an environment variable created during deployment
    # It is the path to the model folder
    # Please provide your model's folder name if there's one:
    output_path = os.environ["AZUREML_BI_OUTPUT_PATH"]
    model_path = os.environ["AZUREML_MODEL_DIR"]
    model_file = glob.glob(f"{model_path}/*/*.pkl")[-1]

    with open(model_file, "rb") as file:
        model = pickle.load(file)


def run(mini_batch: List[str]):
    for file_path in mini_batch:
        data = pd.read_csv(file_path)
        pred = model.predict(data)

        data["prediction"] = pred

        output_file_name = Path(file_path).stem
        output_file_path = os.path.join(output_path, output_file_name + ".parquet")
        data.to_parquet(output_file_path)

    return mini_batch

Remarques :

  • Notez comment la variable d’environnement AZUREML_BI_OUTPUT_PATH est utilisée pour accéder au chemin de sortie du travail de déploiement.
  • La fonction init() remplit une variable globale appelée output_path permettant ultérieurement de savoir où écrire.
  • La méthode run retourne une liste des fichiers traités. La fonction run doit renvoyer un objet list ou pandas.DataFrame.

Avertissement

Tenez compte du fait que tous les exécuteurs de lots ont un accès en écriture à ce chemin simultanément. Cela signifie que vous devez tenir compte de l’accès concurrentiel. Dans ce cas, vérifiez que chaque exécuteur écrit son propre fichier en utilisant le nom du fichier d’entrée comme nom du dossier de sortie.

Créer le point de terminaison

Créez maintenant un point de terminaison par lots nommé heart-classifier-batch où déployer le modèle.

  1. Choisissez le nom du point de terminaison. Le nom du point de terminaison apparaît dans l’URI associé à votre point de terminaison. Par conséquent, les noms de points de terminaison par lots doivent être uniques au sein d’une région Azure. Par exemple, il ne peut y avoir qu’un seul point de terminaison de traitement par lots avec le nom mybatchendpoint dans westus2.

    Dans ce cas, placez le nom du point de terminaison dans une variable pour pouvoir facilement le référencer ultérieurement.

    ENDPOINT_NAME="heart-classifier-custom"

  2. Configurez votre point de terminaison par lots.

    Le fichier YAML suivant définit un point de terminaison de lot :

    endpoint.yml

    $schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
name: heart-classifier-batch
description: A heart condition classifier for batch inference
auth_mode: aad_token

  3. Créez le point de terminaison :

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

Créer le déploiement

Suivez les étapes suivantes pour créer un déploiement à l’aide du script de scoring précédent :

  1. Créez d’abord un environnement où le script de scoring peut être exécuté :

    Aucune étape supplémentaire n’est requise pour Azure Machine Learning CLI. La définition d’environnement est incluse dans le fichier de déploiement.

    environment:
  name: batch-mlflow-xgboost
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml

  2. Créez le déploiement. Notez que output_action a maintenant la valeur SUMMARY_ONLY.

    Remarque

    Cet exemple part du principe que vous avez un cluster de calcul avec le nom batch-cluster. Modifiez ce nom en conséquence.

    Pour créer un nouveau déploiement sous le point de terminaison créé, créez une configuration YAML comme suit. Vous pouvez vérifier le schéma YAML du point de terminaison de lot complet pour obtenir des propriétés supplémentaires.

    $schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json
endpoint_name: heart-classifier-batch
name: classifier-xgboost-custom
description: A heart condition classifier based on XGBoost and Scikit-Learn pipelines that append predictions on parquet files.
type: model
model: azureml:heart-classifier-sklpipe@latest
environment:
  name: batch-mlflow-xgboost
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml
code_configuration:
  code: code
  scoring_script: batch_driver.py
compute: azureml:batch-cluster
resources:
  instance_count: 2
settings:
  max_concurrency_per_instance: 2
  mini_batch_size: 2
  output_action: summary_only
  retry_settings:
    max_retries: 3
    timeout: 300
  error_threshold: -1
  logging_level: info

    Ensuite, créez le déploiement avec la commande suivante :

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

  3. À ce stade, notre point de terminaison batch est prêt à être utilisé.

test du déploiement

Pour tester notre point de terminaison, utilisez un échantillon de données non étiquetées situées dans ce référentiel, que vous pouvez utiliser avec le modèle. Les points de terminaison par lots peuvent uniquement traiter les données situées dans le cloud et accessibles depuis l’espace de travail Azure Machine Learning. Dans cet exemple, chargez les données dans un magasin de données Azure Machine Learning. Vous allez créer une ressource de données qui permet d’appeler le point de terminaison pour le scoring. Toutefois, notez que les points de terminaison de lot acceptent les données pouvant être placées dans plusieurs types d’emplacements.

  1. Appelez le point de terminaison avec les données d’un compte de stockage :

    JOB_NAME = $(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data --query name -o tsv)

    Remarque

    L’utilitaire jq ne sera pas forcément installé sur chaque installation. Vous pouvez obtenir des instructions sur GitHub.

  2. Une tâche de lot est démarrée dès que la commande retourne son résultat. Vous pouvez surveiller l’état du travail jusqu’à ce qu’il se termine :

    az ml job show -n $JOB_NAME --web

Analysez les sorties

Le travail génère une sortie nommée appelée score où tous les fichiers générés sont placés. Étant donné que vous avez écrit directement dans le répertoire un fichier par fichier d’entrée, vous pouvez vous attendre à avoir le même nombre de fichiers. Dans cet exemple particulier, nommez les fichiers de sortie de la même façon que les entrées, mais ils auront une extension parquet.

Remarque

Notez qu’un fichier predictions.csv est également inclus dans le dossier de sortie. Ce fichier contient le résumé des fichiers traités.

Vous pouvez télécharger les résultats du travail à l’aide du nom du travail :

Utilisez les commandes suivantes pour télécharger les prédictions :

az ml job download --name $JOB_NAME --output-name score --download-path ./

Une fois le fichier téléchargé, vous pouvez l’ouvrir à l’aide de votre outil favori. L’exemple suivant charge les prédictions à l’aide du dataframe Pandas.

import pandas as pd
import glob

output_files = glob.glob("named-outputs/score/*.parquet")
score = pd.concat((pd.read_parquet(f) for f in output_files))
score

La sortie se présente comme suit :

age sexe ... thal prediction
63 1 ... fixe 0
67 1 ... normal 1
67 1 ... reversible 0
37 1 ... normal 0

Nettoyer les ressources

Exécutez le code suivant pour supprimer le point de terminaison de lot et tous les déploiements sous-jacents. Les travaux de scoring par lots ne sont pas supprimés.

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

Contenu connexe