Схемы YAML для командного задания CLI (версия 2)

  • Статья

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

Исходную схему JSON можно найти по адресу https://azuremlschemas.azureedge.net/latest/commandJob.schema.json.

Примечание

Синтаксис YAML, описанный в этом документе, основан на схеме JSON для последней версии расширения ML CLI (версия 2). Этот синтаксис гарантированно работает только с последней версией расширения ML CLI (версия 2). Схемы для старых версий расширений можно найти по адресу https://azuremlschemasprod.azureedge.net/.

Синтаксис YAML

Ключ Тип Описание Допустимые значения Значение по умолчанию
$schema строка Схема YAML. При создании файла YAML с помощью расширения VS Code службы машинного обучения Azure вы можете добавить $schema в верхней части файла, чтобы вызвать завершение схемы и ресурсов.
type const Тип задания. command command
name строка Имя задания. Должно быть уникальным для всех заданий в рабочей области. Если этот параметр опущен, Машинное обучение Azure автоматически создаст GUID для имени.
display_name строка Отображаемое имя задания в пользовательском интерфейсе студии. Может быть неуникальным в пределах рабочей области. Если этот параметр опущен, Машинное обучение Azure автоматически создаст для отображаемого имени удобочитаемый идентификатор прилагательного-существительного.
experiment_name строка Имя эксперимента, по которому будет организовано задание. Запись выполнения каждого задания будет организована в соответствующем эксперименте на вкладке "Эксперименты" студии. Если этот параметр опущен, машинное обучение Azure по умолчанию будет использовать имя рабочего каталога, в котором было создано задание.
description строка Описание задания.
tags object Словарь тегов для задания.
command строка Обязательно, если не используется поле component. Команда для выполнения.
code строка Локальный путь к каталогу исходного кода, который будет отправлен и использован для задания.
environment Строка или объект Обязательно, если не используется поле component. Среда, используемая для задания. Это может быть ссылкой на существующую среду управления версиями в рабочей области или спецификацией встроенной среды.

Для ссылки на существующую среду используйте синтаксис azureml:<environment_name>:<environment_version> или azureml:<environment_name>@latest (это ссылка на последнюю версию среды).

Чтобы определить встроенную среду, следуйте схеме среды. Исключите свойства name и version, поскольку они не поддерживаются для встроенных сред.
environment_variables object Словарь пар "ключ — значение" переменной среды, устанавливаемых для процесса, в котором выполняется команда.
distribution object Конфигурация распределения для сценариев распределенного обучения. Является одной из следующих: MpiConfiguration, PyTorchConfiguration или TensorFlowConfiguration.
compute строка Имя целевого объекта вычислений для выполнения задания. Это может быть ссылка на существующие вычислительные ресурсы в рабочей области (с использованием синтаксиса azureml:<compute_name>) или local для обозначения локального выполнения. Примечание. Задания в конвейере не поддерживаются local как compute local
resources.instance_count Целое число Число узлов, используемых для задания. 1
resources.instance_type строка Тип экземпляра, используемый для задания. Применимо для заданий, выполняемых в вычислительной среде Kubernetes с поддержкой Azure Arc (если в поле compute указана целевая вычислительная среда типа type: kubernentes). Если этот параметр не указан, используется тип экземпляра по умолчанию для кластера Kubernetes. Дополнительные сведения см. в статье Создание и выбор типов экземпляров Kubernetes.
resources.shm_size строка Размер блока общей памяти контейнера Docker. Значение должно быть в формате <number><unit> , где число должно быть больше 0, а единица измерения может быть одной из b (байт), k (килобайт), m (мегабайт) или g (гигабайт). 2g
limits.timeout Целое число Максимальное время в секундах, в течение которого разрешено выполнение задания. По достижении этого предела система отменит задание.
inputs объект Словарь входных данных для задания. Ключ — это имя входных данных в контексте задания, а значение — это входное значение.

На входные данные можно ссылаться в command с помощью выражения ${{ inputs.<input_name> }}.
inputs.<input_name> число, целое число, логическое значение, строка или объект Одно из литеральных значений (с типом Number, Integer, Boolean или String) или объект, содержащий спецификацию входных данных для задания.
outputs object Словарь конфигураций выходных данных для задания. Ключ — это имя выходных данных в контексте задания, а значение — выходная конфигурация.

На выходные данные можно ссылаться в command с помощью выражения ${{ outputs.<output_name> }}.
outputs.<output_name> объект Объект можно оставить пустым. В этом случае по умолчанию выходные данные будут иметь тип uri_folder и Машинное обучение Azure создаст расположение выходных данных для выходных данных. Файлы будут сохраняться в выходной каталог, подключенный с правами на чтение и запись. Если вы хотите указать другой режим вывода данных, укажите объект со спецификацией выходных данных для задания.
identity объект Удостоверение используется для доступа к данным. Это может быть UserIdentityConfiguration, ManagedIdentityConfiguration или None. Если это UserIdentityConfiguration, удостоверение отправителя заданий будет использоваться для доступа к входным данным и записи результатов в выходную папку. В противном случае будет использоваться управляемое удостоверение целевого объекта вычислений.

Конфигурации распределения

MpiConfiguration

Ключ Тип Описание Допустимые значения
type const Обязательный. Тип распределения. mpi
process_count_per_instance Целое число Обязательный. Количество процессов, запускаемых на каждом узле для выполнения задания.

PyTorchConfiguration

Ключ Тип Описание Допустимые значения Значение по умолчанию
type const Обязательный. Тип распределения. pytorch
process_count_per_instance Целое число Количество процессов, запускаемых на каждом узле для выполнения задания. 1

TensorFlowConfiguration

Ключ Тип Описание Допустимые значения Значение по умолчанию
type const Обязательный. Тип распределения. tensorflow
worker_count Целое число Количество рабочих ролей, которые необходимо запустить для выполнения задания. По умолчанию — resources.instance_count.
parameter_server_count Целое число Количество серверов параметров, которые необходимо запустить для выполнения задания. 0

Входные данные задания

Ключ Тип Описание Допустимые значения Значение по умолчанию
type строка Тип входных данных для задания. Укажите uri_file, чтобы использовать в качестве источника входные данные из одного файла, или uri_folder, чтобы использовать весь каталог с файлами. uri_file, uri_folder, mlflow_model, custom_model uri_folder
path строка Путь к данным, которые используются в качестве входных данных. Его можно задать в нескольких форматах:

— локальный путь к файлу или папке источника данных, например path: ./iris.csv. Эта данные будут отправлены во время отправки задания.

— универсальный код ресурса (URI) для облачного пути к файлу или папке, которые нужно использовать в качестве входных данных. Поддерживаются следующие типы URI: azureml, https, wasbs, abfss, adl. Дополнительные сведения об использовании формата URI azureml:// см. в разделе Базовый синтаксис YAML.

— Существующий зарегистрированный ресурс данных Машинного обучения Azure для использования в качестве входных данных. Чтобы указать ссылку на зарегистрированный ресурс данных, используйте синтаксис azureml:<data_name>:<data_version> или azureml:<data_name>@latest (это ссылка на последнюю версию ресурса данных), например path: azureml:cifar10-data:1 или path: azureml:cifar10-data@latest.
mode строка Режим доставки данных в целевой объект вычислений.

Для подключения с доступом только для чтения (ro_mount) данные будут использоваться в качестве пути подключения. Папка будет подключена как папка, а файл будет подключен как файл. Машинное обучение Azure разрешит входные данные в пути подключения.

При использовании режима download данные будут скачаны в целевой объект вычислений. Машинное обучение Azure разрешит входные данные в скачанный путь.

Если вам нужен только URL-адрес места хранения артефактов данных, и вы не намерены подключать или скачивать сами данные, можно использовать режим direct. В этом случае в качестве входных данных для задания передается URL-адрес расположения хранилища. Обратите внимание, что при этом вам придется самостоятельно обрабатывать учетные данные для доступа к хранилищу.

eval_mount Режимы и eval_download являются уникальными для MLTable и либо подключают данные в качестве пути, либо загружают данные в целевой объект вычислений.

Дополнительные сведения о режимах см. в статье Доступ к данным в задании.		 ro_mount, download, direct, eval_download, eval_mount ro_mount

Выходные данные задания

Ключ Тип Описание Допустимые значения Значение по умолчанию
type строка Тип выходных данных для задания. По умолчанию используется тип uri_folder, то есть выходные данные сопоставляются с некоторой папкой. uri_folder , mlflow_model, custom_model uri_folder
mode строка Режим доставки выходных файлов в целевое хранилище. Для режима подключения с доступом для чтения и записи (rw_mount) выходным каталогом будет подключенный каталог. В режиме upload все записанные файлы будут отправлены после завершения задания. rw_mount, upload rw_mount

Конфигурации удостоверений

UserIdentityConfiguration

Ключ Тип Описание Допустимые значения
type const Обязательный. Тип удостоверения. user_identity

ManagedIdentityConfiguration

Ключ Тип Описание Допустимые значения
type const Обязательный. Тип удостоверения. managed или managed_identity

Remarks

Команду az ml job можно использовать для управления заданиями Машинного обучения Azure.

Примеры

Примеры доступны в репозитории примеров GitHub. Ниже показаны некоторые из них.

YAML: привет, мир!

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world"
environment:
  image: library/python:latest

YAML: отображаемое имя, имя эксперимента, описание и теги

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world"
environment:
  image: library/python:latest
tags:
  hello: world
display_name: hello-world-example
experiment_name: hello-world-example
description: |
  # Azure Machine Learning "hello world" job

  This is a "hello world" job running in the cloud via Azure Machine Learning!

  ## Description

  Markdown is supported in the studio for job descriptions! You can edit the description there or via CLI.

YAML: переменные среды

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo $hello_env_var
environment:
  image: library/python:latest
environment_variables:
  hello_env_var: "hello world"

YAML: исходный код

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: ls
code: src
environment:
  image: library/python:latest

YAML: литеральные входные данные

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo ${{inputs.hello_string}}
  echo ${{inputs.hello_number}}
environment:
  image: library/python:latest
inputs:
  hello_string: "hello world"
  hello_number: 42

YAML: запись в выходные данные по умолчанию

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world" > ./outputs/helloworld.txt
environment:
  image: library/python:latest

YAML: запись в именованные выходные данные

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world" > ${{outputs.hello_output}}/helloworld.txt
outputs:
  hello_output:
environment:
  image: python

YAML: входные данные файла URI хранилища данных

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo "--iris-csv: ${{inputs.iris_csv}}"
  python hello-iris.py --iris-csv ${{inputs.iris_csv}}
code: src
inputs:
  iris_csv:
    type: uri_file 
    path: azureml://datastores/workspaceblobstore/paths/example-data/iris.csv
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: входные данные папки URI хранилища данных

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  ls ${{inputs.data_dir}}
  echo "--iris-csv: ${{inputs.data_dir}}/iris.csv"
  python hello-iris.py --iris-csv ${{inputs.data_dir}}/iris.csv
code: src
inputs:
  data_dir:
    type: uri_folder 
    path: azureml://datastores/workspaceblobstore/paths/example-data/
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: входные данные файла URI

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo "--iris-csv: ${{inputs.iris_csv}}"
  python hello-iris.py --iris-csv ${{inputs.iris_csv}}
code: src
inputs:
  iris_csv:
    type: uri_file 
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: входные данные папки URI

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  ls ${{inputs.data_dir}}
  echo "--iris-csv: ${{inputs.data_dir}}/iris.csv"
  python hello-iris.py --iris-csv ${{inputs.data_dir}}/iris.csv
code: src
inputs:
  data_dir:
    type: uri_folder 
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML: Notebook через Papermill

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  pip install ipykernel papermill
  papermill hello-notebook.ipynb outputs/out.ipynb -k python
code: src
environment:
  image: library/python:3.11.6

YAML: основное обучение модели Python

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python main.py 
  --iris-csv ${{inputs.iris_csv}}
  --C ${{inputs.C}}
  --kernel ${{inputs.kernel}}
  --coef0 ${{inputs.coef0}}
inputs:
  iris_csv: 
    type: uri_file
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/iris.csv
  C: 0.8
  kernel: "rbf"
  coef0: 0.1
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
compute: azureml:cpu-cluster
display_name: sklearn-iris-example
experiment_name: sklearn-iris-example
description: Train a scikit-learn SVM on the Iris dataset.

YAML: обучение модели Basic R с локальным контекстом сборки Docker

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: >
  Rscript train.R 
  --data_folder ${{inputs.iris}}
code: src
inputs:
  iris: 
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment:
  build:
    path: docker-context
compute: azureml:cpu-cluster
display_name: r-iris-example
experiment_name: r-iris-example
description: Train an R model on the Iris dataset.

YAML: распределенный PyTorch

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py 
  --epochs ${{inputs.epochs}}
  --learning-rate ${{inputs.learning_rate}}
  --data-dir ${{inputs.cifar}}
inputs:
  epochs: 1
  learning_rate: 0.2
  cifar: 
     type: uri_folder
     path: azureml:cifar-10-example@latest
environment: azureml:AzureML-pytorch-1.9-ubuntu18.04-py37-cuda11-gpu@latest
compute: azureml:gpu-cluster
distribution:
  type: pytorch 
  process_count_per_instance: 1
resources:
  instance_count: 2
display_name: pytorch-cifar-distributed-example
experiment_name: pytorch-cifar-distributed-example
description: Train a basic convolutional neural network (CNN) with PyTorch on the CIFAR-10 dataset, distributed via PyTorch.

YAML: распределенный TensorFlow

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py 
  --epochs ${{inputs.epochs}}
  --model-dir ${{inputs.model_dir}}
inputs:
  epochs: 1
  model_dir: outputs/keras-model
environment: azureml:AzureML-tensorflow-2.4-ubuntu18.04-py37-cuda11-gpu@latest
compute: azureml:gpu-cluster
resources:
  instance_count: 2
distribution:
  type: tensorflow
  worker_count: 2
display_name: tensorflow-mnist-distributed-example
experiment_name: tensorflow-mnist-distributed-example
description: Train a basic neural network with TensorFlow on the MNIST dataset, distributed via TensorFlow.

YAML: распределенный MPI

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py
  --epochs ${{inputs.epochs}}
inputs:
  epochs: 1
environment: azureml:AzureML-tensorflow-2.7-ubuntu20.04-py38-cuda11-gpu@latest
compute: azureml:gpu-cluster
resources:
  instance_count: 2
distribution:
  type: mpi
  process_count_per_instance: 1
display_name: tensorflow-mnist-distributed-horovod-example
experiment_name: tensorflow-mnist-distributed-horovod-example
description: Train a basic neural network with TensorFlow on the MNIST dataset, distributed via Horovod.

Дальнейшие действия