CLI (v2) 核心 YAML 語法

適用於：Azure CLI ml 延伸模組 v2 (目前)

每個 Azure 機器學習實體都有架構化的 YAML 表示法。您可以從 YAML 組態檔建立具有 .yml 或 .yaml 擴展名的新實體。

本文提供您在設定這些 YAML 檔案時會遇到的核心語法概念概觀。

參考 Azure 機器學習實體

Azure 機器學習提供參考語法（包含速記和長手格式），以在設定 YAML 檔案時參考現有的 Azure 機器學習實體。例如，您可以參考工作區中現有的已註冊環境，以做為作業的環境。

參考 Azure 機器學習資產

有兩個選項可用來參考 Azure 機器學習資產（環境、模型、數據和元件）：

參考資產的明確版本：

速記語法： azureml:<asset_name>:<asset_version>
Longhand 語法，其中包含資產的 Azure Resource Manager （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>
Longhand 語法，其中包含資源的 ARM 資源識別碼：

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

以下涵蓋支援的案例。

使用作業的 `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

在管線作業中的步驟之間系結輸入和輸出

表達式也用於系結管線作業中步驟之間的輸入和輸出。例如，您可以將管線中一個作業（作業 B）的輸入系結至另一個作業的輸出（作業 A）。此使用方式會向 Azure 發出訊號，機器學習管線圖形的相依性流程，而作業 B 會在作業 A 之後執行，因為作業 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}}步驟 prep 中的command參考會解析為目前內容的輸入，也就是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}} 會解析為新的預設資料存放區，而不是建立排程作業時的預設資料存放區。

運算式	描述	範圍
`${{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 的路徑。

下一步

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2025-02-10

CLI (v2) 核心 YAML 語法

參考 Azure 機器學習 實體

參考 Azure 機器學習 資產

參考 Azure 機器學習 資源

Azure 機器學習 數據參考 URI

設定 Azure 機器學習 作業和元件的表達式語法

使用作業的 command 和 inputs 內容參數化outputs

使用command掃掠作業的內容參數化search_space