Базовый синтаксис 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
и adl
https
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
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}}
Определение необязательных входных данных в командной строке
Если входные данные заданы как 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
.