CLI （v1）管線作業 YAML 架構

發行項
09/01/2024

注意

本文件中詳述的 YAML 語法是以適用於 ML CLI 延伸模組 v1 版本的 JSON 架構為基礎。此語法保證只能使用ML CLI v1擴充功能。針對 ML CLI v2 的語法切換至 v2 （目前版本）。

重要

本文中的 Azure CLI 命令使用 azure-cli-ml 或 v1 (Azure Machine Learning 的擴充功能)。 v1 擴充功能的支援將於 2025 年 9 月 30 日終止。您將能安裝並使用 v1 擴充功能，直到該日期為止。

建議您在 2025 年 9 月 30 日之前轉換至 ml 或 v2 擴充功能。如需有關 v2 擴充功能的詳細資訊，請參閱 Azure ML CLI 擴充功能和 Python SDK v2。

在 YAML 中定義您的機器學習管線。針對 Azure CLI v1 使用機器學習延伸模組時，許多管線相關命令預期會有定義管線的 YAML 檔案。

下表列出在 YAML 中定義管線以搭配 CLI v1 使用時目前不支援的內容：

步驟類型	是否支援？
PythonScriptStep	Yes
ParallelRunStep	Yes
AdlaStep	Yes
AzureBatchStep	Yes
DatabricksStep	Yes
DataTransferStep	Yes
AutoMLStep	No
HyperDriveStep	No
ModuleStep	Yes
MPIStep	No
EstimatorStep	No

管線定義

管線定義會使用下列索引鍵，其對應至 Pipelines 類別：

YAML 金鑰	描述
`name`	管線的描述。
`parameters`	參數（s）至管線。
`data_reference`	定義如何在執行中提供數據及位置。
`default_compute`	管線執行中所有步驟的預設計算目標。
`steps`	管線中使用的步驟。

參數

區 parameters 段使用下列對應至 PipelineParameter 類別的索引鍵：

YAML 金鑰	描述
`type`	參數的實值型別。有效的類型為`string`、、`floatint`、 `bool`或 `datapath`。
`default`	預設值。

每個參數都會命名。例如，下列 YAML 代碼段會定義三個名為 NumIterationsParameter、 DataPathParameter和 NodeCountParameter的參數：

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        NumIterationsParameter:
            type: int
            default: 40
        DataPathParameter:
            type: datapath
            default:
                datastore: workspaceblobstore
                path_on_datastore: sample2.txt
        NodeCountParameter:
            type: int
            default: 4

資料參考

區data_references段會使用下列對應至 DataReference 的索引鍵：

YAML 金鑰	描述
`datastore`	要參考的數據存放區。
`path_on_datastore`	數據參考之備份記憶體中的相對路徑。

每個數據參考都包含在索引鍵中。例如，下列 YAML 代碼段會定義儲存在名為 employee_data之索引鍵中的數據參考：

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        employee_data:
            datastore: adftestadla
            path_on_datastore: "adla_sample/sample_input.csv"

步驟

步驟會定義計算環境，以及要在環境上執行的檔案。若要定義步驟的類型，請使用 type 機碼：

步驟類型	描述
`AdlaStep`	使用 Azure Data Lake Analytics 執行 U-SQL 腳本。對應至 AdlaStep 類別。
`AzureBatchStep`	使用 Azure Batch 執行作業。對應至 AzureBatchStep 類別。
`DatabricsStep`	新增 Databricks 筆記本、Python 腳本或 JAR。對應至 DatabricksStep 類別。
`DataTransferStep`	在記憶體選項之間傳輸數據。對應至 DataTransferStep 類別。
`PythonScriptStep`	執行 Python 腳本。對應至 PythonScriptStep 類別。
`ParallelRunStep`	執行 Python 腳本，以異步和平行方式處理大量數據。對應至 ParallelRunStep 類別。

ADLA 步驟

YAML 金鑰	描述
`script_name`	U-SQL 腳本的名稱（相對於 `source_directory`）。
`compute`	要用於此步驟的 Azure Data Lake 計算目標。
`parameters`	管線的參數。
`inputs`	輸入可以是 InputPortBinding、DataReference、PortDataReference 、PipelineData、Dataset、DatasetDefinition 或 PipelineDataset。
`outputs`	輸出可以是 PipelineData 或 OutputPortBinding。
`source_directory`	包含腳本、元件等的目錄。
`priority`	要用於目前作業的優先順序值。
`params`	名稱/值組的字典。
`degree_of_parallelism`	要用於此作業的平行處理原則程度。
`runtime_version`	Data Lake Analytics 引擎的運行時間版本。
`allow_reuse`	判斷使用相同設定再次執行時，步驟是否應該重複使用先前的結果。

下列範例包含 ADLA 步驟定義：

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        employee_data:
            datastore: adftestadla
            path_on_datastore: "adla_sample/sample_input.csv"
    default_compute: adlacomp
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "AdlaStep"
            name: "MyAdlaStep"
            script_name: "sample_script.usql"
            source_directory: "D:\\scripts\\Adla"
            inputs:
                employee_data:
                    source: employee_data
            outputs:
                OutputData:
                    destination: Output4
                    datastore: adftestadla
                    bind_mode: mount

Azure Batch 步驟

YAML 金鑰	描述
`compute`	要用於此步驟的 Azure Batch 計算目標。
`inputs`	輸入可以是 InputPortBinding、DataReference、PortDataReference 、PipelineData、Dataset、DatasetDefinition 或 PipelineDataset。
`outputs`	輸出可以是 PipelineData 或 OutputPortBinding。
`source_directory`	包含模組二進位檔、可執行檔、元件等的目錄。
`executable`	將在此作業中執行之命令/可執行文件的名稱。
`create_pool`	布爾值旗標，指出在執行作業之前是否要建立集區。
`delete_batch_job_after_finish`	布爾值旗標，指出是否要在作業完成之後，從 Batch 帳戶中刪除作業。
`delete_batch_pool_after_finish`	布爾值旗標，指出是否要在作業完成之後刪除集區。
`is_positive_exit_code_failure`	布爾值旗標，指出工作是否以正代碼結束作業失敗。
`vm_image_urn`	如果 `create_pool` 為 `True`，且 VM 會使用 `VirtualMachineConfiguration`。
`pool_id`	作業執行所在集區的標識碼。
`allow_reuse`	判斷使用相同設定再次執行時，步驟是否應該重複使用先前的結果。

下列範例包含 Azure Batch 步驟定義：

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        input:
            datastore: workspaceblobstore
            path_on_datastore: "input.txt"
    default_compute: testbatch
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "AzureBatchStep"
            name: "MyAzureBatchStep"
            pool_id: "MyPoolName"
            create_pool: true
            executable: "azurebatch.cmd"
            source_directory: "D:\\scripts\\AureBatch"
            allow_reuse: false
            inputs:
                input:
                    source: input
            outputs:
                output:
                    destination: output
                    datastore: workspaceblobstore

Databricks 步驟

YAML 金鑰	描述
`compute`	要用於此步驟的 Azure Databricks 計算目標。
`inputs`	輸入可以是 InputPortBinding、DataReference、PortDataReference 、PipelineData、Dataset、DatasetDefinition 或 PipelineDataset。
`outputs`	輸出可以是 PipelineData 或 OutputPortBinding。
`run_name`	此執行之 Databricks 中的名稱。
`source_directory`	包含腳本和其他檔案的目錄。
`num_workers`	Databricks 執行叢集的靜態背景工作角色數目。
`runconfig`	檔案的路徑 `.runconfig` 。此檔案是 RunConfiguration 類別的 YAML 表示法。如需此檔案結構的詳細資訊，請參閱 runconfigschema.json。
`allow_reuse`	判斷使用相同設定再次執行時，步驟是否應該重複使用先前的結果。

下列範例包含 Databricks 步驟：

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        adls_test_data:
            datastore: adftestadla
            path_on_datastore: "testdata"
        blob_test_data:
            datastore: workspaceblobstore
            path_on_datastore: "dbtest"
    default_compute: mydatabricks
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "DatabricksStep"
            name: "MyDatabrickStep"
            run_name: "DatabricksRun"
            python_script_name: "train-db-local.py"
            source_directory: "D:\\scripts\\Databricks"
            num_workers: 1
            allow_reuse: true
            inputs:
                blob_test_data:
                    source: blob_test_data
            outputs:
                OutputData:
                    destination: Output4
                    datastore: workspaceblobstore
                    bind_mode: mount

數據傳輸步驟

YAML 金鑰	描述
`compute`	要用於此步驟的 Azure Data Factory 計算目標。
`source_data_reference`	做為數據傳輸作業來源的輸入連線。支援的值為 InputPortBinding、DataReference、PortDataReference 、PipelineData、Dataset、DatasetDefinition 或 PipelineDataset。
`destination_data_reference`	做為數據傳輸作業目的地的輸入連線。支援的值為 PipelineData 和 OutputPortBinding。
`allow_reuse`	判斷使用相同設定再次執行時，步驟是否應該重複使用先前的結果。

下列範例包含資料傳輸步驟：

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        adls_test_data:
            datastore: adftestadla
            path_on_datastore: "testdata"
        blob_test_data:
            datastore: workspaceblobstore
            path_on_datastore: "testdata"
    default_compute: adftest
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "DataTransferStep"
            name: "MyDataTransferStep"
            adla_compute_name: adftest
            source_data_reference:
                adls_test_data:
                    source: adls_test_data
            destination_data_reference:
                blob_test_data:
                    source: blob_test_data

Python 腳本步驟

YAML 金鑰	描述
`inputs`	輸入可以是 InputPortBinding、DataReference、PortDataReference 、PipelineData、Dataset、DatasetDefinition 或 PipelineDataset。
`outputs`	輸出可以是 PipelineData 或 OutputPortBinding。
`script_name`	Python 腳本的名稱（相對於 `source_directory`）。
`source_directory`	包含腳本、Conda 環境等的目錄。
`runconfig`	檔案的路徑 `.runconfig` 。此檔案是 RunConfiguration 類別的 YAML 表示法。如需此檔案結構的詳細資訊，請參閱 runconfig.json。
`allow_reuse`	判斷使用相同設定再次執行時，步驟是否應該重複使用先前的結果。

下列範例包含 Python 腳本步驟：

pipeline:
    name: SamplePipelineFromYaml
    parameters:
        PipelineParam1:
            type: int
            default: 3
    data_references:
        DataReference1:
            datastore: workspaceblobstore
            path_on_datastore: testfolder/sample.txt
    default_compute: cpu-cluster
    steps:
        Step1:
            runconfig: "D:\\Yaml\\default_runconfig.yml"
            parameters:
                NUM_ITERATIONS_2:
                    source: PipelineParam1
                NUM_ITERATIONS_1: 7
            type: "PythonScriptStep"
            name: "MyPythonScriptStep"
            script_name: "train.py"
            allow_reuse: True
            source_directory: "D:\\scripts\\PythonScript"
            inputs:
                InputData:
                    source: DataReference1
            outputs:
                OutputData:
                    destination: Output4
                    datastore: workspaceblobstore
                    bind_mode: mount

平行執行步驟

YAML 金鑰	描述
`inputs`	輸入可以是 Dataset、 DatasetDefinition 或 PipelineDataset。
`outputs`	輸出可以是 PipelineData 或 OutputPortBinding。
`script_name`	Python 腳本的名稱（相對於 `source_directory`）。
`source_directory`	包含腳本、Conda 環境等的目錄。
`parallel_run_config`	檔案的路徑 `parallel_run_config.yml` 。此檔案是 ParallelRunConfig 類別的 YAML 表示法。
`allow_reuse`	判斷使用相同設定再次執行時，步驟是否應該重複使用先前的結果。

下列範例包含平行執行步驟：

pipeline:
    description: SamplePipelineFromYaml
    default_compute: cpu-cluster
    data_references:
        MyMinistInput:
            dataset_name: mnist_sample_data
    parameters:
        PipelineParamTimeout:
            type: int
            default: 600
    steps:        
        Step1:
            parallel_run_config: "yaml/parallel_run_config.yml"
            type: "ParallelRunStep"
            name: "parallel-run-step-1"
            allow_reuse: True
            arguments:
            - "--progress_update_timeout"
            - parameter:timeout_parameter
            - "--side_input"
            - side_input:SideInputData
            parameters:
                timeout_parameter:
                    source: PipelineParamTimeout
            inputs:
                InputData:
                    source: MyMinistInput
            side_inputs:
                SideInputData:
                    source: Output4
                    bind_mode: mount
            outputs:
                OutputDataStep2:
                    destination: Output5
                    datastore: workspaceblobstore
                    bind_mode: mount

具有多個步驟的管線

YAML 金鑰	描述
`steps`	一或多個 PipelineStep 定義的序列。請注意， `destination` 一個步驟 `outputs` 的索引鍵會成為 `source` 下一個步驟的索引鍵 `inputs` 。

pipeline:
    name: SamplePipelineFromYAML
    description: Sample multistep YAML pipeline
    data_references:
        TitanicDS:
            dataset_name: 'titanic_ds'
            bind_mode: download
    default_compute: cpu-cluster
    steps:
        Dataprep:
            type: "PythonScriptStep"
            name: "DataPrep Step"
            compute: cpu-cluster
            runconfig: ".\\default_runconfig.yml"
            script_name: "prep.py"
            arguments:
            - '--train_path'
            - output:train_path
            - '--test_path'
            - output:test_path
            allow_reuse: True
            inputs:
                titanic_ds:
                    source: TitanicDS
                    bind_mode: download
            outputs:
                train_path:
                    destination: train_csv
                    datastore: workspaceblobstore
                test_path:
                    destination: test_csv
        Training:
            type: "PythonScriptStep"
            name: "Training Step"
            compute: cpu-cluster
            runconfig: ".\\default_runconfig.yml"
            script_name: "train.py"
            arguments:
            - "--train_path"
            - input:train_path
            - "--test_path"
            - input:test_path
            inputs:
                train_path:
                    source: train_csv
                    bind_mode: download
                test_path:
                    source: test_csv
                    bind_mode: download

排程

定義管線的排程時，它可以根據時間間隔觸發數據存放區或週期性。以下是用來定義排程的索引鍵：

YAML 金鑰	描述
`description`	排程的描述。
`recurrence`	如果排程是週期性，則包含週期性設定。
`pipeline_parameters`	管線所需的任何參數。
`wait_for_provisioning`	是否要等候布建排程完成。
`wait_timeout`	在逾時之前等候的秒數。
`datastore_name`	要監視已修改/新增 Blob 的數據存放區。
`polling_interval`	輪詢已修改/新增 Blob 之間的時間，以分鐘為單位。默認值：5 分鐘。僅支援數據存放區排程。
`data_path_parameter_name`	要以已變更 Blob 路徑設定的數據路徑管線參數名稱。僅支援數據存放區排程。
`continue_on_step_failure`	如果步驟失敗，是否要在提交的 PipelineRun 中繼續執行其他步驟。如果提供，將會覆寫 `continue_on_step_failure` 管線的設定。
`path_on_datastore`	選擇性。要監視已修改/新增 Blob 的數據存放區路徑。路徑位於數據存放區的容器底下，因此排程監視器的實際路徑是容器/`path_on_datastore`。如果沒有，則會監視數據存放區容器。在的 `path_on_datastore` 子資料夾中所做的新增/修改不會受到監視。僅支援數據存放區排程。

下列範例包含資料存放區觸發排程的定義：

Schedule: 
      description: "Test create with datastore" 
      recurrence: ~ 
      pipeline_parameters: {} 
      wait_for_provisioning: True 
      wait_timeout: 3600 
      datastore_name: "workspaceblobstore" 
      polling_interval: 5 
      data_path_parameter_name: "input_data" 
      continue_on_step_failure: None 
      path_on_datastore: "file/path"

定義 週期性排程時，請使用下的 recurrence下列索引鍵：

YAML 金鑰	描述
`frequency`	排程的遞迴頻率。有效值為 `"Minute"`、、`"Hour"`、 `"Day""Week"`或 `"Month"`。
`interval`	排程引發的頻率。整數值是等候排程再次引發的時間單位數目。
`start_time`	排程的開始時間。值的字串格式為 `YYYY-MM-DDThh:mm:ss`。如果未提供任何開始時間，則會立即執行第一個工作負載，而未來的工作負載會根據排程執行。如果開始時間過去，第一個工作負載會在下一個計算的運行時間執行。
`time_zone`	開始時間的時區。如果未提供時區，則會使用UTC。
`hours`	如果 `frequency` 為 `"Day"` 或 `"Week"`，您可以指定一或多個介於 0 到 23 的整數，並以逗號分隔，做為管線應該執行的一天中的小時。只能 `time_of_day` 使用或 `hours` 與 `minutes` 。
`minutes`	如果 `frequency` 為 `"Day"` 或 `"Week"`，您可以指定一或多個介於 0 到 59 的整數，並以逗號分隔，作為管線應該執行時的分鐘數。只能 `time_of_day` 使用或 `hours` 與 `minutes` 。
`time_of_day`	如果 `frequency` 為 `"Day"` 或 `"Week"`，您可以指定要執行排程的一天時間。值的字串格式為 `hh:mm`。只能 `time_of_day` 使用或 `hours` 與 `minutes` 。
`week_days`	如果 `frequency` 為 `"Week"`，您可以在排程應該執行時，指定一或多個以逗號分隔的天數。有效值為 `"Monday"`、、`"Tuesday"`、、`"Wednesday"`、`"Thursday""Friday"`、`"Saturday"`、和 `"Sunday"`。

下列範例包含週期性排程的定義：

Schedule: 
    description: "Test create with recurrence" 
    recurrence: 
        frequency: Week # Can be "Minute", "Hour", "Day", "Week", or "Month". 
        interval: 1 # how often fires 
        start_time: 2019-06-07T10:50:00 
        time_zone: UTC 
        hours: 
        - 1 
        minutes: 
        - 0 
        time_of_day: null 
        week_days: 
        - Friday 
    pipeline_parameters: 
        'a': 1 
    wait_for_provisioning: True 
    wait_timeout: 3600 
    datastore_name: ~ 
    polling_interval: ~ 
    data_path_parameter_name: ~ 
    continue_on_step_failure: None 
    path_on_datastore: ~

下一步

瞭解如何使用適用於 Azure 機器學習的 CLI 擴充功能。

共用方式為

CLI （v1）管線作業 YAML 架構

管線定義

參數

資料參考

步驟

ADLA 步驟

Azure Batch 步驟

Databricks 步驟

數據傳輸步驟

Python 腳本步驟

平行執行步驟

具有多個步驟的管線

排程

下一步

意見反應

其他資源

共用方式為

CLI （v1） 管線作業 YAML 架構

管線定義

參數

資料參考

步驟

ADLA 步驟

Azure Batch 步驟

Databricks 步驟

數據傳輸步驟

Python 腳本步驟

平行執行步驟

具有多個步驟的管線

排程

下一步

意見反應

其他資源

CLI （v1）管線作業 YAML 架構