Condividi tramite

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)

Questo articolo spiega 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 la 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 di richieste prima di implementarla completamente.

In questo articolo si presuppone che vengano usati endpoint online, vale a dire 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 ed 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 gli endpoint Kubernetes, invece, vedere le note contenute in questo documento che sono inline con la discussione sugli endpoint online gestiti.

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 blue in modo che possa gestire più richieste
  • Distribuire la versione 2 del modello (denominata distribuzione "green") nell'endpoint ma inviare la distribuzione senza traffico live
  • Testare la distribuzione green in isolamento
  • Eseguire il mirroring di una percentuale di traffico live nella distribuzione green per convalidarla
  • Inviare una piccola percentuale di traffico live alla distribuzione green
  • Inviare tutto il traffico live alla distribuzione green
  • Eliminare la distribuzione blue v1 non più usata

Prerequisiti

Prima di seguire la procedura descritta 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 Docker Engine nel computer locale. Si consiglia vivamente di usare questa opzione per facilitare il debug dei problemi.

Preparare il sistema

Impostare le variabili di ambiente

Se le impostazioni predefinite per l'interfaccia della riga di comando di Azure non sono già state impostate, salvare le proprie 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 il repository degli esempi (azureml-examples). Passare, quindi, alla directory cli/ del 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 directory cli, mentre i file di configurazione YAML si trovano nella sottodirectory endpoints/online/managed/sample/.

Nota

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

Definire l'endpoint e la distribuzione

Gli endpoint online sono usati per l'inferenza online (in tempo reale). Gli endpoint online contengono distribuzioni pronte a ricevere dati dai client e in grado di 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 key e l'autenticazione basata su token aml_token di Azure Machine Learning. Una chiave non scade, a differenza di un token. 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. Rappresenta il traffico come un dizionario di coppie chiave-valore, in cui le chiavi rappresentano il nome della distribuzione e i valori rappresentano la percentuale di traffico verso tale distribuzione. È possibile impostare il traffico solo dopo aver creato le distribuzioni in un endpoint. È anche possibile aggiornare il traffico per un endpoint online dopo aver creato le distribuzioni. Per altre informazioni su come usare il traffico con mirroring, vedere Allocare una piccola percentuale di traffico live alla nuova distribuzione.
Mirroring del traffico Percentuale di traffico live di cui eseguire il mirroring in 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) di SDK.

Definire una distribuzione

Una distribuzione è un set di risorse necessarie per ospitare il modello che esegue l'inferenza. 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 punteggio 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. Quindi, lo script esegue il modello e restituisce la risposta al client. Lo script di assegnazione dei punteggi è specifico del modello e deve comprendere i dati che il modello prevede come input e restituisce come output.
In questo esempio, è disponibile un file score.py. Questo codice Python deve avere una funzione init() e una funzione run(). La funzione init() verrà chiamata dopo la creazione o l'aggiornamento del modello (ad esempio, è possibile usarla per memorizzare nella cache il modello in memoria). La funzione run() viene chiamata a ogni chiamata dell'endpoint per eseguire l'assegnazione del punteggio e la stima effettive.
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 di 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 almeno su 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) o SDK (v2) ManagedOnlineDeployment Class.

Creare un endpoint online

Impostare prima il nome dell'endpoint, 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'endpointYAML online. Per informazioni sui limiti correlati agli endpoint online gestiti, vedere Limiti sugli endpoint online.

Chiave Descrizione
$schema (Facoltativo) Schema YAML. Per vedere tutte le opzioni disponibili nel file YAML, è possibile visualizzare in un browser lo schema incluso nel frammento di codice precedente.
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 comando az ml online-endpoint get-credentials.

Per creare un endpoint online:

  1. Definire 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 nell’area di Azure. Ad esempio, nell’area di Azure westus2 può esistere un solo endpoint denominato my-endpoint.

  2. Creare l'endpoint nel cloud:

    Eseguire il codice seguente per usare il file endpoint.yml 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 file blue-deployment.yml per la configurazione

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

Importante

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

Nel file blue-deployment.yaml, viene specificato path (da cui 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 nel 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 comandi az ml model create 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, Azure Machine Learning Studio 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 --deployment-name per l'interfaccia della riga di comando v2, o l'opzione deployment_name 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 per il 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

Verranno visualizzati 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 comando invoke. 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 una 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 instance_count sul valore 1 nel file yaml della distribuzione. Un aumento è possibile usando il comando update:

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 comando update usando l'input --file.

Distribuire un nuovo modello, ma non inviare ancora 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, il traffico allocato è pari a zero. Per una verifica, è possibile usare il comando:

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

Testare la nuova distribuzione

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

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

Per 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 in 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 distribuzione green, è possibile copiare o eseguire il mirroring di una percentuale del traffico live. Il mirroring del traffico (detto anche shadowing) non modifica i risultati restituiti ai client. Le richieste continuano a passare al 100% alla distribuzione blue. La percentuale del traffico con mirroring viene copiata e inviata alla distribuzione green in modo da poter raccogliere metriche e registrazioni senza impatto sui client. Il mirroring è utile per convalidare una nuova distribuzione senza impatto sui 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 distribuzione green) può anche essere chiamata distribuzione shadow.

Il mirroring presenta le limitazioni seguenti:

  • Il mirroring è supportato per l'interfaccia della riga di comando (v2) (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 con mirroring.
  • 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 per cui è possibile eseguire il mirroring è del 50%. Questo limite serve per ridurre l'effetto sulla quota di larghezza di banda dell'endpoint (predefinita a 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.

Tenere presente, inoltre, i seguenti comportamenti:

  • 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 esegue il mirroring del traffico verso la distribuzione shadow dal traffico inviato all'endpoint quando non si specifica una distribuzione.

Adesso, verrà impostata la distribuzione green in modo che riceva il 10% del traffico con mirroring. I client riceveranno comunque stime solo dalla distribuzione blue.

Diagramma che mostra il 10% del traffico con mirroring a una distribuzione.

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

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

È possibile testare il traffico con mirroring 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 specificata del traffico sia stata inviata alla distribuzione green visualizzando i log dalla distribuzione:

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

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

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

Allocare una piccola percentuale di traffico live alla nuova distribuzione

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

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

Suggerimento

La somma dei valori in percentuale totale di traffico deve essere pari a 0% (per disabilitare il traffico) o al 100% (per abilitare il traffico).

A questo punto, la distribuzione green riceve il 10% di tutto il traffico live. I client riceveranno stime sia dalle distribuzioni blue che green.

Diagramma che mostra la suddivisione del traffico tra le distribuzioni.

Inviare tutto il traffico alla nuova distribuzione

Quando la distribuzione green soddisfa pienamente le esigenze, inviare tutto il traffico a tale distribuzione.

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

Rimuovere la distribuzione precedente

Seguire questa procedura 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