Syntaxe YAML core CLI (v2)

PLATÍ PRO: Rozšíření Azure CLI ml v2 (aktuální)

Každá entita Azure Machine Learning má reprezentaci YAML s schématem. Novou entitu můžete vytvořit z konfiguračního souboru YAML s příponou nebo .yaml příponou.yml.

Tento článek obsahuje přehled základních konceptů syntaxe, se kterými se setkáte při konfiguraci těchto souborů YAML.

Odkazování na entitu Azure Machine Learning

Azure Machine Learning poskytuje referenční syntaxi (skládající se z zkráceného a dlouhého formátu) pro odkazování na existující entitu Azure Machine Learning při konfiguraci souboru YAML. Můžete například odkazovat na existující zaregistrované prostředí ve vašem pracovním prostoru, které se použije jako prostředí pro úlohu.

Odkazování na prostředek Služby Azure Machine Learning

Existují dvě možnosti pro odkazování na prostředek služby Azure Machine Learning (prostředí, modely, data a komponenty):

• Odkazování na explicitní verzi prostředku:

  • Syntaxe zkratky: azureml:<asset_name>:<asset_version>
  • Dlouhá syntaxe, která zahrnuje ID prostředku Azure Resource Manageru (ARM):

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

• Odkaz na nejnovější verzi prostředku:

  V některých scénářích můžete chtít odkazovat na nejnovější verzi prostředku, aniž byste museli explicitně vyhledat a zadat samotný řetězec skutečné verze. Nejnovější verze je definovaná jako nejnovější (označovaná také jako nejnovější) vytvořená verze prostředku pod daným názvem.

  Nejnovější verzi můžete odkazovat pomocí následující syntaxe: azureml:<asset_name>@latest. Azure Machine Learning přeloží odkaz na explicitní verzi assetu v pracovním prostoru.

Odkaz na prostředek Azure Machine Learning

Pokud chcete odkazovat na prostředek Služby Azure Machine Learning (například výpočetní prostředky), můžete použít některou z následujících syntaxí:

• Syntaxe zkratky: azureml:<resource_name>
• Syntaxe longhand, která zahrnuje ID prostředku ARM prostředku:

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

Referenční identifikátor URI pro data služby Azure Machine Learning

Azure Machine Learning nabízí formát identifikátoru URI referenčního přehledu dat pro odkazování na data ve službě úložiště Azure. To se dá použít ve scénářích, ve kterých potřebujete zadat umístění cloudového úložiště v souboru YAML, například vytvoření modelu Azure Machine Learning ze souborů v úložišti nebo odkazování na data, která se mají předat jako vstup do úlohy.

Chcete-li použít tento formát identifikátoru URI dat, musí být služba úložiště, na kterou chcete odkazovat, nejprve zaregistrována jako úložiště dat ve vašem pracovním prostoru. Azure Machine Learning bude zpracovávat přístup k datům pomocí přihlašovacích údajů, které jste zadali při vytváření úložiště dat.

Formát se skládá z úložiště dat v aktuálním pracovním prostoru a cesty k úložišti dat k souboru nebo složce, na kterou chcete odkazovat:

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

Příklad:

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

Kromě referenčního identifikátoru URI pro data služby Azure Machine Learning podporuje azure Machine Learning také následující protokoly URI přímého úložiště: https, wasbs, abfssa , a také veřejné http a https adlidentifikátory URI.

Syntaxe výrazů pro konfiguraci úloh a komponent služby Azure Machine Learning

Soubory YAML úloh a komponent v2 umožňují použití výrazů k vytvoření vazby na kontexty pro různé scénáře. Základní případ použití používá výraz pro hodnotu, která nemusí být známa v době vytváření konfigurace, ale musí být vyřešena za běhu.

Pomocí následující syntaxe řekněte službě Azure Machine Learning, aby vyhodnotil výraz, a ne jako řetězec:

${{ <expression> }}

Podporované scénáře jsou popsané níže.

Parametrizace command pomocí inputs kontextu outputs úlohy

Jako vstupy do úlohy můžete zadat hodnoty literálů, cesty identifikátorů URI a registrované datové prostředky služby Azure Machine Learning. Potom command lze parametrizovat pomocí odkazů na tyto vstupy pomocí ${{inputs.<input_name>}} syntaxe. Odkazy na literální vstupy se přeloží na literálovou hodnotu za běhu, zatímco odkazy na vstupy dat se přeloží na cestu ke stažení nebo cestu připojení (v závislosti na zadaném mode nastavení).

Podobně lze na výstupy úlohy odkazovat také v sadě command. Pro každý pojmenovaný výstup zadaný ve slovníku outputs služba Azure Machine Learning vygeneruje výstupní umístění ve výchozím úložišti dat, do kterého můžete zapisovat soubory. Umístění výstupu pro každý pojmenovaný výstup je založeno na následující cestě templatized: <default-datastore>/azureml/<job-name>/<output_name>/. Parametrizace command pomocí ${{outputs.<output_name>}} syntaxe přeloží odkaz na cestu vygenerovanou systémem, aby skript mohl zapisovat soubory do daného umístění z úlohy.

V následujícím příkladu pro soubor command YAML úlohy příkazu je parametrizován se dvěma vstupy, literálovým vstupem a vstupem dat a jedním výstupem. Za běhu se ${{inputs.learning_rate}} výraz přeloží na 0.01a ${{inputs.iris}} výraz se přeloží na cestu iris.csv ke stažení souboru. ${{outputs.model_dir}} přeloží se na cestu připojení systémem generovaného výstupního umístění odpovídající výstupu 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:

Parametrizace command s search_space kontextem úlohy uklidit

Tuto syntaxi výrazu použijete také při provádění ladění hyperparametrů prostřednictvím úlohy uklidit, protože skutečné hodnoty hyperparametrů nejsou během vytváření úloh známé. Když spustíte úlohu úklidu, Azure Machine Learning vybere hodnoty hyperparametrů pro každou zkušební verzi na základě hodnoty search_space. Pokud chcete získat přístup k těmto hodnotám v trénovacím skriptu, musíte je předat pomocí argumentů příkazového řádku skriptu. Uděláte to tak, že použijete syntaxi ${{search_space.<hyperparameter>}} v objektu trial.command.

V následujícím příkladu pro soubor ${{search_space.learning_rate}} YAML úlohy uklidit se hodnoty a ${{search_space.boosting}} odkazy trial.command přeloží na skutečné hodnoty hyperparametrů vybrané pro každou zkušební verzi při odeslání úlohy zkušební verze ke spuštění.

$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

Vazby vstupů a výstupů mezi kroky v úloze kanálu

Výrazy se také používají pro vazby vstupů a výstupů mezi kroky v úloze kanálu. Můžete například svázat vstup jedné úlohy (úlohy B) v kanálu s výstupem jiné úlohy (úloha A). Toto použití bude signalizovat tok závislostí v grafu kanálu Azure Machine Learning a úloha B se spustí po úloze A, protože výstup úlohy A se vyžaduje jako vstup pro úlohu B.

U souboru inputs outputs YAML úlohy kanálu se vyhodnocují oddíly každé podřízené úlohy v nadřazeným kontextu (úloha kanálu nejvyšší úrovně). Na commanddruhé straně se přeloží na aktuální kontext (podřízenou úlohu).

Vstupy a výstupy v úloze kanálu lze svázat dvěma způsoby:

Vazba na vstupy nejvyšší úrovně a výstupy úlohy kanálu

Vstupy nebo výstupy podřízené úlohy (krok kanálu) můžete svázat se vstupy a výstupy nadřazené úlohy kanálu nejvyšší úrovně pomocí následující syntaxe: ${{parent.inputs.<input_name>}} nebo ${{parent.outputs.<output_name>}}. Tento odkaz se překládá na parent kontext, a proto vstupy a výstupy nejvyšší úrovně.

V následujícím příkladu je vstup (raw_data) prvního prep kroku vázán na vstup kanálu nejvyšší úrovně prostřednictvím ${{parent.inputs.input_data}}. Výstup (model_dir) posledního train kroku je vázán na výstup úlohy kanálu nejvyšší úrovně prostřednictvím ${{parent.outputs.trained_model}}.

Vytvoření vazby na vstupy a výstupy jiné podřízené úlohy (krok)

Chcete-li svázat vstupy/výstupy jednoho kroku se vstupy/výstupy jiného kroku, použijte následující syntaxi: ${{parent.jobs.<step_name>.inputs.<input_name>}} nebo ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Tento odkaz se znovu přeloží na nadřazený kontext, takže výraz musí začínat parent.jobs.<step_name>na .

V následujícím příkladu je vstup (training_data) train kroku vázán na výstup (clean_data) prep kroku přes ${{parent.jobs.prep.outputs.clean_data}}. Připravená data z prep kroku se použijí jako trénovací data pro train tento krok.

Na druhou stranu se kontextové odkazy v rámci command vlastností přeloží na aktuální kontext. Odkaz v prep kroku command se například ${{inputs.raw_data}} přeloží na vstupy aktuálního kontextu, což je prep podřízená úloha. Vyhledávání bude provedeno na prep.inputs, takže vstup s názvem raw_data musí být definován tam.

$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

Parametrizace command pomocí inputs a outputs kontextů komponenty

command Podobně jako u úlohy může být komponenta command také parametrizována s odkazy na inputs kontexty a outputs kontexty. V tomto případě je odkaz na vstupy a výstupy komponenty. Když se komponenta spustí v úloze, Azure Machine Learning tyto odkazy přeloží na vstup modulu runtime úlohy a výstupní hodnoty zadané pro příslušné vstupy a výstupy komponent. Níže je příklad použití syntaxe kontextu pro specifikaci YAML komponenty příkazu.

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

Definování volitelných vstupů v příkazovém řádku

Když je vstup nastavený jako optional = true, musíte použít $[[]] k přijetí příkazového řádku se vstupy. Příklad: $[[--input1 ${{inputs.input1}}]. Příkazový řádek za běhu může mít různé vstupy.

• Pokud používáte jenom požadované training_data parametry a model_output parametry, bude příkazový řádek vypadat takto:

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

Pokud není za běhu learning_rate zadána žádná hodnota a learning_rate_schedule použije výchozí hodnotu.

• Pokud všechny vstupy a výstupy poskytují hodnoty za běhu, bude příkazový řádek vypadat takto:

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

Výrazy výstupní cesty

Ve výstupní cestě úlohy je možné použít následující výrazy:

Důležité

Následující výrazy se přeloží na straně serveru , ne na straně klienta . U naplánovaných úloh, kde se liší čas vytvoření úlohy a čas odeslání úlohy, se výrazy přeloží při odeslání úlohy. Vzhledem k tomu, že se tyto výrazy přeloží na straně serveru, používají aktuální stav pracovního prostoru, nikoli stav pracovního prostoru při vytvoření naplánované úlohy. Pokud například po vytvoření naplánované úlohy změníte výchozí úložiště dat pracovního prostoru, výraz ${{default_datastore}} se přeloží na nové výchozí úložiště dat, nikoli na výchozí úložiště dat při vytvoření naplánované úlohy.

Expression	Popis	Obor
${{default_datastore}}	Pokud je nakonfigurované výchozí úložiště dat kanálu, přeloží se jako výchozí název úložiště dat kanálu. jinak se přeloží jako výchozí název úložiště dat pracovního prostoru. Výchozí úložiště dat kanálu lze řídit pomocí pipeline_job.settings.default_datastore.	Funguje pro všechny úlohy. Úlohy kanálu mají konfigurovatelné výchozí úložiště dat kanálu.
${{name}}	Název úlohy. U kanálů se jedná o název úlohy kroku, nikoli název úlohy kanálu.	Funguje pro všechny úlohy
${{output_name}}	Název výstupu úlohy	Funguje pro všechny úlohy

Pokud azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} se například používá jako výstupní cesta, za běhu se přeloží jako cesta azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Další kroky

• Instalace a použití rozhraní příkazového řádku (v2)
• Trénování modelů pomocí rozhraní příkazového řádku (v2)
• Schémata YAML rozhraní příkazového řádku (v2)