Procedimiento para implementar un modelo de R registrado en un punto de conexión en línea (en tiempo real)

Artículo
04/18/2023

SE APLICA A:Extensión de ML de la CLI de Azure v2 (actual)

En este artículo, aprenderá a implementar un modelo de R en un punto de conexión administrado (API web) para que la aplicación pueda puntuar nuevos datos en el modelo casi en tiempo real.

Requisitos previos

Un área de trabajo de Azure Machine Learning.
La CLI de Azure y la extensión ml instaladas. O bien, use una instancia de proceso en el área de trabajo, que tiene la CLI preinstalada.
Al menos un entorno personalizado asociado al área de trabajo. Cree un entorno de R o cualquier otro entorno personalizado si no tiene uno.
Descripción del paquete plumber de R
Un modelo que ha entrenado y empaquetado con crate y ha registrado en el área de trabajo

Crear una carpeta con esta estructura

Cree esta estructura de carpetas para el proyecto:

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

El contenido de cada uno de estos archivos se muestra y se explica en este artículo.

Dockerfile

Este es el archivo que define el entorno de contenedor. También definirá aquí la instalación de cualquier paquete de R adicional.

Un dockerfile de ejemplo tendrá este aspecto:

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

Modifique el archivo para agregar los paquetes que necesita para el script de puntuación.

plumber.R

Importante

En esta sección se muestra cómo estructurar el script plumber.R. Para obtener información detallada sobre el paquete plumber, vea la documentación de plumber.

El archivo plumber.R es el script de R donde definirá la función para la puntuación. Este script también realiza tareas necesarias para que el punto de conexión funcione. El script:

Obtiene la ruta de acceso donde se monta el modelo desde la variable de entorno AZUREML_MODEL_DIR del contenedor.
Carga un objeto de modelo creado con la función crate del paquete carrier, que se ha guardado como crate.bin al se empaquetarlo.
Deserializa el objeto de modelo
Define la función de puntuación

Sugerencia

Asegúrese de que cualquier función de puntuación que genere se pueda convertir a JSON. Algunos objetos de R no se convierten fácilmente.

# 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

El archivo start_plumber.R es el script de R que se ejecuta cuando se inicia el contenedor y llama al script de plumber.R. Para ello, use tal cual el script siguiente.

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)

Compilación del contenedor

En estos pasos se supone que tiene una instancia de Azure Container Registry asociada al área de trabajo, que se crea al crear el primer entorno personalizado. Para ver si tiene un entorno personalizado:

Inicie sesión en Azure Machine Learning Studio.
Seleccione el área de trabajo si es necesario.
En el panel de navegación de la izquierda, seleccione Entornos.
En la parte superior, seleccione Entornos personalizados.
Si ve entornos personalizados, no se necesita hacer nada más.
Si no ve ningún entorno personalizado, cree un entorno de R o cualquier otro entorno personalizado. (No usará este entorno para la implementación, si no que usará el registro de contenedor que también se crea automáticamente).

Una vez que compruebe que tiene al menos un entorno personalizado, siga estos pasos para crear un contenedor.

Abra una ventana de terminal e inicie sesión en Azure. Si lo hace desde una instancia de proceso de Azure Machine Learning, use lo siguiente:
```
az login --identity
```
Si no está en la instancia de proceso, omita --identity y siga las indicaciones para abrir una ventana del explorador para autenticarse.
Asegúrese de que tiene las versiones más recientes de la CLI y la extensión ml:
```
az upgrade
```
Si tiene varias suscripciones de Azure, establezca la suscripción activa en la que use para el área de trabajo. (Puede omitir este paso si solo tiene acceso a una sola suscripción). Reemplace <SUBSCRIPTION-NAME> por el nombre de la suscripción. Quite también los corchetes <>.
```
az account set --subscription "<SUBSCRIPTION-NAME>"
```
Establezca el área de trabajo predeterminada. Si lo hace desde una instancia de proceso, puede usar el siguiente comando tal cual. Si está en cualquier otro equipo, sustituya el nombre del grupo de recursos y del área de trabajo en su lugar. (Encontrará estos valores en Estudio de Azure Machine Learning).
```
az configure --defaults group=$CI_RESOURCE_GROUP workspace=$CI_WORKSPACE
```
Asegúrese de que se encuentra en el directorio de proyectos.
```
cd r-deploy-azureml
```
Para compilar la imagen en la nube, ejecute los siguientes comandos de Bash en el terminal. Reemplace <IMAGE-NAME> por el nombre que quiera dar a la imagen.

Si el área de trabajo está en una red virtual, vea Habilitación de Azure Container Registry (ACR) a fin de obtener pasos adicionales para agregar --image-build-compute al comando az acr build en la última línea de este código.
```
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 imagen tardará unos minutos en compilarse. Espere a que el proceso de compilación se complete antes de continuar con la sección siguiente. No cierre este terminal, lo usará a continuación para crear la implementación.

El comando az acr cargará automáticamente la carpeta docker-context, que contiene los artefactos para compilar la imagen, en la nube donde se compilará y hospedará la imagen en una instancia de Azure Container Registry.

Implementación de un modelo

En esta sección del artículo, definirá y creará un punto de conexión e implementación para implementar el modelo y la imagen integrados en los pasos anteriores en un punto de conexión en línea administrado.

Un punto de conexión es un punto de conexión HTTPS al que los clientes, como una aplicación, pueden llamar para recibir la salida de puntuación de un modelo entrenado. Proporciona:

Autenticación mediante autenticación basada en "claves y tokens"
Terminación de SSL
Un URI de puntuación estable (nombre_del_punto_de_conexión.región.inference.ml.Azure.com)

Una implementación es un conjunto de recursos necesarios para hospedar el modelo que realiza la puntuación real. Un únicopunto de conexión puede contener variasimplementaciones. Las funcionalidades de equilibrio de carga de los puntos de conexión administrados de Azure Machine Learning permiten proporcionar cualquier porcentaje de tráfico a cada implementación. La asignación de tráfico se puede usar para realizar implementaciones azul/verde de lanzamiento seguras equilibrando las solicitudes entre las diferentes instancias.

Creación de un punto de conexión en línea administrado

En el directorio del proyecto, agregue el archivo endpoint.yml con el código siguiente. Reemplace <ENDPOINT-NAME> por el nombre que quiera dar al punto de conexión administrado.
```
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: <ENDPOINT-NAME>
auth_mode: aml_token
```
En el mismo terminal donde ha creado la imagen, ejecute el comando siguiente de la CLI para crear un punto de conexión:
```
az ml online-endpoint create -f endpoint.yml
```
Deje abierto el terminal para continuar usándolo en la sección siguiente.

Creación de una implementación

Para crear la implementación, agregue el código siguiente al archivo deployment.yml.

Reemplace <ENDPOINT-NAME> por el nombre del punto de conexión que ha definido en el archivo endpoint.yml
Reemplace <DEPLOYMENT-NAME> por el nombre que quiera dar a la implementación
Reemplace <MODEL-URI> por el URI del modelo registrado en forma de azureml:modelname@latest
Reemplace <IMAGE-TAG> por el valor 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

Después, en el terminal, ejecute el comando siguiente de la CLI para crear la implementación (tenga en cuenta que va a establecer el 100 % del tráfico en este modelo):
```
az ml online-deployment create -f deployment.yml --all-traffic --skip-script-validation
```

Nota

El servicio puede tardar varios minutos en implementarse. Espere hasta que finalice la implementación antes de continuar con la sección siguiente.

Prueba

Una vez que cree correctamente la implementación, puede probar el punto de conexión mediante Studio o la CLI:

Estudio
CLI de Azure

Vaya a Estudio de Azure Machine Learning y seleccione Puntos de conexión en el menú de la izquierda. Después, seleccione r-endpoint-iris que ha creado previamente.

Escriba el siguiente código JSON en el cuadro de texto Datos de entrada al punto de conexión en tiempo real:

{
    "forecast_horizon" : [2]
}

Seleccione Probar. Debería ver la salida siguiente:

Creación de una solicitud de ejemplo

En la carpeta primaria del proyecto, cree un archivo denominado sample_request.json y rellénelo con lo siguiente:

{
    "forecast_horizon" : [2]
}

Invocación del punto de conexión

Invoque la solicitud. En este ejemplo se usa el nombre r-endpoint-forecast:

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

Limpieza de recursos

Ahora que ha puntuado correctamente con el punto de conexión, puede eliminarlo para no incurrir en costos continuos:

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

Pasos siguientes

Para más información sobre el uso de R con Azure Machine Learning, vea Introducción a las funcionalidades de R en Azure Machine Learning