使用元件搭配 Azure Machine Learning CLI 建立和執行機器學習管線

  • 發行項

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

在本文中，您會了解如何使用 Azure CLI 和元件來建立及執行機器學習管線。 您可以不使用元件來建立管線，但元件提供最大的彈性和重複使用量。 Azure Machine Learning 管線可在 YAML 中進行定義並從 CLI 執行、以 Python 撰寫，或使用拖放 UI 在 Azure Machine Learning 工作室設計工具中撰寫。 本文件著重於 CLI。

必要條件

建議的預讀

使用元件建立您的第一個管線

讓我們透過範例使用元件來建立您的第一個管線。 本節旨在提供 Azure Machine Learning 中管線和元件外觀的初始印象，並提供具體範例。

從 azureml-examples 存放庫的 cli/jobs/pipelines-with-components/basics 目錄，瀏覽至 3b_pipeline_with_data 子目錄。 此目錄中有三種類型的檔案。 這些是您在建置自己的管線時必須建立的檔案。

  • pipeline.yml：此 YAML 檔案定義機器學習管線。 此 YAML 檔案描述如何將完整的機器學習工作細分成多步驟工作流程。 例如，假設有個簡單的機器學習工作，其會使用歷史資料來為銷售預測模型定型，則您可以使用資料處理、模型定型和模型評估這三個步驟來建置循序前進的工作流程。 每個步驟都是一個元件，具有妥善定義的介面，可以獨立開發、測試及最佳化。 管線 YAML 也會定義子步驟如何連接到管線中的其他步驟，例如模型定型步驟會產生模型檔案，而模型檔案會傳遞至模型評估步驟。

  • component.yml：此 YAML 檔案定義元件。 會封裝下列資訊：

    • 中繼資料：名稱、顯示名稱、版本、描述、類型等等。中繼資料有助於描述和管理元件。
    • 介面：輸入和輸出。 例如，模型定型元件會將定型資料和 Epoch 數目當作輸入，並產生定型的模型檔案作為輸出。 定義介面之後，不同的小組就可以獨立開發和測試元件。
    • 命令、程式碼和環境：用來執行元件的命令、程式碼和環境。 命令是執行元件的殼層命令。 程式碼通常是指原始程式碼目錄。 環境可以是 Azure Machine Learning 環境 (策劃或客戶建立)、Docker 映像或 Conda 環境。

  • component_src：這是特定元件的原始程式碼目錄。 其中包含在元件中執行的原始程式碼。 您可以使用慣用的語言 (Python、R...)。程式碼必須由殼層命令執行。 原始程式碼可以從殼層命令列取得一些輸入，以控制此步驟的執行方式。 例如，定型步驟可能會採用定型資料、學習速率、Epoch 數目來控制定型程序。 殼層命令的引數可用來將輸入和輸出傳遞至程式碼。

現在讓我們使用 3b_pipeline_with_data 範例建立管線。 我們會在下列各節中詳細說明每個檔案的意義。

首先使用下列命令來列出可用的計算資源：

az ml compute list

如果您沒有此資源，請執行下列程式來建立名為 cpu-cluster 的叢集：

注意

略過此步驟以使用無伺服器計算。

az ml compute create -n cpu-cluster --type amlcompute --min-instances 0 --max-instances 10

現在，使用下列命令建立 pipeline.yml 檔案中定義的管線作業。 計算目標會在 pipeline.yml 檔案中參考為 azureml:cpu-cluster。 如果您的計算目標使用不同的名稱，請記得在 pipeline.yml 檔案中更新。

az ml job create --file pipeline.yml

您應該會收到具有管線工作相關資訊的 JSON 字典，包括：

關鍵 描述
name 以 GUID 為基礎的工作名稱。
experiment_name 在工作室中用來組織作業的名稱。
services.Studio.endpoint 用於監視和檢閱管線工作的 URL。
status 工作的狀態。 這目前可能會是 Preparing。

開啟 services.Studio.endpoint URL 以查看管線的圖表視覺效果。

Screenshot of a graph visualization of the pipeline.

了解管線定義 YAML

讓我們看看 3b_pipeline_with_data/pipeline.yml 檔案中的管線定義。

注意

若要使用無伺服器計算，請將 default_compute: azureml:cpu-cluster 取代為此檔案中的 default_compute: azureml:serverless。

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline

display_name: 3b_pipeline_with_data
description: Pipeline with 3 component jobs with data dependencies

settings:
  default_compute: azureml:cpu-cluster

outputs:
  final_pipeline_output:
    mode: rw_mount

jobs:
  component_a:
    type: command
    component: ./componentA.yml
    inputs:
      component_a_input: 
        type: uri_folder
        path: ./data

    outputs:
      component_a_output: 
        mode: rw_mount
  component_b:
    type: command
    component: ./componentB.yml
    inputs:
      component_b_input: ${{parent.jobs.component_a.outputs.component_a_output}}
    outputs:
      component_b_output: 
        mode: rw_mount
  component_c:
    type: command
    component: ./componentC.yml
    inputs:
      component_c_input: ${{parent.jobs.component_b.outputs.component_b_output}}
    outputs:
      component_c_output: ${{parent.outputs.final_pipeline_output}}
      #  mode: upload

資料表描述管線 YAML 結構描述最常使用的欄位。 若要深入了解，請參閱完整管線 YAML 結構描述。

索引鍵 description
type 必要。 管線作業的作業類型必須是 pipeline。
display_name 工作室 UI 中管線作業的顯示名稱。 可在工作室 UI 中編輯。 不需要是工作區所有作業中的唯一名稱。
jobs 必要。 要在管線內作為步驟執行的個別作業集合的字典。 這些作業可視為父管線作業的子作業。 在此版本中，管線中支援的作業類型為 command 和 sweep
輸入 管線作業的輸入字典。 索引鍵是作業內容中的輸入名稱，值則是輸入值。 使用 ${{ parent.inputs.<input_name> }} 運算式，管線中的個別步驟作業輸入即可參考這些管線輸入。
輸出 管線作業輸出設定的字典。 索引鍵是作業內容中的輸出名稱，值則是輸出設定。 使用 ${{ parents.outputs.<output_name> }} 運算式，管線中的個別步驟作業輸出即可參考這些管線輸出。

在 3b_pipeline_with_data 範例中，我們已建立一個三步驟管線。

  • 三個步驟定義於 jobs 底下。 這三個步驟類型都是命令作業。 每個步驟的定義都位於對應的 component.yml 檔案中。 您可以在 3b_pipeline_with_data 目錄底下看到元件 YAML 檔案。 我們將在下一節中說明 componentA.yml。
  • 此管線具有資料相依性，這在大部分的實際管線中很常見。 Component_a 會從 ./data 底下的本機資料夾取得資料輸入 (17-20 行)，並且將其輸出傳遞至 componentB (29 行)。 Component_a 的輸出可以參考為 ${{parent.jobs.component_a.outputs.component_a_output}}。
  • compute 會定義此管線的預設計算。 如果 jobs 底下的元件針對此元件定義不同的計算，則系統會遵守元件特定設定。

Screenshot of the pipeline with data example.

在管線中讀取和寫入資料

其中一個常見案例是在管線中讀取和寫入資料。 在 Azure Machine Learning 中，我們會針對所有類型的作業 (管線作業、命令作業和掃掠作業) 使用相同的結構描述來讀取和寫入資料。 以下是針對常見案例使用資料的管線作業範例。

了解元件定義 YAML

現在讓我們看看 componentA.yml 作為了解元件定義 YAML 的範例。

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

name: component_a
display_name: componentA
version: 1

inputs:
  component_a_input:
    type: uri_folder

outputs:
  component_a_output:
    type: uri_folder

code: ./componentA_src

environment: 
  image: python

command: >-
  python hello.py --componentA_input ${{inputs.component_a_input}} --componentA_output ${{outputs.component_a_output}}

資料表說明元件 YAML 最常使用的結構描述。 若要深入了解，請參閱完整元件 YAML 結構描述。

索引鍵 description
NAME 必要。 元件的名稱。 在 Azure Machine Learning 工作區之間必須是唯一的名稱。 必須以小寫字母開頭。 允許小寫字母、數字和底線 (_)。 長度上限是 255 個字元。
display_name 工作室 UI 中元件的顯示名稱。 在工作區內不一定要是唯一名稱。
命令 需要命令以便執行
code 要上傳並用於元件的原始程式碼目錄本機路徑。
environment 必要。 用來執行元件的環境。
輸入 元件輸入的字典。 索引鍵是元件內容內的輸入名稱，值則是元件輸入定義。 使用 ${{ inputs.<input_name> }} 運算式，輸入可以在命令中參考。
輸出 元件輸出的字典。 索引鍵是元件內容內的輸出名稱，值則是元件輸出定義。 使用 ${{ outputs.<output_name> }} 運算式，輸出可以在命令中參考。
is_deterministic 如果元件輸入未變更，是否要重複使用先前工作的結果。 預設值為 true，也稱為預設重複使用。 設定為 false 的常見案例是強制從雲端儲存空間或 URL 重新載入資料。

針對 3b_pipeline_with_data/componentA.yml 中的範例，componentA 有一個資料輸入和一個資料輸出，可以連接到父代管線中的其他步驟。 提交管線作業時，元件 YAML 中 code 區段下的所有檔案都會上傳至 Azure Machine Learning。 在此範例中，./componentA_src 底下的檔案將會上傳 (componentA.yml 中的第 16 行)。 您可以在工作室 UI 中看到上傳的原始程式碼：按兩下 ComponentA 步驟並瀏覽至 [快照集] 索引標籤，如下列螢幕擷取畫面所示。 我們可以看到這是 hello-world 指令碼，只是執行一些簡單的列印，並將目前的日期時間寫入 componentA_output 路徑。 元件會透過命令列引數採用輸入和輸出，並使用 argparse 在 hello.py 中處理。

Screenshot of pipeline with data example showing componentA.

輸入和輸出

輸入和輸出會定義元件的介面。 輸入和輸出可以是常值 (類型為 string、number、integer 或 boolean) 或是包含輸入結構描述的物件。

物件輸入 (類型為 uri_file、uri_folder、mltable、mlflow_model、custom_model) 可以連接至父代管線作業中的其他步驟，因而將資料/模型傳遞至其他步驟。 在管線圖形中，物件類型輸入會轉譯為連接點。

常值輸入 (string、number、integer、boolean) 是您可以在執行階段傳遞至元件的參數。 您可以在 default 欄位下新增常值輸入的預設值。 針對 number 和 integer 類型，您也可以使用 min 和 max 欄位，新增接受值的最小值和最大值。 如果輸入值超過最小值和最大值，管線會在驗證時失敗。 在您提交管線作業之前進行驗證，可以節省時間。 驗證適用於 CLI、Python SDK 和設計工具 UI。 以下螢幕擷取畫面顯示設計工具 UI 中的驗證範例。 同樣地，您可以在 enum 欄位中定義允許的值。

Screenshot of the input and output of the train linear regression model component.

如果您要將輸入新增至元件，請記得編輯三個位置：

  • 元件 YAML 中的 inputs 欄位
  • 元件 YAML 中的 command 欄位。
  • 用來處理命令列輸入的元件原始程式碼。 在先前螢幕擷取畫面中以綠色方塊標示。

若要深入了解輸入和輸出，請參閱管理元件與管線的輸入和輸出。

Environment

環境會定義執行元件的環境。 可以是 Azure Machine Learning 環境 (策劃或自訂註冊)、Docker 映像或 Conda 環境。 請參閱下列範例。

註冊要重複使用和共用的元件

雖然某些元件是特定管線專屬，但元件的真正優點是可重複使用和共用。 在機器學習工作區中註冊元件，使其可供重複使用。 註冊的元件會支援自動版本設定，因此您可以更新元件，但請確保需要較舊版本的管線仍能繼續運作。

在 azureml-examples 存放庫中，瀏覽至 cli/jobs/pipelines-with-components/basics/1b_e2e_registered_components 目錄。

若要註冊元件，請使用 az ml component create 命令：

az ml component create --file train.yml
az ml component create --file score.yml
az ml component create --file eval.yml

完成這些命令回合之後，您就可以在工作室中看到這些元件，在 [資產] -> [元件] 底下：

Screenshot of Studio showing the components that were just registered.

選取元件。 您會看到每個元件版本的詳細資訊。

在 [詳細資料] 索引標籤下，您會看到元件的基本資訊，例如名稱、建立者、版本等。您會看到 [標記] 和 [描述] 的可編輯欄位。 這些標籤可用來新增快速搜尋的關鍵字。 [描述] 欄位支援 Markdown 格式，且應該用來描述元件的功能和基本用途。

在 [作業] 索引標籤下，您會看到使用此元件的所有作業歷程記錄。

在管線作業 YAML 檔案中使用已註冊元件

讓我們使用 1b_e2e_registered_components 來示範如何在管線 YAML 中使用已註冊元件。 瀏覽至 1b_e2e_registered_components 目錄，開啟 pipeline.yml 檔案。 inputs 和 outputs 欄位中的索引鍵和值與我們所討論過的索引鍵和值類似。 唯一顯著的差異在於 jobs.<JOB_NAME>.component 項目中 component 欄位的值。 component 值的格式為 azureml:<COMPONENT_NAME>:<COMPONENT_VERSION>。 例如，train-job 定義會指定應使用已註冊元件 my_train 的最新版本：

type: command
component: azureml:my_train@latest
inputs:
  training_data: 
    type: uri_folder 
    path: ./data      
  max_epocs: ${{parent.inputs.pipeline_job_training_max_epocs}}
  learning_rate: ${{parent.inputs.pipeline_job_training_learning_rate}}
  learning_rate_schedule: ${{parent.inputs.pipeline_job_learning_rate_schedule}}
outputs:
  model_output: ${{parent.outputs.pipeline_job_trained_model}}
services:
  my_vscode:

管理元件

您可以使用 CLI (v2) 來檢查元件詳細資料和管理元件。 使用 az ml component -h 以取得元件命令的詳細指示。 下表列出所有可用的命令。 如需更多範例，請參閱 Azure CLI 參考。

命令 description
az ml component create 建立元件
az ml component list 列出工作區中的元件
az ml component show 顯示元件的詳細資料
az ml component update 更新元件。 只有幾個欄位 (描述，display_name) 支援更新
az ml component archive 封存元件容器
az ml component restore 還原封存的元件

下一步