Condividi tramite

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 desidera aggiungere la previsione ai dati originali se i dati sono tabulari.
  • È necessario scrivere le previsioni in un formato di file differente da quello supportato dalle distribuzioni batch.
  • 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 verrà illustrato come distribuire un modello per eseguire l'inferenza batch e scrivere gli output in formato parquet aggiungendo le previsioni 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. È un valore intero compreso tra 0 (assenza) e 1 (presenza).

È stato eseguito il training del modello usando un classificatore XGBBoost e tutta la pre-elaborazione necessaria è stata inserita in un pacchetto come pipeline scikit-learn, rendendo questo modello una pipeline end-to-end che va dai dati non elaborati alle previsioni.

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 Jupyter Notebook

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

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.

  • 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'mlestensione 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 comando az 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>

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.

code/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 funzione init() 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 funzione run restituisca un oggetto list o pandas.DataFrame.

Avviso

Tenere presente che tutti gli executor batch ha accesso in scrittura a questo percorso contemporaneamente. 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; pertanto, i nomi degli endpoint batch devono essere univoci in un'area di Azure. Ad esempio, può esistere solo un endpoint batch con il nome mybatchendpoint in westus2.

    In questo caso, immettere il nome dell'endpoint in una variabile per potervi fare riferimento facilmente in un secondo momento.

    ENDPOINT_NAME="heart-classifier-custom"

  2. Configurare l'endpoint batch

    Il seguente file YAML 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. Innanzitutto, creare 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 elaborazione aa con nome batch-cluster. Modificare il nome come pertinente.

    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 e sono accessibili dall'area di lavoro di Azure Machine Learning. In questo esempio li si caricano 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 di 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é si è scritto direttamente nella directory, un file per ogni file di input, è possibile aspettarsi di avere lo stesso numero di file. In questo particolare esempio, denominare i file di output come gli 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 il proprio strumento preferito. Nell'esempio seguente vengono caricate le previsioni usando il frame di dati 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 sono eliminati.

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

Contenuto correlato