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

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 usando un contenitore personalizzato TensorFlow Serving usando il 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 usando un contenitore personalizzato TensorFlow Serving con il modello integrato nell'immagine.
torchserve/densenet	deploy-custom-container-torchserve-densenet	Distribuire un singolo modello usando un contenitore personalizzato TorchServe.
torchserve/huggingface-textgen	deploy-custom-container-torchserve-huggingface-textgen	Distribuire i modelli Hugging Face in un endpoint online e seguire l'esempio di Hugging Face Transformers 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 Collaboratore 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 dispone di 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

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

Python SDK

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

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

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

Ora che è stato testato 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

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

Python SDK

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:

1. 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

2. 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 usando la ManagedOnlineDeployment classe .

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:

Route di idoneità rispetto a route di attività

Un server HTTP definisce i percorsi sia per l'attività che per l'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. Nell'inferenza di Machine Learning un server potrebbe rispondere 200 OK a una richiesta di liveness prima di caricare un modello. Il server potrebbe rispondere 200 OK a una richiesta di idoneità solo dopo il caricamento del modello in memoria.

Per altre informazioni sulle attività e sui probe di idoneità, vedere la documentazione di Kubernetes.

Si noti che questa distribuzione usa lo stesso percorso sia per l'attività che per l'idoneità, poiché TF Serving definisce solo una route di attività.

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 modello 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 nel computer locale è presente una struttura di directory /azureml-examples/cli/endpoints/online/custom-container , in cui il modello è denominato half_plus_two:

Interfaccia della riga di comando di Azure

E tfserving-deployment.yml contiene:

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

Python SDK

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:

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

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
.....

Python SDK

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:

Creare l'endpoint e la distribuzione

Interfaccia della riga di comando di Azure

Dopo aver compreso 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

Python SDK

Usando il MLClient creato in precedenza, creare 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 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

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

Python SDK

Usando l'oggetto 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

Inviare una richiesta di esempio usando un file JSON. Il codice 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

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

Python SDK

ml_client.online_endpoints.begin_delete(name=online_endpoint_name)

Contenuto correlato

• Implementazione sicura per gli endpoint online
• Risolvere i problemi di distribuzione degli endpoint online gestiti
• Esempio di Torch Serve