Bereitstellen eines registrierten R-Modells auf einem Onlineendpunkt (Echtzeitendpunkt)

Artikel
04/04/2023

GILT FÜRAzure CLI-ML-Erweiterung v2 (aktuell)

In diesem Artikel erfahren Sie, wie Sie ein R-Modell auf einem verwalteten Endpunkt (Web-API) bereitstellen, damit Ihre Anwendung in Quasi-Echtzeit neue Daten anhand des Modells bewerten kann.

Voraussetzungen

Ein Azure Machine Learning-Arbeitsbereich.
Installation der Azure-Befehlszeilenschnittstelle (Azure CLI) und der ML-Erweiterung. Alternativ können Sie eine Compute-Instanz in Ihrem Arbeitsbereich verwenden, auf der die CLI vorinstalliert ist.
Mindestens eine benutzerdefinierte Umgebung, die Ihrem Arbeitsbereich zugeordnet ist. Erstellen Sie eine R-Umgebung oder eine andere benutzerdefinierte Umgebung, falls Sie noch keine haben.
Verständnis des R plumber-Pakets
Ein Modell, das Sie trainiert, mit crate gepackt und in Ihrem Arbeitsbereich registriert haben

Erstellen eines Ordners mit dieser Struktur

Erstellen Sie diese Ordnerstruktur für Ihr Projekt:

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

Der Inhalt jeder dieser Dateien wird in diesem Artikel gezeigt und erläutert.

Dockerfile

Dies ist die Datei, die die Containerumgebung definiert. Außerdem definieren Sie hier die Installation zusätzlicher R-Pakete.

Eine Dockerfile sieht z. B. wie folgt aus:

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

Ändern Sie die Datei, um die Pakete hinzuzufügen, die Sie für Ihr Bewertungsskript benötigen.

plumber.R

Wichtig

In diesem Abschnitt wird gezeigt, wie Sie das plumber.R-Skript strukturieren. Ausführliche Informationen zum plumber-Paket finden Sie in der plumber-Dokumentation.

Die Datei plumber.R ist das R-Skript, in dem Sie die Funktion für die Bewertung definieren. Dieses Skript führt auch Aufgaben aus, die für die einwandfreie Funktion Ihres Endpunkts erforderlich sind. Das Skript

Ruft den Pfad ab, in den das Modell über die AZUREML_MODEL_DIR-Umgebungsvariable im Container eingebunden wird.
Lädt ein mit der crate-Funktion erstelltes Modellobjekt aus dem carrier-Paket, das beim Packen als crate.bin gespeichert wurde.
Deserialisiert das Modellobjekt.
Definiert die Bewertungsfunktion.

Tipp

Stellen Sie sicher, dass alle Ausgaben Ihrer Bewertungsfunktion wieder in JSON konvertiert werden können. Einige R-Objekte können nicht problemlos konvertiert werden.

# 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

Die Datei start_plumber.R ist das R-Skript, das beim Start des Containers ausgeführt wird und Ihr plumber.R-Skript aufruft. Verwenden Sie das folgende Skript unverändert.

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)

Erstellen des Containers

Bei diesen Schritten wird davon ausgegangen, dass Ihrem Arbeitsbereich eine Azure Container Registry-Instanz zugeordnet ist (diese wird beim Erstellen Ihrer ersten benutzerdefinierten Umgebung erstellt). Gehen Sie wie folgt vor, um zu überprüfen, ob Sie über eine benutzerdefinierte Umgebung verfügen:

Melden Sie sich bei Azure Machine Learning Studio an.
Wählen Sie ggf. Ihren Arbeitsbereich aus.
Wählen Sie im linken Navigationsbereich Umgebungen aus.
Wählen Sie oben Benutzerdefinierte Umgebungen aus.
Wenn benutzerdefinierte Umgebungen angezeigt werden, sind keine weiteren Schritte erforderlich.
Falls keine benutzerdefinierten Umgebungen angezeigt werden, erstellen Sie eine R-Umgebung oder eine andere benutzerdefinierte Umgebung. (Sie verwenden diese Umgebung nicht für die Bereitstellung, aber Sie verwenden die Containerregistrierung, die ebenfalls für Sie erstellt wird.)

Nachdem Sie sich vergewissert haben, dass Sie über mindestens eine benutzerdefinierte Umgebung verfügen, führen Sie die folgenden Schritte aus, um einen Container zu erstellen.

Öffnen Sie ein Terminalfenster, und melden Sie sich bei Azure an. Wenn Sie dazu eine Azure Machine Learning-Compute-Instanz verwenden, führen Sie den folgenden Befehl aus:
```
az login --identity
```
Wenn Sie keine Compute-Instanz verwenden, lassen Sie --identity weg, und folgen Sie der Aufforderung, ein Browserfenster zur Authentifizierung zu öffnen.
Stellen Sie sicher, dass Sie über die neuesten Versionen der CLI und der Erweiterung ml verfügen:
```
az upgrade
```
Wenn Sie über mehrere Azure-Abonnements verfügen, legen Sie das aktive Abonnement auf das Abonnement fest, das Sie für Ihren Arbeitsbereich verwenden. (Sie können diesen Schritt überspringen, wenn Sie nur Zugriff auf ein einzelnes Abonnement haben.) Ersetzen Sie <SUBSCRIPTION-NAME> durch Ihren Abonnementnamen. Entfernen Sie auch die Klammern <>.
```
az account set --subscription "<SUBSCRIPTION-NAME>"
```
Legen Sie den Standardarbeitsbereich fest. Wenn Sie dazu eine Compute-Instanz verwenden, können Sie den folgenden Befehl unverändert ausführen. Falls Sie einen anderen Computer verwenden, setzen Sie an den entsprechenden Stellen Ihren Ressourcengruppennamen und Arbeitsbereichsnamen ein. (Sie finden diese Werte in Azure Machine Learning Studio.)
```
az configure --defaults group=$CI_RESOURCE_GROUP workspace=$CI_WORKSPACE
```
Stellen Sie sicher, dass Sie sich in Ihrem Projektverzeichnis befinden.
```
cd r-deploy-azureml
```
Führen Sie die folgenden Bash-Befehle in Ihrem Terminal aus, um das Image in der Cloud zu erstellen. Ersetzen Sie <IMAGE-NAME> durch den Namen, den Sie für das Image verwenden möchten.

Wenn sich Ihr Arbeitsbereich in einem virtuellen Netzwerk befindet, finden Sie unter Aktivieren von Azure Container Registry (ACR) weitere Schritte, mit denen Sie dem Befehl az acr build in der letzten Zeile dieses Codes --image-build-compute hinzufügen können.
```
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
```

Wichtig

Die Erstellung des Images nimmt einige Minuten in Anspruch. Warten Sie, bis der Erstellungsvorgang abgeschlossen ist, bevor Sie mit dem nächsten Abschnitt fortfahren. Schließen Sie dieses Terminal nicht. Sie verwenden es als Nächstes zum Erstellen der Bereitstellung.

Der Befehl az acr lädt Ihren Ordner „docker-context“, der die Artefakte zum Erstellen des Images enthält, automatisch in die Cloud hoch, wo das Image dann erstellt und in einer Azure Container Registry-Instanz gehostet wird.

Bereitstellen des Modells

In diesem Abschnitt des Artikels definieren und erstellen Sie einen Endpunkt und eine Bereitstellung, um das Modell und das in den vorherigen Schritten erstellte Image auf einem verwalteten Onlineendpunkt bereitzustellen.

Ein Endpunkt ist ein HTTPS-Endpunkt, der von Clients wie z. B. einer Anwendung aufgerufen werden kann, um die Bewertungsausgabe eines trainierten Modells zu empfangen. Sie bietet:

Authentifizierung mit "Schlüssel & Token"-basierter Authentifizierung
SSL-Terminierung
Einen Stabilen Bewertungs-URI (endpoint-name.region.inference.ml.azure.com)

Eine Bereitstellung ist ein Satz erforderlicher Ressourcen für das Hosting des Modells, das die eigentliche Bewertung durchführt. Ein einzelnerEndpunkt kann mehrereBereitstellungen enthalten. Mit den Lastenausgleichsfunktionen von verwalteten Azure Machine Learning-Endpunkten können Sie jeder Bereitstellung einen beliebigen Prozentsatz des Datenverkehrs zuordnen. Die Verkehrsaufteilung kann verwendet werden, um sichere Blue/Green-Rollouts durchzuführen, indem Anfragen zwischen verschiedenen Instanzen ausgeglichen werden.

Erstellen eines verwalteten Onlineendpunkts

Fügen Sie in Ihrem Projektverzeichnis die Datei endpoint.yml mit dem folgenden Code hinzu. Ersetzen Sie <ENDPOINT-NAME> durch den Namen, den Sie für den verwalteten Endpunkt verwenden möchten.
```
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: <ENDPOINT-NAME>
auth_mode: aml_token
```
Führen Sie in demselben Terminal, in dem Sie das Image erstellt haben, den folgenden CLI-Befehl aus, um einen Endpunkt zu erstellen:
```
az ml online-endpoint create -f endpoint.yml
```
Lassen Sie das Terminal geöffnet, damit Sie es im nächsten Abschnitt weiter verwenden können.

Bereitstellung erstellen

Fügen Sie der Datei deployment.yml den folgenden Code hinzu, um Ihre Bereitstellung zu erstellen.

Ersetzen Sie <ENDPOINT-NAME> durch den Endpunktnamen, den Sie in der Datei endpoint.yml definiert haben.
Ersetzen Sie <DEPLOYMENT-NAME> durch den Namen, den Sie für die Bereitstellung verwenden möchten.
Ersetzen Sie <MODEL-URI> durch den URI des registrierten Modells im Format azureml:modelname@latest.
Ersetzen Sie <IMAGE-TAG> durch den Wert, den Sie mit folgendem Befehl ermitteln:
```
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

Führen Sie als Nächstes in Ihrem Terminal den folgenden CLI-Befehl aus, um die Bereitstellung zu erstellen (beachten Sie, dass Sie 100 % des Datenverkehrs für dieses Modell zuordnen):
```
az ml online-deployment create -f deployment.yml --all-traffic --skip-script-validation
```

Hinweis

Die Bereitstellung des Diensts kann einige Minuten in Anspruch nehmen. Warten Sie, bis die Bereitstellung abgeschlossen ist, bevor Sie mit dem nächsten Abschnitt fortfahren.

Test

Nachdem Ihre Bereitstellung erfolgreich erstellt wurde, können Sie den Endpunkt mithilfe von Studio oder der CLI testen:

Studio
Azure-Befehlszeilenschnittstelle

Navigieren Sie zu Azure Machine Learning Studio, und wählen Sie im linken Menü Endpunkte aus. Wählen Sie als Nächstes den zuvor erstellten R-Endpunkt aus.

Geben Sie den folgenden JSON-Code in das Textfeld Zum Testen des Echtzeitendpunkts Daten eingeben ein:

{
    "forecast_horizon" : [2]
}

Klicken Sie auf Test. Die folgende Ausgabe wird angezeigt.

Erstellen einer Beispielanforderung

Erstellen Sie in Ihrem übergeordneten Projektordner eine Datei namens sample_request.json, und füllen Sie sie mit folgendem Code auf:

{
    "forecast_horizon" : [2]
}

Aufrufen des Endpunkts

Rufen Sie die Anforderung auf. In diesem Beispiel wird der Name „r-endpoint-forecast“ verwendet:

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

Bereinigen von Ressourcen

Nachdem Sie die Bewertung erfolgreich mit Ihrem Endpunkt durchgeführt haben, können Sie ihn löschen, damit keine laufenden Kosten anfallen:

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

Nächste Schritte

Weitere Informationen zur Verwendung von R mit Azure Machine Learning finden Sie unter Overview of R capabilities in Azure Machine Learning (Übersicht: R-Funktionen in Azure Machine Learning).