CLI (v2) 核心 YAML 语法

Artículo
08/29/2024

适用于：Azure CLI ml 扩展 v2（当前）

每个 Azure 机器学习实体都有一种架构化的 YAML 表示形式。你可以从扩展名为 .yml 或 .yaml 的 YAML 配置文件创建新实体。

本文概述了在配置这些 YAML 文件时你会遇到的核心语法概念。

引用 Azure 机器学习实体

Azure 机器学习提供参考语法（由简写和整写格式组成），用于在配置 YAML 文件时引用现有的 Azure 机器学习实体。例如，可以引用工作区中现有的已注册环境，以用作某个作业的环境。

引用 Azure 机器学习资产

引用 Azure 机器学习资产（环境、模型、数据和组件）时，可以使用两个选项：

引用资产的显式版本：

简写语法：azureml:<asset_name>:<asset_version>
整写语法，其中包括资产的 Azure 资源管理器 (ARM) 资源 ID：

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 资源 ID：

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

Azure 机器学习数据引用 URI

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

除了 Azure 机器学习数据引用 URI 以外，Azure 机器学习还支持以下直接存储 URI 协议：https、wasbs、abfss 和 adl，以及公共 http 和 https URI。

用于配置 Azure 机器学习作业和组件的表达式语法

v2 作业和组件 YAML 文件允许使用表达式绑定到不同方案的上下文。最基本用例是对创建配置时可能未知的，但在运行时必须解析的值使用表达式。

使用以下语法告知 Azure 机器学习要计算表达式而不是将其视为字符串：

${{ <expression> }}

下面介绍了支持的方案。

使用作业的 `inputs` 和 `outputs` 上下文参数化 `command`

可以指定文本值、URI 路径和注册的 Azure 机器学习数据资产作为作业的输入。然后，可以使用 ${{inputs.<input_name>}} 语法通过引用这些输入来参数化 command。对文本输入的引用将在运行时解析为文本值，而对数据输入的引用将解析为下载路径或装载路径（取决于指定的 mode）。

同样，作业的输出也可以在 command 中引用。对于 outputs 字典中指定的每个命名输出，Azure 机器学习将在文件可写入到的默认数据存储上系统生成一个输出位置。每个命名输出的输出位置基于以下模板化路径：<default-datastore>/azureml/<job-name>/<output_name>/。使用 ${{outputs.<output_name>}} 语法参数化 command 会将该引用解析为系统生成的路径，因此脚本可以从作业将文件写入该位置。

在以下命令作业 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.chinacloudapi.cn/datasets/iris.csv
    mode: download
outputs:
  model_dir:

使用扫描作业的 `search_space` 上下文参数化 `command`

在通过扫描作业执行超参数优化时，也会使用此表达式语法，因为在作业创建期间，超参数的实际值是未知的。当你运行扫描作业时，Azure 机器学习将根据 search_space 为每个试运行选择超参数值。若要在训练脚本中访问这些值，必须通过该脚本的命令行参数传递这些值。为此，可在 trial.command 中使用 ${{search_space.<hyperparameter>}} 语法。

在以下扫描作业 YAML 文件示例中，trial.command 中的 ${{search_space.learning_rate}} 和 ${{search_space.boosting}} 引用将解析为在提交试运行作业以供执行时为每个试运行选择的实际超参数值。

$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.chinacloudapi.cn/datasets/iris.csv
    mode: download
compute: azureml:cpu-cluster

在管道作业中的步骤之间绑定输入和输出

表达式还用于在管道作业中的步骤之间绑定输入和输出。例如，可将管道中一个作业（作业 B）的输入绑定到另一个作业（作业 A）的输出。此用法将向 Azure 机器学习告知管道图的依赖关系流，作业 B 将在作业 A 之后执行，因为作业 A 的输出需要用作作业 B 的输入。

对于管道作业 YAML 文件，每个子作业的 inputs 和 outputs 部分将在父上下文（顶级管道作业）中评估。另一方面，command 将解析为当前上下文（子作业）。

可通过两种方式在管道作业中绑定输入和输出：

绑定到管道作业的顶级输入和输出

可使用以下语法将子作业（管道步骤）的输入或输出绑定到顶级父管道作业的输入/输出：${{parent.inputs.<input_name>}} 或 ${{parent.outputs.<output_name>}}。此引用将解析为 parent 上下文，因此会解析为顶级输入/输出。

在以下示例中，第一个 prep 步骤的输入 (raw_data) 通过 ${{parent.inputs.input_data}} 绑定到顶级管道输入。最后一个 train 步骤的输出 (model_dir) 通过 ${{parent.outputs.trained_model}} 绑定到顶级管道作业输出。

绑定到另一个子作业（步骤）的输入和输出

若要将一个步骤的输入/输出绑定到另一步骤的输入/输出，请使用以下语法：${{parent.jobs.<step_name>.inputs.<input_name>}} 或 ${{parent.jobs.<step_name>.outputs.<outputs_name>}}。同样，此引用将解析为父上下文，因此表达式必须以 parent.jobs.<step_name> 开头。

在以下示例中，train 步骤的输入 (training_data) 通过 ${{parent.jobs.prep.outputs.clean_data}} 绑定到 prep 步骤的输出 (clean_data)。 prep 步骤中已准备好的数据将用作 train 步骤的训练数据。

另一方面，command 属性中的上下文引用将解析为当前上下文。例如，prep 步骤的 command 中的 ${{inputs.raw_data}} 引用将解析为当前上下文（即 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.chinacloudapi.cn/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

使用组件的 `inputs` 和 `outputs` 上下文参数化 `command`

与作业的 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}} 将解析为新的默认数据存储，而不是创建计划作业时的默认数据存储。

表达式	说明	作用域
`${{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 的路径。

Compartir a través de

CLI (v2) 核心 YAML 语法

引用 Azure 机器学习实体

引用 Azure 机器学习资产

引用 Azure 机器学习资源

Azure 机器学习数据引用 URI

用于配置 Azure 机器学习作业和组件的表达式语法

使用作业的 `inputs` 和 `outputs` 上下文参数化 `command`

使用扫描作业的 `search_space` 上下文参数化 `command`

在管道作业中的步骤之间绑定输入和输出

使用组件的 `inputs` 和 `outputs` 上下文参数化 `command`

在命令行中定义可选输入

输出路径表达式

后续步骤

Recursos adicionales

Compartir a través de

CLI (v2) 核心 YAML 语法

引用 Azure 机器学习实体

引用 Azure 机器学习资产

引用 Azure 机器学习资源

Azure 机器学习数据引用 URI

用于配置 Azure 机器学习作业和组件的表达式语法

使用作业的 inputs 和 outputs 上下文参数化 command

使用扫描作业的 search_space 上下文参数化 command

在管道作业中的步骤之间绑定输入和输出

使用组件的 inputs 和 outputs 上下文参数化 command

在命令行中定义可选输入

输出路径表达式

后续步骤

Recursos adicionales

使用作业的 `inputs` 和 `outputs` 上下文参数化 `command`

使用扫描作业的 `search_space` 上下文参数化 `command`

使用组件的 `inputs` 和 `outputs` 上下文参数化 `command`