CLI (v2) 扫描作业 YAML 架构

项目
04/12/2024

源 JSON 架构可在 https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json 中找到。

注意

本文档中详细介绍的 YAML 语法基于最新版本的 ML CLI v2 扩展的 JSON 架构。此语法必定仅适用于最新版本的 ML CLI v2 扩展。可以在 https://azuremlschemasprod.azureedge.net/ 上查找早期扩展版本的架构。

YAML 语法

密钥	类型	说明	允许的值	默认值
`$schema`	字符串	YAML 架构。如果使用 Azure 机器学习 VS Code 扩展创作 YAML 文件，可以通过在文件顶部包含 `$schema` 来调用架构和资源完成操作。
`type`	const	必需。作业类型。	`sweep`	`sweep`
`name`	字符串	作业的名称。对工作区中的所有作业必须唯一。如果省略此项，Azure 机器学习将为该名称自动生成一个 GUID。
`display_name`	字符串	作业在工作室 UI 中的显示名称。在工作区中可以不唯一。如果省略此项，Azure 机器学习将为显示名称自动生成人类可读的形容词-名词标识符。
`experiment_name`	string	在试验名称下组织作业。工作室的“试验”选项卡中相应的试验下整理了每项作业的运行记录。如果省略，Azure 机器学习会将 `experiment_name` 默认为创建作业的工作目录的名称。
`description`	string	作业的说明。
`tags`	object	作业的标记字典。
`sampling_algorithm`	object	必需。要对 `search_space` 使用的超参数采样算法。 RandomSamplingAlgorithm、GridSamplingAlgorithm 或 BayesianSamplingAlgorithm 中的一个。
`search_space`	object	必需。超参数搜索空间的字典。超参数名称是键，而值则是参数表达式。可以使用 `${{ search_space.<hyperparameter> }}` 表达式在 `trial.command` 中引用超参数。
`search_space.<hyperparameter>`	object	访问参数表达式，以获取要使用的一组可能的表达式。
`objective.primary_metric`	string	必需。每个试运行作业报告的主要指标的名称。必须使用相应指标名称相同的 `mlflow.log_metric()` 在用户的训练脚本中记录该指标。
`objective.goal`	string	必需。 `objective.primary_metric` 的优化目标。	`maximize`、`minimize`
`early_termination`	object	要使用的提前终止策略。满足指定策略的条件时取消试运行作业。如果省略，则不会应用任何提前终止策略。 BanditPolicy、MedianStoppingPolicy 或 TruncationSelectionPolicy。
`limits`	object	扫描作业的限制。请参阅 `limits` 键的属性。
`compute`	字符串	必需。要对其执行作业的计算目标的名称，其语法为 `azureml:<compute_name>`。
`trial`	object	必需。每个试运行的作业模板。每个试用作业会提供有系统从 `search_space` 中采样的超参数值的不同组合。访问 `trial` 密钥的属性。
`inputs`	object	作业的输入字典。键是作业上下文中的输入名称，值是输入值。可以在 `command` 中使用 `${{ inputs.<input_name> }}` 表达式引用输入。
`inputs.<input_name>`	数字、整数、布尔值、字符串或对象	文本值之一（数字、整数、布尔值或字符串类型）或包含作业输入数据规范的对象。
`outputs`	object	作业的输出配置字典。键是作业上下文中的输出名称，值是输出配置。可以在 `command` 中使用 `${{ outputs.<output_name> }}` 表达式引用输出。
`outputs.<output_name>`	object	可以将该对象留空，在这种情况下，输出会默认为 `uri_folder` 类型，并采用 Azure 机器学习系统为输出生成的输出位置。输出目录的所有文件会通过读写装载写入。要为输出指定不同的模式，请提供包含作业输出规范的对象。
`identity`	object	此标识用于数据访问。它可以是用户标识配置、托管标识配置或 None。对于 UserIdentityConfiguration，将会使用作业提交者的标识来访问输入数据并将结果写入输出文件夹。否则，将使用计算目标的托管标识。

采样算法

RandomSamplingAlgorithm

键	类型	说明	允许的值	默认值
`type`	const	必需。采样算法的类型。	`random`
`seed`	integer	用于初始化随机数生成的随机种子。如果省略，则默认种子值为 null。
`rule`	string	要使用的随机采样的类型。默认值 `random` 使用简单的统一随机采样，而 `sobol` 使用 Sobol 准随机序列。	`random`、`sobol`	`random`

GridSamplingAlgorithm

键	类型	说明	允许的值
`type`	const	必需。采样算法类型。	`grid`

BayesianSamplingAlgorithm

键	类型	说明	允许的值
`type`	const	必需。采样算法类型。	`bayesian`

提前终止策略

BanditPolicy

密钥	类型	说明	允许的值	默认值
`type`	const	必需。策略类型。	`bandit`
`slack_factor`	数字	用于计算与最佳表现试运行之间的允许距离的比率。必须指定 `slack_factor` 或 `slack_amount`。
`slack_amount`	数字	允许与最佳表现试运行之间的绝对距离。必须指定 `slack_factor` 或 `slack_amount`。
`evaluation_interval`	整型	应用策略的频率。		`1`
`delay_evaluation`	整型	延迟第一个策略评估的间隔数。如果指定，则策略将按照大于或等于 `delay_evaluation` 的 `evaluation_interval` 倍数应用。		`0`

MedianStoppingPolicy

密钥	类型	说明	允许的值	默认值
`type`	const	必需。策略类型。	`median_stopping`
`evaluation_interval`	integer	应用策略的频率。		`1`
`delay_evaluation`	整型	延迟第一个策略评估的间隔数。如果指定，则策略将按照大于或等于 `delay_evaluation` 的 `evaluation_interval` 倍数应用。		`0`

TruncationSelectionPolicy

密钥	类型	说明	允许的值	默认值
`type`	const	必需。策略类型。	`truncation_selection`
`truncation_percentage`	integer	必需。在每个评估间隔要取消的试运行作业的百分比。
`evaluation_interval`	整型	应用策略的频率。		`1`
`delay_evaluation`	整型	延迟第一个策略评估的间隔数。如果指定，则策略将按照大于或等于 `delay_evaluation` 的 `evaluation_interval` 倍数应用。		`0`

参数表达式

选择

密钥	类型	说明	允许的值
`type`	const	必需。表达式类型。	`choice`
`values`	数组	必需。要从中选择的离散值的列表。

Randint

密钥	类型	说明	允许的值
`type`	const	必需。表达式类型。	`randint`
`upper`	integer	必需。整数范围的上限（不含）。

Qlognormal、qnormal

密钥	类型	说明	允许的值
`type`	const	必需。表达式类型。	`qlognormal`、`qnormal`
`mu`	数字	必需。正态分布的平均值。
`sigma`	数字	必需。正态分布的标准偏差。
`q`	整型	必需。平滑因子。

Qloguniform、quniform

密钥	类型	说明	允许的值
`type`	const	必需。表达式类型。	`qloguniform`、`quniform`
`min_value`	数字	必需。范围内的最小值（含）。
`max_value`	数字	必需。范围内的最大值（含）。
`q`	整型	必需。平滑因子。

Lognormal、normal

密钥	类型	说明	允许的值
`type`	const	必需。表达式类型。	`lognormal`、`normal`
`mu`	数字	必需。正态分布的平均值。
`sigma`	数字	必需。正态分布的标准偏差。

Loguniform

密钥	类型	说明	允许的值
`type`	const	必需。表达式类型。	`loguniform`
`min_value`	数字	必需。范围内的最小值为 `exp(min_value)`（含）。
`max_value`	数字	必需。范围中的最大值为 `exp(max_value)`（含）。

Uniform

密钥	类型	说明	允许的值
`type`	const	必需。表达式类型。	`uniform`
`min_value`	数字	必需。范围内的最小值（含）。
`max_value`	数字	必需。范围内的最大值（含）。

`limits` 键的属性

键	类型	说明	默认值
`max_total_trials`	整型	最大试用作业数。	`1000`
`max_concurrent_trials`	integer	可以并发运行的最大试用作业数。	默认为 `max_total_trials`。
`timeout`	integer	允许整个扫描作业运行的最长时间（秒）。达到此限制后，系统将取消扫描作业，包括其所有试用。	`5184000`
`trial_timeout`	integer	允许每个试运行作业运行的最长时间（秒）。达到此限制后，系统会取消试用。

`trial` 键的属性

键	类型	说明	默认值
`command`	字符串	必需。要执行的命令。
`code`	字符串	要上传并用于作业的源代码目录的本地路径。
`environment`	字符串或对象	必需。用于作业的环境。此值可以是对工作区中现有版本受控环境的引用，也可以是对内联环境规范的引用。若要引用现有环境，请使用 `azureml:<environment-name>:<environment-version>` 语法。若要以内联方式定义环境，请遵循环境架构。排除 `name` 和 `version` 属性，因为内联环境不支持它们。
`environment_variables`	object	要在执行命令的进程上设置的环境变量名称/值对的字典。
`distribution`	object	分布式训练方案的分布配置。 Mpi 配置、PyTorch 配置或 TensorFlow 配置之一。
`resources.instance_count`	integer	用于作业的节点数。	`1`

分布配置

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`、`mltable`、`mlflow_model`	`uri_folder`
`path`	字符串	用作输入的数据的路径。可以通过几种方式指定此值： - 数据源文件或文件夹的本地路径，例如 `path: ./iris.csv`。数据会在作业提交期间上传。 - 要用作输入的文件或文件夹的云路径的 URI。支持的 URI 类型为 `azureml`、`https`、`wasbs`、`abfss`、`adl`。有关如何使用 `azureml://` URI 格式的详细信息，请访问核心 yaml 语法。 - 要用作输入的现有已注册的 Azure 机器学习数据资产。要引用已注册的数据资产，请使用 `azureml:<data_name>:<data_version>` 语法或 `azureml:<data_name>@latest`（引用该数据资产的最新版本），例如 `path: azureml:cifar10-data:1` 或 `path: azureml:cifar10-data@latest`。
`mode`	string	将数据传送到计算目标的模式。对于只读装载（`ro_mount`），该数据将用作装载路径。文件夹是文件夹装载的，而文件则作为文件装载。 Azure 机器学习会将输入解析为装载路径。对于 `download` 模式，数据将下载到计算目标。 Azure 机器学习会将输入解析为下载的路径。对于数据项目或项目存储位置的 URL，请使用 `direct` 模式，而不是装载或下载数据本身。这会将存储位置的 URL 作为作业输入传入。在这种情况下，你全权负责处理凭证以访问存储。	`ro_mount`、`download`、`direct`	`ro_mount`

作业输出

键	类型	说明	允许的值	默认值
`type`	string	作业输出类型。对于默认的 `uri_folder` 类型，输出对应于某个文件夹。	`uri_file`、`uri_folder`、`mltable`、`mlflow_model`	`uri_folder`
`mode`	string	将输出文件或文件发送到目标存储的模式。对于读写装载模式（`rw_mount`），输出目录是装载的目录。对于上传模式，写入的所有文件会在作业结束时上传。	`rw_mount`、`upload`	`rw_mount`

标识配置

UserIdentityConfiguration

密钥	类型	说明	允许的值
`type`	const	必需。标识类型。	`user_identity`

ManagedIdentityConfiguration

密钥	类型	说明	允许的值
`type`	const	必需。标识类型。	`managed` 或 `managed_identity`

注解

可以使用 az ml job 命令管理 Azure 机器学习作业。

示例

有关示例，请访问示例 GitHub 存储库。下面显示了几个示例：

YAML：hello sweep

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
trial:
  command: >-
    python hello-sweep.py
    --A ${{inputs.A}}
    --B ${{search_space.B}}
    --C ${{search_space.C}}
  code: src
  environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
inputs:
  A: 0.5
sampling_algorithm: random
search_space:
  B:
    type: choice
    values: ["hello", "world", "hello_world"]
  C:
    type: uniform
    min_value: 0.1
    max_value: 1.0
objective:
  goal: minimize
  primary_metric: random_metric
limits:
  max_total_trials: 4
  max_concurrent_trials: 2
  timeout: 3600
display_name: hello-sweep-example
experiment_name: hello-sweep-example
description: Hello sweep job example.

YAML：基本 Python 模型超参数优化

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
trial:
  code: src
  command: >-
    python main.py 
    --iris-csv ${{inputs.iris_csv}}
    --C ${{search_space.C}}
    --kernel ${{search_space.kernel}}
    --coef0 ${{search_space.coef0}}
  environment: azureml:AzureML-sklearn-0.24-ubuntu18.04-py37-cpu@latest
inputs:
  iris_csv: 
    type: uri_file
    path: wasbs://datasets@azuremlexamples.blob.core.chinacloudapi.cn/iris.csv
compute: azureml:cpu-cluster
sampling_algorithm: random
search_space:
  C:
    type: uniform
    min_value: 0.5
    max_value: 0.9
  kernel:
    type: choice
    values: ["rbf", "linear", "poly"]
  coef0:
    type: uniform
    min_value: 0.1
    max_value: 1
objective:
  goal: minimize
  primary_metric: training_f1_score
limits:
  max_total_trials: 20
  max_concurrent_trials: 10
  timeout: 7200
display_name: sklearn-iris-sweep-example
experiment_name: sklearn-iris-sweep-example
description: Sweep hyperparemeters for training a scikit-learn SVM on the Iris dataset.

后续步骤

安装并使用 CLI (v2)