Condividi tramite

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. È possibile inserire tali dati in posizioni diverse. Alcuni tipi di endpoint batch possono anche ricevere parametri letterali come input. Questo articolo illustra come specificare tali input.

Prerequisiti

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

  • Endpoint e distribuzione batch. Se non ne è già disponibile uno, vedere Distribuire modelli per l'assegnazione dei punteggi negli endpoint batch per creare una distribuzione.

  • Autorizzazioni per eseguire una distribuzione di endpoint batch. I ruoli di data scientist, collaboratore e proprietario di AzureML possono essere usati per eseguire una distribuzione. Per le definizioni di ruolo personalizzate, vedere Autorizzazione negli endpoint batch per conoscere le autorizzazioni specifiche necessarie.

  • Un token Microsoft Entra ID valido che rappresenta un'entità di sicurezza per richiamare l'endpoint. L'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. È 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 avviare processi di distribuzione batch, usando diversi tipi di credenziali, vedere Come eseguire processi usando tipi diversi di credenziali.

  • Il cluster di elaborazione 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 di archiviazione di Azure esterno come input di dati, assicurarsi di configurare i cluster di elaborazione per l'accesso ai dati. L'identità gestita del cluster di elaborazione 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. Viene usato l'endpoint predefinito, 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 sugli 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 all'endpoint le informazioni necessarie per eseguire il processo.

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

Gli endpoint batch supportano due tipi di input:

  • Input di dati, che sono puntatori a un percorso di archiviazione specifica o a un asset di Azure Machine Learning.
  • Input letterali, che sono valori letterali (ad esempio, numeri o stringhe) che si desidera passare al processo.

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 di modelli 1 Input dei 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 un percorso 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 Storage Gen1 e Azure Data Lake Storage Gen2.
  • Account di archiviazione di Azure, tra cui Azure Data Lake Storage Gen1, Azure Data Lake Storage 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). Tuttavia, questa operazione comporta 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 al percorso 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 negli archivi dati di Archiviazione Blob di Azure. 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 di Archiviazione BLOB di Azure perché 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 di 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. Innanzitutto, creare l'asset di dati. Questo asset di dati è costituito da una cartella con più file CSV da elaborare in parallelo usando 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 --input per specificare l'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 diversi input. In questi casi, inserire gli input in un file YAMLe 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 eseguirà 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. Questo esempio 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 completato questa operazione prima di procedere.

  3. Creare l'input o la richiesta:

    Inserire 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 --input per specificare l'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 diversi input. In questi casi, inserire gli input in un file YAMLe 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 invece uri_file come tipo.

Dati di input da Account di archiviazione di Azure

Gli endpoint batch di Azure Machine Learning possono leggere i dati dai percorsi 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 elaborazione 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 --input per specificare l'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 diversi input. In questi casi, inserire gli input in un file YAMLe 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 invece uri_file 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 file YAML 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 si specificano diversi 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. Ai fini della 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"

    Ai fini della 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

Contenuto correlato