Guide pratique pour déployer un modèle R inscrit sur un point de terminaison (en temps réel) en ligne

Article
04/04/2023

S’APPLIQUE À :Extension Azure ML CLI v2 (actuelle)

Dans cet article, vous apprenez à déployer un modèle R sur un point de terminaison managé (API web), afin que votre application puisse noter de nouvelles données par rapport au modèle en quasi-temps réel.

Prérequis

Un espace de travail Azure Machine Learning.
Azure CLI et l’extension ml installées. Vous pouvez également utiliser une instance de calcul dans votre espace de travail, sur lequel l’interface CLI est préinstallée.
Au moins un environnement personnalisé associé à votre espace de travail. Créez un environnement R ou tout autre environnement personnalisé si vous n’en avez pas.
Compréhension du package R plumber
Un modèle que vous avez entraîné et empaqueté avec crate, et inscrit dans votre espace de travail

Créer un dossier avec cette structure

Créez cette structure de dossiers pour votre projet :

📂 r-deploy-azureml
 ├─📂 docker-context
 │  ├─ Dockerfile
 │  └─ start_plumber.R
 ├─📂 src
 │  └─ plumber.R
 ├─ deployment.yml
 ├─ endpoint.yml

Le contenu de chacun de ces fichiers est affiché et expliqué dans cet article.

Dockerfile

Il s’agit du fichier qui définit l’environnement de conteneur. Vous allez également définir l’installation de tous les packages R supplémentaires ici.

Un exemple de fichier Dockerfile ressemble à ceci :

# REQUIRED: Begin with the latest R container with plumber
FROM rstudio/plumber:latest

# REQUIRED: Install carrier package to be able to use the crated model (whether from a training job
# or uploaded)
RUN R -e "install.packages('carrier', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"

# OPTIONAL: Install any additional R packages you may need for your model crate to run
RUN R -e "install.packages('<PACKAGE-NAME>', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"
RUN R -e "install.packages('<PACKAGE-NAME>', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"

# REQUIRED
ENTRYPOINT []

COPY ./start_plumber.R /tmp/start_plumber.R 

CMD ["Rscript", "/tmp/start_plumber.R"]

Modifiez le fichier afin d’ajouter les packages dont vous avez besoin pour votre script de scoring.

plumber.R

Important

Cette section montre comment structurer le script plumber.R. Pour plus d’informations sur le package plumber, consultez la documentationplumber.

Le fichier plumber.R est le script R dans lequel vous allez définir la fonction pour le scoring. Ce script effectue également les tâches nécessaires au bon fonctionnement de votre point de terminaison. Le script :

Obtient le chemin par lequel le modèle est monté à partir de la variable d’environnement AZUREML_MODEL_DIR dans le conteneur.
Charge un objet de modèle créé avec la fonction crate, à partir du package carrier, qui a été enregistré sous le nom crate.bin lors de son empaquetage.
Annule la sérialisation de l’objet de modèle
Définit la fonction de scoring

Conseil

Assurez-vous que tout ce que votre fonction de scoring produit peut être reconverti en JSON. Certains objets R ne sont pas facilement convertis.

# plumber.R
# This script will be deployed to a managed endpoint to do the model scoring

# REQUIRED
# When you deploy a model as an online endpoint, Azure Machine Learning mounts your model
# to your endpoint. Model mounting enables you to deploy new versions of the model without
# having to create a new Docker image.

model_dir <- Sys.getenv("AZUREML_MODEL_DIR")

# REQUIRED
# This reads the serialized model with its respecive predict/score method you 
# registered. The loaded load_model object is a raw binary object.
load_model <- readRDS(paste0(model_dir, "/models/crate.bin"))

# REQUIRED
# You have to unserialize the load_model object to make it its function
scoring_function <- unserialize(load_model)

# REQUIRED
# << Readiness route vs. liveness route >>
# An HTTP server defines paths for both liveness and readiness. A liveness route is used to
# check whether the server is running. A readiness route is used to check whether the 
# server's ready to do work. In machine learning inference, a server could respond 200 OK 
# to a liveness request before loading a model. The server could respond 200 OK to a
# readiness request only after the model has been loaded into memory.

#* Liveness check
#* @get /live
function() {
  "alive"
}

#* Readiness check
#* @get /ready
function() {
  "ready"
}

# << The scoring function >>
# This is the function that is deployed as a web API that will score the model
# Make sure that whatever you are producing as a score can be converted 
# to JSON to be sent back as the API response
# in the example here, forecast_horizon (the number of time units to forecast) is the input to scoring_function.  
# the output is a tibble
# we are converting some of the output types so they work in JSON


#* @param forecast_horizon 
#* @post /score
function(forecast_horizon) {
  scoring_function(as.numeric(forecast_horizon)) |> 
    tibble::as_tibble() |> 
    dplyr::transmute(period = as.character(yr_wk),
                     dist = as.character(logmove),
                     forecast = .mean) |> 
    jsonlite::toJSON()
}

start_plumber.R

Le fichier start_plumber.R est le script R qui est exécuté au démarrage du conteneur et qui appelle votre script plumber.R. Utilisez le script tel quel.

entry_script_path <- paste0(Sys.getenv('AML_APP_ROOT'),'/', Sys.getenv('AZUREML_ENTRY_SCRIPT'))

pr <- plumber::plumb(entry_script_path)

args <- list(host = '0.0.0.0', port = 8000); 

if (packageVersion('plumber') >= '1.0.0') {
  pr$setDocs(TRUE)
} else { 
  args$swagger <- TRUE 
} 

do.call(pr$run, args)

Générer un conteneur

Ces étapes supposent que vous disposez d’une instance Azure Container Registry associée à votre espace de travail ; elle est créée lorsque vous créez votre premier environnement personnalisé. Pour voir si vous disposez d’un environnement personnalisé :

Connectez-vous à Azure Machine Learning Studio.
Sélectionnez votre espace de travail si nécessaire.
Dans le volet de navigation de gauche, sélectionnez Environnements.
En haut, sélectionnez Environnements personnalisés.
Si vous voyez des environnements personnalisés, rien de plus n’est nécessaire.
Si vous ne voyez aucun environnement personnalisé, créez un environnement R ou tout autre environnement personnalisé. (Vous n’utiliserez pas cet environnement pour le déploiement, mais vous utiliserez le registre de conteneurs qui est également créé pour vous.)

Après avoir vérifié que vous disposez d’au moins un environnement personnalisé, suivez ces étapes pour générer un conteneur.

Ouvrez une fenêtre de terminal et connectez-vous à Azure. Si vous effectuez cette opération à partir d’une instance de calcul Azure Machine Learning, utilisez :
```
az login --identity
```
Si vous n’êtes pas sur l’instance de calcul, omettez --identity et suivez l’invite pour ouvrir une fenêtre de navigateur et vous authentifier.
Vérifiez que vous disposez des versions les plus récentes de l’interface CLI et de l’extension ml :
```
az upgrade
```
Si vous avez plusieurs abonnements Azure, définissez l’abonnement actif sur celui que vous utilisez pour votre espace de travail. (Vous pouvez ignorer cette étape si vous n’avez accès qu’à un abonnement unique.) Remplacez <SUBSCRIPTION-NAME> par le nom de votre abonnement. Supprimez également les crochets <>.
```
az account set --subscription "<SUBSCRIPTION-NAME>"
```
Définissez l'espace de travail par défaut. Si vous effectuez cette opération à partir d’une instance de calcul, vous pouvez utiliser la commande suivante telle quelle. Si vous êtes sur un autre ordinateur, remplacez les noms du groupe de ressources et de l’espace de travail par les vôtres. (Vous trouvez ces valeurs dans Azure Machine Learning studio.)
```
az configure --defaults group=$CI_RESOURCE_GROUP workspace=$CI_WORKSPACE
```
Vérifiez que vous êtes dans le répertoire de votre projet.
```
cd r-deploy-azureml
```
Pour générer l’image dans le cloud, exécutez les commandes bash suivantes dans votre terminal. Remplacez <IMAGE-NAME> par le nom que vous souhaitez donner à l’image.

Si votre espace de travail se trouve dans un réseau virtuel, consultez Activer Azure Container Registry (ACR) pour connaître les étapes supplémentaires permettant d’ajouter --image-build-compute à la commande az acr build dans la dernière ligne de ce code.
```
WORKSPACE=$(az config get --query "defaults[?name == 'workspace'].value" -o tsv)
ACR_NAME=$(az ml workspace show -n $WORKSPACE --query container_registry -o tsv | cut -d'/' -f9-)
IMAGE_TAG=${ACR_NAME}.azurecr.io/<IMAGE-NAME>

az acr build ./docker-context -t $IMAGE_TAG -r $ACR_NAME
```

Important

La création de l’image prend quelques minutes. Attendez que le processus de génération se termine avant de passer à la section suivante. Ne fermez pas ce terminal, vous allez bientôt l’utiliser pour créer le déploiement.

La commande az acr charge automatiquement votre dossier de contexte Docker (qui contient les artefacts de génération de l’image) dans le cloud où l’image sera générée et hébergée dans une instance Azure Container Registry.

Déployer un modèle

Dans cette section de l’article, vous allez définir et créer un point de terminaison et un déploiement pour déployer le modèle et l’image créés aux étapes précédentes sur un point de terminaison en ligne managé.

Un point de terminaison est un point de terminaison HTTPS que les clients, tels qu’une application, peuvent appeler pour recevoir la sortie de scoring d’un modèle entraîné. Il offre :

Authentification basée sur la méthode « clé et jeton »
Arrêt SSL
Un URI de scoring stable (endpoint-name.region.inference.ml.Azure.com)

Un déploiement est un ensemble de ressources nécessaires à l’hébergement du modèle qui procède au scoring réel. Un point de terminaisonunique peut contenir plusieursdéploiements. Les fonctionnalités d’équilibrage de charge des points de terminaison managés Azure Machine Learning vous permettent de donner un pourcentage de trafic à chaque déploiement. L’allocation du trafic peut être utilisée pour effectuer des déploiements bleus/verts sûrs en équilibrant les requêtes entre les différentes instances.

Créer un point de terminaison en ligne managé

Dans le répertoire de votre projet, ajoutez le fichier endpoint.yml avec le code suivant. Remplacez <ENDPOINT-NAME> par le nom que vous souhaitez donner à votre point de terminaison managé.
```
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: <ENDPOINT-NAME>
auth_mode: aml_token
```
À l’aide du même terminal que celui qui vous a servi à générer l’image, exécutez la commande CLI suivante pour créer un point de terminaison :
```
az ml online-endpoint create -f endpoint.yml
```
Laissez le terminal ouvert pour continuer à l’utiliser dans la section suivante.

Créer un déploiement

Pour créer votre déploiement, ajoutez le code suivant au fichier deployment.yml.

Remplacez <ENDPOINT-NAME> par le nom du point de terminaison que vous avez défini dans le fichier endpoint.yml.
Remplacez <DEPLOYMENT-NAME> par le nom que vous souhaitez donner au déploiement.
Remplacez <MODEL-URI> par l’URI du modèle inscrit, sous la forme azureml:modelname@latest.
Remplacez <IMAGE-TAG> par la valeur provenant de :
```
echo $IMAGE_TAG
```

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: <DEPLOYMENT-NAME>
endpoint_name: <ENDPOINT-NAME>
code_configuration:
  code: ./src
  scoring_script: plumber.R
model: <MODEL-URI>
environment:
  image: <IMAGE-TAG>
  inference_config:
    liveness_route:
      port: 8000
      path: /live
    readiness_route:
      port: 8000
      path: /ready
    scoring_route:
      port: 8000
      path: /score
instance_type: Standard_DS2_v2
instance_count: 1

Ensuite, dans votre terminal, exécutez la commande CLI suivante pour créer le déploiement (notez que vous définissez 100 % du trafic sur ce modèle) :
```
az ml online-deployment create -f deployment.yml --all-traffic --skip-script-validation
```

Notes

Le déploiement du service peut prendre plusieurs minutes. Attendez que le déploiement soit terminé avant de passer à la section suivante.

Test

Une fois votre déploiement correctement créé, vous pouvez tester le point de terminaison à l’aide du studio ou de l’interface CLI :

Studio
Azure CLI

Accédez à Azure Machine Learning studio et sélectionnez Points de terminaison dans le menu de gauche. Ensuite, sélectionnez le point de terminaison r-endpoint-iris que vous avez créé précédemment.

Entrez le code json suivant dans la zone de texte Données d’entrée pour tester le point de terminaison en temps réel :

{
    "forecast_horizon" : [2]
}

Sélectionnez Test. Vous devez normalement voir la sortie suivante :

Créer un exemple de requête

Dans le dossier parent de votre projet, créez un fichier appelé sample_request.json et remplissez-le avec :

{
    "forecast_horizon" : [2]
}

Appeler le point de terminaison

Appelez la requête. Cet exemple utilise le nom r-endpoint-forecast :

az ml online-endpoint invoke --name r-endpoint-forecast --request-file sample_request.json

Nettoyer les ressources

Maintenant que vous avez obtenu un score avec votre point de terminaison, vous pouvez le supprimer pour ne pas entraîner de coûts récurrents :

az ml online-endpoint delete --name r-endpoint-forecast

Étapes suivantes

Pour plus d’informations sur l’utilisation de R avec Azure Machine Learning, consultez Vue d’ensemble des fonctionnalités R dans Azure Machine Learning