Come distribuire un modello R registrato in un endpoint online (in tempo reale)

Articolo
10/16/2024

SI APPLICA A: estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)

In questo articolo verrà spiegato come distribuire un modello R in un endpoint gestito (API Web) in modo che l'applicazione possa assegnare punteggi ai nuovi dati rispetto al modello in near real-time.

Prerequisiti

Un'area di lavoro di Azure Machine Learning.
Interfaccia della riga di comando di Azure ed estensione ML installata. In alternativa, usare un'istanza di ambiente di calcolo nell'area di lavoro, che include l'interfaccia della riga di comando preinstallata.
Almeno un ambiente personalizzato associato all'area di lavoro. Creare un ambiente R o qualsiasi altro ambiente personalizzato, se non ne è disponibile uno.
Conoscenza del pacchetto R plumber
Modello sottoposto a training e incluso in un pacchetto con crate e registrato nell'area di lavoro

Creare una cartella con questa struttura

Creare questa struttura di cartelle per il progetto:

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

Il contenuto di ognuno di questi file è illustrato e spiegato in questo articolo.

Dockerfile

Si tratta del file che definisce l'ambiente contenitore. Qui inoltre verrà definita l'installazione di eventuali pacchetti R aggiuntivi.

Un Dockerfile di esempio ha un aspetto simile a quanto segue:

# 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"]

Modificare il file per aggiungere i pacchetti necessari per lo script di assegnazione dei punteggi.

plumber.R

Importante

In questa sezione viene illustrato come strutturare lo script plumber.R. Per informazioni dettagliate sul pacchetto plumber, vedere la plumber documentazione .

Il file plumber.R è lo script R in cui si definirà la funzione per l'assegnazione dei punteggi. Questo script esegue anche attività necessarie al funzionamento dell'endpoint. Lo script:

Riceve il percorso in cui il modello viene montato dalla variabile di ambiente AZUREML_MODEL_DIR nel contenitore.
Carica un oggetto modello creato con la funzione crate dal pacchetto carrier salvato come crate.bin quando è stato incluso nel pacchetto.
Annulla la serializzazione dell'oggetto modello
Definisce la funzione di assegnazione dei punteggi

Suggerimento

Assicurarsi che qualsiasi prodotto della funzione di punteggio possa essere convertito in JSON. Alcuni oggetti R non vengono convertiti facilmente.

# 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

Il file start_plumber. R è lo script R che viene eseguito all'avvio del contenitore e chiama lo script plumber.R. Usare lo script seguente così come è.

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)

Compilare un contenitore

Questi passaggi presuppongono che sia associato un Registro Azure Container all'area di lavoro, che viene creato quando si crea il primo ambiente personalizzato. Per verificare se si dispone di un ambiente personalizzato:

Accedere ad Azure Machine Learning Studio.
Selezionare l'area di lavoro, se necessario.
Nel riquadro di spostamento a sinistra selezionare Ambienti.
Nella parte superiore selezionare Ambienti personalizzati.
Se vengono visualizzati ambienti personalizzati, non sono necessari altri elementi.
Se non vengono visualizzati ambienti personalizzati, creare un ambiente R o qualsiasi altro ambiente personalizzato. Questo ambiente non verrà usato per la distribuzione, ma verrà usato anche il registro contenitori creato automaticamente.

Una volta verificato di disporre di almeno un ambiente personalizzato, avviare un terminale e configurare l'interfaccia della riga di comando:

Aprire una finestra del terminale e accedere ad Azure. Se è in uso un'istanza di ambiente di calcolo di Azure Machine Learning, usare:
```
az login --identity
```
Se non si usa l'istanza di ambiente calcolo, omettere --identity e seguire la richiesta di aprire una finestra del browser per l'autenticazione.
Assicurarsi di avere le versioni più recenti dell'interfaccia della riga di comando e l'estensione ml:
```
az upgrade
```
Se si hanno più sottoscrizioni di Azure, impostare la sottoscrizione attiva su quella usata per l'area di lavoro. (È possibile ignorare questo passaggio se si ha accesso solo a una sottoscrizione singola.) Sostituire <YOUR_SUBSCRIPTION_NAME_OR_ID> con il nome o l'ID della sottoscrizione. Rimuovere anche le parentesi quadre <>.
```
az account set -s "<YOUR_SUBSCRIPTION_NAME_OR_ID>"
```
Impostare l'area di lavoro predefinita. Se è in uso un'istanza di ambiente di calcolo, è possibile mantenere il comando seguente così com'è. Se si usa qualsiasi altro computer, sostituire invece il gruppo di risorse e il nome dell'area di lavoro. È possibile trovare questi valori nello studio di Azure Machine Learning.
```
az configure --defaults group=$CI_RESOURCE_GROUP workspace=$CI_WORKSPACE
```

Dopo aver configurato l'interfaccia della riga di comando, seguire i passaggi successivi per creare un contenitore.

Assicurarsi di essere nella directory del progetto.
```
cd r-deploy-azureml
```
Per compilare l'immagine nel cloud, eseguire i comandi bash seguenti nel terminale. Sostituire <IMAGE-NAME> con il nome che si vuole assegnare all'immagine.

Se l'area di lavoro si trova in una rete virtuale, vedere Abilitare Registro Azure Container (ACR) per gli altri passaggi utili ad aggiungere --image-build-compute al comando az acr build nell'ultima riga di questo codice.
```
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
```

Importante

La compilazione dell'immagine richiederà alcuni minuti. Attendere il completamento del processo di compilazione prima di procedere alla sezione successiva. Non chiudere questo terminale, verrà usato successivamente per creare la distribuzione.

Il comando az acr caricherà automaticamente la cartella docker-context, che contiene gli artefatti per compilare l'immagine, nel cloud in cui verrà compilata e ospitata in un Registro Azure Container.

Distribuire un modello

In questa sezione dell'articolo si definirà e si creerà un endpoint e una distribuzione per distribuire il modello e l'immagine compilati nei passaggi precedenti a un endpoint gestito online.

Un endpoint è un endpoint HTTPS che i client, ad esempio un'applicazione, possono chiamare per ricevere l'output di assegnazione dei punteggi di un modello sottoposto a training. Offre:

Autenticazione con l'autenticazione basata su "chiave e token"
Terminazione SSL
URI di assegnazione dei punteggi stabile (endpoint-name.region.inference.ml.Azure.com)

Perdistribuzione si intende un set di risorse necessarie per ospitare il modello che esegue l'assegnazione dei punteggi effettiva. Un singolo endpoint può contenere più distribuzioni. Le funzionalità di bilanciamento del carico degli endpoint gestiti di Azure Machine Learning consentono di assegnare qualsiasi percentuale di traffico a ogni distribuzione. L'allocazione del traffico può essere usata per eseguire il rollout sicuro di distribuzioni blu/verdi bilanciando le richieste tra istanze diverse.

Creare un endpoint gestito online

Nella directory del progetto aggiungere il file endpoint.yml con il codice seguente. Sostituire <ENDPOINT-NAME> con il nome che si vuole assegnare all'endpoint gestito.
```
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: <ENDPOINT-NAME>
auth_mode: aml_token
```
Usando lo stesso terminale in cui è stata compilata l'immagine, eseguire il comando dell'interfaccia della riga di comando seguente per creare un endpoint:
```
az ml online-endpoint create -f endpoint.yml
```
Lasciare aperto il terminale per continuare a usarlo nella sezione successiva.

Creare la distribuzione

Per creare la distribuzione, aggiungere il codice seguente al file deployment.yml.

Sostituire <ENDPOINT-NAME> con il nome dell'endpoint definito nel file endpoint.yml
Sostituire <DEPLOYMENT-NAME> con il nome che si vuole assegnare alla distribuzione
Sostituire <MODEL-URI> con l'URI del modello registrato sotto forma di azureml:modelname@latest
Sostituire <IMAGE-TAG> con il valore da:
```
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

Successivamente, nel terminale eseguire il comando seguente dell'interfaccia della riga di comando per creare la distribuzione. Si noti che si sta impostando il 100% del traffico su questo modello:
```
az ml online-deployment create -f deployment.yml --all-traffic --skip-script-validation
```

Nota

La distribuzione del servizio potrebbe richiedere alcuni minuti. Attendere il completamento della distribuzione prima di procedere alla sezione successiva.

Test

Dopo aver creato correttamente la distribuzione, è possibile testare l'endpoint usando Studio o l'interfaccia della riga di comando:

Studio
Interfaccia della riga di comando di Azure

Passare allo studio di Azure Machine Learning e selezionare dal menu a sinistra Endpoint. Selezionare quindi r-endpoint-iris creato in precedenza.

Immettere il codice JSON seguente nella casella di testoDati di input per l'endpoint REST in tempo reale:

{
    "forecast_horizon" : [2]
}

Selezionare Verifica. Verrà visualizzato l'output seguente:

Creare una richiesta di esempio

Nella cartella padre del progetto creare un file denominato sample_request.json e popolarlo con:

{
    "forecast_horizon" : [2]
}

Richiamare l'endpoint

Richiamare la richiesta. In questo esempio viene usato il nome r-endpoint-forecast:

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

Pulire le risorse

Dopo aver ottenuto un punteggio con l'endpoint, è possibile eliminarlo in modo da non comportare costi continui:

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

Passaggi successivi

Per altre informazioni sull'uso di R con Azure Machine Learning, vedere Panoramica delle funzionalità R in Azure Machine Learning

Condividi tramite