CLI (v2) 命令作業 YAML 結構描述

  • 發行項

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

您可以在 https://azuremlschemas.azureedge.net/latest/commandJob.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 字串 作業的名稱。 必須是工作區所有作業中的唯一名稱。 如果省略，Azure Machine Learning 會自動產生名稱的 GUID。
display_name 字串 工作室 UI 中作業的顯示名稱。 在工作區內不一定要是唯一名稱。 如果省略，Azure Machine Learning 會針對顯示名稱自動產生人類可讀取的形容詞-名詞識別碼。
experiment_name 字串 用來將作業組織到其底下的實驗名稱。 每個作業的執行記錄都會組織在 Studio 的 [實驗] 索引標籤中對應的實驗之下。如果省略，Azure Machine Learning 會將它預設為建立作業的工作目錄名稱。
description 字串 作業的描述。
tags object 作業的標籤字典。
command 字串 必要 (如不使用 component 欄位)。 要執行的命令。
code 字串 要上傳並用於作業的原始程式碼目錄本機路徑。
environment 字串或物件 必要 (如不使用 component 欄位)。 要用於作業的環境。 這可以是工作區中現有已建立版本環境的參考，也可以是內嵌環境規格。

若要參考現有的環境，請使用 azureml:<environment_name>:<environment_version> 語法或 azureml:<environment_name>@latest (以便參考環境的最新版本)。

若要定義內嵌環境，請遵循環境結構描述。 請排除 name 和 version 屬性，因為內嵌環境不支援這些屬性。
environment_variables object 要在命令執行所在流程上設定的環境變數機碼值組字典。
distribution object 分散式定型案例的分散設定。 MpiConfiguration、PyTorchConfiguration 或 TensorFlowConfiguration 其中一個。
compute 字串 計算目標的名稱，代表要執行作業的地方。 這可以是工作區中現有計算的參考 (使用 azureml:<compute_name> 語法) 或要指定本機執行的 local。 注意： 管線中的作業不支援 local 作為 compute local
resources.instance_count 整數 要用於作業的節點數目。 1
resources.instance_type 字串 要用於作業的執行個體類型。 適用於在啟用 Azure Arc 的 Kubernetes 計算上執行的作業 (其中計算目標會於 type: kubernentes 的 compute 欄位中指定)。 如果省略，則會將此預設為 Kubernetes 叢集的預設執行個體類型。 如需詳細資訊，請參閱建立和選取 Kubernetes 執行個體類型。
resources.shm_size string Docker 容器的共用記憶體區塊大小。 這應該是 <number><unit> number 必須大於 0 的格式，而單位可以是其中一個 b (個位元組) 、 (KB) 、 km (MB) ，或 g (GB) 。 2g
limits.timeout 整數 允許執行作業的時間上限，以秒為單位。 一旦達到此限制，系統就會取消作業。
inputs object 作業輸入的字典。 索引鍵是作業內容中的輸入名稱，值則是輸入值。

您可以使用 ${{ inputs.<input_name> }} 運算式在 command 中參考輸入。
inputs.<input_name> 數字、整數、布林值、字串或物件 其中一個常值 (類型為數字、整數、布林值或字串) 或包含作業輸入資料規格的物件。
outputs object 作業輸出設定的字典。 索引鍵是作業內容中的輸出名稱，值則是輸出設定。

您可以使用 ${{ outputs.<output_name> }} 運算式在 command 中參考輸出。
outputs.<output_name> object 您可以將物件保留空白，在此情況下，輸出會是 類型 uri_folder ，而 Azure Machine Learning 會系統產生輸出的輸出位置。 輸出目錄的檔案會透過讀寫掛接寫入。 如果要指定不同的輸出模式，請提供包含作業輸出規格的物件。
identity object 身分識別用於資料存取。 它可以是 UserIdentityConfiguration、 ManagedIdentityConfiguration 或 None。 如果是 UserIdentityConfiguration 作業提交者的身分識別，將會用來存取輸入資料並將結果寫入輸出檔案夾，否則將會使用計算目標的受控識別。

分散設定

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, mlflow_model, custom_model uri_folder
path 字串 要作為輸入之資料的路徑。 這能以一些方式指定：

- 資料來源檔案或資料夾的本機路徑，例如 path: ./iris.csv。 資料會在作業提交期間上傳。

- 要作為輸入之檔案或資料夾的雲端路徑 URI。 支援的 URI 類型為 azureml、https、wasbs、abfss 及 adl。 如需如何使用 azureml:// URI 格式的詳細資訊，請參閱核心 YAML 語法。

- 現有的已註冊 Azure Machine Learning 資料資產，用來作為輸入。 若要參考已註冊的資料資產，請使用 azureml:<data_name>:<data_version> 語法或 azureml:<data_name>@latest (以參考該資料資產的最新版本)，例如 path: azureml:cifar10-data:1 或 path: azureml:cifar10-data@latest。
mode 字串 用來將資料傳送至計算目標的模式。

針對唯讀掛接 (ro_mount)，會以掛接路徑的形式取用資料。 資料夾會掛接為資料夾，檔案則會掛接為檔案。 Azure Machine Learning 會將輸入解析為掛接路徑。

若為 download 模式，資料會下載至計算目標。 Azure Machine Learning 會將輸入解析為下載的路徑。

如果只想要資料成品儲存位置的 URL，而不想掛接或下載資料本身，您可以使用 direct 模式。 這會傳入儲存位置的 URL 作為作業輸入。 請注意，在此情況中，您完全負責處理認證以存取儲存位置。

eval_mount和 eval_download 模式對 MLTable 而言是唯一的，並將資料掛接為路徑，或將資料下載至計算目標。

如需模式的詳細資訊，請參閱 存取作業中的資料		 ro_mount, download, direct, eval_download, eval_mount ro_mount

作業輸出

索引鍵 類型 描述 允許的值 預設值
type 字串 作業輸出的類型。 針對預設 uri_folder 類型，輸出會對應至資料夾。 uri_folder , mlflow_model, custom_model uri_folder
mode 字串 用來將輸出檔案傳送至目的地儲存體的模式。 針對讀寫掛接模式 (rw_mount)，輸出目錄會是已掛接的目錄。 針對上傳模式，寫入的檔案會在作業結束時上傳。 rw_mount, upload rw_mount

身分識別組態

UserIdentityConfiguration

索引鍵 類型 描述 允許的值
type const 必要。 身分識別類型。 user_identity

ManagedIdentityConfiguration

索引鍵 類型 描述 允許的值
type const 必要。 身分識別類型。 managed 或 managed_identity

備註

您可以使用 az ml job 命令來管理 Azure Machine Learning 作業。

範例

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

YAML：hello world

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world"
environment:
  image: library/python:latest

YAML：顯示名稱、實驗名稱、描述和標籤

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world"
environment:
  image: library/python:latest
tags:
  hello: world
display_name: hello-world-example
experiment_name: hello-world-example
description: |
  # Azure Machine Learning "hello world" job

  This is a "hello world" job running in the cloud via Azure Machine Learning!

  ## Description

  Markdown is supported in the studio for job descriptions! You can edit the description there or via CLI.

YAML：環境變數

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo $hello_env_var
environment:
  image: library/python:latest
environment_variables:
  hello_env_var: "hello world"

YAML：原始程式碼

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: ls
code: src
environment:
  image: library/python:latest

YAML：常值輸入

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo ${{inputs.hello_string}}
  echo ${{inputs.hello_number}}
environment:
  image: library/python:latest
inputs:
  hello_string: "hello world"
  hello_number: 42

YAML：寫入至預設輸出

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world" > ./outputs/helloworld.txt
environment:
  image: library/python:latest

YAML：寫入至具名資料輸出

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: echo "hello world" > ${{outputs.hello_output}}/helloworld.txt
outputs:
  hello_output:
environment:
  image: python

YAML：資料存放區 URI 檔案輸入

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo "--iris-csv: ${{inputs.iris_csv}}"
  python hello-iris.py --iris-csv ${{inputs.iris_csv}}
code: src
inputs:
  iris_csv:
    type: uri_file 
    path: azureml://datastores/workspaceblobstore/paths/example-data/iris.csv
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML：資料存放區 URI 資料夾輸入

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  ls ${{inputs.data_dir}}
  echo "--iris-csv: ${{inputs.data_dir}}/iris.csv"
  python hello-iris.py --iris-csv ${{inputs.data_dir}}/iris.csv
code: src
inputs:
  data_dir:
    type: uri_folder 
    path: azureml://datastores/workspaceblobstore/paths/example-data/
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML：URI 檔案輸入

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  echo "--iris-csv: ${{inputs.iris_csv}}"
  python hello-iris.py --iris-csv ${{inputs.iris_csv}}
code: src
inputs:
  iris_csv:
    type: uri_file 
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML：URI 資料夾輸入

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  ls ${{inputs.data_dir}}
  echo "--iris-csv: ${{inputs.data_dir}}/iris.csv"
  python hello-iris.py --iris-csv ${{inputs.data_dir}}/iris.csv
code: src
inputs:
  data_dir:
    type: uri_folder 
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

YAML：透過 Papermill 的筆記本

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: |
  pip install ipykernel papermill
  papermill hello-notebook.ipynb outputs/out.ipynb -k python
code: src
environment:
  image: library/python:3.11.6

YAML：基本 Python 模型定型

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python main.py 
  --iris-csv ${{inputs.iris_csv}}
  --C ${{inputs.C}}
  --kernel ${{inputs.kernel}}
  --coef0 ${{inputs.coef0}}
inputs:
  iris_csv: 
    type: uri_file
    path: wasbs://datasets@azuremlexamples.blob.core.windows.net/iris.csv
  C: 0.8
  kernel: "rbf"
  coef0: 0.1
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
compute: azureml:cpu-cluster
display_name: sklearn-iris-example
experiment_name: sklearn-iris-example
description: Train a scikit-learn SVM on the Iris dataset.

YAML：使用本機 Docker 組建內容進行基本 R 模型定型

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
command: >
  Rscript train.R 
  --data_folder ${{inputs.iris}}
code: src
inputs:
  iris: 
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment:
  build:
    path: docker-context
compute: azureml:cpu-cluster
display_name: r-iris-example
experiment_name: r-iris-example
description: Train an R model on the Iris dataset.

YAML：分散式 PyTorch

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py 
  --epochs ${{inputs.epochs}}
  --learning-rate ${{inputs.learning_rate}}
  --data-dir ${{inputs.cifar}}
inputs:
  epochs: 1
  learning_rate: 0.2
  cifar: 
     type: uri_folder
     path: azureml:cifar-10-example@latest
environment: azureml:AzureML-pytorch-1.9-ubuntu18.04-py37-cuda11-gpu@latest
compute: azureml:gpu-cluster
distribution:
  type: pytorch 
  process_count_per_instance: 1
resources:
  instance_count: 2
display_name: pytorch-cifar-distributed-example
experiment_name: pytorch-cifar-distributed-example
description: Train a basic convolutional neural network (CNN) with PyTorch on the CIFAR-10 dataset, distributed via PyTorch.

YAML：分散式 TensorFlow

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py 
  --epochs ${{inputs.epochs}}
  --model-dir ${{inputs.model_dir}}
inputs:
  epochs: 1
  model_dir: outputs/keras-model
environment: azureml:AzureML-tensorflow-2.4-ubuntu18.04-py37-cuda11-gpu@latest
compute: azureml:gpu-cluster
resources:
  instance_count: 2
distribution:
  type: tensorflow
  worker_count: 2
display_name: tensorflow-mnist-distributed-example
experiment_name: tensorflow-mnist-distributed-example
description: Train a basic neural network with TensorFlow on the MNIST dataset, distributed via TensorFlow.

YAML：分散式 MPI

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python train.py
  --epochs ${{inputs.epochs}}
inputs:
  epochs: 1
environment: azureml:AzureML-tensorflow-2.7-ubuntu20.04-py38-cuda11-gpu@latest
compute: azureml:gpu-cluster
resources:
  instance_count: 2
distribution:
  type: mpi
  process_count_per_instance: 1
display_name: tensorflow-mnist-distributed-horovod-example
experiment_name: tensorflow-mnist-distributed-horovod-example
description: Train a basic neural network with TensorFlow on the MNIST dataset, distributed via Horovod.

後續步驟