CLI (v2) 核心 YAML 語法
每個 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> }}
以下涵蓋支援的案例。
使用作業的 inputs 和 outputs 內容參數化command
您可以將常值、URI 路徑和已註冊的 Azure 機器學習 數據資產指定為作業的輸入。 command然後可以使用 語法，使用${{inputs.<input_name>}}這些輸入的參考來參數化 。 常值輸入的參考會在運行時間解析為常值，而數據輸入的參考會解析為下載路徑或掛接路徑（視 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.windows.net/datasets/iris.csv
mode: download
outputs:
model_dir:
使用search_space掃掠作業的內容參數化command
透過掃掠作業執行超參數微調時，您也會使用此表達式語法，因為作業撰寫期間不知道超參數的實際值。 當您執行掃掠作業時，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 內容，因此最上層的輸入/輸出。
在下列範例中，第一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>。
在下列範例中，步驟的輸入 （training_data） 會透過 ${{parent.jobs.prep.outputs.clean_data}}系結至步驟的prep輸出 （clean_data）。train 步驟中 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
使用 inputs 元件的和 outputs 內容參數化command
與command作業的 類似，command元件也可以使用 和 outputs 內容的參考inputs參數化元件。 在此情況下，參考是元件的輸入和輸出。 當元件在作業中執行時，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 的路徑。