Share via

Gestire input e output di componenti e pipeline

  • Articolo

Contenuto dell'articolo:

  • Panoramica degli input e degli output nel componente e nella pipeline
  • Come alzare di livello input/output dei componenti agli input/output della pipeline
  • Come definire gli input facoltativi
  • Come personalizzare il percorso degli output
  • Come scaricare gli output
  • Come registrare gli output come asset denominato

Panoramica degli input e degli output

Le pipeline di Azure Machine Learning supportano input e output sia a livello di componente che di pipeline.

A livello di componente, gli input e gli output definiscono l'interfaccia di un componente. L'output di un componente può essere usato come input per un altro componente nella stessa pipeline padre, consentendo il passaggio di dati o modelli tra i componenti. Questa interconnettività costituisce un grafico che illustra il flusso di dati all'interno della pipeline.

A livello di pipeline, gli input e gli output sono utili per l'invio di processi della pipeline con input o parametri di dati variabili che controllano la logica di training , ad esempio learning_rate. Sono particolarmente utili quando si richiama la pipeline tramite un endpoint REST. Questi input e output consentono di assegnare valori diversi all'input della pipeline o accedere all'output dei processi della pipeline tramite l'endpoint REST. Per altre informazioni, vedere Creazione di processi e dati di input per l'endpoint batch.

Tipi di input e output

I tipi seguenti sono supportati come output di un componente o di una pipeline.

L'uso dell'output di dati o di modello essenzialmente serializza gli output e li salva come file in un percorso di archiviazione. Nei passaggi successivi, questo percorso di archiviazione può essere montato, scaricato o caricato nel file system di destinazione di calcolo, consentendo al passaggio successivo di accedere ai file durante l'esecuzione del processo.

Questo processo richiede che il codice sorgente del componente serializzi l'oggetto di output desiderato, in genere archiviato in memoria, in file. Ad esempio, è possibile serializzare un dataframe pandas come file CSV. Nota: Azure Machine Learning non definisce metodi standardizzati per la serializzazione degli oggetti. Gli utenti hanno la flessibilità di scegliere il metodo preferito per serializzare gli oggetti in file. In seguito, nel componente downstream è possibile deserializzare e leggere questi file in modo indipendente. Ecco alcuni esempi per il riferimento:

  • Nell'esempio nyc_taxi_data_regression, il componente di preparazione ha un output di tipo uri_folder. Nel codice sorgente del componente, legge i file CSV dalla cartella di input, elabora i file e scrive i file CSV elaborati nella cartella di output.
  • Nell'esempio nyc_taxi_data_regression, il componente di training ha un output di tipo mlflow_model. Nel codice sorgente del componente salva il modello sottoposto a training usando il metodo mlflow.sklearn.save_model.

Oltre ai tipi di dati o modelli precedenti, la pipeline o gli input del componente possono essere anche i tipi primitivi seguenti.

  • string
  • number
  • integer
  • boolean

Nell'esempio nyc_taxi_data_regression, il componente di training ha un input number denominato test_split_ratio.

Nota

L'output dei tipi primitivi non è supportato.

Percorso e modalità per input/output dei dati

Per l'input/output dell'asset di dati, è necessario specificare un parametro path che punta alla posizione dei dati. Questa tabella mostra i diversi percorsi di dati supportati dalla pipeline di Azure Machine Learning e mostra anche esempi di parametri di percorso:

Ufficio Esempi Input Output
Un percorso nel computer locale ./home/username/data/my_data ✓
Percorso in un server HTTP pubblico https://raw.githubusercontent.com/pandas-dev/pandas/main/doc/data/titanic.csv ✓
Un percorso in Archiviazione di Azure wasbs://<container_name>@<account_name>.blob.core.windows.net/<path>
abfss://<file_system>@<account_name>.dfs.core.windows.net/<path>		 Non consigliato perché potrebbe essere necessaria una configurazione di identità aggiuntiva per leggere i dati.
Percorso in un archivio dati di Azure Machine Learning azureml://datastores/<data_store_name>/paths/<path> ✓ ✓
Percorso per un asset di dati azureml:<my_data>:<version> ✓ ✓

Nota

Per l'input/output nell'archiviazione, è consigliabile usare il percorso dell'archivio dati di Azure Machine Learning anziché il percorso diretto di Archiviazione di Azure. Il percorso dell'archivio dati è supportato in vari tipi di processo nella pipeline.

Per l'input/output dei dati, è possibile scegliere tra diverse modalità (download, montaggio o caricamento) per definire la modalità di accesso ai dati nella destinazione di calcolo. La tabella illustra le modalità possibili per combinazioni diverse di tipo/modalità/input/output.

Type Input/Output upload download ro_mount rw_mount direct eval_download eval_mount
uri_folder Input ✓ ✓ ✓
uri_file Input ✓ ✓ ✓
mltable Input ✓ ✓ ✓ ✓ ✓
uri_folder Output ✓ ✓
uri_file Output ✓ ✓
mltable Output ✓ ✓ ✓

Nota

Nella maggior parte dei casi, è consigliabile usare la modalità ro_mount o rw_mount. Per altre informazioni sulla modalità, vedere modalità di asset di dati.

Rappresentazione visiva in studio di Azure Machine Learning

Gli screenshot seguenti forniscono un esempio di come vengono visualizzati input e output in un processo della pipeline in studio di Azure Machine Learning. Questo particolare processo, denominato nyc-taxi-data-regression, è disponibile in azureml-example.

Nella pagina del processo della pipeline di studio, l'input/output del tipo di dati/modello di un componente viene visualizzato come un piccolo cerchio nel componente corrispondente, noto come porta di input/output. Queste porte rappresentano il flusso di dati in una pipeline.

L'output a livello di pipeline viene visualizzato come casella viola per facilitare l'identificazione.

Screenshot highlighting the pipeline input and output port.

Quando si passa il mouse su una porta di input/output, viene visualizzato il tipo.

Screenshot highlighting the port type when hovering the mouse.

Gli input del tipo primitivo non verranno visualizzati nel grafico. È disponibile nella scheda Impostazioni del pannello di panoramica del processo della pipeline (per gli input a livello di pipeline) o nel pannello dei componenti (per gli input a livello di componente). Lo screenshot seguente mostra la scheda Impostazioni di un processo della pipeline che può essere aperta selezionando il collegamento Panoramica processo.

Se si desidera controllare gli input per un componente, fare doppio clic sul componente per aprire il pannello dei componenti.

Screenshot highlighting the job overview setting panel.

Analogamente, quando si modifica una pipeline nella finestra di progettazione, è possibile trovare gli input e gli output della pipeline nel pannello Interfaccia pipeline e gli input e gli output dei componenti nel pannello del componente (trigger facendo doppio clic sul componente).

Screenshot highlighting the pipeline interface in designer.

Come alzare di livello di input/output dei componenti ai livelli della pipeline

La promozione dell'input/output di un componente a livello di pipeline consente di sovrascrivere l'input/output del componente durante l'invio di un processo della pipeline. È utile anche se si vuole attivare la pipeline usando l'endpoint REST.

Di seguito sono riportati esempi per promuovere gli input/output dei componenti agli input/output di livello di pipeline.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
display_name: 1b_e2e_registered_components
description: E2E dummy train-score-eval pipeline with registered components

inputs:
  pipeline_job_training_max_epocs: 20
  pipeline_job_training_learning_rate: 1.8
  pipeline_job_learning_rate_schedule: 'time-based'

outputs: 
  pipeline_job_trained_model:
    mode: upload
  pipeline_job_scored_data:
    mode: upload
  pipeline_job_evaluation_report:
    mode: upload

settings:
 default_compute: azureml:cpu-cluster

jobs:
  train_job:
    type: command
    component: azureml:my_train@latest
    inputs:
      training_data: 
        type: uri_folder 
        path: ./data      
      max_epocs: ${{parent.inputs.pipeline_job_training_max_epocs}}
      learning_rate: ${{parent.inputs.pipeline_job_training_learning_rate}}
      learning_rate_schedule: ${{parent.inputs.pipeline_job_learning_rate_schedule}}
    outputs:
      model_output: ${{parent.outputs.pipeline_job_trained_model}}
    services:
      my_vscode:
        type: vs_code
      my_jupyter_lab:
        type: jupyter_lab
      my_tensorboard:
        type: tensor_board
        log_dir: "outputs/tblogs"
    #  my_ssh:
    #    type: tensor_board
    #    ssh_public_keys: <paste the entire pub key content>
    #    nodes: all # Use the `nodes` property to pick which node you want to enable interactive services on. If `nodes` are not selected, by default, interactive applications are only enabled on the head node.

  score_job:
    type: command
    component: azureml:my_score@latest
    inputs:
      model_input: ${{parent.jobs.train_job.outputs.model_output}}
      test_data: 
        type: uri_folder 
        path: ./data
    outputs:
      score_output: ${{parent.outputs.pipeline_job_scored_data}}

  evaluate_job:
    type: command
    component: azureml:my_eval@latest
    inputs:
      scoring_result: ${{parent.jobs.score_job.outputs.score_output}}
    outputs:
      eval_output: ${{parent.outputs.pipeline_job_evaluation_report}}

L'esempio completo è disponibile in pipeline train-score-eval con componenti registrati. Questa pipeline promuove tre input e tre output a livello di pipeline. Prendiamo pipeline_job_training_max_epocs come esempio. Viene dichiarata nella sezione inputs a livello radice, ovvero l'input a livello di pipeline corrispondente. Nella sezione jobs -> train_job, l'input denominato max_epocs viene riferito come ${{parent.inputs.pipeline_job_training_max_epocs}}, che indica che il max_epocs dell’input dell' train_job fa riferimento all'input a livello di pipeline pipeline_job_training_max_epocs. Analogamente, è possibile alzare di livello l'output della pipeline usando lo stesso schema.

Studio

È possibile alzare di livello l'input di un componente all'input di livello pipeline nella pagina di creazione della finestra di progettazione. Passare al pannello delle impostazioni del componente facendo doppio clic sul componente -> trovare l'input che si vuole alzare di livello -> Selezionare i tre puntini a destra -> Selezionare Aggiungi all'input della pipeline.

Screenshot highlighting how to promote to pipeline input in designer.

Input facoltativo

Per impostazione predefinita, tutti gli input sono necessari e devono essere assegnati a un valore (o un valore predefinito) ogni volta che si invia un processo della pipeline. Tuttavia, potrebbero essere presenti istanze in cui sono necessari input facoltativi. In questi casi, è possibile non assegnare un valore all'input quando si invia un processo della pipeline.

L'input facoltativo può essere utile nei due scenari seguenti:

  • Se si dispone di un input facoltativo di tipo dati/modello e non si assegna un valore a esso durante l'invio del processo della pipeline, nella pipeline sarà presente un componente che non dispone di una dipendenza dei dati precedente. In altre parole, la porta di input non è collegata ad alcun nodo di componente o dati/modello. In questo modo il servizio pipeline richiama direttamente questo componente, anziché attendere che la dipendenza precedente sia pronta.

  • Lo screenshot seguente fornisce un esempio chiaro del secondo scenario. Se si imposta continue_on_step_failure = True per la pipeline e si dispone di un secondo nodo (node2) che usa l'output del primo nodo (node1) come input facoltativo, node2 verrà comunque eseguito anche se node1 ha esito negativo. Tuttavia, se node2 usa l'input richiesto da node1, non verrà eseguito se node1 ha esito negativo.

    Screenshot to show the orchestration logic of optional input and continue on failure.

Di seguito sono riportati alcuni esempi su come definire l'input facoltativo.

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
name: train_data_component_cli
display_name: train_data
description: A example train component
tags:
  author: azureml-sdk-team
version: 9
type: command
inputs:
  training_data: 
    type: uri_folder
  max_epocs:
    type: integer
    optional: true
  learning_rate: 
    type: number
    default: 0.01
    optional: true
  learning_rate_schedule: 
    type: string
    default: time-based
    optional: true
outputs:
  model_output:
    type: uri_folder
code: ./train_src
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
command: >-
  python train.py 
  --training_data ${{inputs.training_data}} 
  $[[--max_epocs ${{inputs.max_epocs}}]]
  $[[--learning_rate ${{inputs.learning_rate}}]]
  $[[--learning_rate_schedule ${{inputs.learning_rate_schedule}}]]
  --model_output ${{outputs.model_output}}

Quando l'input viene impostato come optional = true, è necessario usare $[[]] per adottare la riga di comando con gli input. Vedere la riga evidenziata nell'esempio precedente.

Nota

L'output facoltativo non è supportato.

Nel grafico della pipeline, gli input facoltativi del tipo dati/modello sono rappresentati da un cerchio puntinato. Gli input facoltativi dei tipi primitivi possono trovarsi nella scheda Impostazioni. A differenza degli input obbligatori, gli input facoltativi non hanno un asterisco accanto a essi, a indicare che non sono obbligatori.

Screenshot highlighting the optional input.

Come personalizzare il percorso dell’output

Per impostazione predefinita, l'output di un componente verrà archiviato in azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}}. {default_datastore} è il set di clienti dell'archivio dati predefinito per la pipeline. Se non è impostata, è l'archiviazione BLOB dell'area di lavoro. {name} è il nome del processo, che verrà risolto in fase di esecuzione del processo. {output_name} è il nome di output definito dal cliente nel componente YAML.

Ma è anche possibile personalizzare la posizione in cui archiviare l'output definendo il percorso di un output. Di seguito è riportato un esempio:

pipeline.yaml definisce una pipeline con tre output a livello di pipeline. Il file YAML completo è disponibile nella pipeline train-score-eval con esempio dei componenti registrati. È possibile usare il comando seguente per impostare il percorso di output personalizzato per l'output pipeline_job_trained_model.

# define the custom output path using datastore uri
# add relative path to your blob container after "azureml://datastores/<datastore_name>/paths"
output_path="azureml://datastores/{datastore_name}/paths/{relative_path_of_container}"  

# create job and define path using --outputs.<outputname>
az ml job create -f ./pipeline.yml --set outputs.pipeline_job_trained_model.path=$output_path

Come scaricare l'output

È possibile scaricare l'output o l'output della pipeline di un componente seguendo l'esempio seguente.

Scaricare l'output a livello di pipeline

# Download all the outputs of the job
az ml job download --all -n <JOB_NAME> -g <RESOURCE_GROUP_NAME> -w <WORKSPACE_NAME> --subscription <SUBSCRIPTION_ID>

# Download specific output
az ml job download --output-name <OUTPUT_PORT_NAME> -n <JOB_NAME> -g <RESOURCE_GROUP_NAME> -w <WORKSPACE_NAME> --subscription <SUBSCRIPTION_ID>

Scaricare l'output del processo figlio

Quando è necessario scaricare l'output di un processo figlio (un output del componente che non promuove al livello della pipeline), è necessario elencare prima di tutto l'entità processo figlio di un processo della pipeline e quindi usare codice simile per scaricare l'output.

# List all child jobs in the job and print job details in table format
az ml job list --parent-job-name <JOB_NAME> -g <RESOURCE_GROUP_NAME> -w <WORKSPACE_NAME> --subscription <SUBSCRIPTION_ID> -o table

# Select needed child job name to download output
az ml job download --all -n <JOB_NAME> -g <RESOURCE_GROUP_NAME> -w <WORKSPACE_NAME> --subscription <SUBSCRIPTION_ID>

Come registrare l'output come asset denominato

È possibile registrare l'output di un componente o di una pipeline come asset denominato assegnando name e version all'output. L'asset registrato può essere elencato nell'area di lavoro tramite interfaccia utente/interfaccia della riga di comando/SDK di studio e viene anche usato come riferimento nei processi futuri.

Registrare l'output della pipeline

display_name: register_pipeline_output
type: pipeline
jobs:
  node:
    type: command
    inputs:
      component_in_path:
        type: uri_file
        path: https://dprepdata.blob.core.windows.net/demo/Titanic.csv
    component: ../components/helloworld_component.yml
    outputs:
      component_out_path: ${{parent.outputs.component_out_path}}
outputs:
  component_out_path:
    type: mltable
    name: pipeline_output  # Define name and version to register pipeline output
    version: '1'
settings:
  default_compute: azureml:cpu-cluster

Registrare l'output di un processo figlio

display_name: register_node_output
type: pipeline
jobs:
  node:
    type: command
    component: ../components/helloworld_component.yml
    inputs:
      component_in_path:
        type: uri_file
        path: 'https://dprepdata.blob.core.windows.net/demo/Titanic.csv'
    outputs:
      component_out_path:
        type: uri_folder
        name: 'node_output'  # Define name and version to register a child job's output
        version: '1'
settings:
  default_compute: azureml:cpu-cluster

Passaggi successivi