Usare un contenitore personalizzato per distribuire un modello in un endpoint online

Articolo
10/18/2024

SI APPLICA A:Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)Python SDK azure-ai-ml v2 (corrente)

Informazioni su come usare un contenitore personalizzato per distribuire un modello in un endpoint online in Azure Machine Learning.

Le distribuzioni di contenitori personalizzate possono usare server Web diversi dal server Python Flask predefinito utilizzato da Azure Machine Learning. Gli utenti di queste distribuzioni possono comunque sfruttare i vantaggi del monitoraggio, del ridimensionamento, degli avvisi e dell'autenticazione predefiniti di Azure Machine Learning.

Nella tabella seguente sono elencati vari esempi di distribuzione che usano contenitori personalizzati, come TensorFlow Serving, TorchServe, Server inferenza DiCenter, pacchetto Plumber R e immagine minima dell'inferenza di Azure Machine Learning.

Esempio	Script (CLI)	Descrizione
minimal/multimodel	deploy-custom-container-minimal-multimodel	Distribuire diversi modelli in una singola distribuzione estendendo l'immagine minima dell'inferenza di Azure Machine Learning.
minimal/single-model	deploy-custom-container-minimal-single-model	Distribuire un singolo modello estendendo l'immagine minima dell'inferenza di Azure Machine Learning.
mlflow/multideployment-scikit	deploy-custom-container-mlflow-multideployment-scikit	Distribuire due modelli MLFlow con requisiti Python diversi in due distribuzioni separate dietro un singolo endpoint utilizzando l'immagine minima di inferenza di Azure Machine Learning.
r/multimodel-plumber	deploy-custom-container-r-multimodel-plumber	Distribuire tre modelli di regressione in un endpoint usando il pacchetto Plumber R
tfserving/half-plus-two	deploy-custom-container-tfserving-half-plus-two	Distribuire un modello Half Plus Two utilizzando un contenitore personalizzato TensorFlow Serving per mezzo del processo di registrazione del modello standard.
tfserving/half-plus-two-integrated	deploy-custom-container-tfserving-half-plus-two-integrated	Distribuire un modello Half Plus Two utilizzando un contenitore personalizzato TensorFlow Serving con un modello integrato nell'immagine.
torchserve/densenet	deploy-custom-container-torchserve-densenet	Distribuire un singolo modello usando un contenitore personalizzato TorchServe.
triton/single-model	deploy-custom-container-triton-single-model	Distribuire un modello Triton utilizzando un contenitore personalizzato

Questo articolo è incentrato sulla gestione di un modello TensorFlow con TensorFlow (TF) Serving.

Avviso

Microsoft potrebbe non essere in grado di risolvere i problemi causati da un'immagine personalizzata. Se si verificano problemi, potrebbe essere richiesto di usare l'immagine predefinita o una delle immagini fornite da Microsoft per verificare se il problema è specifico dell'immagine.

Prerequisiti

Prima di seguire la procedura descritta in questo articolo, assicurarsi di disporre dei prerequisiti seguenti:

Un'area di lavoro di Azure Machine Learning. Se non è disponibile, seguire la procedura descritta nell'articolo Avvio rapido: Creare risorse dell'area di lavoro per crearne una.
L'interfaccia della riga di comando di Azure e l'estensione ml oppure Python SDK v2 per Azure Machine Learning:
- Per installare l'interfaccia della riga di comando di Azure e l'estensione, vedere Installare, configurare e usare l'interfaccia della riga di comando di Azure (v2).
  
  Importante
  
  Gli esempi dell'interfaccia della riga di comando in questo articolo presuppongono che si usi la shell Bash (o compatibile). Ad esempio, un sistema Linux o un sottosistema Windows per Linux.
- Per installare Python SDK v2, usare il comando seguente:
```
pip install azure-ai-ml azure-identity
```
  Per aggiornare un'installazione esistente di SDK alla versione più recente, usare il comando seguente:
```
pip install --upgrade azure-ai-ml azure-identity
```
  Per altre informazioni, vedere Installare Python SDK v2 per Azure Machine Learning.

L'utente o l'entità servizio usata deve avere l'accesso Contributore al gruppo di risorse di Azure che contiene l'area di lavoro. Se l'area di lavoro è stata configurata usando l'articolo di avvio rapido, si ha un gruppo di risorse di questo tipo.
Per eseguire la distribuzione in locale, è necessario che il motore Docker sia in esecuzione in locale. Questo passaggio è altamente consigliato. Consente di eseguire il debug dei problemi.

Scaricare il codice sorgente

Per seguire questa esercitazione, clonare il codice sorgente da GitHub.

Interfaccia della riga di comando di Azure
Python SDK

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

Vedere anche il notebook di esempio, ma si noti che la sezione 3. Test locally del notebook presuppone l'esecuzione nella directory azureml-examples/sdk.

Inizializzare le variabili di ambiente

Definire le variabili di ambiente:

BASE_PATH=endpoints/online/custom-container/tfserving/half-plus-two
AML_MODEL_NAME=tfserving-mounted
MODEL_NAME=half_plus_two
MODEL_BASE_PATH=/var/azureml-app/azureml-models/$AML_MODEL_NAME/1

Scaricare un modello TensorFlow

Scaricare e decomprimere un modello che divide un input per due e aggiunge 2 al risultato:

wget https://aka.ms/half_plus_two-model -O $BASE_PATH/half_plus_two.tar.gz
tar -xvf $BASE_PATH/half_plus_two.tar.gz -C $BASE_PATH

Eseguire un'immagine TF Serving localmente per verificare che funzioni

Usare Docker per eseguire l'immagine in locale la verifica:

docker run --rm -d -v $PWD/$BASE_PATH:$MODEL_BASE_PATH -p 8501:8501 \
 -e MODEL_BASE_PATH=$MODEL_BASE_PATH -e MODEL_NAME=$MODEL_NAME \
 --name="tfserving-test" docker.io/tensorflow/serving:latest
sleep 10

Verificare che sia possibile inviare richieste di liveness e assegnazione dei punteggi all'immagine

Prima di tutto, verificare che il contenitore sia attivo, ovvero che il processo all'interno del contenitore sia ancora in esecuzione. Dovrebbe essere visualizzata una risposta 200 (OK).

curl -v http://localhost:8501/v1/models/$MODEL_NAME

Verificare quindi di poter ottenere previsioni sui dati senza etichetta:

curl --header "Content-Type: application/json" \
  --request POST \
  --data @$BASE_PATH/sample_request.json \
  http://localhost:8501/v1/models/$MODEL_NAME:predict

Arrestare l'immagine

Una volta eseguita la verifica in locale, arrestare l'immagine:

docker stop tfserving-test

Distribuire l'endpoint online in Azure

A questo punto, distribuire l'endpoint online in Azure.

Interfaccia della riga di comando di Azure
Python SDK

Creare un file YAML per l'endpoint e la distribuzione

È possibile configurare la distribuzione cloud usando YAML. Dare un'occhiata al campione YAML per questo esempio:

tfserving-endpoint.yml

$schema: https://azuremlsdk2.blob.core.windows.net/latest/managedOnlineEndpoint.schema.json
name: tfserving-endpoint
auth_mode: aml_token

tfserving-deployment.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: tfserving-deployment
endpoint_name: tfserving-endpoint
model:
  name: tfserving-mounted
  version: {{MODEL_VERSION}}
  path: ./half_plus_two
environment_variables:
  MODEL_BASE_PATH: /var/azureml-app/azureml-models/tfserving-mounted/{{MODEL_VERSION}}
  MODEL_NAME: half_plus_two
environment:
  #name: tfserving
  #version: 1
  image: docker.io/tensorflow/serving:latest
  inference_config:
    liveness_route:
      port: 8501
      path: /v1/models/half_plus_two
    readiness_route:
      port: 8501
      path: /v1/models/half_plus_two
    scoring_route:
      port: 8501
      path: /v1/models/half_plus_two:predict
instance_type: Standard_DS3_v2
instance_count: 1

Connettersi all'area di lavoro di Azure Machine Learning

Connettersi all'area di lavoro di Azure Machine Learning, configurare i dettagli dell'area di lavoro e ottenere un handle per l'area di lavoro come indicato di seguito:

Importare le librerie necessarie:

# import required libraries
from azure.ai.ml import MLClient
from azure.ai.ml.entities import (
   ManagedOnlineEndpoint,
   ManagedOnlineDeployment,
   Model,
   Environment,
   CodeConfiguration,
)
from azure.identity import DefaultAzureCredential

Configurare i dettagli e ottenere un handle per l'area di lavoro:

# enter details of your Azure Machine Learning workspace
subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace = "<AZUREML_WORKSPACE_NAME>"

# get a handle to the workspace
ml_client = MLClient(
   DefaultAzureCredential(), subscription_id, resource_group, workspace
)

Per altre informazioni, vedere Distribuire modelli di machine learning nell'endpoint online gestito con Python SDK v2.

Configurare l'endpoint online

Suggerimento

name: nome dell'endpoint. Deve essere univoco nell'area di Azure. Il nome di un endpoint deve iniziare con una lettera maiuscola o minuscola ed è costituito solo da caratteri '-' e alfanumerici. Per altre informazioni sulle regole di denominazione, vedere i limiti degli endpoint.
auth_mode: usare key per l'autenticazione basata su chiave. Usare aml_token per l'autenticazione basata su token di Azure Machine Learning. Un elemento key non scade, mentre un elemento aml_token scade. Per altre informazioni sull'autenticazione, vedere Eseguire l'autenticazione a un endpoint online.

Facoltativamente, è possibile aggiungere la descrizione e tag per l'endpoint.

# Creating a unique endpoint name with current datetime to avoid conflicts
import datetime

online_endpoint_name = "endpoint-" + datetime.datetime.now().strftime("%m%d%H%M%f")

# create an online endpoint
endpoint = ManagedOnlineEndpoint(
    name=online_endpoint_name,
    description="this is a sample online endpoint",
    auth_mode="key",
    tags={"foo": "bar"},
)

Configurare la distribuzione online

Per distribuzione si intende un set di risorse necessarie per ospitare il modello che esegue l'inferenza effettiva. Creare una distribuzione per l'endpoint, si usa la classe ManagedOnlineDeployment.

Suggerimento

name: nome della distribuzione.
endpoint_name: nome dell'endpoint in cui creare la distribuzione.
model: modello da usare per la distribuzione. Questo valore può essere un riferimento a un modello con controllo delle versioni > esistente nell'area di lavoro o a una specifica del modello inline.
environment: ambiente da usare per la distribuzione. Questo valore può essere un riferimento a un ambiente con controllo delle versioni > esistente nell'area di lavoro o a una specifica dell'ambiente inline.
code_configuration: configurazione per il codice sorgente e lo script di assegnazione dei punteggi
- path: percorso della directory del codice sorgente per l'assegnazione dei punteggi al modello
- scoring_script: percorso relativo del file di assegnazione dei punteggi nella directory del codice sorgente
instance_type: dimensioni della macchina virtuale da usare per la distribuzione. Per l'elenco delle dimensioni supportate, vedere l'elenco degli SKU degli endpoint.
instance_count: numero di istanze da usare per la distribuzione

# create a blue deployment
model = Model(name="tfserving-mounted", version="1", path="half_plus_two")

env = Environment(
    image="docker.io/tensorflow/serving:latest",
    inference_config={
        "liveness_route": {"port": 8501, "path": "/v1/models/half_plus_two"},
        "readiness_route": {"port": 8501, "path": "/v1/models/half_plus_two"},
        "scoring_route": {"port": 8501, "path": "/v1/models/half_plus_two:predict"},
    },
)

blue_deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=online_endpoint_name,
    model=model,
    environment=env,
    environment_variables={
        "MODEL_BASE_PATH": "/var/azureml-app/azureml-models/tfserving-mounted/1",
        "MODEL_NAME": "half_plus_two",
    },
    instance_type="Standard_DS2_v2",
    instance_count=1,
)

Esistono alcuni concetti importanti da notare in questo parametro YAML/Python:

Immagine di base

L'immagine di base viene specificata come parametro nell'ambiente e docker.io/tensorflow/serving:latest viene usata in questo esempio. Quando si esamina il contenitore, è possibile notare che questo server usa ENTRYPOINT per avviare uno script del punto di ingresso, che accetta le variabili di ambiente come MODEL_BASE_PATH e MODEL_NAMEe espone porte come 8501. Questi dettagli sono tutte informazioni specifiche per questo server scelto. È possibile usare questa conoscenza del server per determinare come definire la distribuzione. Ad esempio, se si impostano le variabili di ambiente per MODEL_BASE_PATH e MODEL_NAME nella definizione di distribuzione, il server (in questo caso TF Serving) accetta i valori per avviare il server. Analogamente, se si imposta la porta per le route che si trovano 8501 nella definizione di distribuzione, la richiesta dell'utente a tali route verrà indirizzata correttamente al server tf serving.

Si noti che questo esempio specifico si basa sul caso TF Serving, ma è possibile usare tutti i contenitori che rimarranno attivi e risponderanno alle richieste in arrivo a route attive, idoneità e assegnazione dei punteggi. È possibile fare riferimento ad altri esempi e vedere come viene formato il dockerfile (ad esempio, usando CMD invece di ENTRYPOINT) per creare i contenitori.

Configurazione dell'inferenza

La configurazione dell'inferenza è un parametro nell'ambiente e specifica la porta e il percorso per 3 tipi di route: liveness, readiness e scoring route. La configurazione dell'inferenza è necessaria se si vuole eseguire il proprio contenitore con l'endpoint online gestito.

Route di preparazione e route liveness

Il server API scelto può fornire un modo per controllare lo stato del server. Esistono due tipi di route che è possibile specificare: liveness e idoneità. Viene utilizzata una route dell'attività per verificare se il server è in esecuzione. Viene usata una route dell'idoneità per verificare se il server è pronto per eseguire il processo. Nel contesto dell'inferenza di Machine Learning, un server potrebbe rispondere 200 OK a una richiesta di attività prima di caricare un modello e il server potrebbe rispondere 200 OK a una richiesta di idoneità solo dopo il caricamento del modello nella memoria.

Per altre informazioni su liveness and readiness probes in generale, vedere la documentazione di Kubernetes.

Le route di liveness e readiness saranno determinate dal server API preferito, come si sarebbe potuto identificare durante il test del contenitore in locale nel passaggio precedente. Si noti che la distribuzione di esempio in questo articolo usa lo stesso percorso per liveness e idoneità, poiché TF Serving definisce solo una route di attività. Fare riferimento ad altri esempi per modelli diversi per definire le route.

Route di assegnazione dei punteggi

Il server API scelto offre un modo per ricevere il payload su cui lavorare. Nel contesto dell'inferenza di Machine Learning, un server riceverà i dati di input tramite una route specifica. Identificare questa route per il server API durante il test del contenitore in locale nel passaggio precedente e specificarla quando si definisce la distribuzione da creare. Si noti che la creazione corretta della distribuzione aggiornerà anche il parametro scoring_uri dell'endpoint, che è possibile verificare con az ml online-endpoint show -n <name> --query scoring_uri.

Individuazione del modello montato

Quando si distribuisce un modello come endpoint online, Azure Machine Learning monta il modello nell'endpoint. Il montaggio del modello consente di distribuire nuove versioni del suddetto senza dover creare una nuova immagine Docker. Per impostazione predefinita, un modello registrato con il nome foo e la versione 1 si trova nel percorso seguente all'interno del contenitore distribuito: /var/azureml-app/azureml-models/foo/1

Ad esempio, se si dispone di una struttura di directory di /azureml-examples/cli/endpoints/online/custom-container nel computer locale, dove il modello è denominato half_plus_two:

Diagramma che mostra una visualizzazione struttura ad albero della struttura di directory locale.

Interfaccia della riga di comando di Azure
Python SDK

E tfserving-deployment.yml contiene:

model:
    name: tfserving-mounted
    version: 1
    path: ./half_plus_two

E Model la classe contiene:

model = Model(name="tfserving-mounted", version="1", path="half_plus_two")

Il modello si troverà quindi in /var/azureml-app/azureml-models/tfserving-deployment/1 nella distribuzione:

Diagramma che mostra una visualizzazione struttura ad albero della struttura della directory di distribuzione.

Facoltativamente, è possibile configurare model_mount_path. Consente di modificare il percorso in cui è montato il modello.

Importante

model_mount_path deve essere un percorso assoluto valido in Linux (sistema operativo dell'immagine del contenitore).

Interfaccia della riga di comando di Azure
Python SDK

Ad esempio, è possibile avere il parametro model_mount_path in tfserving-deployment.yml:

name: tfserving-deployment
endpoint_name: tfserving-endpoint
model:
  name: tfserving-mounted
  version: 1
  path: ./half_plus_two
model_mount_path: /var/tfserving-model-mount
.....

Ad esempio, è possibile avere il parametro model_mount_path nella classe ManagedOnlineDeployment:

blue_deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=online_endpoint_name,
    model=model,
    environment=env,
    model_mount_path="/var/tfserving-model-mount",
    ...
)

Il modello si trova quindi in /var/tfserving-model-mount/tfserving-deployment/1 nella distribuzione. Si noti che non è più in azureml-app/azureml-models, ma nel percorso di montaggio specificato:

Diagramma che mostra una visualizzazione struttura ad albero della struttura di directory di distribuzione quando si usa mount_model_path.

Creare l'endpoint e la distribuzione

Interfaccia della riga di comando di Azure
Python SDK

Ora che si sa come è stato costruito il file YAML, creare l'endpoint.

az ml online-endpoint create --name tfserving-endpoint -f endpoints/online/custom-container/tfserving-endpoint.yml

La creazione di una distribuzione potrebbe richiedere alcuni minuti.

az ml online-deployment create --name tfserving-deployment -f endpoints/online/custom-container/tfserving-deployment.yml --all-traffic

Usando l'oggetto MLClient creato in precedenza, verrà ora creato l'endpoint nell'area di lavoro. Questo comando avvia la creazione dell'endpoint e restituisce una risposta di conferma mentre la procedura è ancora in corso.

ml_client.begin_create_or_update(endpoint)

Creare anche la distribuzione eseguendo:

ml_client.begin_create_or_update(blue_deployment)

Richiamare l'endpoint

Al termine della distribuzione, verificare se è possibile effettuare una richiesta di assegnazione dei punteggi all'endpoint distribuito.

Interfaccia della riga di comando di Azure
Python SDK

RESPONSE=$(az ml online-endpoint invoke -n $ENDPOINT_NAME --request-file $BASE_PATH/sample_request.json)

Usando il MLClient creato in precedenza, si ottiene un handle per l'endpoint. È possibile richiamare l'endpoint usando il comando invoke con i parametri seguenti:

endpoint_name: nome dell'endpoint
request_file: file con i dati della richiesta
deployment_name: nome della distribuzione specifica da testare in un endpoint

Verrà inviata una richiesta di esempio usando un file JSON. L'estensione JSON di esempio si trova nel repository di esempio.

# test the blue deployment with some sample data
ml_client.online_endpoints.invoke(
    endpoint_name=online_endpoint_name,
    deployment_name="blue",
    request_file="sample-request.json",
)

Eliminare l'endpoint

Dopo aver ottenuto un punteggio con l'endpoint, è possibile eliminarlo:

Interfaccia della riga di comando di Azure
Python SDK

az ml online-endpoint delete --name tfserving-endpoint

ml_client.online_endpoints.begin_delete(name=online_endpoint_name)

Condividi tramite

Usare un contenitore personalizzato per distribuire un modello in un endpoint online

Prerequisiti

Scaricare il codice sorgente

Inizializzare le variabili di ambiente

Scaricare un modello TensorFlow

Eseguire un'immagine TF Serving localmente per verificare che funzioni

Verificare che sia possibile inviare richieste di liveness e assegnazione dei punteggi all'immagine

Arrestare l'immagine

Distribuire l'endpoint online in Azure

Creare un file YAML per l'endpoint e la distribuzione

Connettersi all'area di lavoro di Azure Machine Learning

Configurare l'endpoint online

Configurare la distribuzione online

Immagine di base

Configurazione dell'inferenza

Route di preparazione e route liveness

Route di assegnazione dei punteggi

Individuazione del modello montato

Creare l'endpoint e la distribuzione

Richiamare l'endpoint

Eliminare l'endpoint

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Usare un contenitore personalizzato per distribuire un modello in un endpoint online

Prerequisiti

Scaricare il codice sorgente

Inizializzare le variabili di ambiente

Scaricare un modello TensorFlow

Eseguire un'immagine TF Serving localmente per verificare che funzioni

Verificare che sia possibile inviare richieste di liveness e assegnazione dei punteggi all'immagine

Arrestare l'immagine

Distribuire l'endpoint online in Azure

Creare un file YAML per l'endpoint e la distribuzione

Immagine di base

Configurazione dell'inferenza

Route di preparazione e route liveness

Route di assegnazione dei punteggi

Individuazione del modello montato

Creare l'endpoint e la distribuzione

Richiamare l'endpoint

Eliminare l'endpoint

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive