Sintassi YAML principale dell'interfaccia della riga di comando (v2)

  • Articolo

SI APPLICA A: estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)

Ogni entità di Azure Machine Learning ha una rappresentazione YAML schematizzata. È possibile creare una nuova entità da un file di configurazione YAML con un'estensione .yml o .yaml .

Questo articolo offre una panoramica dei concetti di sintassi di base che verranno riscontrati durante la configurazione di questi file YAML.

Riferimento a un'entità di Azure Machine Learning

Azure Machine Learning fornisce una sintassi di riferimento (costituita da un formato abbreviato e longhand) per fare riferimento a un'entità di Azure Machine Learning esistente durante la configurazione di un file YAML. Ad esempio, è possibile fare riferimento a un ambiente registrato esistente nell'area di lavoro da usare come ambiente per un processo.

Riferimento a un asset di Azure Machine Learning

Sono disponibili due opzioni per fare riferimento a un asset di Azure Machine Learning (ambienti, modelli, dati e componenti):

  • Fare riferimento a una versione esplicita di un asset:

    • Sintassi abbreviata: azureml:<asset_name>:<asset_version>
    • Sintassi longhand, che include l'ID risorsa di Azure Resource Manager (ARM) dell'asset:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • Fare riferimento alla versione più recente di un asset:

    In alcuni scenari è possibile fare riferimento alla versione più recente di un asset senza dover cercare in modo esplicito e specificare la stringa di versione effettiva stessa. La versione più recente è definita come la versione più recente (nota anche come più recente) creata di un asset con un determinato nome.

    È possibile fare riferimento alla versione più recente usando la sintassi seguente: azureml:<asset_name>@latest. Azure Machine Learning risolverà il riferimento a una versione esplicita dell'asset nell'area di lavoro.

Fare riferimento a una risorsa di Azure Machine Learning

Per fare riferimento a una risorsa di Azure Machine Learning, ad esempio calcolo, è possibile usare una delle sintassi seguenti:

  • Sintassi abbreviata: azureml:<resource_name>
  • Sintassi longhand, che include l'ID risorsa ARM della risorsa:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

URI di riferimento ai dati di Azure Machine Learning

Azure Machine Learning offre un formato URI di riferimento ai dati pratico per puntare ai dati in un servizio di archiviazione di Azure. Può essere usato per gli scenari in cui è necessario specificare un percorso di archiviazione cloud nel file YAML, ad esempio la creazione di un modello di Azure Machine Learning da file nell'archiviazione o il puntamento ai dati da passare come input a un processo.

Per usare questo formato URI dati, il servizio di archiviazione a cui si vuole fare riferimento deve prima essere registrato come archivio dati nell'area di lavoro. Azure Machine Learning gestirà l'accesso ai dati usando le credenziali specificate durante la creazione dell'archivio dati.

Il formato è costituito da un archivio dati nell'area di lavoro corrente e dal percorso dell'archivio dati al file o alla cartella a cui si vuole puntare:

azureml://datastores/<datastore-name>/paths/<path-on-datastore>/

Ad esempio:

  • azureml://datastores/workspaceblobstore/paths/example-data/
  • azureml://datastores/workspaceblobstore/paths/example-data/iris.csv

Oltre all'URI di riferimento ai dati di Azure Machine Learning, Azure Machine Learning supporta anche i protocolli URI di archiviazione diretta seguenti: , , e adl, nonché URI pubblici http e https . abfsswasbshttps

Sintassi delle espressioni per la configurazione di processi e componenti di Azure Machine Learning

I file YAML del processo e del componente v2 consentono l'uso di espressioni da associare ai contesti per scenari diversi. Il caso d'uso essenziale usa un'espressione per un valore che potrebbe non essere noto al momento della creazione della configurazione, ma deve essere risolto in fase di esecuzione.

Usare la sintassi seguente per indicare ad Azure Machine Learning di valutare un'espressione anziché considerarla come stringa:

${{ <expression> }}

Di seguito sono descritti gli scenari supportati.

Parametrizzazione di command con i inputs contesti e outputs di un processo

È possibile specificare valori letterali, percorsi URI e asset di dati registrati di Azure Machine Learning come input per un processo. Può command quindi essere parametrizzato con riferimenti a tali input usando la ${{inputs.<input_name>}} sintassi . I riferimenti agli input letterali verranno risolti nel valore letterale in fase di esecuzione, mentre i riferimenti agli input di dati verranno risolti nel percorso di download o nel percorso di montaggio (a seconda dell'oggetto mode specificato).

Analogamente, è anche possibile fare riferimento agli output al processo in command. Per ogni output denominato specificato nel outputs dizionario, Azure Machine Learning genererà un percorso di output nell'archivio dati predefinito in cui è possibile scrivere file. Il percorso di output per ogni output denominato si basa sul percorso templatizzato seguente: <default-datastore>/azureml/<job-name>/<output_name>/. La parametrizzazione di command con la ${{outputs.<output_name>}} sintassi risolverà il riferimento al percorso generato dal sistema, in modo che lo script possa scrivere file in tale posizione dal processo.

Nell'esempio seguente per un file YAML del processo di comando, command viene parametrizzato con due input, un input letterale e un input di dati e un output. In fase di esecuzione, l'espressione ${{inputs.learning_rate}} verrà risolta in 0.01e l'espressione ${{inputs.iris}} verrà risolta nel percorso di download del iris.csv file. ${{outputs.model_dir}} verrà risolto nel percorso di montaggio del percorso di output generato dal sistema corrispondente all'output model_dir .

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: ./src
command: python train.py --lr ${{inputs.learning_rate}} --training-data ${{inputs.iris}} --model-dir ${{outputs.model_dir}}
environment: azureml:AzureML-Minimal@latest
compute: azureml:cpu-cluster
inputs:
  learning_rate: 0.01
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
outputs:
  model_dir:

Parametrizzazione di command con il search_space contesto di un processo sweep

Questa sintassi di espressione verrà usata anche quando si esegue l'ottimizzazione degli iperparametri tramite un processo sweep, poiché i valori effettivi degli iperparametri non sono noti durante il tempo di creazione del processo. Quando si esegue un processo sweep, Azure Machine Learning selezionerà i valori degli iperparametri per ogni versione di valutazione in base a search_space. Per accedere a tali valori nello script di training, è necessario passarli tramite gli argomenti della riga di comando dello script. A tale scopo, usare la ${{search_space.<hyperparameter>}} sintassi in trial.command.

Nell'esempio seguente per un file YAML del processo sweep, i ${{search_space.learning_rate}} riferimenti e ${{search_space.boosting}} in trial.command risolveranno i valori degli iperparametri effettivi selezionati per ogni versione di valutazione quando il processo di valutazione viene inviato per l'esecuzione.

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
sampling_algorithm:
  type: random
search_space:
  learning_rate:
    type: uniform
    min_value: 0.01
    max_value: 0.9
  boosting:
    type: choice
    values: ["gbdt", "dart"]
objective:
  goal: minimize
  primary_metric: test-multi_logloss
trial:
  code: ./src
  command: >-
    python train.py 
    --training-data ${{inputs.iris}}
    --lr ${{search_space.learning_rate}}
    --boosting ${{search_space.boosting}}
  environment: azureml:AzureML-Minimal@latest
inputs:
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
compute: azureml:cpu-cluster

Associazione di input e output tra i passaggi in un processo della pipeline

Le espressioni vengono usate anche per l'associazione di input e output tra i passaggi in un processo della pipeline. Ad esempio, è possibile associare l'input di un processo (processo B) in una pipeline all'output di un altro processo (processo A). Questo utilizzo segnalerà ad Azure Machine Learning il flusso di dipendenza del grafico della pipeline e il processo B verrà eseguito dopo il processo A, perché l'output del processo A è necessario come input per il processo B.

Per un file YAML del processo della pipeline, le inputs sezioni e outputs di ogni processo figlio vengono valutate all'interno del contesto padre (processo della pipeline di primo livello). L'oggetto command, invece, verrà risolto nel contesto corrente (il processo figlio).

Esistono due modi per associare input e output in un processo della pipeline:

Eseguire il binding agli input e agli output di primo livello del processo della pipeline

È possibile associare gli input o gli output di un processo figlio (un passaggio della pipeline) agli input/output del processo della pipeline padre di primo livello usando la sintassi seguente: ${{parent.inputs.<input_name>}} o ${{parent.outputs.<output_name>}}. Questo riferimento viene risolto nel parent contesto, quindi gli input/output di primo livello.

Nell'esempio seguente, l'input (raw_data) del primo prep passaggio è associato all'input della pipeline di primo livello tramite ${{parent.inputs.input_data}}. L'output (model_dir) del passaggio finale train è associato all'output del processo della pipeline di primo livello tramite ${{parent.outputs.trained_model}}.

Eseguire il binding agli input e agli output di un altro processo figlio (passaggio)

Per associare gli input/output di un passaggio agli input/output di un altro passaggio, usare la sintassi seguente: ${{parent.jobs.<step_name>.inputs.<input_name>}} o ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Anche in questo caso, questo riferimento viene risolto nel contesto padre, quindi l'espressione deve iniziare con parent.jobs.<step_name>.

Nell'esempio seguente l'input (training_data) del train passaggio viene associato all'output (clean_data) del prep passaggio tramite ${{parent.jobs.prep.outputs.clean_data}}. I dati preparati del prep passaggio verranno usati come dati di training per il train passaggio.

D'altra parte, i riferimenti di contesto all'interno delle command proprietà verranno risolti nel contesto corrente. Ad esempio, il ${{inputs.raw_data}} riferimento nel prep passaggio command verrà risolto negli input del contesto corrente, ovvero il prep processo figlio. La ricerca verrà eseguita in prep.inputs, quindi è necessario definire un input denominato raw_data in tale posizione.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
inputs:
  input_data: 
    type: uri_folder
    path: https://azuremlexamples.blob.core.windows.net/datasets/cifar10/
outputs:
  trained_model:
jobs:
  prep:
    type: command
    inputs:
      raw_data: ${{parent.inputs.input_data}}
    outputs:
      clean_data:
    code: src/prep
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python prep.py 
      --raw-data ${{inputs.raw_data}} 
      --prep-data ${{outputs.clean_data}}
    compute: azureml:cpu-cluster
  train:
    type: command
    inputs: 
      training_data: ${{parent.jobs.prep.outputs.clean_data}}
      num_epochs: 1000
    outputs:
      model_dir: ${{parent.outputs.trained_model}}
    code: src/train
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python train.py 
      --epochs ${{inputs.num_epochs}}
      --training-data ${{inputs.training_data}} 
      --model-output ${{outputs.model_dir}}
    compute: azureml:gpu-cluster

Parametrizzazione di command con i inputs contesti e outputs di un componente

Analogamente a per un processo, l'oggetto command command per un componente può anche essere parametrizzato con riferimenti ai inputs contesti e outputs . In questo caso, il riferimento è agli input e agli output del componente. Quando il componente viene eseguito in un processo, Azure Machine Learning risolverà tali riferimenti ai valori di input e output del runtime del processo specificati per i rispettivi input e output dei componenti. Di seguito è riportato un esempio di utilizzo della sintassi di contesto per una specifica YAML del componente di comando.

$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
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.5/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}}

Definire input facoltativi nella riga di comando

Quando l'input viene impostato come optional = true, è necessario usare $[[]] per adottare la riga di comando con gli input. Ad esempio, $[[--input1 ${{inputs.input1}}]. La riga di comando in fase di esecuzione può avere input diversi.

  • Se si usano solo i parametri e model_output obbligatoritraining_data, la riga di comando sarà simile alla seguente:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Se non viene specificato alcun valore in fase di esecuzione learning_rate e learning_rate_schedule userà il valore predefinito.

  • Se tutti gli input/output forniscono valori durante il runtime, la riga di comando sarà simile alla seguente:
python train.py --training_data some_input_path --max_epocs 10 --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Espressioni di percorso di output

Le espressioni seguenti possono essere usate nel percorso di output del processo:

Importante

Le espressioni seguenti vengono risolte sul lato server, non sul lato client. Per i processi pianificati in cui l'ora di creazione del processo e l'ora di invio del processo sono diverse, le espressioni vengono risolte quando viene inviato il processo. Poiché queste espressioni vengono risolte sul lato server, usano lo stato corrente dell'area di lavoro, non lo stato dell'area di lavoro al momento della creazione del processo pianificato. Ad esempio, se si modifica l'archivio dati predefinito dell'area di lavoro dopo aver creato un processo pianificato, l'espressione ${{default_datastore}} viene risolta nel nuovo archivio dati predefinito, non nell'archivio dati predefinito al momento della creazione del processo pianificato.

Expression Descrizione Scope
${{default_datastore}} Se l'archivio dati predefinito della pipeline è configurato, viene risolto come nome predefinito dell'archivio dati della pipeline; in caso contrario, viene risolto come nome predefinito dell'archivio dati dell'area di lavoro.

L'archivio dati predefinito della pipeline può essere controllato tramite pipeline_job.settings.default_datastore.		 Funziona per tutti i processi.

I processi della pipeline hanno un archivio dati predefinito della pipeline configurabile.
${{name}} Nome processo. Per le pipeline, si tratta del nome del processo del passaggio, non del nome del processo della pipeline. Funziona per tutti i processi
${{output_name}} Nome dell'output del processo Funziona per tutti i processi

Ad esempio, se azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} viene usato come percorso di output, in fase di esecuzione viene risolto come percorso di azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Passaggi successivi