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)

In Azure Machine Learning è possibile usare un contenitore personalizzato per distribuire un modello in un endpoint online. Le distribuzioni di contenitori personalizzati possono usare server Web diversi dal server Python Flask predefinito usato da Azure Machine Learning.

Quando si usa una distribuzione personalizzata, è possibile:

• Usare vari strumenti e tecnologie, ad esempio TensorFlow Serving (TF Serving), TorchServe, Triton Inference Server, il pacchetto Plumber R e l'immagine minima di inferenza di Azure Machine Learning.
• Sfruttare comunque i vantaggi del monitoraggio, del ridimensionamento, degli avvisi e dell'autenticazione predefiniti offerti da Azure Machine Learning.

Questo articolo illustra come usare un'immagine TF Serving per gestire un modello TensorFlow.

Prerequisiti

• Un'area di lavoro di Azure Machine Learning. Per istruzioni sulla creazione di un'area di lavoro, vedere Creare l'area di lavoro.

• Interfaccia della riga di comando di Azure e l'estensione ml o Azure Machine Learning Python SDK v2:

  Interfaccia della riga di comando di Azure

  Per installare l'interfaccia della riga di comando di Azure e l'estensioneml, vedere Installare e configurare l'interfaccia della riga di comando (v2).

  Gli esempi in questo articolo presuppongono che si usi una shell Bash o una shell compatibile. Ad esempio, è possibile usare una shell in un sistema Linux o in un sottosistema Windows per Linux.

  Python SDK

  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 Libreria client del pacchetto di Azure Machine Learning per Python.

• Un gruppo di risorse di Azure che contiene l'area di lavoro e a cui l'utente o l'entità servizio hanno accesso come Collaboratore. Se si usano i passaggi descritti in Creare l'area di lavoro per configurare l'area di lavoro , è necessario soddisfare questo requisito.

• Motore Docker, installato ed in esecuzione in locale. Questo prerequisito è altamente consigliato. È necessario per distribuire un modello in locale ed è utile per il debug.

Esempi di distribuzione

Nella tabella seguente sono elencati gli esempi di distribuzione che usano contenitori personalizzati e sfruttano diversi strumenti e tecnologie.

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

Questo articolo illustra come usare l'esempio tfserving/half-plus-two.

Avviso

I team di supporto Microsoft potrebbero non essere in grado di risolvere i problemi causati da un'immagine personalizzata. In caso di problemi, potrebbe essere richiesto di usare l'immagine predefinita o una delle immagini fornite da Microsoft per verificare se il problema è specifico dell'immagine.

Scaricare il codice sorgente

I passaggi descritti in questo articolo usano esempi di codice del repository azureml-examples . Seguire i comandi seguenti per clonare il repository:

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

Nel repository di esempi la maggior parte degli esempi di Python si trova nella cartella sdk/python. Per questo articolo, passare invece alla cartella cli. La cartella cli ha una struttura leggermente diversa rispetto alla struttura sdk/python in questo caso. La maggior parte dei passaggi di questo articolo richiede la struttura CLI.

Per seguire i passaggi di esempio, consultare un notebook Jupyter nel repository degli esempi. Tuttavia, nelle sezioni seguenti del notebook, i passaggi vengono eseguiti dalla cartella azureml-examples/sdk/python anziché dalla cartella cli.

• 3. Esegui test localmente
• 5. Testare l'endpoint con dati di esempio

Inizializzare le variabili di ambiente

Per usare un modello TensorFlow, sono necessarie diverse variabili di ambiente. Eseguire i comandi seguenti per definire tali variabili:

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 valore di input per due e aggiunge due 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

Testare un'immagine di TF Serving nell'ambiente locale

Usare Docker per eseguire l'immagine in locale per i test:

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

Inviare richieste di liveness e assegnazione dei punteggi all'immagine

Invia una richiesta di controllo di attività per verificare che il processo all'interno del contenitore sia in esecuzione. Dovresti ricevere un codice di stato della risposta 200 OK.

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

Inviare una richiesta di assegnazione dei punteggi per verificare che sia possibile ottenere stime 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

Al termine del test in locale, fermare l'immagine.

docker stop tfserving-test

Distribuire l'endpoint online in Azure

Per distribuire l'endpoint online in Azure, seguire questa procedura nelle sezioni seguenti.

Interfaccia della riga di comando di Azure

Creare file YAML per l'endpoint e la distribuzione

È possibile configurare la distribuzione cloud usando YAML. Ad esempio, per configurare l'endpoint, è possibile creare un file YAML denominato tfserving-endpoint.yml contenente le righe seguenti:

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

Per configurare la distribuzione, è possibile creare un file YAML denominato tfserving-deployment.yml contenente le righe seguenti:

$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

Per configurare l'area di lavoro di Azure Machine Learning, seguire questa procedura:

1. Importare le librerie necessarie:

   # Import the 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 le impostazioni dell'area di lavoro e ottenere un handle per l'area di lavoro:

   # Enter information about your Azure Machine Learning workspace.
   subscription_id = "<subscription-ID>"
   resource_group = "<resource-group-name>"
   workspace = "<Azure-Machine-Learning-workspace-name>"
   
   # Get a handle to the workspace.
   ml_client = MLClient(
     DefaultAzureCredential(), subscription_id, resource_group, workspace
   )
   

Per altre informazioni, vedere Distribuire e assegnare punteggi a un modello di Machine Learning usando un endpoint online.

Configurare un endpoint online

Usare il codice seguente per configurare un endpoint online. Tenere presente quanto segue:

• Il nome dell'endpoint deve essere univoco nell'area di Azure. Inoltre, un nome endpoint deve iniziare con una lettera e deve essere costituito solo da caratteri alfanumerici e trattini. Per altre informazioni sulle regole di denominazione, vedere Endpoint online e endpoint batch di Azure Machine Learning.
• Per il auth_mode valore, usare key per l'autenticazione basata su chiave. Usare aml_token per l'autenticazione basata su token di Azure Machine Learning. Una chiave non scade, a differenza di un token. Per altre informazioni sull'autenticazione, vedere Autenticare i client per gli endpoint online.
• La descrizione e i tag sono facoltativi.

# To create a unique endpoint name, use a time stamp of the current date and time.
import datetime

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

# Configure an online endpoint.
endpoint = ManagedOnlineEndpoint(
    name=online_endpoint_name,
    description="A sample online endpoint",
    auth_mode="key",
    tags={"env": "dev"},
)

Configurare una distribuzione online

Una distribuzione è un set di risorse necessarie per ospitare il modello che esegue l'inferenza effettiva. È possibile usare la ManagedOnlineDeployment classe per configurare una distribuzione per l'endpoint. Il costruttore di tale classe usa i parametri seguenti:

• 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.
• environment_variables: variabili di ambiente impostate durante la distribuzione.
  • MODEL_BASE_PATH: Il percorso della cartella madre che contiene una cartella del tuo modello.
  • MODEL_NAME: nome del modello.
• instance_type: dimensioni della macchina virtuale da usare per la distribuzione. Per un elenco delle dimensioni supportate, vedere Elenco di SKU degli endpoint online gestiti.
• instance_count: numero di istanze da usare per la distribuzione.

Usare il codice seguente per configurare una distribuzione per l'endpoint:

# 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,
)

Le sezioni seguenti illustrano concetti importanti sui parametri YAML e Python.

Immagine di base

environment Nella sezione in YAML o nel Environment costruttore in Python si specifica l'immagine di base come parametro. In questo esempio, docker.io/tensorflow/serving:latest viene usato come valore image.

Se si esamina il contenitore, è possibile notare che questo server usa ENTRYPOINT i comandi per avviare uno script del punto di ingresso. Tale script accetta variabili di ambiente come MODEL_BASE_PATH e MODEL_NAMEe espone porte come 8501. Questi dettagli riguardano tutti questo server ed è possibile usare queste informazioni per determinare come definire la distribuzione. Ad esempio, se si impostano le MODEL_BASE_PATH variabili di ambiente e MODEL_NAME nella definizione di distribuzione, TF Serving usa tali valori per avviare il server. Analogamente, se si imposta la porta per ogni route su 8501 nella definizione di distribuzione, le richieste utente a tali route vengono indirizzate correttamente al server tf serving.

Questo esempio si basa sul caso TF Serving. Tuttavia, è possibile utilizzare qualsiasi contenitore che rimanga attivo e risponda alle richieste dirette alle route di verifica dello stato, disponibilità e punteggio. Per informazioni su come formare un Dockerfile per creare un contenitore, è possibile fare riferimento ad altri esempi. Alcuni server usano CMD istruzioni anziché ENTRYPOINT istruzioni.

Il parametro configurazione_inferenza

Nella environment sezione o nella Environment classe, inference_config è un parametro. Specifica la porta e il percorso per tre tipi di rottae: rotta di attivazione, rotta di prontezza e rotta di valutazione. Il inference_config parametro è obbligatorio se si vuole eseguire il proprio contenitore con un endpoint online gestito.

Route di disponibilità e route di attività

Alcuni server API consentono di controllare lo stato del server. Esistono due tipi di route che è possibile specificare per controllare lo stato:

• Route di attività : per verificare se un server è in esecuzione, si usa una route di attività.
• Route di idoneità : per verificare se un server è pronto per il lavoro, usare una route di idoneità.

Nel contesto dell'inferenza di Machine Learning, un server potrebbe rispondere con un codice di stato 200 OK a una richiesta di attività prima di caricare un modello. Il server potrebbe rispondere con un codice di stato 200 OK a una richiesta di idoneità solo dopo il caricamento del modello in memoria.

Per altre informazioni sull'attività e sui probe di idoneità, vedere Configurare Liveness, Readiness and Startup Probes .For more information about liveness and readiness probes, see Configure Liveness, Readiness and Startup Probes.For more information about liveness and readiness probes, see Configure Liveness, Readiness and Startup Probes.

Il server API scelto determina le route di attività e conformità. Il server viene identificato in un passaggio precedente quando si testa il contenitore in locale. In questo articolo, la distribuzione di esempio usa lo stesso percorso per le route di liveness e readiness, perché TF Serving definisce solo una route di liveness. Per altri modi per definire le route, vedere altri esempi.

Route di assegnazione dei punteggi

Il server API usato offre un modo per ricevere il payload su cui lavorare. Nel contesto dell'inferenza di Machine Learning, un server riceve i dati di input tramite una route specifica. Identificare la route per il server API quando si testa il contenitore in locale in un passaggio precedente. Specificare quel percorso come percorso di assegnazione dei punteggi quando si definisce la distribuzione da creare.

La creazione corretta della distribuzione aggiorna anche il scoring_uri parametro dell'endpoint. È possibile verificare questo fatto eseguendo il comando seguente: az ml online-endpoint show -n <endpoint-name> --query scoring_uri.

Individuare il modello montato

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

Si consideri ad esempio la configurazione seguente:

• Una struttura di directory sul tuo computer locale di /azureml-examples/cli/endpoints/online/custom-container
• Nome del modello di half_plus_two

Interfaccia della riga di comando di Azure

Si supponga che il file tfserving-deployment.yml contenga le righe seguenti nella relativa model sezione. In questa sezione il name valore fa riferimento al nome usato per registrare il modello in Azure Machine Learning.

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

Python SDK

Si supponga di usare il codice seguente per creare una Model classe . In questo codice il name valore fa riferimento al nome usato per registrare il modello in Azure Machine Learning.

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

In questo caso, quando si crea una distribuzione, il modello si trova nella cartella seguente: /var/azureml-app/azureml-models/tfserving-mounted/1.

È possibile configurare facoltativamente il valore model_mount_path. Modificando questa impostazione, è possibile modificare il percorso in cui è montato il modello.

Importante

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

Quando si modifica il valore di , è necessario aggiornare anche la MODEL_BASE_PATH variabile di model_mount_pathambiente. Impostare MODEL_BASE_PATH sullo stesso valore di model_mount_path per evitare una distribuzione non riuscita a causa di un errore relativo al percorso di base non trovato.

Interfaccia della riga di comando di Azure

Ad esempio, è possibile aggiungere il model_mount_path parametro al file tfserving-deployment.yml. È anche possibile aggiornare il MODEL_BASE_PATH valore in tale file:

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

Python SDK

Ad esempio, è possibile aggiungere il model_mount_path parametro alla ManagedOnlineDeployment classe . È anche possibile aggiornare il MODEL_BASE_PATH valore nel codice:

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

Nella distribuzione il modello si trova quindi in /var/tfserving-model-mount/tfserving-mounted/1. 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 costruito il file YAML, usare il comando seguente per creare l'endpoint:

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

Usare il comando seguente per creare la distribuzione. Questo passaggio potrebbe essere eseguito per alcuni minuti.

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

Python SDK

Usare il codice seguente per creare l'endpoint nell'area di lavoro. Questo codice usa l'istanza di MLClient creata in precedenza. Il begin_create_or_update metodo avvia la creazione dell'endpoint. Restituisce quindi una risposta di conferma mentre la creazione dell'endpoint continua.

ml_client.begin_create_or_update(endpoint)

Creare la distribuzione eseguendo il codice seguente:

ml_client.begin_create_or_update(blue_deployment)

Richiamare l'endpoint

Al termine della distribuzione, 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

Usare l'istanza di MLClient creata in precedenza per ottenere un handle per l'endpoint. Usare quindi il invoke metodo e i parametri seguenti per richiamare l'endpoint:

• endpoint_name: nome dell'endpoint
• request_file: file che contiene i dati della richiesta
• deployment_name: nome della distribuzione da testare nell'endpoint

Per i dati della richiesta, è possibile usare un file JSON di esempio dal repository di esempio.

# Test the blue deployment by using some sample data.
response = ml_client.online_endpoints.invoke(
    endpoint_name=online_endpoint_name,
    deployment_name="blue",
    request_file="sample_request.json",
)

Eliminare l'endpoint

Se l'endpoint non è più necessario, eseguire il comando seguente per 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

• Eseguire l'implementazione sicura delle nuove distribuzioni per l'inferenza in tempo reale
• Risolvere i problemi di distribuzione e assegnazione dei punteggi degli endpoint online
• Esempio di Torch Serve