Eseguire l'implementazione sicura delle nuove distribuzioni per l'inferenza in tempo reale

  • Articolo

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

In questo articolo si apprenderà come distribuire una nuova versione di un modello di Machine Learning nell'ambiente di produzione senza causare interruzioni. Si userà una strategia di distribuzione blu-verde (nota anche come strategia di implementazione sicura) per introdurre una nuova versione di un servizio Web nell'ambiente di produzione. Questa strategia consentirà di implementare la nuova versione del servizio Web in un piccolo subset di utenti o richieste prima di implementarla completamente.

Questo articolo presuppone che si usino endpoint online, ovvero endpoint usati per l'inferenza online (in tempo reale). Esistono due tipi di endpoint online: endpoint online gestiti ed endpoint online Kubernetes. Per altre informazioni sugli endpoint e sulle differenze tra endpoint online gestiti e endpoint online Kubernetes, vedere Che cosa sono gli endpoint di Azure Machine Learning?.

L'esempio principale in questo articolo usa endpoint online gestiti per la distribuzione. Per usare invece gli endpoint Kubernetes, vedere le note contenute in questo documento inline con la discussione sull'endpoint online gestito.

In questo articolo si apprenderà come:

  • Definire un endpoint online con una distribuzione denominata "blu" per servire la versione 1 di un modello
  • Ridimensionare la distribuzione blu in modo che possa gestire più richieste
  • Distribuire la versione 2 del modello (denominata distribuzione "verde") all'endpoint, ma inviare la distribuzione senza traffico in tempo reale
  • Testare la distribuzione verde in isolamento
  • Eseguire il mirroring di una percentuale di traffico attivo verso la distribuzione verde per convalidarla
  • Inviare una piccola percentuale di traffico in tempo reale alla distribuzione verde
  • Inviare tutto il traffico live alla distribuzione verde
  • Eliminare la distribuzione blu v1 non usata

Prerequisiti

Prima di seguire i passaggi descritti in questo articolo, assicurarsi di disporre dei prerequisiti seguenti:

  • I controlli degli accessi in base al ruolo di Azure vengono usati per concedere l'accesso alle operazioni in Azure Machine Learning. Per eseguire la procedura descritta in questo articolo, all'account utente deve essere assegnato il ruolo di proprietario o collaboratore per l'area di lavoro di Azure Machine Learning o a un ruolo personalizzato che consente Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*. Per altre informazioni, vedere Gestire l'accesso a un'area di lavoro di Azure Machine Learning.

  • (Facoltativo) Per eseguire la distribuzione in locale, è necessario installare il motore Docker nel computer locale. Si consiglia vivamente questa opzione, quindi è più semplice eseguire il debug dei problemi.

Preparare il sistema

Impostare le variabili di ambiente

Se non sono già state impostate le impostazioni predefinite per l'interfaccia della riga di comando di Azure, salvare le impostazioni predefinite. Per evitare di passare più volte i valori per la sottoscrizione, l'area di lavoro e il gruppo di risorse, eseguire questo codice:

az account set --subscription <subscription id>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

Clonare il repository di esempi

Per seguire questo articolo, clonare prima di tutto il repository di esempi (azureml-examples). Passare quindi alla directory del cli/ repository:

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

Suggerimento

Usare --depth 1 per clonare solo il commit più recente nel repository. In questo modo si riduce il tempo necessario per completare l'operazione.

I comandi di questa esercitazione si trovano nel file deploy-safe-rollout-online-endpoints.sh nella cli directory e i file di configurazione YAML si trovano nella endpoints/online/managed/sample/ sottodirectory .

Nota

I file di configurazione YAML per gli endpoint online kubernetes si trovano nella endpoints/online/kubernetes/ sottodirectory.

Definire l'endpoint e la distribuzione

Gli endpoint online sono usati per l'inferenza online (in tempo reale). Gli endpoint online contengono distribuzioni pronte per ricevere dati dai client e inviare risposte in tempo reale.

Definire un endpoint

Nella tabella seguente sono elencati gli attributi chiave da specificare quando si definisce un endpoint.

Attributo Descrizione
Name Obbligatorio. Nome dell'endpoint. Deve essere univoco nell'area di Azure. Per altre informazioni sulle regole di denominazione, vedere Limiti degli endpoint.
Modalità di autenticazione Metodo di autenticazione per l'endpoint. Scegliere tra l'autenticazione basata su chiave e l'autenticazione keyaml_tokenbasata su token di Azure Machine Learning. Una chiave non scade, ma un token scade. Per altre informazioni sull'autenticazione, vedere Eseguire l'autenticazione a un endpoint online.
Descrizione Descrizione dell'endpoint.
Tag Dizionario dei tag per l'endpoint.
Traffico Regole su come instradare il traffico tra le distribuzioni. Rappresentare il traffico come dizionario di coppie chiave-valore, dove la chiave rappresenta il nome e il valore della distribuzione rappresenta la percentuale di traffico verso tale distribuzione. È possibile impostare il traffico solo quando sono state create le distribuzioni in un endpoint. È anche possibile aggiornare il traffico per un endpoint online dopo la creazione delle distribuzioni. Per altre informazioni su come usare il traffico con mirroring, vedere Allocare una piccola percentuale di traffico in tempo reale alla nuova distribuzione.
Eseguire il mirroring del traffico Percentuale di traffico attivo da eseguire con mirroring a una distribuzione. Per altre informazioni su come usare il traffico con mirroring, vedere Testare la distribuzione con il traffico con mirroring.

Per visualizzare un elenco completo degli attributi che è possibile specificare quando si crea un endpoint, vedere Schema YAML dell'endpoint online dell'interfaccia della riga di comando (v2) o classe ManagedOnlineEndpoint (v2).

Definire una distribuzione

Una distribuzione è un set di risorse necessarie per ospitare il modello che esegue l'inferenza effettiva. Nella tabella seguente vengono descritti gli attributi chiave da specificare quando si definisce una distribuzione.

Attributo Descrizione
Name Obbligatorio. Nome della distribuzione.
Nome endpoint Obbligatorio. Nome dell'endpoint in cui creare la distribuzione.
Modello 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. Nell'esempio è disponibile un modello scikit-learn che esegue la regressione.
Percorso del codice Percorso della directory nell'ambiente di sviluppo locale che contiene tutto il codice sorgente Python per l'assegnazione del punteggio al modello. È possibile usare directory e pacchetti annidati.
Scoring script (Script di assegnazione punteggi) Codice Python che esegue il modello in una determinata richiesta di input. Questo valore può essere il percorso relativo del file di assegnazione dei punteggi nella directory del codice sorgente.
Lo script di assegnazione dei punteggi riceve i dati inviati a un servizio Web distribuito e lo passa al modello. Lo script esegue quindi il modello e restituisce la risposta al client. Lo script di assegnazione dei punteggi è specifico del modello e deve comprendere i dati previsti dal modello come input e restituiti come output.
In questo esempio è disponibile un file score.py . Questo codice Python deve avere una init() funzione e una run() funzione. La init() funzione verrà chiamata dopo la creazione o l'aggiornamento del modello ( ad esempio, è possibile usarla per memorizzare nella cache il modello in memoria). La run() funzione viene chiamata a ogni chiamata dell'endpoint per eseguire l'effettivo punteggio e la stima.
Ambiente Obbligatorio. Ambiente in cui ospitare il modello e il codice. 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. L'ambiente può essere un'immagine Docker con dipendenze Conda, un Dockerfile o un ambiente registrato.
Tipo di istanza Obbligatorio. Dimensioni della macchina virtuale da usare per la distribuzione. Per l'elenco delle dimensioni supportate, vedere Elenco degli SKU degli endpoint online gestiti.
Numero di istanze Obbligatorio. Numero di istanze da usare per la distribuzione. Basare il valore sul carico di lavoro previsto. Per la disponibilità elevata, è consigliabile impostare il valore su almeno 3. Si riserva un ulteriore 20% per l'esecuzione degli aggiornamenti. Per altre informazioni, vedere Limiti per gli endpoint online.

Per visualizzare un elenco completo degli attributi che è possibile specificare quando si crea una distribuzione, vedere Schema YAML della distribuzione online gestita dall'interfaccia della riga di comando (v2) ManagedOnlineDeployment Class (classe YAML) gestita dall'interfaccia della riga di comando (v2).

Creare un endpoint online

Impostare prima il nome dell'endpoint e quindi configurarlo. In questo articolo si userà il file endpoints/online/managed/sample/endpoint.yml per configurare l'endpoint. Il frammento di codice seguente mostra il contenuto del file:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

Il riferimento per il formato YAML dell'endpoint è descritto nella tabella seguente. Per informazioni su come specificare questi attributi, vedere le informazioni di riferimento sull'endpoint YAML online. Per informazioni sui limiti correlati agli endpoint online gestiti, vedere Limiti per gli endpoint online.

Chiave Descrizione
$schema (Facoltativo) Schema YAML. Per visualizzare tutte le opzioni disponibili nel file YAML, è possibile visualizzare lo schema nel frammento di codice precedente in un browser.
name Nome dell'endpoint.
auth_mode Usare key per l'autenticazione basata su chiave. Usare aml_token per l'autenticazione basata su token di Azure Machine Learning. Per ottenere il token più recente, usare il az ml online-endpoint get-credentials comando .

Per creare un endpoint online:

  1. Impostare il nome dell'endpoint:

    Per Unix, eseguire questo comando (sostituire YOUR_ENDPOINT_NAME con un nome univoco):

    export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

    Importante

    I nomi degli endpoint devono essere univoci all'interno di un'area di Azure. Nell'area di Azure westus2 , ad esempio, può essere presente un solo endpoint con il nome my-endpoint.

  2. Creare l'endpoint nel cloud:

    Eseguire il codice seguente per usare il endpoint.yml file per configurare l'endpoint:

    az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

Creare la distribuzione "blue"

In questo articolo si userà il file endpoints/online/managed/sample/blue-deployment.yml per configurare gli aspetti chiave della distribuzione. Il frammento di codice seguente mostra il contenuto del file:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

Per creare una distribuzione denominata blue per l'endpoint, eseguire il comando seguente per usare il blue-deployment.yml file da configurare

az ml online-deployment create --name blue --endpoint-name $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic

Importante

Il --all-traffic flag in az ml online-deployment create alloca il 100% del traffico dell'endpoint alla distribuzione blu appena creata.

blue-deployment.yaml Nel file si specifica path (da dove caricare i file) inline. L'interfaccia della riga di comando carica automaticamente i file e registra il modello e l'ambiente. Come procedura consigliata per la produzione, è necessario registrare il modello e l'ambiente e specificare il nome e la versione registrati separatamente in YAML. Usare il modulo model: azureml:my-model:1 o environment: azureml:my-env:1.

Per la registrazione, è possibile estrarre le definizioni YAML di model e environment in file YAML separati e usare i az ml model create comandi e az ml environment create. Per altre informazioni su questi comandi, eseguire az ml model create -h e az ml environment create -h.

Per altre informazioni sulla registrazione del modello come asset, vedere Registrare il modello come asset in Machine Learning usando l'interfaccia della riga di comando. Per altre informazioni sulla creazione di un ambiente, vedere Gestire gli ambienti di Azure Machine Learning con l'interfaccia della riga di comando e l'SDK (v2).

Confermare la distribuzione esistente

Un modo per confermare la distribuzione esistente consiste nel richiamare l'endpoint in modo che possa assegnare un punteggio al modello per una determinata richiesta di input. Quando si richiama l'endpoint tramite l'interfaccia della riga di comando o Python SDK, è possibile scegliere di specificare il nome della distribuzione che riceverà il traffico in ingresso.

Nota

A differenza dell'interfaccia della riga di comando o di Python SDK, studio di Azure Machine Learning richiede di specificare una distribuzione quando si richiama un endpoint.

Richiamare l'endpoint con il nome della distribuzione

Se si richiama l'endpoint con il nome della distribuzione che riceverà il traffico, Azure Machine Learning instrada il traffico dell'endpoint direttamente alla distribuzione specificata e ne restituisce l'output. È possibile usare l'opzione per l'interfaccia --deployment-name della riga di comando v2 o deployment_name l'opzione per SDK v2 per specificare la distribuzione.

Richiamare l'endpoint senza specificare la distribuzione

Se si richiama l'endpoint senza specificare la distribuzione che riceverà il traffico, Azure Machine Learning instrada il traffico in ingresso dell'endpoint alle distribuzioni nell'endpoint in base alle impostazioni di controllo del traffico.

Le impostazioni di controllo del traffico allocano le percentuali di traffico in ingresso a ogni distribuzione nell'endpoint. Ad esempio, se le regole di traffico specificano che una particolare distribuzione nell'endpoint riceverà il traffico in ingresso del 40% del tempo, Azure Machine Learning instrada il 40% del traffico dell'endpoint a tale distribuzione.

È possibile visualizzare lo stato dell'endpoint e della distribuzione esistenti eseguendo:

az ml online-endpoint show --name $ENDPOINT_NAME 

az ml online-deployment show --name blue --endpoint $ENDPOINT_NAME

Verrà visualizzato l'endpoint identificato da $ENDPOINT_NAME e, una distribuzione denominata blue.

Testare l'endpoint con dati di esempio

L'endpoint può essere richiamato usando il invoke comando . Verrà inviata una richiesta di esempio usando un file JSON .

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

Ridimensionare la distribuzione esistente per gestire più traffico

Nella distribuzione descritta in Distribuire e assegnare un punteggio a un modello di Machine Learning con un endpoint online, impostare il instance_count valore sul valore 1 nel file yaml di distribuzione. È possibile aumentare il numero di istanze usando il update comando :

az ml online-deployment update --name blue --endpoint-name $ENDPOINT_NAME --set instance_count=2

Nota

Si noti che nel comando precedente viene usato --set per eseguire l'override della configurazione della distribuzione. In alternativa, è possibile aggiornare il file yaml e passarlo come input al update comando usando l'input --file .

Distribuire un nuovo modello, ma non inviarlo ancora al traffico

Creare una nuova distribuzione denominata green:

az ml online-deployment create --name green --endpoint-name $ENDPOINT_NAME -f endpoints/online/managed/sample/green-deployment.yml

Poiché non è stato allocato in modo esplicito alcun traffico a green, non è stato allocato alcun traffico. È possibile verificare che usando il comando :

az ml online-endpoint show -n $ENDPOINT_NAME --query traffic

Testare la nuova distribuzione

Anche se green ha allocato il 0% del traffico, è possibile richiamarlo direttamente specificando il --deployment nome:

az ml online-endpoint invoke --name $ENDPOINT_NAME --deployment-name green --request-file endpoints/online/model-2/sample-request.json

Se si vuole usare un client REST per richiamare la distribuzione direttamente senza passare attraverso le regole del traffico, impostare l'intestazione HTTP seguente: azureml-model-deployment: <deployment-name>. Il frammento di codice seguente usa curl per richiamare direttamente la distribuzione. Il frammento di codice deve funzionare negli ambienti Unix/WSL:

# get the scoring uri
SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)
# use curl to invoke the endpoint
curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --header "azureml-model-deployment: green" --data @endpoints/online/model-2/sample-request.json

Testare la distribuzione con il traffico con mirroring

Dopo aver testato la green distribuzione, è possibile eseguire il mirroring (o copiare) una percentuale del traffico attivo verso di esso. Il mirroring del traffico (detto anche shadowing) non modifica i risultati restituiti ai client. Le richieste continuano a passare al 100% alla blue distribuzione. La percentuale di mirroring del traffico viene copiata e inviata alla green distribuzione in modo da poter raccogliere metriche e registrazione senza influire sui client. Il mirroring è utile quando si vuole convalidare una nuova distribuzione senza influire sul client. Ad esempio, è possibile usare il mirroring per verificare se la latenza si trova all'interno di limiti accettabili o per verificare che non siano presenti errori HTTP. Il test della nuova distribuzione con mirroring/shadowing del traffico è noto anche come shadow testing. La distribuzione che riceve il traffico con mirroring (in questo caso, la green distribuzione) può anche essere chiamata distribuzione shadow.

Il mirroring presenta le limitazioni seguenti:

  • Il mirroring è supportato per l'interfaccia della riga di comando (versione 2.4.0 o successiva) e Python SDK (v2) (versione 1.0.0 o successiva). Se si usa una versione precedente dell'interfaccia della riga di comando o dell'SDK per aggiornare un endpoint, si perderà l'impostazione del traffico mirror.
  • Il mirroring non è attualmente supportato per gli endpoint online kubernetes.
  • È possibile eseguire il mirroring del traffico a una sola distribuzione in un endpoint.
  • La percentuale massima di traffico che è possibile eseguire il mirroring è del 50%. Questo limite consiste nel ridurre l'effetto sulla quota di larghezza di banda dell'endpoint (predefinito 5 MBPS): la larghezza di banda dell'endpoint viene limitata se si supera la quota allocata. Per informazioni sul monitoraggio della limitazione della larghezza di banda, vedere Monitorare gli endpoint online gestiti.

Si notino anche i comportamenti seguenti:

  • Una distribuzione può essere configurata per ricevere solo il traffico live o il traffico con mirroring, non entrambi.
  • Quando si richiama un endpoint, è possibile specificare il nome di una delle relative distribuzioni, anche una distribuzione shadow, per restituire la stima.
  • Quando si richiama un endpoint con il nome della distribuzione che riceverà il traffico in ingresso, Azure Machine Learning non eseguirà il mirroring del traffico verso la distribuzione shadow. Azure Machine Learning riflette il traffico verso la distribuzione shadow dal traffico inviato all'endpoint quando non si specifica una distribuzione.

Impostare ora la distribuzione verde per ricevere il 10% del traffico con mirroring. I client riceveranno comunque stime solo dalla distribuzione blu.

Diagram showing 10% traffic mirrored to one deployment.

Il comando seguente rispecchia il 10% del traffico verso la green distribuzione:

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=10"

È possibile testare il traffico mirror richiamando l'endpoint più volte senza specificare una distribuzione per ricevere il traffico in ingresso:

for i in {1..20} ; do
    az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json
done

È possibile verificare che la percentuale specifica del traffico sia stata inviata alla green distribuzione visualizzando i log dalla distribuzione:

az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

Dopo il test, è possibile impostare il traffico mirror su zero per disabilitare il mirroring:

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=0"

Allocare una piccola percentuale di traffico attivo alla nuova distribuzione

Dopo aver testato la green distribuzione, allocare una piccola percentuale di traffico a tale distribuzione:

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=90 green=10"

Suggerimento

La percentuale di traffico totale deve sommare al 0% (per disabilitare il traffico) o al 100% (per abilitare il traffico).

green La distribuzione riceve ora il 10% di tutto il traffico live. I client riceveranno stime sia dalle distribuzioni che dalle bluegreen distribuzioni.

Diagram showing traffic split between deployments.

Inviare tutto il traffico alla nuova distribuzione

Dopo aver soddisfatto completamente la green distribuzione, passare tutto il traffico a esso.

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=0 green=100"

Rimuovere la distribuzione precedente

Usare la procedura seguente per eliminare una singola distribuzione da un endpoint online gestito. L'eliminazione di una singola distribuzione influisce sulle altre distribuzioni nell'endpoint online gestito:

az ml online-deployment delete --name blue --endpoint $ENDPOINT_NAME --yes --no-wait

Eliminare l'endpoint e la distribuzione

Se non si intende usare l'endpoint e la distribuzione, è necessario eliminarli. Eliminando l'endpoint, verranno eliminate anche tutte le distribuzioni sottostanti.

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait

Contenuto correlato