Distribuire e assegnare un punteggio a un modello di Machine Learning usando un endpoint online

  • 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 il modello in un endpoint online da usare nell'inferenza in tempo reale. Si inizierà distribuendo un modello nel computer locale per eseguire il debug di eventuali errori. Si distribuirà e testerà quindi il modello in Azure. Si apprenderà anche per visualizzare i log di distribuzione e monitorare il contratto di servizio. Al termine di questo articolo, si avrà un endpoint HTTPS/REST scalabile che è possibile usare per l'inferenza in tempo reale.

Gli endpoint online sono endpoint usati per l'inferenza 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?.

Gli endpoint online gestiti consentono di distribuire i modelli di Machine Learning in modo pronto all'uso. Funzionano con computer CPU e GPU potenti in Azure in modo scalabile e completamente gestito. Gli endpoint online gestiti si occupano di gestire, dimensionare, proteggere e monitorare i modelli, liberando l'utente dalle attività di configurazione e gestione dell'infrastruttura sottostante.

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

Prerequisiti

SI APPLICA A:Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)

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/*. Se si usa Studio per creare/gestire endpoint/distribuzioni online, è necessaria richiedere un'autorizzazione aggiuntiva "Microsoft.Resources/deployments/write" al proprietario del gruppo di risorse. Per altre informazioni, vedere Gestire gli accessi 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.

Allocazione della quota di macchine virtuali per la distribuzione

Per gli endpoint online gestiti, Azure Machine Learning riserva il 20% delle risorse di calcolo per l'esecuzione di aggiornamenti in alcuni SKU di macchine virtuali. Se si richiede un determinato numero di istanze per gli SKU di macchine virtuali in una distribuzione, è necessario disporre di una quota per ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU evitare di ricevere un errore. Ad esempio, se si richiedono 10 istanze di una macchina virtuale Standard_DS3_v2 (fornita con 4 core) in una distribuzione, è necessario avere una quota per 48 core (12 instances * 4 cores) disponibili. Questa quota aggiuntiva è riservata alle operazioni initabili del sistema, ad esempio l'aggiornamento del sistema operativo, il ripristino di macchine virtuali e così via, e non comporta costi a meno che tale operazione non venga eseguita. Per visualizzare gli incrementi relativi all'utilizzo e alla quota di richieste, vedere Visualizzare l'utilizzo e le quote nel portale di Azure. Per visualizzare il costo dell'esecuzione di endpoint online gestiti, vedere Visualizzare i costi per l'endpoint online gestito. Esistono determinati SKU di macchina virtuale esentati dalla prenotazione di quote aggiuntive. Per visualizzare l'elenco completo, vedere l'elenco degli SKU degli endpoint online gestiti.

Azure Machine Learning offre un pool di quote condivise da cui tutti gli utenti possono accedere alla quota per eseguire test per un periodo di tempo limitato. Quando si usa lo studio per distribuire modelli Llama-2, Phi, Nemotron, Mistral, Dolly e Deci-DeciLM dal catalogo dei modelli a un endpoint online gestito, Azure Machine Learning consente di accedere a questa quota condivisa per un breve periodo di tempo.

Per altre informazioni su come usare la quota condivisa per la distribuzione di endpoint online, vedere Come distribuire i modelli di base usando lo studio.

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 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). Eseguire quindi il codice seguente per passare 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, riducendo il tempo necessario per completare l'operazione.

I comandi di questa esercitazione si trovano nei file deploy-local-endpoint.sh e deploy-managed-online-endpoint.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

Per definire un endpoint, è necessario specificare:

  • Nome endpoint: 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 basata su 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.
  • Facoltativamente, è possibile aggiungere una descrizione e tag all'endpoint.

Impostare un nome endpoint

Per impostare il nome dell'endpoint, eseguire il comando seguente (sostituire YOUR_ENDPOINT_NAME con un nome univoco).

Per Linux, eseguire questo comando:

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

Configurare l'endpoint

Il frammento di codice seguente mostra il file endpoints/online/managed/sample/endpoint.yml :

$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 gestiti, vedere Limiti per gli 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.

Definire la distribuzione

Per distribuzione si intende un set di risorse necessarie per ospitare il modello che esegue l'inferenza effettiva. Per distribuire un modello, è necessario disporre di:

  • File di modello (oppure il nome e la versione di un modello già registrato nell'area di lavoro). Nell'esempio è disponibile un modello scikit-learn che esegue la regressione.
  • Uno script di assegnazione dei punteggi, ovvero il codice che esegue il modello in una determinata richiesta di input. 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 .
  • Ambiente in cui viene eseguito il modello. L'ambiente può essere un'immagine Docker con dipendenze Conda o dockerfile.
  • Impostazioni per specificare il tipo di istanza e la capacità di ridimensionamento.

La tabella seguente descrive gli attributi chiave di una distribuzione:

Attributo Descrizione
Name Nome della distribuzione.
Nome endpoint 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.
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) Percorso relativo del file di punteggio nella directory del codice sorgente. 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 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.
Tipo di istanza 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 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 Allocazione della quota di macchine virtuali per le distribuzioni.

Avviso

  • Il modello e l'immagine del contenitore (come definito in Ambiente) possono essere nuovamente referenziati in qualsiasi momento dalla distribuzione quando le istanze dietro la distribuzione passano attraverso patch di sicurezza e/o altre operazioni di ripristino. Se è stata usata un'immagine del modello o del contenitore registrata in Registro Azure Container per la distribuzione e rimosso il modello o l'immagine del contenitore, le distribuzioni basate su questi asset possono non riuscire quando si verifica la ricreazione dell'immagine. Se è stato rimosso il modello o l'immagine del contenitore, assicurarsi che le distribuzioni dipendenti vengano ricreate o aggiornate con un modello o un'immagine del contenitore alternativa.
  • Il registro contenitori a cui fa riferimento l'ambiente può essere privato solo se l'identità dell'endpoint ha l'autorizzazione per accedervi tramite l'autenticazione di Microsoft Entra e il controllo degli accessi in base al ruolo di Azure. Per lo stesso motivo, i registri Docker privati diversi da Registro Azure Container non sono supportati.

Configurare una distribuzione

Il frammento di codice seguente mostra il file endpoints/online/managed/sample/blue-deployment.yml , con tutti gli input necessari per configurare una distribuzione:

$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

Nota

Nel file blue-deployment.yml sono stati specificati gli attributi di distribuzione seguenti:

  • model- In questo esempio si specificano le proprietà del modello inline usando .path I file del modello vengono caricati e registrati automaticamente con un nome generato automaticamente.
  • environment- In questo esempio sono presenti definizioni inline che includono .path Verrà usato environment.docker.image per l'immagine. Le conda_file dipendenze verranno installate sopra l'immagine.

Durante la distribuzione, i file locali, ad esempio l'origine Python per il modello di assegnazione dei punteggi, vengono caricati dall'ambiente di sviluppo.

Per altre informazioni sullo schema YAML, vedere le informazioni di riferimento sull'endpoint YAML online.

Nota

Per usare Kubernetes anziché gli endpoint gestiti come destinazione di calcolo:

  1. Creare e collegare il cluster Kubernetes come destinazione di calcolo all'area di lavoro di Azure Machine Learning usando studio di Azure Machine Learning.
  2. Usare l'endpoint YAML per specificare come destinazione Kubernetes anziché l'endpoint gestito YAML. Sarà necessario modificare il file YAML per modificare il valore di target impostando il nome della destinazione di calcolo registrata. È possibile usare questo file deployment.yaml con proprietà aggiuntive applicabili alla distribuzione di Kubernetes.

Tutti i comandi usati in questo articolo (ad eccezione del monitoraggio facoltativo del contratto di servizio e dell'integrazione di Azure Log Analytics) possono essere usati con endpoint gestiti o con endpoint Kubernetes.

Registrare il modello e l'ambiente separatamente

In questo esempio viene specificato il 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 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).

Usare tipi e immagini di istanze di CPU e GPU diversi

La definizione precedente nel file blue-deployment.yml usa un'istanza di tipo Standard_DS3_v2 generico e un'immagine mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latestDocker non GPU. Per il calcolo GPU, scegliere uno SKU del tipo di calcolo GPU e un'immagine Docker GPU.

Per i tipi di istanza per utilizzo generico e GPU supportati, vedere SKU di VM supportati per gli endpoint online gestiti. Per un elenco delle immagini di base della CPU e della GPU di Azure Machine Learning, vedere Immagini di base di Azure Machine Learning.

Nota

Per usare Kubernetes anziché gli endpoint gestiti come destinazione di calcolo, vedere Introduzione alla destinazione di calcolo kubernetes.

Identificare il percorso del modello in relazione a AZUREML_MODEL_DIR

Quando si distribuisce il modello in Azure Machine Learning, è necessario specificare il percorso del modello da distribuire come parte della configurazione della distribuzione. In Azure Machine Learning il percorso del modello viene monitorato con la AZUREML_MODEL_DIR variabile di ambiente. Identificando il percorso del modello rispetto a AZUREML_MODEL_DIR, è possibile distribuire uno o più modelli archiviati in locale nel computer o distribuire un modello registrato nell'area di lavoro di Azure Machine Learning.

Ad esempio, si fa riferimento alla struttura di cartelle locale seguente per i primi due casi in cui si distribuisce un singolo modello o si distribuiscono più modelli archiviati in locale:

Screenshot che mostra una struttura di cartelle contenente più modelli.

Usare un singolo modello locale in una distribuzione

Per usare un singolo modello presente nel computer locale in una distribuzione, specificare model per path nella distribuzione YAML. Ecco un esempio della distribuzione YAML con il percorso /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl:

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

Dopo aver creato la distribuzione, la variabile di ambiente punterà alla posizione di archiviazione AZUREML_MODEL_DIR in Azure in cui è archiviato il modello. Ad esempio, /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 conterrà il modello sample_m1.pkl.

All'interno dello script di assegnazione dei punteggi (score.py), è possibile caricare il modello (in questo esempio sample_m1.pkl) nella init() funzione :

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "sample_m1.pkl") 
    model = joblib.load(model_path)

Usare più modelli locali in una distribuzione

Anche se l'interfaccia della riga di comando di Azure, Python SDK e altri strumenti client consentono di specificare un solo modello per distribuzione nella definizione di distribuzione, è comunque possibile usare più modelli in una distribuzione registrando una cartella del modello che contiene tutti i modelli come file o sottodirectory.

Nella struttura di cartelle di esempio precedente si noterà che nella cartella sono presenti più modelli models . Nella distribuzione YAML è possibile specificare il percorso della models cartella come indicato di seguito:

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

Dopo aver creato la distribuzione, la variabile di ambiente punterà alla posizione di archiviazione AZUREML_MODEL_DIR in Azure in cui sono archiviati i modelli. Ad esempio, /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 conterrà i modelli e la struttura di file.

Per questo esempio, il contenuto della AZUREML_MODEL_DIR cartella sarà simile al seguente:

Screenshot della struttura di cartelle del percorso di archiviazione per più modelli.

Nello script di assegnazione dei punteggi (score.py) è possibile caricare i modelli nella init() funzione . Il codice seguente carica il sample_m1.pkl modello:

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "models","model_1","v1", "sample_m1.pkl ") 
    model = joblib.load(model_path)

Per un esempio di come distribuire più modelli in una distribuzione, vedere Distribuire più modelli in un'unica distribuzione (esempio dell'interfaccia della riga di comando) e Distribuire più modelli in una distribuzione (esempio dell'SDK).

Suggerimento

Se sono presenti più di 1500 file da registrare, è consigliabile comprimere i file o le sottodirectory come .tar.gz durante la registrazione dei modelli. Per utilizzare i modelli, è possibile decomprimere i file o le sottodirectory nella init() funzione dallo script di assegnazione dei punteggi. In alternativa, quando si registrano i modelli, impostare la azureml.unpack proprietà su True, per decomprimere automaticamente i file o le sottodirectory. In entrambi i casi, la decompressione avviene una volta nella fase di inizializzazione.

Usare i modelli registrati nell'area di lavoro di Azure Machine Learning in una distribuzione

Per usare uno o più modelli registrati nell'area di lavoro di Azure Machine Learning, nella distribuzione specificare il nome dei modelli registrati nel file YAML di distribuzione. Ad esempio, la configurazione YAML di distribuzione seguente specifica il nome registrato model come azureml:local-multimodel:3:

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

Per questo esempio, si consideri che local-multimodel:3 contiene gli artefatti del modello seguenti, che possono essere visualizzati dalla scheda Modelli nella studio di Azure Machine Learning:

Screenshot della struttura di cartelle che mostra gli artefatti del modello registrato.

Dopo aver creato la distribuzione, la variabile di ambiente punterà alla posizione di archiviazione AZUREML_MODEL_DIR in Azure in cui sono archiviati i modelli. Ad esempio, /var/azureml-app/azureml-models/local-multimodel/3 conterrà i modelli e la struttura di file. AZUREML_MODEL_DIR punterà alla cartella contenente la radice degli artefatti del modello. In base a questo esempio, il contenuto della AZUREML_MODEL_DIR cartella sarà simile al seguente:

Screenshot della struttura di cartelle che mostra più modelli.

Nello script di assegnazione dei punteggi (score.py) è possibile caricare i modelli nella init() funzione . Ad esempio, caricare il diabetes.sav modello:

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR"), "models", "diabetes", "1", "diabetes.sav") 
    model = joblib.load(model_path)

Informazioni sullo script di assegnazione dei punteggi

Suggerimento

Il formato dello script di assegnazione dei punteggi per gli endpoint online è lo stesso formato usato nella versione precedente dell'interfaccia della riga di comando e in Python SDK.

Come indicato in precedenza, lo script di assegnazione dei punteggi specificato in code_configuration.scoring_script deve avere una init() funzione e una run() funzione.

In questo esempio viene usato il file di score.py: score.py

import os
import logging
import json
import numpy
import joblib


def init():
    """
    This function is called when the container is initialized/started, typically after create/update of the deployment.
    You can write the logic here to perform init operations like caching the model in memory
    """
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Init complete")


def run(raw_data):
    """
    This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
    In the example we extract the data from the json input and call the scikit-learn model's predict()
    method and return the result back
    """
    logging.info("model 1: request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

La init() funzione viene chiamata quando il contenitore viene inizializzato o avviato. L'inizializzazione si verifica in genere poco dopo la creazione o l'aggiornamento della distribuzione. La init funzione è la posizione in cui scrivere la logica per operazioni di inizializzazione globali, ad esempio la memorizzazione nella cache del modello in memoria (come in questo esempio).

La run() funzione viene chiamata per ogni chiamata dell'endpoint ed esegue l'effettivo punteggio e la stima. In questo esempio si estraggono dati da un input JSON, si chiamerà il metodo del predict() modello scikit-learn e quindi si restituirà il risultato.

Distribuire ed eseguire il debug in locale usando endpoint locali

È consigliabile testare l'endpoint in locale convalidando e eseguendo il debug del codice e della configurazione prima di eseguire la distribuzione in Azure. L'interfaccia della riga di comando di Azure e Python SDK supportano endpoint e distribuzioni locali, mentre studio di Azure Machine Learning e il modello arm non lo fanno.

Per eseguire la distribuzione in locale, è necessario installare ed eseguire il motore Docker. Docker Engine viene in genere avviato all'avvio del computer. In caso contrario, è possibile eseguire la risoluzione dei problemi relativi a Docker Engine.

Suggerimento

È possibile usare il pacchetto Python del server HTTP di inferenza di Azure Machine Learning per eseguire il debug dello script di assegnazione dei punteggi in locale senza il motore Docker. Il debug con il server di inferenza consente di eseguire il debug dello script di assegnazione dei punteggi prima della distribuzione negli endpoint locali in modo che sia possibile eseguire il debug senza influire sulle configurazioni del contenitore di distribuzione.

Nota

Gli endpoint locali presentano le limitazioni seguenti:

  • Non supportano regole di traffico, autenticazione o impostazioni probe.
  • Supportano una sola distribuzione per endpoint.
  • Supportano solo file di modello e ambiente locali con file conda locali. Se si vogliono testare i modelli registrati, prima di tutto scaricarli usando l'interfaccia della riga di comando o l'SDK, usare path nella definizione di distribuzione per fare riferimento alla cartella padre. Per testare gli ambienti registrati, controllare il contesto dell'ambiente in studio di Azure Machine Learning e preparare il file conda locale da usare. Nell'esempio riportato in questo articolo viene illustrato l'uso del modello locale e dell'ambiente con il file conda locale, che supporta la distribuzione locale.

Per altre informazioni sul debug degli endpoint online in locale prima della distribuzione in Azure, vedere Eseguire il debug degli endpoint online in locale in Visual Studio Code.

Distribuire il modello in locale

Creare prima di tutto un endpoint. Facoltativamente, per un endpoint locale, è possibile ignorare questo passaggio e creare direttamente la distribuzione (passaggio successivo), che a sua volta creerà i metadati necessari. La distribuzione dei modelli in locale è utile a scopo di sviluppo e test.

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

Creare ora una distribuzione denominata blue nell'endpoint.

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

Il --local flag indirizza l'interfaccia della riga di comando a distribuire l'endpoint nell'ambiente Docker.

Suggerimento

Usare Visual Studio Code per testare ed eseguire il debug degli endpoint in locale. Per altre informazioni, vedere Eseguire il debug degli endpoint online in locale in Visual Studio Code.

Verificare la corretta esecuzione della distribuzione locale

Controllare lo stato per verificare se il modello è stato distribuito senza errori:

az ml online-endpoint show -n $ENDPOINT_NAME --local

L'output dovrebbe essere simile al codice JSON seguente. Il provisioning_state è Succeeded.

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

La tabella seguente contiene i valori possibili per provisioning_state:

Stato Descrizione
Creazione La risorsa viene creata.
Aggiornamento La risorsa viene aggiornata.
Eliminazione in corso La risorsa viene eliminata.
Completato Operazione di creazione/aggiornamento completata.
Non riuscito L'operazione di creazione/aggiornamento/eliminazione non è riuscita.

Richiamare l'endpoint locale per assegnare punteggi ai dati usando il modello

Richiamare l'endpoint per assegnare un punteggio al modello usando il comando invoke pratico e passando i parametri di query archiviati in un file JSON:

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

Se si vuole usare un client REST (ad esempio curl), è necessario disporre dell'URI di assegnazione dei punteggi. Per ottenere l'URI di assegnazione dei punteggi, eseguire az ml online-endpoint show --local -n $ENDPOINT_NAME. Nei dati restituiti trovare l'attributo scoring_uri . I comandi basati su curl di esempio sono disponibili più avanti in questo documento.

Esaminare i log per l'output dell'operazione invoke

Nell'esempio score.py file il run() metodo registra un output nella console.

È possibile visualizzare questo output usando il get-logs comando :

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

Distribuire l'endpoint online in Azure

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

Distribuzione in Azure

Per creare l'endpoint nel cloud, eseguire il codice seguente:

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

Per creare la distribuzione denominata blue nell'endpoint, eseguire il codice seguente:

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

Questa distribuzione potrebbe richiedere fino a 15 minuti, a seconda che l'ambiente o l'immagine sottostante venga compilata per la prima volta. Le distribuzioni successive che usano lo stesso ambiente termineranno l'elaborazione più rapidamente.

Suggerimento

  • Se si preferisce non bloccare la console dell'interfaccia della riga di comando, è possibile aggiungere il flag --no-wait al comando . Tuttavia, questa operazione arresterà la visualizzazione interattiva dello stato della distribuzione.

Importante

Il flag --all-traffic usato in az ml online-deployment create alloca il 100% del traffico dell'endpoint alla distribuzione blu appena creata. Anche se questo è utile ai fini dello sviluppo e del test, per l'ambiente di produzione, potrebbe essere necessario aprire il traffico per la nuova distribuzione tramite un comando esplicito. Ad esempio: az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100".

Suggerimento

Controllare lo stato dell'endpoint

Il show comando contiene informazioni in provisioning_state per l'endpoint e la distribuzione:

az ml online-endpoint show -n $ENDPOINT_NAME

È possibile elencare tutti gli endpoint nell'area di lavoro in un formato di tabella usando il list comando :

az ml online-endpoint list --output table

Controllare lo stato della distribuzione online

Controllare i log per verificare se il modello è stato distribuito senza errori.

Per visualizzare l'output del log da un contenitore, usare il comando dell'interfaccia della riga di comando seguente:

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

Per impostazione predefinita, i log vengono estratti dal contenitore del server di inferenza. Per visualizzare i log dal contenitore dell'inizializzatore di archiviazione, aggiungere il --container storage-initializer flag . Per altre informazioni sui log di distribuzione, vedere Ottenere i log dei contenitori.

Richiamare l'endpoint per assegnare un punteggio ai dati usando il modello

È possibile usare il invoke comando o un client REST di propria scelta per richiamare l'endpoint e assegnare un punteggio ad alcuni dati:

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

L'esempio seguente illustra come ottenere la chiave usata per l'autenticazione all'endpoint:

Suggerimento

È possibile controllare quali entità di sicurezza di Microsoft Entra possono ottenere la chiave di autenticazione assegnandole a un ruolo personalizzato che consente Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action e Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action. Per altre informazioni, vedere Gestire l'accesso a un'area di lavoro di Azure Machine Learning.

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

Usare quindi curl per assegnare punteggi ai dati.

SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

Si noti che vengono usati show i comandi e get-credentials per ottenere le credenziali di autenticazione. Si noti anche che si sta usando il --query flag per filtrare gli attributi solo a ciò di cui abbiamo bisogno. Per altre informazioni su , vedere Eseguire query sull'output--query dei comandi dell'interfaccia della riga di comando di Azure.

Per visualizzare i log delle chiamate, eseguire get-logs di nuovo.

Per informazioni sull'autenticazione con un token, vedere Eseguire l'autenticazione agli endpoint online.

(Facoltativo) Aggiornare la distribuzione

Se si vuole aggiornare il codice, il modello o l'ambiente, aggiornare il file YAML e quindi eseguire il az ml online-endpoint update comando .

Nota

Se si aggiorna il numero di istanze (per ridimensionare la distribuzione) insieme ad altre impostazioni del modello (ad esempio codice, modello o ambiente) in un singolo update comando, l'operazione di ridimensionamento verrà eseguita per prima cosa, quindi verranno applicati gli altri aggiornamenti. È consigliabile eseguire queste operazioni separatamente in un ambiente di produzione.

Per comprendere il funzionamento update :

  1. Aprire il file online/model-1/onlinescoring/score.py.

  2. Modificare l'ultima riga della init() funzione: dopo logging.info("Init complete"), aggiungere logging.info("Updated successfully").

  3. Salvare il file.

  4. Eseguire questo comando:

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

    Nota

    L'aggiornamento tramite YAML è dichiarativo. Ciò significa che le modifiche nel file YAML si riflettono nelle risorse di Azure Resource Manager sottostanti (endpoint e distribuzioni). Un approccio dichiarativo facilita GitOps: tutte le modifiche apportate agli endpoint e alle distribuzioni (anche instance_count) passano attraverso YAML.

    Suggerimento

    • È possibile usare parametri di aggiornamento generici, ad esempio il --set parametro , con il comando dell'interfaccia update della riga di comando per eseguire l'override degli attributi nel file YAML o per impostare attributi specifici senza passarli nel file YAML. L'uso --set di per attributi singoli è particolarmente utile negli scenari di sviluppo e test. Ad esempio, per aumentare il instance_count valore per la prima distribuzione, è possibile usare il --set instance_count=2 flag . Tuttavia, poiché YAML non viene aggiornato, questa tecnica non facilita GitOps.
    • Specificare il file YAML non è obbligatorio. Ad esempio, se si vuole testare un'impostazione di concorrenza diversa per una determinata distribuzione, è possibile provare qualcosa come az ml online-deployment update -n blue -e my-endpoint --set request_settings.max_concurrent_requests_per_instance=4 environment_variables.WORKER_COUNT=4. Questa operazione manterrà tutte le configurazioni esistenti, ma aggiornerà solo i parametri specificati.

  5. Poiché la init() funzione è stata modificata, che viene eseguita quando l'endpoint viene creato o aggiornato, il messaggio Updated successfully verrà visualizzato nei log. Recuperare i log eseguendo:

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

Il update comando funziona anche con le distribuzioni locali. Usare lo stesso az ml online-deployment update comando con il --local flag .

Nota

L'aggiornamento precedente alla distribuzione è un esempio di aggiornamento in sequenza in locale.

  • Per un endpoint online gestito, la distribuzione viene aggiornata alla nuova configurazione con il 20% dei nodi alla volta. Ovvero, se la distribuzione ha 10 nodi, verranno aggiornati 2 nodi alla volta.
  • Per un endpoint online Kubernetes, il sistema creerà in modo iterativo una nuova istanza di distribuzione con la nuova configurazione ed eliminerà quella precedente.
  • Per l'utilizzo di produzione, è consigliabile prendere in considerazione la distribuzione blu-verde, che offre un'alternativa più sicura per l'aggiornamento di un servizio Web.

(Facoltativo) Configurare la scalabilità automatica

La scalabilità automatica usa automaticamente la quantità corretta di risorse per gestire il carico dell'applicazione. Gli endpoint online gestiti supportano la scalabilità automatica tramite l'integrazione con la funzionalità di scalabilità automatica di Monitoraggio di Azure. Per configurare la scalabilità automatica, vedere Come ridimensionare automaticamente gli endpoint online.

(Facoltativo) Monitorare il contratto di servizio usando Monitoraggio di Azure

Per visualizzare le metriche e impostare gli avvisi in base al contratto di servizio, completare i passaggi descritti in Monitorare gli endpoint online.

(Facoltativo) Eseguire l'integrazione con Log Analytics

Il get-logs comando per l'interfaccia della riga di comando o il get_logs metodo per SDK fornisce solo le ultime centinaia di righe di log da un'istanza selezionata automaticamente. Tuttavia, Log Analytics consente di archiviare e analizzare i log in modo durevole. Per altre informazioni sull'uso della registrazione, vedere Monitorare gli endpoint online.

Eliminare l'endpoint e la distribuzione

Se non si usa la distribuzione, è necessario eliminarla eseguendo il codice seguente (elimina l'endpoint e tutte le distribuzioni sottostanti):

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

Contenuto correlato