Share via

YAML-syntaxis van CLI (v2) core

  • Artikel

VAN TOEPASSING OP:Azure CLI ml-extensie v2 (huidige)

Elke Azure Machine Learning-entiteit heeft een geschematiseerde YAML-weergave. U kunt een nieuwe entiteit maken op basis van een YAML-configuratiebestand met een .yml of .yaml extensie.

Dit artikel bevat een overzicht van de belangrijkste syntaxisconcepten die u tegenkomt tijdens het configureren van deze YAML-bestanden.

Verwijzen naar een Azure Machine Learning-entiteit

Azure Machine Learning biedt een verwijzingssyntaxis (bestaande uit een verkorte en lange-indeling) voor het verwijzen naar een bestaande Azure Machine Learning-entiteit bij het configureren van een YAML-bestand. U kunt bijvoorbeeld verwijzen naar een bestaande geregistreerde omgeving in uw werkruimte om te gebruiken als de omgeving voor een taak.

Verwijzen naar een Azure Machine Learning-asset

Er zijn twee opties voor het verwijzen naar een Azure Machine Learning-asset (omgevingen, modellen, gegevens en onderdelen):

  • Verwijzen naar een expliciete versie van een asset:

    • Korte syntaxis: azureml:<asset_name>:<asset_version>
    • Lange syntaxis, die de resource-id van Azure Resource Manager (ARM) van de asset bevat:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • Verwijs naar de nieuwste versie van een asset:

    In sommige scenario's wilt u mogelijk verwijzen naar de nieuwste versie van een asset zonder dat u expliciet hoeft op te zoeken en de werkelijke versietekenreeks zelf op te geven. De meest recente versie wordt gedefinieerd als de meest recente versie van een asset onder een bepaalde naam.

    U kunt verwijzen naar de nieuwste versie met behulp van de volgende syntaxis: azureml:<asset_name>@latest Azure Machine Learning lost de verwijzing naar een expliciete assetversie in de werkruimte op.

Verwijzen naar een Azure Machine Learning-resource

Als u wilt verwijzen naar een Azure Machine Learning-resource (zoals compute), kunt u een van de volgende syntaxis gebruiken:

  • Korte syntaxis: azureml:<resource_name>
  • Lange syntaxis, die de ARM-resource-id van de resource bevat:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

Azure Machine Learning-gegevensreferentie-URI

Azure Machine Learning biedt een handige URI-indeling voor gegevensreferenties om te verwijzen naar gegevens in een Azure-opslagservice. Dit kan worden gebruikt voor scenario's waarin u een cloudopslaglocatie in uw YAML-bestand moet opgeven, zoals het maken van een Azure Machine Learning-model op basis van een of meer bestanden in de opslag of het verwijzen naar gegevens die moeten worden doorgegeven als invoer voor een taak.

Als u deze gegevens-URI-indeling wilt gebruiken, moet de opslagservice waarnaar u wilt verwijzen eerst worden geregistreerd als een gegevensarchief in uw werkruimte. Azure Machine Learning verwerkt de gegevenstoegang met behulp van de referenties die u hebt opgegeven tijdens het maken van het gegevensarchief.

De indeling bestaat uit een gegevensarchief in de huidige werkruimte en het pad in het gegevensarchief naar het bestand of de map waarnaar u wilt verwijzen:

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

Bijvoorbeeld:

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

Naast de azure Machine Learning-gegevensreferentie-URI biedt Azure Machine Learning ook ondersteuning voor de volgende protocollen voor directe opslag-URI's: https, abfsswasbs, en , en adlopenbare http URI's.https

Expressiesyntaxis voor het configureren van Azure Machine Learning-taken en -onderdelen

Met YAML-bestanden voor v2-taken en onderdelen kan het gebruik van expressies worden gekoppeld aan contexten voor verschillende scenario's. De essentiële use case is het gebruik van een expressie voor een waarde die mogelijk niet bekend is op het moment van het ontwerpen van de configuratie, maar moet tijdens runtime worden opgelost.

Gebruik de volgende syntaxis om Azure Machine Learning te vertellen een expressie te evalueren in plaats van deze te behandelen als een tekenreeks:

${{ <expression> }}

De ondersteunde scenario's worden hieronder behandeld.

Het parameteriseren van de command taak met de inputs en outputs contexten van een taak

U kunt letterlijke waarden, URI-paden en geregistreerde Azure Machine Learning-gegevensassets opgeven als invoer voor een taak. De command parameter kan vervolgens worden geparameteriseerd met verwijzingen naar deze invoer(en) met behulp van de ${{inputs.<input_name>}} syntaxis. Verwijzingen naar letterlijke invoer worden tijdens runtime omgezet in de letterlijke waarde, terwijl verwijzingen naar gegevensinvoer worden omgezet in het downloadpad of koppelpad (afhankelijk van de mode opgegeven).

Op dezelfde manier kunnen ook uitvoer naar de taak worden verwezen in de command. Voor elke benoemde uitvoer die is opgegeven in de outputs woordenlijst, genereert Azure Machine Learning een uitvoerlocatie in het standaardgegevensarchief waarnaar u bestanden kunt schrijven. De uitvoerlocatie voor elke benoemde uitvoer is gebaseerd op het volgende ge templatiseerde pad: <default-datastore>/azureml/<job-name>/<output_name>/. Als u de command${{outputs.<output_name>}} syntaxis parameteriseert, wordt deze verwijzing naar het door het systeem gegenereerde pad omgezet, zodat uw script bestanden naar die locatie kan schrijven vanuit de taak.

In het onderstaande voorbeeld voor een YAML-bestand met een opdrachttaak wordt het command geparameteriseerd met twee invoerwaarden, een letterlijke invoer en een gegevensinvoer en één uitvoer. Tijdens runtime wordt de ${{inputs.learning_rate}} expressie omgezet in 0.01en wordt de ${{inputs.iris}} expressie omgezet in het downloadpad van het iris.csv bestand. ${{outputs.model_dir}} wordt omgezet in het koppelpad van de door het systeem gegenereerde uitvoerlocatie die overeenkomt met de model_dir uitvoer.

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

Parameteriseren van de command met de search_space context van een sweep-taak

U gebruikt deze expressiesyntaxis ook bij het afstemmen van hyperparameters via een sweep-taak, omdat de werkelijke waarden van de hyperparameters niet bekend zijn tijdens het ontwerpen van taken. Wanneer u een sweep-taak uitvoert, selecteert Azure Machine Learning hyperparameterwaarden voor elke proefversie op basis van de search_space. Als u toegang wilt krijgen tot deze waarden in uw trainingsscript, moet u deze doorgeven via de opdrachtregelargumenten van het script. Gebruik hiervoor de ${{search_space.<hyperparameter>}} syntaxis in de trial.command.

In het onderstaande voorbeeld voor een YAML-bestand voor een opruimende taak worden de ${{search_space.learning_rate}} en ${{search_space.boosting}} verwijzingen in trial.command omgezet in de werkelijke hyperparameterwaarden die zijn geselecteerd voor elke proefversie wanneer de proeftaak wordt verzonden voor uitvoering.

$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

Bindinginvoer en uitvoer tussen stappen in een pijplijntaak

Expressies worden ook gebruikt voor bindingsinvoer en uitvoer tussen stappen in een pijplijntaak. U kunt bijvoorbeeld de invoer van één taak (taak B) in een pijplijn binden aan de uitvoer van een andere taak (taak A). Dit gebruik geeft aan Azure Machine Learning de afhankelijkheidsstroom van de pijplijngrafiek aan en taak B wordt uitgevoerd na taak A, omdat de uitvoer van taak A is vereist als invoer voor taak B.

Voor een YAML-bestand voor een pijplijntaak worden de inputs en outputs secties van elke onderliggende taak geëvalueerd in de bovenliggende context (de pijplijntaak op het hoogste niveau). De command, daarentegen, wordt omgezet in de huidige context (de onderliggende taak).

Er zijn twee manieren om invoer en uitvoer in een pijplijntaak te binden:

Binden aan de invoer en uitvoer op het hoogste niveau van de pijplijntaak

U kunt de invoer of uitvoer van een onderliggende taak (een pijplijnstap) binden aan de invoer/uitvoer van de bovenliggende pijplijntaak op het hoogste niveau met behulp van de volgende syntaxis: ${{parent.inputs.<input_name>}} of ${{parent.outputs.<output_name>}}. Deze verwijzing wordt omgezet in de parent context; vandaar de invoer/uitvoer op het hoogste niveau.

In het onderstaande voorbeeld is de invoer (raw_data) van de eerste prep stap gebonden aan de pijplijninvoer op het hoogste niveau via ${{parent.inputs.input_data}}. De uitvoer (model_dir) van de laatste train stap is gebonden aan de uitvoer van de pijplijntaak op het hoogste niveau via ${{parent.outputs.trained_model}}.

Binden aan de invoer en uitvoer van een andere onderliggende taak (stap)

Gebruik de volgende syntaxis om de invoer/uitvoer van één stap te binden aan de invoer/uitvoer van een andere stap: ${{parent.jobs.<step_name>.inputs.<input_name>}} of ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Nogmaals, deze verwijzing wordt omgezet in de bovenliggende context, dus de expressie moet beginnen met parent.jobs.<step_name>.

In het onderstaande voorbeeld is de invoer (training_data) van de train stap gebonden aan de uitvoer (clean_data) van de prep stap via ${{parent.jobs.prep.outputs.clean_data}}. De voorbereide gegevens uit de prep stap worden gebruikt als de trainingsgegevens voor de train stap.

Aan de andere kant worden de contextverwijzingen binnen de command eigenschappen omgezet in de huidige context. De verwijzing in de prep stap command wordt bijvoorbeeld ${{inputs.raw_data}} omgezet in de invoer van de huidige context. Dit is de prep onderliggende taak. De zoekactie wordt uitgevoerd, prep.inputszodat daar een invoer met de naam raw_data moet worden gedefinieerd.

$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

Parameteriseren van de command met de inputs en outputs contexten van een onderdeel

Net als voor command een taak kan het command voor een onderdeel ook worden geparameteriseerd met verwijzingen naar de inputs en outputs contexten. In dit geval is de verwijzing naar de invoer en uitvoer van het onderdeel. Wanneer het onderdeel wordt uitgevoerd in een taak, worden deze verwijzingen naar de taakruntime-invoer- en uitvoerwaarden die zijn opgegeven voor de respectieve onderdeleninvoer en -uitvoer, in Azure Machine Learning omgezet. Hieronder ziet u een voorbeeld van het gebruik van de contextsyntaxis voor een YAML-specificatie voor een opdrachtonderdeel.

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

Optionele invoer definiëren in de opdrachtregel

Wanneer de invoer is ingesteld als optional = true, moet u de $[[]] opdrachtregel met invoer omhelzen. Bijvoorbeeld $[[--input1 ${{inputs.input1}}]. De opdrachtregel tijdens runtime kan verschillende invoer hebben.

  • Als u alleen de vereiste parameters model_output gebruikttraining_data, ziet de opdrachtregel er als volgt uit:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Als er tijdens runtime learning_rate geen waarde is opgegeven en learning_rate_schedule de standaardwaarde wordt gebruikt.

  • Als alle invoer/uitvoer waarden leveren tijdens runtime, ziet de opdrachtregel er als volgt uit:
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

Expressies voor uitvoerpaden

De volgende expressies kunnen worden gebruikt in het uitvoerpad van uw taak:

Belangrijk

De volgende expressies worden opgelost aan de serverzijde , niet aan de clientzijde . Voor geplande taken waarbij de aanmaaktijd en de tijd voor het indienen van taken verschillen, worden de expressies opgelost wanneer de taak wordt verzonden. Omdat deze expressies aan de serverzijde worden omgezet, gebruiken ze de huidige status van de werkruimte, niet de status van de werkruimte wanneer de geplande taak is gemaakt. Als u bijvoorbeeld het standaardgegevensarchief van de werkruimte wijzigt nadat u een geplande taak hebt gemaakt, wordt de expressie ${{default_datastore}} omgezet in het nieuwe standaardgegevensarchief, niet het standaardgegevensarchief wanneer de geplande taak is gemaakt.

Expression Beschrijving Bereik
${{default_datastore}} Als het standaardgegevensarchief van de pijplijn is geconfigureerd, wordt deze omgezet als standaardnaam voor het gegevensarchief van de pijplijn; anders wordt omgezet als de standaardnaam van het gegevensarchief van de werkruimte.

Standaardgegevensarchief voor pijplijnen kan worden beheerd met behulp van pipeline_job.settings.default_datastore.		 Werkt voor alle taken.

Pijplijntaken hebben een configureerbaar standaardgegevensarchief voor pijplijnen.
${{name}} De taaknaam. Voor pijplijnen is dit de naam van de staptaak, niet de naam van de pijplijntaak. Werkt voor alle taken
${{output_name}} De naam van de taakuitvoer Werkt voor alle taken

Als azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} dit bijvoorbeeld wordt gebruikt als het uitvoerpad, wordt deze tijdens runtime omgezet als een pad van azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Volgende stappen