CLI (v2) YAML-Kernsyntax

GILT FÜR Azure CLI-ML-Erweiterung v2 (aktuell)

Jede Azure Machine Learning-Entität verfügt über eine schematisierte YAML-Darstellung. Sie können eine neue Entität aus einer YAML-Konfigurationsdatei mit der Erweiterung .yml oder .yaml erstellen.

Dieser Artikel bietet eine Übersicht über die grundlegenden Syntaxkonzepte, die beim Konfigurieren dieser YAML-Dateien auftreten werden.

Verweisen auf eine Azure Machine Learning-Entität

Azure Machine Learning stellt eine Referenzsyntax (bestehend aus einem kompakten und einem ausgeschriebenen Format) zum Verweisen auf eine vorhandene Azure Machine Learning-Entität beim Konfigurieren einer YAML-Datei zur Verfügung. Sie können beispielsweise auf eine vorhandene registrierte Umgebung in Ihrem Arbeitsbereich verweisen, um sie in der Umgebung für einen Auftrag zu verwenden.

Verweisen auf eine Azure Machine Learning-Ressource

Es gibt zwei Optionen zum Verweisen auf ein Azure Machine Learning-Objekt (Umgebungen, Modelle, Daten und Komponenten):

• Verweisen Sie auf eine explizite Version eines Objekts:

  • Kurze Syntax: azureml:<asset_name>:<asset_version>
  • Lange Syntax, die die ARM-Ressourcen-ID (Azure Resource Manager) des Objekts enthält:

  azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>
  

• Verweisen Sie auf die neueste Version eines Objekts:

  In einigen Szenarien möchten Sie möglicherweise auf die neueste Version eines Objekts verweisen, ohne die tatsächliche Versionszeichenfolge selbst explizit suchen und angeben zu müssen. Die neueste Version wird als die neueste (auch als aktuellste) erstellte Version eines Objekts unter einem bestimmten Namen definiert.

  Sie können mit der folgenden Syntax auf die neueste Version verweisen: azureml:<asset_name>@latest. Azure Machine Learning löst den Verweis auf eine explizite Objektversion im Arbeitsbereich auf.

Verweisen auf eine Azure Machine Learning-Ressource

Um auf eine Azure Machine Learning-Ressource (so wie Compute) zu verweisen, können Sie eine der folgenden Syntaxen verwenden:

• Kurze Syntax: azureml:<resource_name>
• Lange Syntax, die die ARM-Ressourcen-ID der Ressource enthält:

azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

Azure Machine Learning-Datenverweis-URI

Azure Machine Learning bietet ein komfortables URI-Format für Datenverweise, um auf Daten in einem Azure-Speicherdienst zu verweisen. Dies kann für Szenarien verwendet werden, in denen Sie einen Cloudspeicherort in Ihrer YAML-Datei angeben müssen, z. B. beim Erstellen eines Azure Machine Learning-Modells aus Dateien im Speicher oder beim Verweisen auf Daten, die als Eingabe an einen Auftrag übergeben werden sollen.

Um dieses Daten-URI-Format zu verwenden, muss der Speicherdienst, auf den Sie verweisen möchten, zunächst als Datenspeicher in Ihrem Arbeitsbereich registriert werden. Azure Machine Learning verarbeitet den Datenzugriff mit den Anmeldeinformationen, die Sie bei der Erstellung des Datenspeichers angegeben haben.

Das Format besteht aus einem Datenspeicher im aktuellen Arbeitsbereich und dem Pfad des Datenspeichers zu der Datei oder dem Ordner, auf die Sie verweisen möchten:

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

Zum Beispiel:

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

Zusätzlich zum Azure Machine Learning-Datenverweis-URI unterstützt Azure Machine Learning auch die folgenden direkten Speicher-URI-Protokolle: https, wasbs, abfss und adl sowie öffentliche http- und https-URIs.

Ausdruckssyntax zum Konfigurieren von Azure Machine Learning-Aufträgen und Komponenten

YAML-Dateien für einen v2-Auftrag und für v2-Komponenten ermöglichen die Verwendung von Ausdrücken zum Binden an Kontexte für verschiedene Szenarien. Der grundlegende Anwendungsfall verwendet einen Ausdruck für einen Wert, der zum Zeitpunkt der Dokumenterstellung der Konfiguration möglicherweise noch nicht bekannt ist, aber zur Runtime aufgelöst werden muss.

Verwenden Sie die folgende Syntax, um Azure Machine Learning anzuweisen, einen Ausdruck zu bewerten, anstatt ihn als Zeichenfolge zu behandeln:

${{ <expression> }}

Die unterstützten Szenarien werden unten behandelt.

Parametrisiert command mit den Kontexten inputs und outputs eines Auftrags

Sie können Literalwerte, URI-Pfade und registrierte Azure Machine Learning-Datenressourcen als Eingaben für einen Auftrag angeben. command kann dann mit Verweisen auf diese Eingabe(n) parametrisiert werden, indem die Syntax ${{inputs.<input_name>}} verwendet wird. Verweise auf Literaleingaben werden zur Runtime in den Literalwert aufgelöst, während Verweise auf Daten-URI oder auf Azure ML-Dataset-Eingaben in den Downloadpfad oder den Einbindungspfad aufgelöst werden (je nach festgelegtem mode).

Ebenso können Ausgaben an den Auftrag auch an command verwiesen werden. Für jede im outputs-Wörterbuch angegebene benannte Ausgabe generiert Azure Machine Learning automatisch einen Ausgabespeicherort im Standarddatenspeicher, in den Sie Dateien schreiben können. Der Ausgabespeicherort für jede benannte Ausgabe basiert auf dem folgenden vorgegebenen Pfad: <default-datastore>/azureml/<job-name>/<output_name>/. Durch Parametrisieren von command mit der ${{outputs.<output_name>}}-Syntax wird dieser Verweis auf den automatisch generierten Pfad aufgelöst, sodass Ihr Skript Dateien an diesen Speicherort des Auftrags schreiben kann.

Im folgenden Beispiel für eine YAML-Datei eines Befehlsauftrags wird command mit zwei Eingaben, einer Literaleingabe sowie einer URI-Eingabe und einer Ausgabe parametrisiert. Zur Runtime wird der Ausdruck ${{inputs.learning_rate}} in 0.01 aufgelöst und der Ausdruck ${{inputs.iris}} in den Downloadpfad iris.csv aufgelöst. ${{outputs.model_dir}} wird in den Bereitstellungspfad des vom System generierten Ausgabespeicherorts aufgelöst, der der model_dir-Ausgabe entspricht.

$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:

Parametrisiert command mit dem Kontext search_space eines Löschauftrags

Sie verwenden diese Ausdruckssyntax auch, wenn Sie die Hyperparameteroptimierung durch einen Löschauftrag ausführen, da die tatsächlichen Hyperparameterwerte zur Zeit der Dokumenterstellung des Auftrags nicht bekannt sind. Wenn Sie einen Löschauftrag ausführen, wählt Azure Machine Learning Hyperparameterwerte für jede Testversion basierend auf search_space aus. Um auf diese Werte in Ihrem Trainingsskript zugreifen zu können, müssen Sie diese über die Befehlszeilenargumente des Skripts übergeben. Verwenden Sie dazu die Syntax ${{search_space.<hyperparameter>}} in trial.command.

Im folgenden Beispiel für eine YAML-Datei für einen Löschauftrag werden die Verweise ${{search_space.learning_rate}} und ${{search_space.boosting}} in trial.command in die tatsächlichen Hyperparameterwerte aufgelöst, die für jede Testversion beim Übermittelt des Testauftrags zur Ausführung ausgewählt wurden.

$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

Binden von Eingaben und Ausgaben zwischen den Schritten in einem Pipelineauftrag

Ausdrücke werden auch zum Binden von Eingaben und Ausgaben zwischen Schritten in einem Pipelineauftrag verwendet. Beispielsweise können Sie die Eingabe eines Auftrags (Auftrag B) in einer Pipeline an die Ausgabe eines anderen Auftrags (Auftrag A) binden. Diese Verwendung signalisiert Azure Machine Learning den Abhängigkeitsflow des Pipeline-Diagramms und Auftrag B wird nach Auftrag A ausgeführt, da die Ausgabe von Auftrag A als Eingabe für Auftrag B erforderlich ist.

Für eine YAML-Datei eines Pipelineauftrags werden die Abschnitte inputs und outputs jedes untergeordneten Auftrags im übergeordneten Kontext (dem Pipelineauftrag der obersten Ebene) ausgewertet. Andererseits wird command in den aktuellen Kontext (den untergeordneten Auftrag) aufgelöst.

Es gibt zwei Möglichkeiten, Eingaben und Ausgaben in einem Pipelineauftrag zu binden:

Binden an die Eingaben und Ausgaben der obersten Ebene des Pipeline-Auftrags

Sie können die Ein- oder Ausgaben eines untergeordneten Auftrags (ein Pipeline-Schritt) mithilfe der folgenden Syntax an die Ein-/Ausgaben des übergeordneten Pipeline-Auftrags der obersten Ebene binden: ${{parent.inputs.<input_name>}} oder ${{parent.outputs.<output_name>}}. Dieser Verweis wird in den übergeordneten parent-Kontext aufgelöst, daher die Eingaben/Ausgaben der obersten Ebene.

Im folgenden Beispiel wird die Ausgabe (raw_data) des ersten prep-Schritts über ${{parent.inputs.input_data}} an die Ausgabe des Pipeline-Auftrags der obersten Ebene gebunden. Im folgenden Beispiel wird die Ausgabe (model_dir) des letzten train-Schritts über ${{parent.outputs.trained_model}} an die Ausgabe des Pipeline-Auftrags der obersten Ebene gebunden.

Binden an die Ein- und Ausgaben eines anderen untergeordneten Auftrags (Schritt)

Verwenden Sie die folgende Syntax, um die Eingaben/Ausgaben eines Schritts an die Eingaben/Ausgaben eines anderen Schritts zu binden: ${{parent.jobs.<step_name>.inputs.<input_name>}} oder ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Auch hier wird dieser Verweis in den übergeordneten Kontext aufgelöst, sodass der Kontext mit parent.jobs.<step_name> beginnt.

Im folgenden Beispiel wird die Eingabe (training_data) des Schritts train über ${{parent.jobs.prep.outputs.clean_data}} an die Ausgabe (clean_data) des Schritts prep gebunden. Die vorbereiteten Daten aus dem Schritt prep werden als Trainingsdaten für den Schritt train verwendet.

Andererseits werden die Kontextverweise innerhalb der Eigenschaften command in den aktuellen Kontext aufgelöst. Beispielsweise wird der Verweis ${{inputs.raw_data}} in prep des Schritts command in die Eingaben des aktuellen Kontexts aufgelöst, bei dem es sich um den untergeordneten Auftrag prep handelt. Der Lookup wird auf prep.inputs durchgeführt, sodass eine Eingabe mit dem Namen raw_data dort definiert werden muss.

$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

Parametrisiert command mit den Kontexten inputs und outputs einer Komponente

Ähnlich wie bei command eines Auftrags kann command für eine Komponente auch mit Verweisen auf die Kontexte inputs und outputs parametrisiert werden. In diesem Fall bezieht sich der Verweis auf die Ein- und Ausgaben dieser Komponente. Wenn die Komponente in einem Auftrag ausgeführt wird, löst Azure Machine Learning diese Verweise auf die Eingabe- und Ausgabewerte der Runtime des Auftrags auf, die für die jeweiligen Komponenteneingaben und -ausgaben angegeben sind. Im Folgenden finden Sie ein Beispiel für die Verwendung der Kontextsyntax für eine YAML-Spezifikation der Befehlskomponente.

$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}}

Definieren optionaler Eingaben in der Befehlszeile

Wenn die Eingabe als optional = true festgelegt ist, müssen Sie $[[]] verwenden, um die Befehlszeile mit Eingaben zu nutzen. Beispiel: $[[--input1 ${{inputs.input1}}]. Die Befehlszeile zur Laufzeit verfügt möglicherweise über unterschiedliche Eingaben.

• Wenn Sie nur die erforderlichen Parameter training_data und model_output verwenden, sieht die Befehlszeile wie folgt aus:

python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Wird zur Laufzeit kein Wert angegeben, nutzen learning_rate und learning_rate_schedule den Standardwert.

• Wenn alle Eingaben/Ausgaben Werte während der Laufzeit bereitstellen, sieht die Befehlszeile wie folgt aus:

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

Ausgabepfadausdrücke

Die folgenden Ausdrücke können im Ausgabepfad Ihres Auftrags verwendet werden:

Wichtig

Die folgenden Ausdrücke werden auf der Serverseite aufgelöst, nicht auf der Clientseite. Bei geplanten Aufträgen, bei denen sich der Erstellungszeitpunkt und der Übermittlungszeitpunkt des Auftrags unterscheiden, werden die Ausdrücke bei Übermittlung des Auftrags aufgelöst. Da diese Ausdrücke serverseitig aufgelöst werden, verwenden sie den aktuellen Zustand des Arbeitsbereichs und nicht den Zustand des Arbeitsbereichs zum Zeitpunkt der Erstellung des geplanten Auftrags. Wenn Sie beispielsweise den Standarddatenspeicher des Arbeitsbereichs ändern, nachdem Sie einen geplanten Auftrag erstellt haben, wird der Ausdruck ${{default_datastore}} in den neuen Standarddatenspeicher aufgelöst, nicht in den Standarddatenspeicher zum Zeitpunkt der Auftragsplanung.

Ausdruck	Beschreibung	Bereich
${{default_datastore}}	Wenn der Standarddatenspeicher der Pipeline konfiguriert ist, wird er als Standarddatenspeichername der Pipeline aufgelöst; andernfalls wird er als Standarddatenspeichername des Arbeitsbereichs aufgelöst. Der Standarddatenspeicher der Pipeline kann mit pipeline_job.settings.default_datastore gesteuert werden.	Funktioniert für alle Aufträge. Pipelineaufträge verfügen über einen konfigurierbaren Standarddatenspeicher der Pipeline.
${{name}}	Der Auftragsname. Bei Pipelines ist dies der Name des Schrittauftrags, nicht der Name des Pipelineauftrags.	Funktioniert für alle Aufträge
${{output_name}}	Der Name der Auftragsausgabe	Funktioniert für alle Aufträge

Wenn beispielsweise azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} als Ausgabepfad verwendet wird, wird er zur Laufzeit in den Pfad azureml://datastores/workspaceblobstore/paths/<job-name>/model_path aufgelöst.

Nächste Schritte

• Installieren und Verwenden der CLI (V2)
• Trainieren von Modellen mit der CLI (v2)
• YAML-Schemas für CLI (v2)