Créer des modèles empaquetés (préversion)

L’empaquetage de modèle est une fonctionnalité d’Azure Machine Learning qui vous permet de collecter toutes les dépendances requises pour déployer un modèle Machine Learning sur une plateforme de service. Créer des paquets avant de déployer des modèles permet un déploiement robuste et fiable et un flux de travail MLOps plus efficace. Les paquets peuvent être déplacés entre les espaces de travail et même en dehors d’Azure Machine Learning.

Important

Cette fonctionnalité est actuellement disponible en préversion publique. Cette préversion est fournie sans contrat de niveau de service et n’est pas recommandée pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge.

Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Dans cet article, vous allez apprendre à empaqueter un modèle pour le déploiement.

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 Comment gérer des espaces de travail pour en créer un.

• 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é. Pour plus d’informations, consultez Gérer l’accès à un espace de travail Azure Machine Learning.

À propos de cet exemple

Dans cet exemple, vous allez apprendre à empaqueter des modèles dans Azure Machine Learning.

Cloner le référentiel

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

Cette section utilise l’exemple dans le dossier endpoints/online/deploy-packages/custom-model.

Se connecter à un espace de travail

Connectez-vous à votre espace de travail Azure Machine Learning pour commencer à travailler.

Azure CLI

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

Python

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, vous vous connectez à l’espace de travail dans lequel vous effectuez des tâches de déploiement.

1. Importez les bibliothèques nécessaires :

   from azure.identity import DefaultAzureCredential
   from azure.ai.ml import MLClient
   from azure.ai.ml.entities import (
       AzureMLOnlineInferencingServer,
       ModelPackage,
       CodeConfiguration,
       BaseEnvironment,
       ModelConfiguration,
   )
   from azure.ai.ml.entities import (
       ManagedOnlineEndpoint,
       ManagedOnlineDeployment,
       Environment,
       Model,
   )
   

2. Si vous exécutez une instance de calcul dans Azure Machine Learning, créez un MLClient comme suit :

   ml_client = MLClient.from_config(DefaultAzureCredential())
   

   Autrement, configurez les détails de votre espace de travail et obtenez un descripteur de l’espace de travail :

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

Empaqueter un modèle

Vous pouvez créer explicitement des modèles empaquetés pour vous permettre de contrôler l’opération d’empaquetage. Utilisez ce flux de travail quand :

• vous souhaitez personnaliser la façon dont le modèle empaqueté est créé ;
• vous souhaitez déployer le modèle empaqueté en dehors d’Azure Machine Learning ;
• vous souhaitez utiliser des modèles empaquetés dans un flux de travail MLOps.

Vous pouvez créer des modèles empaquetés en spécifiant les éléments suivants :

• Modèle à empaqueter : chaque modèle empaqueté ne peut contenir qu’un seul modèle. Azure Machine Learning ne prend pas en charge l’empaquetage de plusieurs modèles dans un même paquet.
• Environnement de base : les environnements sont utilisés pour indiquer l’image de base et, dans les paquets Python, les dépendances dont votre modèle a besoin. Azure Machine Learning génère automatiquement les environnements de base des modèles MLflow. Vous devez spécifier un environnement de base pour les modèles personnalisés.
• Technologie de service : la pile d’inférence utilisée pour exécuter le modèle.

Inscrire le modèle

Les modèles empaquetés nécessitent l’inscription du modèle dans votre espace de travail ou dans un registre Azure Machine Learning. 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 section si le modèle que vous essayez de déployer est déjà inscrit.

Azure CLI

MODEL_NAME='sklearn-regression'
MODEL_PATH='model'
az ml model create --name $MODEL_NAME --path $MODEL_PATH --type custom_model

Python

model_name = "sklearn-regression"
model_path = "model"

model = ml_client.models.create_or_update(Model(name=model_name, path=model_path))

Créer l’environnement de base

Les environnements de base sont utilisés pour indiquer l’image de base et les dépendances des modèles empaquetés Python. Notre modèle nécessite que les packages suivants soient utilisés comme indiqué dans le fichier conda :

conda.yaml

name: model-env
channels:
  - conda-forge
dependencies:
  - python=3.9
  - numpy=1.23.5
  - pip=23.0.1
  - scikit-learn=1.2.2
  - scipy=1.10.1
  - xgboost==1.3.3

Remarque

Comment l’environnement de base diffère-t-il de l’environnement que vous utilisez pour le déploiement de modèles vers des points de terminaison en ligne et par lots ? Lorsque vous déployez des modèles vers des points de terminaison, votre environnement doit inclure les dépendances du modèle et les packages Python nécessaires au bon fonctionnement des points de terminaison en ligne managés. Cela amène un processus manuel dans le déploiement, où vous devez combiner les exigences de votre modèle avec les exigences de la plateforme de service. En revanche, l’utilisation de packages de modèles supprime cette friction, car les packages requis pour le serveur d’inférence seront automatiquement injectés dans le modèle empaqueté au moment de l’empaquetage.

Créez l’environnement ainsi :

Azure CLI

Créez une définition d’environnement :

sklearn-regression-env.yml

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

Créez ensuite l’environnement :

az ml environment create -f environment/sklearn-regression-env.yml

Python

base_environment = ml_client.environments.create_or_update(
    Environment(
        name=f"{model_name}-env",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04",
        conda_file="environment/conda.yml",
    )
)

Créer une spécification de paquet

Vous pouvez créer des modèles empaquetés dans Azure Machine Learning, à l’aide d’Azure CLI ou du Kit de développement logiciel (SDK) Azure Machine Learning pour Python. La spécification de package personnalisée prend en charge les attributs suivants :

Azure CLI

Attribut	Type	Description	Obligatoire
target_environment	str	Nom du package à créer. Le résultat d’une opération d’empaquetage est un environnement dans Azure Machine Learning.	Oui
base_environment_source	object	L’mage de base à utiliser pour créer le package où les dépendances du modèle sont spécifiées.	Oui, sauf si le modèle est MLflow.
base_environment_source.type	str	Le type de l’image de base. Seule l’utilisation d’un autre environnement comme image de base est prise en charge (type: environment_asset).
base_environment_source.resource_id	str	L’ID de ressource de l’environnement de base à utiliser. Utilisez le format azureml:<name>:<version> ou un ID de ressource long.
inferencing_server	object	Le serveur d’inférence à utiliser.	Oui
inferencing_server.type	azureml_online custom	Utilisez azureml_online pour le serveur d’inférence Azure Machine Learning, ou custom pour un serveur en ligne personnalisé tel que TensorFlow service ou Torch Serve.	Oui
inferencing_server.code_configuration	object	La configuration du code avec la routine d’inférence. Il doit contenir au moins un fichier Python avec des méthodes init et run.	Oui, sauf si le modèle est MLflow.
model_configuration	object	La configuration du modèle. Utilisez cet attribut pour contrôler la façon dont le modèle est empaqueté dans l’image résultante.	Non
model_configuration.mode	download copy	Indiquez comment le modèle serait placé dans le package. Les valeurs possibles sont download (par défaut) et copy. Utilisez download quand vous voulez que le modèle soit téléchargé depuis le registre de modèles au moment du déploiement. Cette option crée des images Docker plus petites, car le modèle n’y est pas inclus. Utilisez copy quand vous voulez déconnecter l’image d’Azure Machine Learning. Le modèle sera copié à l’intérieur de l’image Docker au moment de la création du package. copy n’est pas pris en charge sur les espaces de travail avec liaison privée.	Non

Python

Attribut	Type	Description	Obligatoire
target_environment	str	Nom du package à créer. Le résultat d’une opération d’empaquetage est un environnement dans Azure Machine Learning.	Oui
base_environment_source	BaseEnvironment	L’mage de base à utiliser pour créer le package où les dépendances du modèle sont spécifiées.	Oui, sauf si le type de modèle est MLflow.
base_environment_source.type	BaseEnvironmentType	Le type de l’image de base. Utilisez uniquement un autre environnement (EnvironmentAsset), car l’image de base est prise en charge.
base_environment_source.resource_id	str	L’ID de ressource de l’environnement de base à utiliser. Utilisez le format azureml:<name>:<version> ou un ID de ressource long.
inferencing_server	AzureMLOnlineInferencingServer CustomOnlineInferenceServer	Le serveur d’inférence à utiliser. Utilisez AzureMLOnlineInferencingServer pour le serveur d’inférence Azure Machine Learning, ou CustomOnlineInferenceServer pour un serveur en ligne personnalisé tel que TensorFlow service ou Torch Serve, etc. Si la valeur est AzureMLInferencingServer et que le type de modèle n’est pas Mlflow, une section de configuration de code doit être spécifiée, contenant au moins un fichier Python avec des méthodes init et run. Si la valeur est CustomOnlineInferenceServer, une section de configuration de serveur en ligne doit être spécifiée.	Oui
model_configuration	ModelConfiguration	La configuration du modèle. Utilisez cet attribut pour contrôler la façon dont le modèle est empaqueté dans l’image résultante.	Non
model_configuration.mode	ModelInputMode	Indiquez comment le modèle serait placé dans le package. Les valeurs possibles sont ModelInputMode.DOWNLOAD (par défaut) et ModelInputMode.COPY. Utilisez ModelInputMode.DOWNLOAD quand vous voulez que le modèle soit téléchargé depuis le registre de modèles au moment du déploiement. Cette option crée des images Docker plus petites, car le modèle n’y est pas inclus. Utilisez ModelInputMode.COPY quand vous voulez déconnecter l’image d’Azure Machine Learning. Le modèle sera copié à l’intérieur de l’image Docker au moment de la création du package. ModelInputMode.COPY n’est pas pris en charge sur les espaces de travail avec liaison privée.	Non

1. Créez une spécification de paquet en suivant ces étapes :

   Azure CLI

   package-moe.yml

   $schema: http://azureml/sdk-2-0/ModelVersionPackage.json
   base_environment_source:
       type: environment_asset
       resource_id: azureml:sklearn-regression-env:1
   target_environment: sklearn-regression-online-pkg
   inferencing_server: 
       type: azureml_online
       code_configuration:
         code: src
         scoring_script: score.py
   

   Python

   Pour créer un modèle empaqueté, créez une spécification de paquet comme suit :

   pakage_config = ModelPackage(
       target_environment="sklearn-regression-online-pkg",
       base_environment_source=BaseEnvironment(
           type="asset",
           resource_id=f"azureml:{base_environment.name}:{base_environment.version}",
       ),
       inferencing_server=AzureMLOnlineInferencingServer(
           code_configuration=CodeConfiguration(code="src", scoring_script="score.py")
       ),
   )

2. Lancez l’opération d’empaquetage de modèle :

   Azure CLI

   az ml model package -n $MODEL_NAME -v $MODEL_VERSION --file package-moe.yml
   

   Python

   model_package = ml_client.models.package(model_name, model.version, pakage_config)

3. Le résultat de l’opération d’empaquetage est un environnement.

Empaqueter un modèle qui a des dépendances dans les flux Python privés

Les modèles empaquetés peuvent résoudre les dépendances Python disponibles dans les flux privés. Pour utiliser cette fonctionnalité, vous devez créer une connexion entre votre espace de travail et le flux et spécifier la configuration du jeton PAT. Le code Python suivant montre comment configurer l’espace de travail où vous exécutez l’opération d’empaquetage.

from azure.ai.ml.entities import WorkspaceConnection
from azure.ai.ml.entities import PatTokenConfiguration

# fetching secrets from env var to secure access, these secrets can be set outside or source code
git_pat = os.environ["GIT_PAT"]

credentials = PatTokenConfiguration(pat=git_pat)

ws_connection = WorkspaceConnection(
    name="<workspace_connection_name>",
    target="<git_url>",
    type="git",
    credentials=credentials,
)

ml_client.connections.create_or_update(ws_connection)

Une fois la connexion créée, générez le modèle empaqueté comme décrit dans la section Empaqueter un modèle. Dans l’exemple suivant, l’environnement de base du package utilise un flux privé pour la dépendance Python bar, comme spécifié dans le fichier conda suivant :

conda.yml

name: foo
channels:
  - defaults
dependencies:
  - python
  - pip
  - pip:
    - --extra-index-url <python_feed_url>
    - bar

Si vous utilisez un modèle MLflow, les dépendances du modèle sont indiquées à l’intérieur du modèle lui-même, et par conséquent, un environnement de base n’est pas nécessaire. Au lieu de cela, spécifiez les dépendances de flux privé lors de la journalisation du modèle, comme expliqué dans Journalisation des modèles avec une signature, un environnement ou des exemples personnalisés.

Empaqueter un modèle hébergé dans un registre

Les modèles empaquetés offrent un moyen pratique de collecter des dépendances avant le déploiement. Toutefois, lorsque les modèles sont hébergés dans des registres, la cible de déploiement est généralement un autre espace de travail. Lors de la création de packages dans cette configuration, utilisez la propriété target_environment pour spécifier l’emplacement complet où vous souhaitez que le modèle empaqueté soit créé, au lieu de son nom seulement.

Le code suivant crée un modèle t5-base empaqueté à partir d’un registre :

1. Connectez-vous au registre où se trouve le modèle et l’espace de travail dans lequel vous avez besoin que le modèle empaqueté soit créé :

   Azure CLI

   az login
   

   Python

   registry_client = MLClient(
       credential=DefaultAzureCredential(),
       subscription_id=ml_client.subscription_id,
       resource_group_name=ml_client.resource_group_name,
       workspace_reference=ml_client.workspace_name,
       registry_name=registry_name,
   )

2. Obtenez une référence au modèle que vous souhaitez empaqueter. Dans ce cas, nous empaquetons le modèle t5-base à partir du registre azureml.

   Azure CLI

   MODEL_NAME="t5-base"
   MODEL_VERSION=$(az ml model show --name $MODEL_NAME --label latest --registry-name azureml | jq .version -r)
   

   Python

   model_name = "t5-base"
   model = registry_client.models.get(name=model_name, label="latest")

3. Configurez une spécification de paquet. Étant donné que le modèle que nous voulons empaqueter est MLflow, l’environnement de base et le script de scoring sont facultatifs.

   Azure CLI

   package.yml

   $schema: http://azureml/sdk-2-0/ModelVersionPackage.json
   target_environment: pkg-t5-base-online
   inferencing_server: 
       type: azureml_online
   

   Python

   import time
   
   model_package_name = f"pkg-{model.name}-{model.version}"
   model_package_version = str(int(time.time()))
   
   package_config = ModelPackage(
       target_environment=model_package_name,
       target_environment_version=model_package_version,
       inferencing_server=AzureMLOnlineInferencingServer(),
   )

4. Démarrez l’opération pour créer le modèle empaqueté :

   Azure CLI

   az ml model package --name $MODEL_NAME \
                       --version $MODEL_VERSION \
                       --registry-name azureml \
                       --file package.yml
   

   Python

   model_package = registry_client.models.package(
       model.name, model.version, package_config
   )

5. Le package est maintenant créé dans l’espace de travail cible et prêt à être déployé.

Modèles empaquetés à déployer en dehors d’Azure Machine Learning

Les modèles empaquetés peuvent être déployés en dehors d’Azure Machine Learning si nécessaire. Pour garantir la portabilité, assurez-vous simplement que la configuration du modèle dans votre package a la valeur copy pour que le modèle lui-même soit copié à l’intérieur de l’image Docker générée au lieu d’être référencée à partir du registre de modèles dans Azure Machine Learning.

Le code suivant montre comment configurer copy dans un modèle empaqueté :

Azure CLI

package-external.yml

$schema: http://azureml/sdk-2-0/ModelVersionPackage.json
base_environment_source:
    type: environment_asset
    resource_id: azureml:sklearn-regression-env:1
target_environment: sklearn-regression-docker-pkg
inferencing_server: 
    type: azureml_online
    code_configuration:
      code: src
      scoring_script: score.py
model_configuration:
  mode: copy

Python

pakage_config = ModelPackage(
    target_environment="sklearn-regression-online-pkg",
    base_environment_source=BaseEnvironment(
        type="asset",
        resource_id=f"azureml:{base_environment.name}:{base_environment.version}",
    ),
    inferencing_server=AzureMLOnlineInferencingServer(
        code_configuration=CodeConfiguration(code="src", scoring_script="score.py")
    ),
    model_configuration=ModelConfiguration(mode="copy"),
)

Étape suivante

• Empaquetez et déployer un modèle sur des points de terminaison en ligne.
• Empaquetez et déployer un modèle sur App Service.