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

發行項
03/18/2024

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

必要條件

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。試用免費或付費版本的 Azure Machine Learning。
Azure Machine Learning 工作區。建立工作區資源。
安裝和設定 Machine Learning 的 Azure CLI 擴充功能。

複製範例存放庫：

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli/jobs/pipelines-with-components/basics

建議的預讀

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

讓我們透過範例使用元件來建立您的第一個管線。本節旨在提供 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 以查看管線的圖表視覺效果。

管線圖表視覺效果的螢幕快照。

了解管線定義 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 底下的元件針對此元件定義不同的計算，則系統會遵守元件特定設定。

在管線中讀取和寫入資料

其中一個常見案例是在管線中讀取和寫入資料。在 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 中處理。

輸入和輸出

輸入和輸出會定義元件的介面。輸入和輸出可以是常值 (類型為 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 欄位中定義允許的值。

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

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

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

Environment

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

Azure Machine Learning 已註冊環境資產。在遵循 azureml:<environment-name>:<environment-version> 語法的元件中參考。
公用 Docker 映像
Conda 檔案 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

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

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

在 [詳細資料] 索引標籤下，您會看到元件的基本資訊，例如名稱、建立者、版本等。您會看到 [標記] 和 [描述] 的可編輯欄位。這些標籤可用來新增快速搜尋的關鍵字。 [描述] 欄位支援 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`	還原封存的元件

下一步

試用 CLI 第 2 版元件範例

共用方式為

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

必要條件

建議的預讀

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

了解管線定義 YAML

在管線中讀取和寫入資料

了解元件定義 YAML

輸入和輸出

Environment

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

管理元件

下一步

其他資源

共用方式為

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

必要條件

建議的預讀

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

了解管線定義 YAML

在管線中讀取和寫入資料

了解元件定義 YAML

輸入和輸出

Environment

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

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

管理元件

下一步

其他資源