Platform For AI：建立自訂群組件

背景資訊

自訂群組件底層採用了阿里雲開源的KubeDL，這是一個基於Kubernetes的AI工作負載管理架構。

建立自訂群組件支援選擇不同的任務類型（包括：Tensorflow、PyTorch、XGBoost、ElasticBatch）、建立輸入輸出管道、配置超參等，自訂群組件建立成功後，會轉換為Designer介面可視化參數配置，詳情請參見操作步驟。

• 針對不同的任務類型，KubeDL會下發同步的環境變數，通過這些環境變數，您可以擷取機器數量和拓撲資訊，詳情請參見附錄1：任務類型介紹。

• 通過在執行命令中配置環境變數來讀取輸入輸出管道資料、超參資料等，詳情請參見如何讀取管道及超參資料。

• 在執行代碼中，除了通過環境變數擷取輸入或輸出管道外，也可以直接通過容器內掛載路徑進行訪問，詳情請參見輸入輸出目錄結構。

使用限制

僅華北2（北京）、華東2（上海）、華東1（杭州）和華南1（深圳）支援建立自訂群組件。

前提條件

已建立工作空間，建立的自訂群組件均與該工作空間綁定。具體操作，請參見建立工作空間。

操作步驟

1. 進入組件管理頁面。

   1. 登入PAI控制台。

   2. 在左側導覽列單擊工作空間列表，在工作空間列表頁面中單擊待操作的工作空間名稱，進入對應工作空間內。

   3. 在左側導覽列，選擇AI資產管理>自訂群組件。

2. 在組件列表頁面，單擊新群組件，並在新群組件頁面配置以下參數。

   • 基本資料配置

     參數	描述
     組件名稱	自訂群組件名稱，在同一個地區下要求主帳號內唯一。
     組件描述	對建立的自訂群組件進行簡單描述，以區分不同的組件。
     組件版本	建立的自訂群組件版本號碼。 說明 建議使用x.y.z的版本號碼格式來管理版本。例如，第一個大版本為1.0.0，對該版本進行小問題修複時，可以將版本號碼升級為1.0.1；而進行小型功能更新時，則可以將版本號碼升級為1.1.0。這樣的版本號碼管理方式清晰明了，便於您瞭解各個版本之間的差異和更新內容。
     版本描述	對當前建立的自訂群組件版本進行描述。例如：初始版本。

   • 執行配置

     參數	描述
     任務類型	建立自訂群組件時，需要選擇任務類型。目前支援Tensorflow、PyTorch、XGBoost、ElasticBatch四種任務類型，其分別對應了KubeDL中的TFJob、PyTorchJob、XGBoostJob、ElasticBatchJob四種任務類型。關於每種任務類型更詳細的介紹，請參見附錄：任務類型介紹。
     執行鏡像	當前支援選擇社區鏡像、官方鏡像和自訂鏡像，您也可以在鏡像地址頁簽配置三種類型的鏡像地址。 說明 由於公網頻寬有限，為了保證任務的穩定性，請使用同一個Region下阿里雲的鏡像服務（ACR）。 目前只支援ACR個人版，不支援企業版，鏡像地址請填寫VPC地址，格式為：registry-vpc.${region}.aliyuncs.com。 使用自訂鏡像時，請勿在同一版本中頻繁更新鏡像，因為這會導致鏡像緩衝無法及時更新，從而導致任務啟動時間延長。 為確保鏡像正常執行，鏡像中必須包含sh shell命令。同時，鏡像執行命令的方式將使用sh -c方式。 如果使用了自訂鏡像，請確保該鏡像中包含了Python相關的執行環境和pip命令，否則可能導致任務運行失敗。
     執行代碼	自訂群組件的代碼目錄支援OSS目錄和Git地址： OSS掛載：組件運行時，該OSS目錄中所有檔案將會被下載到/ml/usercode/目錄下，您可以通過命令執行該目錄下的檔案。 說明 建議該目錄只存放當前演算法必需的檔案，否則可能導致組件啟動時間過長、甚至啟動逾時。 當代碼目錄中存在requirements.txt檔案時，演算法運行時會自動執行pip install -r requirements.txt安裝相關依賴。 PAI代碼配置：配置Git程式碼程式庫。
     執行命令	組件鏡像的執行命令，可以通過環境變數擷取實際的值，配置格式如下： python main.py $PAI_USER_ARGS --{CHANNEL_NAME} $PAI_INPUT_{CHANNEL_NAME} --{CHANNEL_NAME} $PAI_OUTPUT_{CHANNEL_NAME} && sleep 150 && echo "job finished" 執行命令中通過配置PAI_USER_ARGS、PAI_INPUT_{CHANNEL_NAME}、PAI_OUTPUT_{CHANNEL_NAME}環境變數來讀取超參、輸入和輸出管道資料，具體資料讀取方法，請參見如何讀取管道及超參資料。 例如：輸入管道名稱分別為test、train；輸出管道名稱分別為model、checkpoints，則配置樣本如下： python main.py $PAI_USER_ARGS --train $PAI_INPUT_TRAIN --test $PAI_INPUT_TEST --model $PAI_OUTPUT_MODEL --checkpoints $PAI_OUTPUT_CHECKPOINTS && sleep 150 && echo "job finished" 其中配套的代碼入口檔案main.py中主要提供瞭解析參數的邏輯樣本，在實際使用時，您將自己的演算法邏輯整合進去即可，樣本內容如下所示： import os import argparse import json def parse_args(): """解析給到指令碼的arguments.""" parser = argparse.ArgumentParser(description="PythonV2 component script example.") # input & output channels parser.add_argument("--train", type=str, default=None, help="input channel train.") parser.add_argument("--test", type=str, default=None, help="input channel test.") parser.add_argument("--model", type=str, default=None, help="output channel model.") parser.add_argument("--checkpoints", type=str, default=None, help="output channel checkpoints.") # parameters parser.add_argument("--param1", type=int, default=None, help="param1") parser.add_argument("--param2", type=float, default=None, help="param2") parser.add_argument("--param3", type=str, default=None, help="param3") parser.add_argument("--param4", type=bool, default=None, help="param4") parser.add_argument("--param5", type=int, default=None, help="param5") args, _ = parser.parse_known_args() return args if __name__ == "__main__": args = parse_args() print("Input channel train={}".format(args.train)) print("Input channel test={}".format(args.test)) print("Output channel model={}".format(args.model)) print("Output channel checkpoints={}".format(args.checkpoints)) print("Parameters param1={}".format(args.param1)) print("Parameters param2={}".format(args.param2)) print("Parameters param3={}".format(args.param3)) print("Parameters param4={}".format(args.param4)) print("Parameters param5={}".format(args.param5)) 下面是上述範例程式碼實際運行中列印的日誌，您可以看到通過以上方式能夠擷取到任務執行個體的參數資訊： Input channel train=/ml/input/data/train Input channel test=/ml/input/data/test/easyrec_config.config Output channel model=/ml/output/model/ Output channel checkpoints=/ml/output/checkpoints/ Parameters param1=6 Parameters param2=0.3 Parameters param3=test1 Parameters param4=True Parameters param5=2 job finished

   • 管道及參數

     單擊配置自訂群組件的輸入管道（Input Channel）、輸出管道（Output Channel）和參數。名稱命名格式如下：

     • 要求全域唯一，且互相不能重複。

     • 支援數字、字母、底線（_）和減號（-），不能以底線開頭。

       說明

       如果名稱中包含了環境變數不支援的字元（僅支援字母、數字和底線），在產生環境變數時，這些字元將被替換為底線。此外，名稱中的小寫字母將被轉換為大寫字母。因此，應避免出現轉換為環境變數後可能產生衝突的情況。例如：如果參數名分別為test_model、test-model，在轉換為環境變數後，它們將全部變為PAI_HPS_TEST_MODEL，可能會出現衝突。

     管道及參數配置與Designer組件介面化參數對應關係如下圖所示：

     具體參數配置說明如下：

     參數	描述
     輸入	自訂群組件通過輸入管道擷取輸入資料或finetune的模型，支援配置以下參數： 輸入名稱：參照介面提示配置輸入管道名稱。 輸入來源：指定輸入管道讀取OSS、NAS或MaxCompute路徑的資料。輸入資料會以掛載的形式，掛載到訓練容器的/ml/input/data/{channel_name}/目錄下，組件可以通過讀取本地檔案的方式讀取到OSS、NAS或MaxCompute上的資料。
     輸出	輸出管道用於儲存訓練模型、Checkpoints等結果，支援配置以下參數： 輸出名稱：參照介面提示配置輸出管道名稱。 儲存類型：每個輸出管道需要指定一個OSS或MaxCompute目錄，該目錄將會以掛載的方式掛載到訓練容器的/ml/output/{channel_name}/下。
     參數	超參資訊，支援配置以下參數： 參數名稱：參照介面提示配置參數名稱。 參數類型：目前支援配置Int、Float、String、Bool四種類型。 參數約束：在預設值列，單擊約束，來配置參數約束關係。約束類型取值如下： 範圍：通過配置最大值和最小值來指定取值範圍，僅Int、Float、String類型支援配置。 枚舉：為參數配置枚舉值。僅Int、Float、String類型支援配置。

   • 訓練約束

     訓練約束用於定義訓練任務需要的計算資源，您可以開啟訓練約束開關進行配置。

     訓練約束配置轉換為Designer組件介面化參數執行調優配置：

     具體參數說明如下：

     參數	描述
     機器類型	配置自訂群組件支援CPU或GPU機器。
     支援多機	組件是否支援多機分布式運行： 支援：組件運行時，支援配置節點數。 不支援：組件運行時，節點數只能為1，不支援修改。
     支援多卡	僅當機器類型選擇GPU時，支援配置該參數。 自訂群組件是否支援多卡： 支援：機器類型支援選擇單卡或多卡GPU機器。 不支援：機器類型僅支援選擇單卡GPU機器。

3. 單擊提交。

   組件列表頁面顯示已建立的自訂群組件。

組件建立成功後，後續您可以在Designer中使用該自訂群組件，詳情請參見使用自訂群組件。

附錄1：任務類型介紹

{
  "cluster": {
    "chief": [
      "dlc17****iui3e94-chief-0.t104140334615****.svc:2222"
    ],
    "evaluator": [
      "dlc17****iui3e94-evaluator-0.t104140334615****.svc:2222"
    ],
    "ps": [
      "dlc17****iui3e94-ps-0.t104140334615****.svc:2222"
    ],
    "worker": [
      "dlc17****iui3e94-worker-0.t104140334615****.svc:2222",
      "dlc17****iui3e94-worker-1.t104140334615****.svc:2222",
      "dlc17****iui3e94-worker-2.t104140334615****.svc:2222",
      "dlc17****iui3e94-worker-3.t104140334615****.svc:2222"
    ]
  },
  "task": {
    "type": "chief",
    "index": 0
  }
}

{
  "task": {
    "type": "worker",
    "index": 0
  },
  "environment": "cloud"
}

附錄2：自訂群組件實現原理

如何讀取管道及超參資料

讀取輸入管道資料

對於每一個輸入管道的資料，會以PAI_INPUT_{CHANNEL_NAME}的環境變數注入到訓練作業的容器中。

例如自訂群組件有train、test兩個輸入管道，其值分別為：oss://<YourOssBucket>.<OssEndpoint>/path-to-data/和oss://<YourOssBucket>.<OssEndpoint>/path-to-data/test.csv，則注入的環境變數如下：

PAI_INPUT_TRAIN=/ml/input/data/train/
PAI_INPUT_TEST=/ml/input/data/test/test.csv

讀取輸出管道資料

組件可以通過PAI_OUTPUT_{CHANNEL_NAME}環境變數，擷取到對應的路徑。

例如自訂群組件有model和checkpoints兩個輸出管道，則注入的環境變數如下：

PAI_OUTPUT_MODEL=/ml/output/model/
PAI_OUTPUT_CHECKPOINTS=/ml/output/checkpoints/

讀取超參資料

通過以下環境變數讀取超參資料：

• PAI_USER_ARGS

  組件運行時，作業的所有超參資訊會以PAI_USER_ARGS環境變數，使用--{hyperparameter_name} {hyperparameter_value}的形式，注入到訓練作業的容器中。

  例如訓練作業指定了超參{"epochs": 10, "batch-size": 32, "learning-rate": 0.001}，則PAI_USER_ARGS環境變數的值為：

  PAI_USER_ARGS="--epochs 10 --batch-size 32 --learning-rate 0.001"

• PAI_HPS_{HYPERPARAMETER_NAME}

  單個參數的值，也會以環境變數的形式注入到訓練作業的容器中。對於超參名中，環境變數中不支援的字元（僅支援字母、數字和底線）會被替換為底線。

  例如訓練作業指定了超參{"epochs": 10, "batch-size": 32, "train.learning_rate": 0.001}，對應的環境變數資訊如下：

  PAI_HPS_EPOCHS=10
  PAI_HPS_BATCH_SIZE=32
  PAI_HPS_TRAIN_LEARNING_RATE=0.001

• PAI_HPS

  訓練作業的超參資訊會以JSON格式通過PAI_HPS環境變數注入到訓練作業的容器中。

  例如訓練作業傳遞了超參{"epochs": 10, "batch-size": 32}，則PAI_HPS環境變數的值為：

  PAI_HPS={"epochs": 10, "batch-size": 32}

輸入輸出目錄結構

在執行代碼中，除了通過環境變數擷取輸入或輸出管道外，也可以直接通過容器內掛載路徑進行訪問。組件提交的任務在容器內執行時，會按照以下規則建立相應路徑：

• 代碼路徑：/ml/usercode/。

• 超參設定檔：/ml/input/config/hyperparameters.json。

• 訓練作業的完整設定檔：/ml/input/config/training_job.json。

• 輸入管道的目錄路徑：/ml/input/data/{channel_name}/。

• 輸出管道的目錄路徑：/ml/output/{channel_name}/。

自訂群組件執行作業的輸入輸出目錄結構完整樣本如下：

/ml
|-- usercode                        # 使用者代碼載入到/ml/usercode目錄，這裡也是使用者代碼的工作目錄. 可以通過環境變數PAI_WORKING_DIR獲得。
|   |-- requirements.txt
|   |-- main.py
|-- input                           # 作業輸入資料和配置資訊
|   |-- config                      # config目錄包含了作業的配置資訊, 可以通過PAI_CONFIG_DIR擷取。
|       |-- training_job.json       # 作業的完整配置。
|       |-- hyperparameters.json    # 訓練作業超參.
|   |-- data                        # 作業的InputChannels: 以下目錄包含了兩個channel: train_data和test_data。
|       |-- test_data
|       |   |-- test.csv
|       |-- train_data
|           |-- train.csv
|-- output                          # 作業的輸出Channels: 這裡有model/checkpoints兩個輸出channel。
        |-- model                   # 通過環境變數PAI_OUTPUT_{OUTPUT_CHANNEL_NAME}可以獲輸出路徑。
        |-- checkpoints

如何判斷是否是GPU機器以及GPU卡數

任務啟動後，可以通過環境變數NVIDIA_VISIBLE_DEVICES來判斷當前機器是否具有GPU以及GPU卡數。例如：NVIDIA_VISIBLE_DEVICES=0,1,2,3表示當前機器具有4張GPU卡。