Creare processi e inserire dati negli endpoint batch

  • Articolo

Gli endpoint batch possono essere usati per eseguire operazioni batch lunghe su grandi quantità di dati. Tali dati possono essere inseriti in posizioni diverse. Alcuni tipi di endpoint batch possono anche ricevere parametri letterali come input. In questa esercitazione verrà illustrato come specificare tali input e i diversi tipi o posizioni supportati.

Prima di richiamare un endpoint

Per richiamare correttamente un endpoint batch e creare processi, assicurarsi di disporre degli elementi seguenti:

  • Si dispone delle autorizzazioni per eseguire una distribuzione di endpoint batch. I ruoli azureML Scienziato dei dati, collaboratore e proprietario possono essere usati per eseguire una distribuzione. Per le definizioni di ruoli personalizzati, leggere Autorizzazione negli endpoint batch per conoscere le autorizzazioni specifiche necessarie.

  • Si dispone di un token ID Microsoft Entra valido che rappresenta un'entità di sicurezza per richiamare l'endpoint. Questa entità può essere un'entità utente o un'entità servizio. In ogni caso, una volta richiamato un endpoint, viene creato un processo di distribuzione batch con l'identità associata al token. A scopo di test, è possibile usare le proprie credenziali per la chiamata, come indicato di seguito.

    Usare l'interfaccia della riga di comando di Azure per accedere usando l'autenticazione interattiva o del codice del dispositivo:

    az login

    Per altre informazioni su come eseguire l'autenticazione con più tipi di credenziali, vedere Autorizzazione sugli endpoint batch.

  • Il cluster di calcolo in cui viene distribuito l'endpoint ha accesso per leggere i dati di input.

    Suggerimento

    Se si usa un archivio dati senza credenziali o un account Archiviazione di Azure esterno come input di dati, assicurarsi di configurare i cluster di calcolo per l'accesso ai dati. L'identità gestita del cluster di calcolo viene usata per il montaggio dell'account di archiviazione. L'identità del processo (invoker) viene comunque usata per leggere i dati sottostanti, consentendo di ottenere un controllo di accesso granulare.

Nozioni di base sulla creazione di processi

Per creare un processo da un endpoint batch, è necessario richiamarlo. La chiamata può essere eseguita usando l'interfaccia della riga di comando di Azure, Azure Machine Learning SDK per Python o una chiamata API REST. Negli esempi seguenti vengono illustrati i concetti di base della chiamata per un endpoint batch che riceve una singola cartella di dati di input per l'elaborazione. Vedere Informazioni su input e output per esempi con input e output diversi.

Usare l'operazione invoke negli endpoint batch:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Richiamare una distribuzione specifica

Gli endpoint batch possono ospitare più distribuzioni nello stesso endpoint. L'endpoint predefinito viene usato a meno che l'utente non specifichi diversamente. È possibile modificare la distribuzione usata nel modo seguente:

Usare l'argomento --deployment-name o -d per specificare il nome della distribuzione:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --deployment-name $DEPLOYMENT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Configurare le proprietà del processo

È possibile configurare alcune delle proprietà nel processo creato in fase di chiamata.

Nota

La configurazione delle proprietà del processo è disponibile solo negli endpoint batch con le distribuzioni dei componenti della pipeline entro il momento.

Configurare il nome dell'esperimento

Usare l'argomento --experiment-name per specificare il nome dell'esperimento:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --experiment-name "my-batch-job-experiment" \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Informazioni su input e output

Gli endpoint batch forniscono un'API durevole che i consumer possono usare per creare processi batch. La stessa interfaccia può essere usata per specificare gli input e gli output previsti dalla distribuzione. Usare gli input per passare le informazioni necessarie all'endpoint per eseguire il processo.

Diagramma che mostra come vengono usati input e output negli endpoint batch.

Gli endpoint batch supportano due tipi di input:

Il numero e il tipo di input e output dipendono dal tipo di distribuzione batch. Le distribuzioni di modelli richiedono sempre un input di dati e producono un output dei dati. Gli input letterali non sono supportati. Tuttavia, le distribuzioni dei componenti della pipeline forniscono un costrutto più generale per compilare gli endpoint e consentono di specificare un numero qualsiasi di input (dati e valori letterali) e output.

La tabella seguente riepiloga gli input e gli output per le distribuzioni batch:

Tipo di distribuzione Numero dell'input Tipi di input supportati Numero dell'output Tipi di output supportati
Distribuzione del modello 1 Input di dati 1 Output dei dati
Distribuzione di componenti della pipeline [0..N] Input di dati e input letterali [0..N] Output dei dati

Suggerimento

Gli input e gli output sono sempre denominati. Questi nomi fungono da chiavi per identificarli e passare il valore effettivo durante la chiamata. Per le distribuzioni di modelli, poiché richiedono sempre un input e un output, il nome viene ignorato durante la chiamata. È possibile assegnare il nome che descrive meglio il caso d'uso, ad esempio "sales_estimation".

Input dati

Gli input di dati fanno riferimento agli input che puntano a una posizione in cui vengono inseriti i dati. Poiché gli endpoint batch in genere usano grandi quantità di dati, non è possibile passare i dati di input come parte della richiesta di chiamata. Specificare invece il percorso in cui l'endpoint batch deve cercare i dati. I dati di input vengono montati e trasmessi nel calcolo di destinazione per migliorare le prestazioni.

Gli endpoint batch supportano la lettura dei file che si trovano nelle opzioni di archiviazione seguenti:

  • Asset di dati di Azure Machine Learning, tra cui Cartella (uri_folder) e File (uri_file).
  • Archivi dati di Azure Machine Learning, tra cui Archiviazione BLOB di Azure, Azure Data Lake Archiviazione Gen1 e Azure Data Lake Archiviazione Gen2.
  • Archiviazione di Azure Account, tra cui Azure Data Lake Archiviazione Gen1, Azure Data Lake Archiviazione Gen2 e Archiviazione BLOB di Azure.
  • Cartelle/file di dati locali (interfaccia della riga di comando di Azure Machine Learning o Azure Machine Learning SDK per Python). Questa operazione comporta tuttavia il caricamento dei dati locali nell'archivio dati predefinito di Azure Machine Learning dell'area di lavoro su cui si sta lavorando.

Importante

Avviso di deprecazione: i set di dati di tipo FileDataset (V1) sono deprecati e verranno ritirati in futuro. Gli endpoint batch esistenti basati su questa funzionalità continueranno a funzionare, ma gli endpoint batch creati con l'interfaccia della riga di comando v2 con disponibilità generale (2.4.0 e versioni successive) o l'API REST con disponibilità generale (2022-05-01 e versioni successive) non supporteranno il set di dati V1.

Input letterali

Gli input letterali fanno riferimento a input che possono essere rappresentati e risolti in fase di chiamata, ad esempio stringhe, numeri e valori booleani. In genere si usano input letterali per passare parametri all'endpoint come parte della distribuzione di un componente della pipeline. Gli endpoint batch supportano i tipi letterali seguenti:

  • string
  • boolean
  • float
  • integer

Gli input letterali sono supportati solo nelle distribuzioni dei componenti della pipeline. Per informazioni su come specificarli, vedere Creare processi con input letterali.

Output dei dati

Gli output dei dati fanno riferimento alla posizione in cui devono essere inseriti i risultati di un processo batch. Gli output vengono identificati in base al nome e Azure Machine Learning assegna automaticamente un percorso univoco a ogni output denominato. Tuttavia, se necessario, è possibile specificare un altro percorso.

Importante

Gli endpoint batch supportano solo la scrittura di output in Archiviazione BLOB di Azure archivi dati. Se è necessario scrivere in un account di archiviazione con spazi dei nomi gerarchici abilitati (noti anche come Azure Datalake Gen2 o ADLS Gen2), si noti che tale servizio di archiviazione può essere registrato come archivio dati Archiviazione BLOB di Azure poiché i servizi sono completamente compatibili. In questo modo, è possibile scrivere output dagli endpoint batch in ADLS Gen2.

Creare processi con input di dati

Gli esempi seguenti illustrano come creare processi, accettando input di dati da asset di dati, archivi dati e account Archiviazione di Azure.

Immettere dati da un asset di dati

Gli asset di dati di Azure Machine Learning (noti in precedenza come set di dati) sono supportati come input per i processi. Seguire questa procedura per eseguire un processo di endpoint batch usando i dati archiviati in un asset di dati registrato in Azure Machine Learning:

Avviso

Gli asset di dati di tipo Tabella (MLTable) non sono attualmente supportati.

  1. Creare prima di tutto l'asset di dati. Questo asset di dati è costituito da una cartella con più file CSV che verranno elaborati in parallelo, usando gli endpoint batch. È possibile ignorare questo passaggio se i dati sono già registrati come asset di dati.

    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: heart-classifier-mlflow/data

    Creare quindi l'asset di dati:

    az ml data create -f heart-dataset-unlabeled.yml

  2. Creare l'input o la richiesta:

    DATASET_ID=$(az ml data show -n heart-dataset-unlabeled --label latest | jq -r .id)

    Nota

    L'ID degli asset di dati sarà simile a /subscriptions/<subscription>/resourcegroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/data/<data-asset>/versions/<version>. È anche possibile usare azureml:/<datasset_name>@latest come modo per specificare l'input.

  3. Eseguire l'endpoint:

    Usare l'argomento --set per specificare l'input:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$DATASET_ID

    Per un endpoint che gestisce una distribuzione del modello, è possibile usare l'argomento per specificare l'input --input dei dati, poiché una distribuzione del modello richiede sempre un solo input di dati.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $DATASET_ID

    L'argomento --set tende a produrre comandi lunghi quando vengono specificati più input. In questi casi, inserire gli input in un YAML file e usare --file per specificare gli input necessari per la chiamata dell'endpoint.

    inputs.yml

    inputs:
  heart_dataset: azureml:/<datasset_name>@latest

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

Dati di input dagli archivi dati

È possibile fare riferimento direttamente ai dati degli archivi dati registrati di Azure Machine Learning tramite processi di distribuzione batch. In questo esempio si caricano prima alcuni dati nell'archivio dati predefinito nell'area di lavoro di Azure Machine Learning e quindi si esegue una distribuzione batch. Seguire questa procedura per eseguire un processo di endpoint batch usando i dati archiviati in un archivio dati.

  1. Accedere all'archivio dati predefinito nell'area di lavoro di Azure Machine Learning. Se i dati si trovano in un archivio diverso, è possibile usare tale archivio. Non è necessario usare l'archivio dati predefinito.

    DATASTORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')

    Nota

    L'ID degli archivi dati sarà simile a /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>.

    Suggerimento

    L'archivio dati BLOB predefinito in un'area di lavoro è denominato workspaceblobstore. È possibile ignorare questo passaggio se si conosce già l'ID risorsa dell'archivio dati predefinito nell'area di lavoro.

  2. È necessario caricare alcuni dati di esempio nell'archivio dati. In questo esempio si presuppone che siano già stati caricati i dati di esempio inclusi nel repository nella cartella sdk/python/endpoints/batch/deploy-models/heart-classifier-mlflow/data nella cartella heart-disease-uci-unlabeled nell'account di archiviazione BLOB. Assicurarsi di aver fatto questa operazione prima di procedere.

  3. Creare l'input o la richiesta:

    Posizionare il percorso del file nella variabile seguente:

    DATA_PATH="heart-disease-uci-unlabeled"
INPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"

    Nota

    Vedere in che modo il percorso paths viene aggiunto all'ID risorsa dell'archivio dati per indicare che ciò che segue è un percorso all'interno di esso.

    Suggerimento

    È anche possibile usare azureml://datastores/<data-store>/paths/<data-path> come modo per specificare l'input.

  4. Eseguire l'endpoint:

    Usare l'argomento --set per specificare l'input:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$INPUT_PATH

    Per un endpoint che gestisce una distribuzione del modello, è possibile usare l'argomento per specificare l'input --input dei dati, poiché una distribuzione del modello richiede sempre un solo input di dati.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_PATH --input-type uri_folder

    L'argomento --set tende a produrre comandi lunghi quando vengono specificati più input. In questi casi, inserire gli input in un YAML file e usare --file per specificare gli input necessari per la chiamata dell'endpoint.

    inputs.yml

    inputs:
  heart_dataset:
    type: uri_folder
    path: azureml://datastores/<data-store>/paths/<data-path>

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

    Se i dati sono un file, usare uri_file invece come tipo.

Dati di input da account Archiviazione di Azure

Gli endpoint batch di Azure Machine Learning possono leggere i dati dalle posizioni cloud negli Account di archiviazione di Azure, sia pubblici che privati. Usare la procedura seguente per eseguire un processo di endpoint batch usando i dati archiviati in un account di archiviazione:

Nota

Vedere la sezione Configurare i cluster di calcolo per l'accesso ai dati per altre informazioni sulla configurazione aggiuntiva necessaria per leggere correttamente i dati dagli accessi all'archiviazione.

  1. Creare l'input o la richiesta:

    INPUT_DATA = "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data"

    Se i dati sono un file:

    INPUT_DATA = "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data/heart.csv"

  2. Eseguire l'endpoint:

    Usare l'argomento --set per specificare l'input:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$INPUT_DATA

    Per un endpoint che gestisce una distribuzione del modello, è possibile usare l'argomento per specificare l'input --input dei dati, poiché una distribuzione del modello richiede sempre un solo input di dati.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_DATA --input-type uri_folder

    L'argomento --set tende a produrre comandi lunghi quando vengono specificati più input. In questi casi, inserire gli input in un YAML file e usare --file per specificare gli input necessari per la chiamata dell'endpoint.

    inputs.yml

    inputs:
  heart_dataset:
    type: uri_folder
    path: https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

    Se i dati sono un file, usare uri_file invece come tipo.

Creare processi con input letterali

Le distribuzioni dei componenti della pipeline possono accettare input letterali. Nell'esempio seguente viene illustrato come specificare un input denominato score_mode, di tipo string, con un valore :append

Inserire gli input in un YAML file e usare --file per specificare gli input necessari per la chiamata all'endpoint.

inputs.yml

inputs:
  score_mode:
    type: string
    default: append

az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

È anche possibile usare l'argomento --set per specificare il valore. Tuttavia, tende a produrre comandi lunghi quando vengono specificati più input:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.score_mode.type="string" inputs.score_mode.default="append"

Creare processi con output di dati

Nell'esempio seguente viene illustrato come modificare il percorso in cui viene inserito un output denominato score . Per completezza, questi esempi configurano anche un input denominato heart_dataset.

  1. Usare l'archivio dati predefinito nell'area di lavoro di Azure Machine Learning per salvare gli output. È possibile usare qualsiasi altro archivio dati nell'area di lavoro, purché si tratti di un account di archiviazione BLOB.

    DATASTORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')

    Nota

    L'ID degli archivi dati sarà simile a /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>.

  2. Creare un output dei dati:

    DATA_PATH="batch-jobs/my-unique-path"
OUTPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"

    Per completezza, creare anche un input di dati:

    INPUT_PATH="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data"

    Nota

    Vedere in che modo il percorso paths viene aggiunto all'ID risorsa dell'archivio dati per indicare che ciò che segue è un percorso all'interno di esso.

  3. Eseguire la distribuzione:

    Usare l'argomento --set per specificare l'input:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.path=$INPUT_PATH \
    --set outputs.score.path=$OUTPUT_PATH

Passaggi successivi