Базовый синтаксис YAML интерфейса командной строки (версия 2)

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ:расширение Машинного обучения для Azure CLI версии 2 (текущая версия)

Каждая сущность Машинного обучения Azure имеет схематизированное представление YAML. Вы можете создать новую сущность из файла конфигурации YAML с расширением .yml или .yaml.

В этой статье представлен обзор основных понятий синтаксиса, с которыми вы столкнетесь при настройке этих файлов YAML.

Ссылка на сущность Машинное обучение Azure

Машинное обучение Azure предоставляет ссылочный синтаксис (состоящий из короткого и длинного формата) для ссылки на существующую сущность Машинное обучение Azure при настройке ФАЙЛА YAML. Например, вы можете сослаться на существующую зарегистрированную среду в рабочей области, чтобы использовать ее в среде для задания.

Ссылка на ресурс Машинное обучение Azure

Существует два варианта ссылки на ресурс Машинное обучение Azure (среды, модели, данные и компоненты):

  • Ссылка на явную версию актива:

    • Сокращенный синтаксис: azureml:<asset_name>:<asset_version>
    • Обычный синтаксис, который включает идентификатор ARM для актива:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • Ссылка на последнюю версию актива:

    В некоторых сценариях может потребоваться создать ссылку на последнюю версию актива без явного поиска и указания фактической строки версии. Последняя версия определяется как последняя (самая актуальная) созданная версия актива с заданным именем.

    Вы можете создать ссылку на последнюю версию с помощью следующего синтаксиса: azureml:<asset_name>@latest. Машинное обучение Azure будет разрешать ссылку на явную версию ресурса в рабочей области.

Ссылка на ресурс Машинное обучение Azure

Чтобы ссылаться на ресурс Машинное обучение Azure (например, вычисление), можно использовать любой из следующих синтаксисов:

  • Сокращенный синтаксис: azureml:<resource_name>
  • Обычный синтаксис, включающий идентификатор ARM для ресурса:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

URI справочника по данным Машинное обучение Azure

Машинное обучение Azure предлагает удобный формат URI ссылки на данные для указания данных в службе хранилища Azure. Это можно использовать для сценариев, в которых необходимо указать расположение облачного хранилища в YAML-файле, например создание модели Машинное обучение Azure из файлов в хранилище или указание данных для передачи в качестве входных данных заданию.

Чтобы использовать этот формат URI данных, служба хранения, на которую вы хотите сослаться, должна быть сначала зарегистрирована как хранилище данных в вашей рабочей области. Машинное обучение Azure будет обрабатывать доступ к данным с помощью учетных данных, предоставленных во время создания хранилища данных.

Формат состоит из хранилища данных в текущей рабочей области и пути в хранилище данных к файлу или папке, на которые вы хотите указать:

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

Например:

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

Помимо URI ссылки на данные Машинное обучение Azure, Машинное обучение Azure также поддерживает следующие протоколы URI прямого хранилища: https, wasbs, abfssи, а также общедоступные http и adlhttps URI.

Синтаксис выражений для настройки заданий и компонентов Машинное обучение Azure

Файлы YAML заданий и компонентов версии 2 позволяют использовать выражения для привязки к контекстам в различных сценариях. Существенным вариантом использования является использование выражения для значения, которое может быть неизвестно во время разработки конфигурации, но должно быть разрешено во время выполнения.

Используйте следующий синтаксис, чтобы сообщить Машинное обучение Azure, чтобы оценить выражение, а не рассматривать его как строку:

${{ <expression> }}

Поддерживаемые сценарии описаны ниже.

Параметризация command с контекстами inputs и outputs задания

Можно указать литеральные значения, пути URI и зарегистрированные Машинное обучение Azure ресурсы данных в качестве входных данных для задания. Затем command можно параметризовать ссылками на эти входные данные, используя синтаксис ${{inputs.<input_name>}}. Ссылки на литеральные входные данные будут разрешены в литеральные значения во время выполнения, а ссылки на входные данные будут разрешены в путь скачивания или путь подключения (в зависимости от указанного mode).

Аналогично, на выходные данные задания также можно ссылаться в command. Для каждого именованного выходных данных, указанного outputs в словаре, Машинное обучение Azure система создаст расположение выходных данных в хранилище данных по умолчанию, в котором можно записывать файлы. Расположение вывода для каждого именованного вывода основано на следующем шаблонизируемом пути: <default-datastore>/azureml/<job-name>/<output_name>/. Параметризация command с помощью синтаксиса ${{outputs.<output_name>}} разрешит эту ссылку в сгенерированный системой путь, чтобы скрипт мог записывать файлы в это расположение из задания.

В приведенном ниже примере для файла YAML командного задания command параметризован двумя вводами, литеральным вводом и вводом данных, а также одним выводом. Во время выполнения выражение ${{inputs.learning_rate}} разрешается в 0.01, а выражение ${{inputs.iris}} разрешается в путь загрузки файла iris.csv. ${{outputs.model_dir}} разрешается в путь подключения созданного системой расположения вывода, соответствующего выходных данным 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:

Параметризация command с помощью контекста search_space задания очистки

Этот синтаксис выражений также будет использоваться при выполнении настройки гиперпараметров с помощью задания очистки, поскольку фактические значения гиперпараметров не известны во время разработки задания. При выполнении задания очистки Машинное обучение Azure будет выбирать значения гиперпараметров для каждой пробной версии на search_spaceоснове . Чтобы получить доступ к этим значениям в обучающем скрипте, необходимо передать их в с помощью аргументов командной строки скрипта. Для этого используйте синтаксис ${{search_space.<hyperparameter>}} в trial.command.

В приведенном ниже примере для файла YAML задания очистки ссылки ${{search_space.learning_rate}} и ${{search_space.boosting}} в trial.command будут разрешаться в фактические значения гиперпараметров, выбранные для каждой пробной версии, когда пробное задание отправляется для выполнения.

$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

Привязка входных и выходных данных между шагами в задании конвейера

Выражения также используются для привязки входных и выходных данных между шагами в задании конвейера. Например, можно привязать входные данные одного задания (задания Б) в конвейере к выходным данным другого задания (задание А). Это использование сигнализирует Машинное обучение Azure поток зависимостей графа конвейера, а задание B будет выполнено после задания А, так как выходные данные задания A необходимы в качестве входных данных для задания B.

Для файла YAML задания конвейера разделы inputs и outputs каждого дочернего задания оцениваются в родительском контексте (задание конвейера верхнего уровня). command, с другой стороны, будет разрешаться в текущий контекст (дочернее задание).

Существует два способа привязки входных и выходных данных в задании конвейера.

Привязка к входным и выходным данным верхнего уровня задания конвейера

Входные и выходные данные дочернего задания (этап конвейера) можно привязать к входным и выходным данным задания родительского конвейера верхнего уровня, используя следующий синтаксис: ${{parent.inputs.<input_name>}} или ${{parent.outputs.<output_name>}}. Эта ссылка разрешается в контекст типа parent; поэтому используются вводы/выводы верхнего уровня.

В приведенном ниже примере входные данные (raw_data) первого шага prep привязываются к входным данным конвейера верхнего уровня с помощью ${{parent.inputs.input_data}}. Выходные данные (model_dir) последнего шага train привязываются к выходным данным задания конвейера верхнего уровня с помощью ${{parent.outputs.trained_model}}.

Привязка к входным и выходным данным другого дочернего задания (этап)

Чтобы привязать входные и выходные данные одного шага к входным и выходным данным другого шага, используйте следующий синтаксис: ${{parent.jobs.<step_name>.inputs.<input_name>}} или ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Опять же, эта ссылка разрешается в родительский контекст, поэтому выражение начинается с parent.jobs.<step_name>.

В приведенном ниже примере входные данные (training_data) шага train привязываются к выходным данным (clean_data) шага prep через ${{parent.jobs.prep.outputs.clean_data}}. Подготовленные данные из шага prep будут использоваться в качестве обучающих данных для шага train.

С другой стороны, ссылки на контекст в свойствах command будут разрешаться в текущий контекст. Например, ссылка ${{inputs.raw_data}} в command шага prep будет разрешаться во входные данные текущего контекста, который является дочерним заданием prep. Поиск будет выполнен в prep.inputs, поэтому там должны быть определены входные данные с именем raw_data.

$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

Параметризация command с контекстами inputs и outputs компонента

Подобно command для задания, command для компонента также можно параметризовать ссылками на контексты inputs и outputs. В этом случае ссылка указывает на входные и выходные данные компонента. Когда компонент выполняется в задании, Машинное обучение Azure будет разрешать эти ссылки на входные и выходные значения среды выполнения задания, указанные для соответствующих входных и выходных данных компонента. Ниже приведен пример использования синтаксиса контекста для спецификации YAML командного компонента.

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

Определение необязательных входных данных в командной строке

Если входные данные заданы как optional = true, необходимо использовать для $[[]] применения командной строки с входными данными. Например $[[--input1 ${{inputs.input1}}]. Командная строка во время выполнения может иметь разные входные данные.

  • Если вы используете только необходимые training_data и model_output параметры, командная строка будет выглядеть следующим образом:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Если значение не указано во время выполнения, learning_rate и learning_rate_schedule будет использоваться значение по умолчанию.

  • Если все входные и выходные данные предоставляют значения во время выполнения, командная строка будет выглядеть следующим образом:
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

Выражения выходного пути

Следующие выражения можно использовать в выходном пути задания:

Важно!

Следующие выражения разрешаются на стороне сервера , а не на стороне клиента . Для запланированных заданий, в которых время создания задания и время отправки задания отличаются, выражения разрешаются при отправке задания. Так как эти выражения разрешаются на стороне сервера, они используют текущее состояние рабочей области, а не состояние рабочей области при создании запланированного задания. Например, если изменить хранилище данных по умолчанию рабочей области после создания запланированного задания, выражение ${{default_datastore}} разрешается в новое хранилище данных по умолчанию, а не хранилище данных по умолчанию при создании запланированного задания.

Expression Description Область действия
${{default_datastore}} Если хранилище данных по умолчанию конвейера настроено, разрешается как имя хранилища данных по умолчанию конвейера; в противном случае разрешается как имя хранилища данных по умолчанию рабочей области.

Хранилище данных по умолчанию конвейера можно контролировать с помощью pipeline_job.settings.default_datastore.		 Работает для всех заданий.

Задания конвейера имеют настраиваемое хранилище данных по умолчанию конвейера.
${{name}} Имя задания. Для конвейеров это имя задания шага, а не имя задания конвейера. Работает для всех заданий
${{output_name}} Имя выходных данных задания Работает для всех заданий

Например, если azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} используется в качестве выходного пути, во время выполнения он разрешается как путь azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Следующие шаги