Personalizzare gli output nelle distribuzioni batch

  • Articolo

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

Questa guida illustra come creare distribuzioni che generano output e file personalizzati. In alcuni casi è necessario un maggiore controllo su ciò che viene scritto come output dai processi di inferenza batch. Questi casi includono le situazioni seguenti:

  • È necessario controllare la modalità di scrittura delle stime nell'output. Ad esempio, si vuole aggiungere la stima ai dati originali se i dati sono tabulari.
  • È necessario scrivere le stime in un formato di file diverso da quello supportato per le distribuzioni batch.You need to write your predictions in a different file format than one supported out-of-the-box by batch deployments.
  • Il modello è un modello generativo che non può scrivere l'output in un formato tabulare. Ad esempio, i modelli che producono immagini come output.
  • Il modello produce più file tabulari anziché uno singolo. Ad esempio, i modelli che eseguono la previsione considerando più scenari.

Le distribuzioni batch consentono di assumere il controllo dell'output dei processi consentendo di scrivere direttamente nell'output del processo di distribuzione batch. In questa esercitazione si apprenderà come distribuire un modello per eseguire l'inferenza batch e scrivere gli output in formato parquet aggiungendo le stime ai dati di input originali.

Informazioni sull'esempio

Questo esempio illustra come distribuire un modello per eseguire l'inferenza batch e personalizzare la modalità di scrittura delle previsioni nell'output. Il modello si basa sul set di dati UCI Heart Disease. Il database contiene 76 attributi, ma in questo esempio viene utilizzato un subset di 14 attributi. Il modello cerca di prevedere la presenza di una malattia cardiaca in un paziente. Valore intero compreso tra 0 (nessuna presenza) e 1 (presenza).

Il training del modello è stato eseguito usando un XGBBoost classificatore e tutto il pre-elaborazione richiesto è stato inserito in un pacchetto come scikit-learn pipeline, rendendo questo 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 in:

cd endpoints/batch/deploy-models/custom-outputs-parquet

Seguire la procedura in un notebook di Jupyter

È disponibile un notebook di Jupyter che è possibile usare per seguire questo esempio. Nel repository clonato aprire il notebook denominato custom-output-batch.ipynb.

Prerequisiti

Prima di seguire la procedura descritta in questo articolo, assicurarsi di disporre dei prerequisiti seguenti:

  • 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. Se non è disponibile, usare la procedura descritta nell'articolo Gestire le aree di lavoro di Azure Machine Learning per crearne una.

  • Assicurarsi di disporre delle autorizzazioni seguenti nell'area di lavoro:

    • Creare o gestire endpoint e distribuzioni batch: usare un ruolo Proprietario, Collaboratore o Personalizzato che consenta Microsoft.MachineLearningServices/workspaces/batchEndpoints/*.

    • Creare distribuzioni arm nel gruppo di risorse dell'area di lavoro: usare un ruolo Proprietario, Collaboratore o Personalizzato che consenta Microsoft.Resources/deployments/write nel gruppo di risorse in cui viene distribuita l'area di lavoro.

  • Per usare Azure Machine Learning, è necessario installare il software seguente:

    L'Interfaccia della riga di comando di Azure e l'mlestensione per Azure Machine Learning.

    az extension add -n ml

    Nota

    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 az extension update --name ml per ottenere l'ultima versione.

Connettersi all'area di lavoro

L'area di lavoro è la risorsa di primo livello per Azure Machine Learning, che fornisce una posizione centralizzata da cui gestire tutti gli artefatti creati quando si usa Azure Machine Learning. In questa sezione ci si connetterà all'area di lavoro in cui verranno eseguite le attività di distribuzione.

Passare 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>

Creare una distribuzione batch con un output personalizzato

In questo esempio si crea una distribuzione in grado di scrivere direttamente nella cartella di output del processo di distribuzione batch. La distribuzione usa questa funzionalità per scrivere file Parquet personalizzati.

Registrare il modello

È possibile distribuire modelli registrati solo usando un endpoint batch. In questo caso è già disponibile una copia locale del modello nel repository, quindi è sufficiente pubblicare il modello nel Registro di sistema nell'area di lavoro. È possibile ignorare questo passaggio se il modello che si sta tentando di distribuire è già registrato.

MODEL_NAME='heart-classifier-sklpipe'
az ml model create --name $MODEL_NAME --type "custom_model" --path "model"

Creare uno script di punteggio

È necessario creare uno script di assegnazione dei punteggi in grado di leggere i dati di input forniti dalla distribuzione batch e restituire i punteggi del modello. Si scriverà anche direttamente nella cartella di output del processo. In sintesi, lo script di assegnazione dei punteggi proposto esegue le operazioni seguenti:

  1. Legge i dati di input come file CSV.
  2. Esegue la funzione predict del modello MLflow sui dati di input.
  3. Aggiunge le previsioni a un oggetto pandas.DataFrame insieme ai dati di input.
  4. Scrive i dati in un file denominato come file di input, ma in formato parquet.

codice/batch_driver.py

import os
import pickle
import glob
import pandas as pd
from pathlib import Path
from typing import List


def init():
    global model
    global output_path

    # 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:
    output_path = os.environ["AZUREML_BI_OUTPUT_PATH"]
    model_path = os.environ["AZUREML_MODEL_DIR"]
    model_file = glob.glob(f"{model_path}/*/*.pkl")[-1]

    with open(model_file, "rb") as file:
        model = pickle.load(file)


def run(mini_batch: List[str]):
    for file_path in mini_batch:
        data = pd.read_csv(file_path)
        pred = model.predict(data)

        data["prediction"] = pred

        output_file_name = Path(file_path).stem
        output_file_path = os.path.join(output_path, output_file_name + ".parquet")
        data.to_parquet(output_file_path)

    return mini_batch

Note:

  • Si noti che la variabile di ambiente AZUREML_BI_OUTPUT_PATH viene usata per ottenere l'accesso al percorso di output del processo di distribuzione.
  • La init() funzione popola una variabile globale denominata output_path che può essere usata in un secondo momento per sapere dove scrivere.
  • Il metodo run restituisce un elenco dei file elaborati. È necessario che la run funzione restituisca un list oggetto o pandas.DataFrame .

Avviso

Tenere presente che tutti gli executor batch hanno accesso in scrittura contemporaneamente a questo percorso. Ciò significa che è necessario tenere conto della concorrenza. In questo caso, assicurarsi che ogni executor scriva il proprio file usando il nome del file di input come nome della cartella di output.

Creare l'endpoint

A questo punto si crea un endpoint batch denominato heart-classifier-batch in cui viene distribuito il modello.

  1. Decidere il nome dell'endpoint. Il nome dell'endpoint viene visualizzato nell'URI associato all'endpoint, quindi i nomi degli endpoint batch devono essere univoci all'interno di un'area di Azure. Ad esempio, può essere presente un solo endpoint batch con il nome mybatchendpoint in westus2.

    In questo caso, inserire il nome dell'endpoint in una variabile in modo da poterlo fare facilmente riferimento in un secondo momento.

    ENDPOINT_NAME="heart-classifier-custom"

  2. Configurare l'endpoint batch.

    Il file YAML seguente definisce un endpoint batch:

    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

  3. Creare l'endpoint:

    az ml batch-endpoint create -n $ENDPOINT_NAME -f endpoint.yml

Creare la distribuzione

Seguire i passaggi successivi per creare una distribuzione usando lo script di assegnazione dei punteggi precedente:

  1. Creare prima di tutto un ambiente in cui è possibile eseguire lo script di assegnazione dei punteggi:

    Non è necessario alcun passaggio aggiuntivo per l'interfaccia della riga di comando di Azure Machine Learning. La definizione dell'ambiente è inclusa nel file di distribuzione.

    environment:
  name: batch-mlflow-xgboost
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml

  2. Creare la distribuzione. Si noti che output_action è ora impostato su SUMMARY_ONLY.

    Nota

    In questo esempio si presuppone che sia presente un cluster di calcolo con nome batch-cluster. Modificare il nome di conseguenza.

    Per creare una nuova distribuzione nell'endpoint creato, creare una configurazione YAML simile alla seguente. È possibile controllare lo schema YAML dell'endpoint batch completo per ottenere proprietà aggiuntive.

    $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 and Scikit-Learn pipelines that append predictions on parquet files.
type: model
model: azureml:heart-classifier-sklpipe@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: summary_only
  retry_settings:
    max_retries: 3
    timeout: 300
  error_threshold: -1
  logging_level: info

    Creare quindi la distribuzione con il comando seguente:

    az ml batch-deployment create --file deployment.yml --endpoint-name $ENDPOINT_NAME --set-default

  3. A questo punto, l'endpoint batch è pronto per essere usato.

Testare la distribuzione

Per testare l'endpoint, usare un esempio di dati senza etichetta che si trovano in questo repository, che possono essere usati con il modello. Gli endpoint batch possono elaborare solo i dati che si trovano nel cloud ed è accessibile dall'area di lavoro di Azure Machine Learning. In questo esempio viene caricato in un archivio dati di Azure Machine Learning. Si creerà un asset di dati che può essere usato per richiamare l'endpoint per l'assegnazione dei punteggi. Si noti tuttavia che gli endpoint batch accettano dati che possono essere inseriti in più tipi di posizioni.

  1. Richiamare l'endpoint con i dati da un account di archiviazione:

    JOB_NAME = $(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data --query name -o tsv)

    Nota

    L'utilità jq potrebbe non essere installata in ogni installazione. È possibile ottenere istruzioni su GitHub.

  2. Un processo batch viene avviato non appena viene restituito il comando. È possibile monitorare lo stato del processo fino al termine dell'operazione:

    az ml job show -n $JOB_NAME --web

Analizzare gli output

Il processo genera un output denominato score in cui vengono inseriti tutti i file generati. Poiché la directory è stata scritta direttamente, un file per ogni file di input, è quindi possibile prevedere lo stesso numero di file. In questo esempio particolare assegnare un nome ai file di output uguali agli input, ma hanno un'estensione parquet.

Nota

Si noti che un file predictions.csv è incluso anche nella cartella di output. Questo file contiene il riepilogo dei file elaborati.

È 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 ./

Una volta scaricato il file, è possibile aprirlo usando lo strumento preferito. Nell'esempio seguente vengono caricate le previsioni usando il dataframe Pandas.

import pandas as pd
import glob

output_files = glob.glob("named-outputs/score/*.parquet")
score = pd.concat((pd.read_parquet(f) for f in output_files))
score

L'output sarà simile al seguente:

età sex ... thal stima
63 1 ... fixed 0
67 1 ... normale 1
67 1 ... reversible 0
37 1 ... normale 0

Pulire le risorse

Eseguire il codice seguente per eliminare l'endpoint batch e tutte le distribuzioni sottostanti. I processi di assegnazione dei punteggi batch non vengono eliminati.

az ml batch-endpoint delete --name $ENDPOINT_NAME --yes

Contenuto correlato