CLI (v2) 命令元件 YAML 結構描述

  • 發行項

適用於：Azure CLI ml 延伸模組第 2 版 (目前)

您可以在 https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json 中找到來源 JSON 結構描述。

注意

此文件中詳述的 YAML 語法是以最新版 ML CLI v2 延伸模組的 JSON 結構描述為基礎。 此語法只保證能與最新版的 ML CLI v2 延伸模組搭配使用。 您可以在 https://azuremlschemasprod.azureedge.net/ 找到舊版延伸模組的結構描述。

YAML 語法

索引鍵 類型 描述 允許的值 預設值
$schema 字串 YAML 結構描述。 如果您使用 Azure Machine Learning VS Code 擴充功能來撰寫 YAML 檔案，在檔案頂端包含 $schema 可讓您叫用結構描述和資源完成。
type const 元件的類型。 command command
name 字串 必要。 元件的名稱。 必須以小寫字母開頭。 允許的字元為小寫字母、數字和底線 (_)。 長度上限是 255 個字元。
version 字串 元件的版本。 如果省略，Azure Machine Learning 會自動產生版本。
display_name 字串 工作室 UI 中元件的顯示名稱。 在工作區內不一定要是唯一名稱。
description 字串 元件的描述。
tags object 元件的標籤字典。
is_deterministic boolean 此選項會判斷元件是否會針對相同的輸入資料產生相同的輸出。 針對從外部來源載入資料的元件，通常應該將此設定 false 為 ，例如從 URL 匯入資料。 這是因為 URL 上的資料可能會隨著時間而變更。 true
command 字串 必要。 要執行的命令。
code 字串 要上傳並用於元件的原始程式碼目錄本機路徑。
environment 字串或物件 必要。 要用於元件的環境。 此值可以是工作區中現有已建立版本環境的參考，也可以是內嵌環境規格。

若要參考現有的環境，請使用 azureml:<environment-name>:<environment-version> 語法。

若要定義內嵌環境，請遵循環境結構描述。 請排除 name 和 version 屬性，因為內嵌環境不支援這些屬性。
distribution object 分散式定型案例的分散設定。 MpiConfiguration、PyTorchConfiguration 或 TensorFlowConfiguration 其中一個。
resources.instance_count 整數 要用於作業的節點數目。 1
inputs object 元件輸入的字典。 索引鍵是元件內容內的輸入名稱，值則是元件輸入定義。

您可以使用 ${{ inputs.<input_name> }} 運算式在 command 中參考輸入。
inputs.<input_name> object 元件輸入定義。 請參閱可設定屬性集的元件輸入。
outputs object 元件輸出的字典。 索引鍵是元件內容內的輸出名稱，值則是元件輸出定義。

您可以使用 ${{ outputs.<output_name> }} 運算式在 command 中參考輸出。
outputs.<output_name> object 元件輸出定義。 請參閱可設定屬性集的元件輸出。

分散設定

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 字串 必要。 元件輸入的類型。 深入了解資料存取 number, integer, boolean, string, uri_file, uri_folder, mltable, mlflow_model
description 字串 輸入的描述。
default 數字、整數、布林值或字串 輸入的預設值。
optional boolean 輸入是否為必要項。 如果設定為 true，您需要使用包含選擇性輸入的命令搭配 $[[]] false
min 整數或數字 輸入的可接受最小值。 只有當 type 欄位是 number 或 integer 時，才能指定此欄位。
max 整數或數字 輸入的可接受最大值。 只有當 type 欄位是 number 或 integer 時，才能指定此欄位。
enum array 輸入的允許值清單。 僅適用於 type 欄位是 string 時。

元件輸出

索引鍵 類型 描述 允許的值 預設值
type 字串 必要。 元件輸出的類型。 uri_file, uri_folder, mltable, mlflow_model
description 字串 輸出的描述。

備註

您可以使用 az ml component 命令來管理 Azure Machine Learning 元件。

範例

範例 GitHub 存放庫中有命令元件範例可用。 選取範例如下所示。

範例 GitHub 存放庫中有範例可用。 以下顯示其中幾個。

YAML：Hello World 命令元件

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
type: command

name: hello_python_world
display_name: Hello_Python_World
version: 1

code: ./src

environment: 
  image: python

command: >-
  python hello.py

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

常見錯誤和建議

以下是定義元件時的一些常見錯誤和對應的建議建議。

答案 錯誤 建議
命令 1.只有選擇性輸入可以位於 $[[]]
2.命令不支援使用 \ 來建立新行。
3.找不到輸入或輸出。		 1. 檢查 命令中使用的所有輸入或輸出都已在 和 outputs 區段中定義 inputs ，並使用正確的格式進行選擇性輸入 $[[]] 或必要 ${{}} 輸入。
2.請勿使用 \ 來建立新行。
Environment 1.環境 {envName} 版本 {envVersion} 沒有定義。
2.名稱 {envName} 、版本 {envVersion} 沒有環境存在。
3. 找不到識別碼為 的資產 {envAssetId} 。		 1.請確定您在元件定義中參考的環境名稱和版本存在。
2.如果您參考已註冊的環境，則必須指定版本。
輸入/輸出 1.輸入/輸出名稱與系統保留參數衝突。
2.輸入或輸出的重複名稱。		 1.請勿使用這些保留參數作為您的輸入/輸出名稱： path 、、 homeld_library_pathshelluserlognamepwd 。
2.請確定輸入和輸出的名稱不會重複。

後續步驟