Distribuire modelli MLflow nelle distribuzioni batch in Azure Machine Learning
SI APPLICA A:Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)Python SDK azure-ai-ml v2 (corrente)
Questo articolo illustra come distribuire modelli MLflow in Azure Machine Learning per l'inferenza batch usando endpoint batch. Quando si distribuiscono modelli MLflow in endpoint batch, Azure Machine Learning completa le attività seguenti:
- Fornisce un ambiente curato o di immagine di base di MLflow che contiene le dipendenze necessarie per eseguire un processo batch di Machine Learning.
- Crea una pipeline di processi batch con uno script di assegnazione dei punteggi che è possibile usare per elaborare i dati usando la parallelizzazione.
Per altre informazioni sui tipi di file di input supportati e sui dettagli sul funzionamento del modello MLflow, vedere Considerazioni per la distribuzione nell'inferenza batch.
Prerequisiti
Una sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare. Provare la versione gratuita o a pagamento di Azure Machine Learning.
Un'area di lavoro di Azure Machine Learning. Per creare un'area di lavoro, vedere Gestire le aree di lavoro di Azure Machine Learning.
Assicurarsi di disporre delle autorizzazioni seguenti nell'area di lavoro di Azure Machine Learning:
- Creare o gestire endpoint e distribuzioni batch: usare un ruolo di proprietario, collaboratore o personalizzato che consenta
Microsoft.MachineLearningServices/workspaces/batchEndpoints/*
. - Creare distribuzioni di Azure Resource Manager nel gruppo di risorse dell'area di lavoro: usare un ruolo di Proprietario, Contributore o Personalizzato che consenta
Microsoft.Resources/deployments/write
nel gruppo di risorse in cui viene distribuita l'area di lavoro.
- Creare o gestire endpoint e distribuzioni batch: usare un ruolo di proprietario, collaboratore o personalizzato che consenta
Installare il software seguente per usare Azure Machine Learning:
Eseguire il comando seguente per installare l'interfaccia della riga di comando di Azure e l'
ml
estensione per Azure Machine Learning:az extension add -n ml
Le distribuzioni dei componenti della pipeline per gli endpoint batch sono state introdotte nella versione 2.7 dell'estensione
ml
per l'interfaccia della riga di comando di Azure. Usare il comandoaz extension update --name ml
per ottenere la versione più recente.
Connettersi all'area di lavoro
L'area di lavoro è la risorsa di primo livello per Machine Learning. Fornisce una posizione centralizzata per lavorare con tutti gli artefatti creati durante l'uso di Machine Learning. In questa sezione ci si connette all'area di lavoro in cui verranno eseguite le attività di distribuzione.
Immettere i valori per l'ID sottoscrizione, l'area di lavoro, la posizione e il gruppo di risorse nel codice seguente:
az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>
Esplorare l'esempio
L'esempio in questo articolo illustra come distribuire un modello MLflow in un endpoint batch per eseguire stime batch. Il modello MLflow si basa sul set di dati UCI Heart Disease. Il database contiene 76 attributi, ma l'esempio usa solo un subset di 14. Il modello tenta di stimare la presenza di malattie cardiache in un paziente con un valore intero compreso tra 0 (nessuna presenza) e 1 (presenza).
Il training del modello viene eseguito usando un classificatore XGBBoost
. Tutta la pre-elaborazione richiesta viene inserita in un pacchetto come pipeline scikit-learn
, che rende il modello una pipeline end-to-end che passa dai dati non elaborati alle stime.
L'esempio contenuto in questo articolo si basa sugli esempi di codice contenuti nel repository azureml-examples. Per eseguire i comandi in locale senza dover copiare o incollare il file YAML e altri file, innanzitutto clonare il repository quindi cambiare le directory nella cartella:
git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli
I file per questo esempio si trovano nella cartella seguente:
cd endpoints/batch/deploy-models/heart-classifier-mlflow
Seguire la procedura in Jupyter Notebook
È possibile seguire questo esempio usando un Jupyter Notebook pubblico. Nel repository clonato, aprire il notebook: mlflow-for-batch-tabular.ipynb.
Distribuire il modello MLflow
In questa sezione si distribuisce un modello MLflow in un endpoint batch in modo da poter eseguire l'inferenza batch sui nuovi dati. Prima di procedere con la distribuzione, è necessario assicurarsi che il modello sia registrato e che sia disponibile un cluster di elaborazione nell'area di lavoro.
Registrare il modello
Gli endpoint batch possono distribuire solo i modelli registrati. In questo articolo viene usata una copia locale del modello nel repository. Di conseguenza, è sufficiente pubblicare il modello nel Registro di sistema nell'area di lavoro.
Nota
Se il modello che si sta distribuendo è già registrato, è possibile continuare con la sezione Creare il cluster di elaborazione.
Registrare il modello eseguendo il comando seguente:
MODEL_NAME='heart-classifier-mlflow'
az ml model create --name $MODEL_NAME --type "mlflow_model" --path "model"
Creare il cluster di elaborazione
È necessario assicurarsi che le distribuzioni batch possano essere eseguite in un'infrastruttura disponibile (calcolo). Le distribuzioni batch possono essere eseguite in qualsiasi ambiente di calcolo di Machine Learning già esistente nell'area di lavoro. Più distribuzioni batch possono condividere la stessa infrastruttura di calcolo.
In questo articolo si lavora su un cluster di elaborazione di Machine Learning denominato cpu-cluster. Nell'esempio seguente viene verificata l'esistenza di un ambiente di calcolo nell'area di lavoro o viene creato un nuovo ambiente di calcolo.
Creare un cluster di calcolo:
az ml compute create -n batch-cluster --type amlcompute --min-instances 0 --max-instances 5
Creare un endpoint batch
Per creare un endpoint, è necessario un nome e una descrizione. Il nome dell'endpoint viene visualizzato nell'URI associato all'endpoint, quindi deve essere univoco all'interno di un'area di Azure. Ad esempio, può esistere solo un endpoint batch con il nome mybatchendpoint
nell'area Stati Uniti occidentali 2.
Inserire il nome dell'endpoint in una variabile per un riferimento semplice in un secondo momento:
Esegui questo comando:
ENDPOINT_NAME="heart-classifier"
Creare l'endpoint:
Per creare un nuovo endpoint, creare una configurazione
YAML
simile al codice seguente:endpoint.yml
$schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json name: heart-classifier-batch description: A heart condition classifier for batch inference auth_mode: aad_token
Creare l'endpoint con il comando seguente:
az ml batch-endpoint create -n $ENDPOINT_NAME -f endpoint.yml
Creare una distribuzione batch
I modelli MLflow non richiedono di indicare un ambiente o uno script di assegnazione dei punteggi quando si crea la distribuzione. Lo script di assegnazione dei punteggi o dell'ambiente viene creato automaticamente. Tuttavia, è possibile specificare l'ambiente o lo script di assegnazione dei punteggi se si desidera personalizzare la modalità di inferenza della distribuzione.
Per creare una nuova distribuzione nell'endpoint creato, creare una configurazione
YAML
come mostrato nel codice seguente. È possibile controllare lo schema YAML dell'endpoint batch completo per ottenere proprietà aggiuntive.deployment-simple/deployment.yml
$schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json endpoint_name: heart-classifier-batch name: classifier-xgboost-mlflow description: A heart condition classifier based on XGBoost type: model model: azureml:heart-classifier-mlflow@latest compute: azureml:batch-cluster resources: instance_count: 2 settings: max_concurrency_per_instance: 2 mini_batch_size: 2 output_action: append_row output_file_name: predictions.csv retry_settings: max_retries: 3 timeout: 300 error_threshold: -1 logging_level: info
Creare la distribuzione con il comando seguente:
az ml batch-deployment create --file deployment-simple/deployment.yml --endpoint-name $ENDPOINT_NAME --set-default
Importante
Configurare il valore timeout
nella distribuzione in base al tempo necessario per l'esecuzione dell'inferenza del modello in un singolo batch. Quanto maggiore è la dimensione del batch, tanto maggiore è il valore timeout
. Tenere a mente che mini_batch_size
indica il numero di file in un batch, non il numero di campioni. Quando si usano dati tabulari, ogni file può contenere più righe che aumentano il tempo necessario per l'elaborazione di ogni file da parte dell'endpoint batch. In questi casi, usare valori timeout
elevati per evitare errori di timeout.
Richiamare l'endpoint
Anche se è possibile richiamare una distribuzione specifica all'interno di un endpoint, è normale richiamare l'endpoint stesso e consentire all'endpoint di decidere quale distribuzione usare. Questo tipo di distribuzione è denominata distribuzione "predefinita". Questo approccio consente di modificare la distribuzione predefinita, che consente di modificare il modello che gestisce la distribuzione senza modificare il contratto con l'utente che richiama l'endpoint.
Usare l'istruzione seguente per aggiornare la distribuzione predefinita:
DEPLOYMENT_NAME="classifier-xgboost-mlflow"
az ml batch-endpoint update --name $ENDPOINT_NAME --set defaults.deployment_name=$DEPLOYMENT_NAME
L'endpoint batch è ora pronto per l'uso.
Testare la distribuzione
Per testare l'endpoint, usare un esempio di dati senza etichetta che si trovano in questo repository che può essere usato con il modello. Gli endpoint batch possono elaborare solo i dati presenti nel cloud e accessibili dall'area di lavoro di Machine Learning. In questo esempio si carica l'esempio in un archivio dati di Machine Learning. Si crea un asset di dati che può essere usato per richiamare l'endpoint per l'assegnazione dei punteggi. Tenere a mente che gli endpoint batch accettano dati che possono essere inseriti in diverse posizioni.
Innanzitutto, creare l'asset di dati. L'asset di dati è costituito da una cartella con più file CSV da elaborare in parallelo usando endpoint batch. È possibile ignorare questo passaggio perché i dati sono già registrati come asset di dati o si vuole usare un tipo di input diverso.
Creare una definizione di asset di dati in YAML:
heart-dataset-unlabeled.yml
$schema: https://azuremlschemas.azureedge.net/latest/data.schema.json name: heart-dataset-unlabeled description: An unlabeled dataset for heart classification. type: uri_folder path: data
Creare l'asset di dati:
az ml data create -f heart-dataset-unlabeled.yml
Dopo aver caricato i dati, richiamare l'endpoint.
Suggerimento
Nei comandi seguenti si noti che il nome della distribuzione non è indicato nell'operazione
invoke
. L'endpoint instrada automaticamente il processo alla distribuzione predefinita perché l'endpoint ha una sola distribuzione. È possibile specificare come destinazione una distribuzione specifica indicando l'argomento/parametrodeployment_name
.Eseguire il comando riportato di seguito:
JOB_NAME = $(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input azureml:heart-dataset-unlabeled@latest --query name -o tsv)
Nota
L'utilità
jq
potrebbe non essere installata in ogni installazione. Per istruzioni di installazione, vedere Scaricare jq.Un processo batch viene avviato non appena viene restituito il comando. È possibile monitorare lo stato del processo fino al termine dell'operazione:
Esegui questo comando:
az ml job show -n $JOB_NAME --web
Analizzare gli output
Le stime di output vengono generate nel file predictions.csv come indicato nella configurazione della distribuzione. Il processo genera un output denominato score, in cui viene inserito il file. Viene generato un solo file per ogni processo batch.
Il file è strutturato come segue:
Una riga per ogni punto dati inviato al modello. Per i dati tabulari, il file predictions.csv contiene una riga per ogni riga presente in ogni file elaborato. Per altri tipi di dati (immagini, audio, testo), è presente una riga per ogni file elaborato.
Le colonne seguenti si trovano nel file (nell'ordine specificato):
row
(facoltativo): indice di riga corrispondente nel file di dati di input. Questa colonna si applica solo se i dati di input sono tabulari. Le stime vengono restituite nello stesso ordine in cui vengono visualizzate nel file di input. È possibile fare affidamento sul numero di riga in modo che corrisponda alla stima corrispondente.prediction
: Stima associata ai dati di input. Questo valore viene restituito "così come è", come è stato fornito dalla funzionepredict().
del modello.file_name
: nome del nome file in cui sono letti i dati. Nei dati tabulari usare questo campo per determinare quale stima appartiene ai singoli dati di input.
È possibile scaricare i risultati del processo usando il nome del processo.
Per scaricare le previsioni, usare il comando seguente:
az ml job download --name $JOB_NAME --output-name score --download-path ./
Dopo aver scaricato il file, è possibile aprire il file con lo strumento di modifica preferito. Nell'esempio seguente, vengono caricate le previsioni usando un dataframe Pandas
.
import pandas as pd
score = pd.read_csv(
"named-outputs/score/predictions.csv", names=["row", "prediction", "file"]
)
L'output visualizza una tabella:
Riga | Previsione | file |
---|---|---|
0 | 0 | heart-unlabeled-0.csv |
1 | 1 | heart-unlabeled-0.csv |
2 | 0 | heart-unlabeled-0.csv |
... | ... | ... |
307 | 0 | heart-unlabeled-3.csv |
Suggerimento
Si noti che in questo esempio i dati di input contengono dati tabulari in formato CSV. Esistono quattro file di input differenti: heart-unlabeled-0.csv, heart-unlabeled-1.csv, heart-unlabeled-2.csve heart-unlabeled-3.csv.
Esaminare le considerazioni per l'inferenza batch
Machine Learning supporta la distribuzione di modelli MLflow in endpoint batch senza indicare uno script di assegnazione dei punteggi. Questo approccio è un modo pratico per distribuire modelli che richiedono l'elaborazione di grandi quantità di dati simili all'elaborazione batch. Machine Learning usa le informazioni nella specifica del modello MLflow per orchestrare il processo di inferenza.
Esplorare la distribuzione del lavoro sui lavoratori
Gli endpoint batch distribuiscono il lavoro a livello di file, sia per i dati strutturati che non strutturati. Di conseguenza, per questa funzionalità sono supportati solo i file URI e le cartelle URI. Ogni ruolo di lavoro elabora batch di file Mini batch size
alla volta. Per i dati tabulari, gli endpoint batch non prendono in considerazione il numero di righe all'interno di ogni file durante la distribuzione del lavoro.
Avviso
Le strutture di cartelle annidate non vengono esaminate durante l'inferenza. Se si partiziona i dati usando le cartelle, assicurarsi di rendere flat la struttura prima di procedere.
Le distribuzioni batch chiamano la funzione predict
del modello MLflow una volta per ogni file. Per i file CSV contenenti più righe, questa azione può comportare un utilizzo elevato di memoria nel calcolo sottostante. Il comportamento può aumentare il tempo necessario per il modello per assegnare un punteggio a un singolo file, soprattutto per modelli costosi come modelli linguistici di grandi dimensioni. Se si verificano diverse eccezioni di memoria insufficiente o voci di timeout nei log, è consigliabile suddividere i dati in file più piccoli con meno righe o implementare l'invio in batch a livello di riga all'interno dello script di modello/assegnazione dei punteggi.
Esaminare il supporto per i tipi di file
I tipi di dati seguenti sono supportati per l'inferenza batch durante la distribuzione di modelli MLflow senza un ambiente o uno script di assegnazione dei punteggi. Per elaborare un tipo di file differente o eseguire l'inferenza in modo differente, è possibile creare la distribuzione personalizzando la distribuzione del modello MLflow con uno script di assegnazione dei punteggi.
Estensione di file | Tipo restituito come input di modello | Requisito di firma |
---|---|---|
.csv , .parquet , .pqt |
pd.DataFrame |
ColSpec . Se non specificato, la digitazione delle colonne non viene applicata. |
.png , .jpg , .jpeg , .tiff , .bmp , .gif |
np.ndarray |
TensorSpec . L'input viene rimodellato in modo che corrisponda alla forma tensori, se disponibile. Se non è disponibile alcuna firma, vengono dedotti tensori di tipo np.uint8 . Per altre informazioni, vedere Considerazioni per i modelli MLflow che elaborano immagini. |
Avviso
Qualsiasi file non supportato che potrebbe essere presente nei dati di input causa l'esito negativo del processo. In questi casi viene visualizzato un errore simile a ERROR:azureml:Error processing input file: '/mnt/batch/tasks/.../a-given-file.avro'. Il tipo di file 'avro' non è supportato.
Comprendere l'applicazione della firma per i modelli MLflow
I tipi di dati di input vengono applicati dai processi di distribuzione batch durante la lettura dei dati usando la firma del modello MLflow disponibile. Di conseguenza, l'input dei dati è conforme ai tipi indicati nella firma del modello. Se i dati non possono essere analizzati come previsto, il processo ha esito negativo con un errore simile a ERROR:azureml:Error processing input file: '/mnt/batch/tasks/.../a-given-file.csv'. Eccezione: valore letterale non valido per int() con base 10: 'value'.
Suggerimento
Le firme nei modelli MLflow sono facoltative, ma sono altamente incoraggiate. Offrono un modo pratico per il rilevamento anticipato dei problemi di compatibilità dei dati. Per altre informazioni su come registrare modelli con firme, vedere Registrazione di modelli con una firma, un ambiente o esempi personalizzati.
È possibile esaminare la firma del modello aprendo il file MLmodel
associato al modello MLflow. Per altre informazioni sul funzionamento delle firme in MLflow, vedere Firme in MLflow.
Esaminare il supporto per la versione
Le distribuzioni batch supportano solo la distribuzione di modelli MLflow con una versione pyfunc
. Per distribuire una versione differente, vedere Personalizzare le distribuzioni del modello con lo script di assegnazione dei punteggi.
Personalizzare la distribuzione del modello con lo script di assegnazione dei punteggi
I modelli MLflow possono essere distribuiti negli endpoint batch senza indicare uno script di punteggio nella definizione di distribuzione. Tuttavia, è possibile acconsentire esplicitamente a indicare questo file (comunemente definito driver batch) per personalizzare l'esecuzione dell'inferenza.
In genere si seleziona questo flusso di lavoro per gli scenari seguenti:
- Tipi di file di elaborazione non supportati dalle distribuzioni batch di distribuzioni MLflow.
- Personalizzare la modalità di esecuzione del modello, ad esempio usando una versione specifica per caricarlo con la funzione
mlflow.<flavor>.load()
. - Completare la pre-elaborazione o la post-elaborazione nella routine di assegnazione dei punteggi, quando non viene completata dal modello stesso.
- Regolare la presentazione del modello che non presenta bene dati tabulari, ad esempio un grafico tensore che rappresenta un'immagine.
- Consentire al modello di leggere i dati in blocchi perché non può elaborare ogni file contemporaneamente a causa di vincoli di memoria.
Importante
Per indicare uno script di assegnazione dei punteggi per una distribuzione del modello MLflow, è necessario specificare l'ambiente in cui viene eseguita la distribuzione.
Usare lo script di assegnazione dei punteggi
Usare la procedura seguente per distribuire un modello MLflow con uno script di assegnazione dei punteggi personalizzato:
Identificare la cartella in cui si trova il modello MLflow.
Nel portale di Azure Machine Learning andare a Modelli.
Selezionare il modello da distribuire quindi selezionare la scheda Artefatti.
Prendere nota della cartella visualizzata. Tale cartella è stata specificata al momento della registrazione del modello.
Creare uno script di assegnazione del punteggio. Si noti che il nome della cartella
model
precedente è incluso nella funzioneinit()
.deployment-custom/code/batch_driver.py
# Copyright (c) Microsoft. All rights reserved. # Licensed under the MIT license. import os import glob import mlflow import pandas as pd import logging def init(): global model global model_input_types global model_output_names # AZUREML_MODEL_DIR is an environment variable created during deployment # It is the path to the model folder # Please provide your model's folder name if there's one model_path = glob.glob(os.environ["AZUREML_MODEL_DIR"] + "/*/")[0] # Load the model, it's input types and output names model = mlflow.pyfunc.load(model_path) if model.metadata and model.metadata.signature: if model.metadata.signature.inputs: model_input_types = dict( zip( model.metadata.signature.inputs.input_names(), model.metadata.signature.inputs.pandas_types(), ) ) if model.metadata.signature.outputs: if model.metadata.signature.outputs.has_input_names(): model_output_names = model.metadata.signature.outputs.input_names() elif len(model.metadata.signature.outputs.input_names()) == 1: model_output_names = ["prediction"] else: logging.warning( "Model doesn't contain a signature. Input data types won't be enforced." ) def run(mini_batch): print(f"run method start: {__file__}, run({len(mini_batch)} files)") data = pd.concat( map( lambda fp: pd.read_csv(fp).assign(filename=os.path.basename(fp)), mini_batch ) ) if model_input_types: data = data.astype(model_input_types) # Predict over the input data, minus the column filename which is not part of the model. pred = model.predict(data.drop("filename", axis=1)) if pred is not pd.DataFrame: if not model_output_names: model_output_names = ["pred_col" + str(i) for i in range(pred.shape[1])] pred = pd.DataFrame(pred, columns=model_output_names) return pd.concat([data, pred], axis=1)
Creare un ambiente in cui è possibile eseguire lo script di assegnazione dei punteggi. Poiché il modello in questo esempio è MLflow, i requisiti conda vengono specificati anche nel pacchetto del modello. Per altre informazioni sui modelli MLflow e sui file inclusi, vedere Il formato MLmodel.
In questo passaggio si compila l'ambiente usando le dipendenze conda dal file. È inoltre necessario includere il pacchetto
azureml-core
che è richiesto per le distribuzioni batch.Suggerimento
Se il modello è già registrato nel Registro di sistema dei modelli, è possibile scaricare e copiare il file
conda.yml
associato al modello. Il file è disponibile in Studio di Azure Machine Learning in Modelli>Selezionare il modello nell'elenco>Artefatti. Nella cartella radice selezionare il fileconda.yml
, quindi selezionare Scarica o copiarne il contenuto.Importante
In questo esempio, viene usato un ambiente Conda specificato in
/heart-classifier-mlflow/environment/conda.yaml
. Questo file è stato creato combinando il file di dipendenze MLflow conda originale e aggiungendo il pacchettoazureml-core
. Non è possibile usare il fileconda.yml
direttamente dal modello.La definizione dell'ambiente viene inclusa nella definizione della distribuzione stessa come ambiente anonimo. Nella distribuzione sono visualizzate le righe seguenti:
environment: name: batch-mlflow-xgboost image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest conda_file: environment/conda.yaml
Configurare la distribuzione:
Per creare una nuova distribuzione nell'endpoint creato, creare una configurazione
YAML
come mostrato nel frammento di codice seguente. È possibile controllare lo schema YAML dell'endpoint batch completo per ottenere proprietà aggiuntive.deployment-custom/deployment.yml
$schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json endpoint_name: heart-classifier-batch name: classifier-xgboost-custom description: A heart condition classifier based on XGBoost type: model model: azureml:heart-classifier-mlflow@latest environment: name: batch-mlflow-xgboost image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest conda_file: environment/conda.yaml code_configuration: code: code scoring_script: batch_driver.py compute: azureml:batch-cluster resources: instance_count: 2 settings: max_concurrency_per_instance: 2 mini_batch_size: 2 output_action: append_row output_file_name: predictions.csv retry_settings: max_retries: 3 timeout: 300 error_threshold: -1 logging_level: info
Creare la distribuzione:
Eseguire il codice seguente:
az ml batch-deployment create --file deployment-custom/deployment.yml --endpoint-name $ENDPOINT_NAME
L'endpoint batch è ora pronto per l'uso.
Pulire le risorse
Dopo aver completato l'esercizio, eliminare le risorse non più necessarie.
Eseguire il codice seguente per eliminare l'endpoint batch e tutte le distribuzioni sottostanti:
az ml batch-endpoint delete --name $ENDPOINT_NAME --yes
Questo comando non elimina i processi di assegnazione dei punteggi batch.