背景信息

自定義組件底層采用了阿里云開源的KubeDL，這是一個基于Kubernetes的AI工作負載管理框架。

創(chuàng)建自定義組件支持選擇不同的任務(wù)類型（包括：Tensorflow、PyTorch、XGBoost、ElasticBatch）、創(chuàng)建輸入輸出管道、配置超參等，自定義組件創(chuàng)建成功后，會轉(zhuǎn)換為Designer界面可視化參數(shù)配置，詳情請參見操作步驟。

• 針對不同的任務(wù)類型，KubeDL會下發(fā)同步的環(huán)境變量，通過這些環(huán)境變量，您可以獲取機器數(shù)量和拓撲信息，詳情請參見附錄1：任務(wù)類型介紹。

• 通過在執(zhí)行命令中配置環(huán)境變量來讀取輸入輸出管道數(shù)據(jù)、超參數(shù)據(jù)等，詳情請參見如何讀取管道及超參數(shù)據(jù)。

• 在執(zhí)行代碼中，除了通過環(huán)境變量獲取輸入或輸出管道外，也可以直接通過容器內(nèi)掛載路徑進行訪問，詳情請參見輸入輸出目錄結(jié)構(gòu)。

使用限制

僅華北2（北京）、華東2（上海）、華東1（杭州）和華南1（深圳）支持創(chuàng)建自定義組件。

前提條件

已創(chuàng)建工作空間，創(chuàng)建的自定義組件均與該工作空間綁定。具體操作，請參見創(chuàng)建工作空間。

操作步驟

1. 進入組件管理頁面。

   1. 登錄PAI控制臺。

   2. 在左側(cè)導航欄單擊工作空間列表，在工作空間列表頁面中單擊待操作的工作空間名稱，進入對應(yīng)工作空間內(nèi)。

   3. 在左側(cè)導航欄，選擇AI資產(chǎn)管理>自定義組件。

2. 在組件列表頁面，單擊新建組件，并在新建組件頁面配置以下參數(shù)。

   • 基本信息配置

     參數(shù)	描述
     組件名稱	自定義組件名稱，在同一個地域下要求主賬號內(nèi)唯一。
     組件描述	對創(chuàng)建的自定義組件進行簡單描述，以區(qū)分不同的組件。
     組件版本	創(chuàng)建的自定義組件版本號。 說明 建議使用x.y.z的版本號格式來管理版本。例如，第一個大版本為1.0.0，對該版本進行小問題修復時，可以將版本號升級為1.0.1；而進行小型功能升級時，則可以將版本號升級為1.1.0。這樣的版本號管理方式清晰明了，便于您了解各個版本之間的差異和更新內(nèi)容。
     版本描述	對當前創(chuàng)建的自定義組件版本進行描述。例如：初始版本。

   • 執(zhí)行配置

     參數(shù)	描述
     任務(wù)類型	創(chuàng)建自定義組件時，需要選擇任務(wù)類型。目前支持Tensorflow、PyTorch、XGBoost、ElasticBatch四種任務(wù)類型，其分別對應(yīng)了KubeDL中的TFJob、PyTorchJob、XGBoostJob、ElasticBatchJob四種任務(wù)類型。關(guān)于每種任務(wù)類型更詳細的介紹，請參見附錄：任務(wù)類型介紹。
     執(zhí)行鏡像	當前支持選擇社區(qū)鏡像、官方鏡像和自定義鏡像，您也可以在鏡像地址頁簽配置三種類型的鏡像地址。 說明 由于公網(wǎng)帶寬有限，為了保證任務(wù)的穩(wěn)定性，請使用同一個Region下阿里云的鏡像服務(wù)（ACR）。 目前只支持ACR個人版，不支持企業(yè)版，鏡像地址請?zhí)顚?span id="z68uejxpaoma" class="help-letter-space">VPC地址，格式為：registry-vpc.${region}.aliyuncs.com。 使用自定義鏡像時，請勿在同一版本中頻繁更新鏡像，因為這會導致鏡像緩存無法及時更新，從而導致任務(wù)啟動時間延長。 為確保鏡像正常執(zhí)行，鏡像中必須包含sh shell命令。同時，鏡像執(zhí)行命令的方式將使用sh -c方式。 如果使用了自定義鏡像，請確保該鏡像中包含了Python相關(guān)的執(zhí)行環(huán)境和pip命令，否則可能導致任務(wù)運行失敗。
     執(zhí)行代碼	自定義組件的代碼目錄支持OSS目錄和Git地址： OSS掛載：組件運行時，該OSS目錄中所有文件將會被下載到/ml/usercode/目錄下，您可以通過命令執(zhí)行該目錄下的文件。 說明 建議該目錄只存放當前算法必需的文件，否則可能導致組件啟動時間過長、甚至啟動超時。 當代碼目錄中存在requirements.txt文件時，算法運行時會自動執(zhí)行pip install -r requirements.txt安裝相關(guān)依賴。 PAI代碼配置：配置Git代碼庫。
     執(zhí)行命令	組件鏡像的執(zhí)行命令，可以通過環(huán)境變量獲取實際的值，配置格式如下： python main.py $PAI_USER_ARGS --{CHANNEL_NAME} $PAI_INPUT_{CHANNEL_NAME} --{CHANNEL_NAME} $PAI_OUTPUT_{CHANNEL_NAME} && sleep 150 && echo "job finished" 執(zhí)行命令中通過配置PAI_USER_ARGS、PAI_INPUT_{CHANNEL_NAME}、PAI_OUTPUT_{CHANNEL_NAME}環(huán)境變量來讀取超參、輸入和輸出管道數(shù)據(jù)，具體數(shù)據(jù)讀取方法，請參見如何讀取管道及超參數(shù)據(jù)。 例如：輸入管道名稱分別為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中主要提供了解析參數(shù)的邏輯示例，在實際使用時，您將自己的算法邏輯整合進去即可，示例內(nèi)容如下所示： 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)) 下面是上述示例代碼實際運行中打印的日志，您可以看到通過以上方式能夠獲取到任務(wù)實例的參數(shù)信息： 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

   • 管道及參數(shù)

     單擊配置自定義組件的輸入管道（Input Channel）、輸出管道（Output Channel）和參數(shù)。名稱命名格式如下：

     • 要求全局唯一，且互相不能重復。

     • 支持數(shù)字、字母、下劃線（_）和減號（-），不能以下劃線開頭。

       說明

       如果名稱中包含了環(huán)境變量不支持的字符（僅支持字母、數(shù)字和下劃線），在生成環(huán)境變量時，這些字符將被替換為下劃線。此外，名稱中的小寫字母將被轉(zhuǎn)換為大寫字母。因此，應(yīng)避免出現(xiàn)轉(zhuǎn)換為環(huán)境變量后可能產(chǎn)生沖突的情況。例如：如果參數(shù)名分別為test_model、test-model，在轉(zhuǎn)換為環(huán)境變量后，它們將全部變?yōu)?span id="z68uejxpaoma" class="help-letter-space">PAI_HPS_TEST_MODEL，可能會出現(xiàn)沖突。

     管道及參數(shù)配置與Designer組件界面化參數(shù)對應(yīng)關(guān)系如下圖所示：

     具體參數(shù)配置說明如下：

     參數(shù)	描述
     輸入	自定義組件通過輸入管道獲取輸入數(shù)據(jù)或finetune的模型，支持配置以下參數(shù)： 輸入名稱：參照界面提示配置輸入管道名稱。 輸入來源：指定輸入管道讀取OSS、NAS或MaxCompute路徑的數(shù)據(jù)。輸入數(shù)據(jù)會以掛載的形式，掛載到訓練容器的/ml/input/data/{channel_name}/目錄下，組件可以通過讀取本地文件的方式讀取到OSS、NAS或MaxCompute上的數(shù)據(jù)。
     輸出	輸出管道用于保存訓練模型、Checkpoints等結(jié)果，支持配置以下參數(shù)： 輸出名稱：參照界面提示配置輸出管道名稱。 存儲類型：每個輸出管道需要指定一個OSS或MaxCompute目錄，該目錄將會以掛載的方式掛載到訓練容器的/ml/output/{channel_name}/下。
     參數(shù)	超參信息，支持配置以下參數(shù)： 參數(shù)名稱：參照界面提示配置參數(shù)名稱。 參數(shù)類型：目前支持配置Int、Float、String、Bool四種類型。 參數(shù)約束：在默認值列，單擊約束，來配置參數(shù)約束關(guān)系。約束類型取值如下： 范圍：通過配置最大值和最小值來指定取值范圍，僅Int、Float、String類型支持配置。 枚舉：為參數(shù)配置枚舉值。僅Int、Float、String類型支持配置。

   • 訓練約束

     訓練約束用于定義訓練任務(wù)需要的計算資源，您可以打開訓練約束開關(guān)進行配置。

     訓練約束配置轉(zhuǎn)換為Designer組件界面化參數(shù)執(zhí)行調(diào)優(yōu)配置：

     具體參數(shù)說明如下：

     參數(shù)	描述
     機器類型	配置自定義組件支持CPU或GPU機器。
     支持多機	組件是否支持多機分布式運行： 支持：組件運行時，支持配置節(jié)點數(shù)。 不支持：組件運行時，節(jié)點數(shù)只能為1，不支持修改。
     支持多卡	僅當機器類型選擇GPU時，支持配置該參數(shù)。 自定義組件是否支持多卡： 支持：機器類型支持選擇單卡或多卡GPU機器。 不支持：機器類型僅支持選擇單卡GPU機器。

3. 單擊提交。

   組件列表頁面顯示已創(chuàng)建的自定義組件。

組件創(chuàng)建成功后，后續(xù)您可以在Designer中使用該自定義組件，詳情請參見使用自定義組件。

附錄1：任務(wù)類型介紹

{
  "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：自定義組件實現(xiàn)原理

如何讀取管道及超參數(shù)據(jù)

讀取輸入管道數(shù)據(jù)

對于每一個輸入管道的數(shù)據(jù)，會以PAI_INPUT_{CHANNEL_NAME}的環(huán)境變量注入到訓練作業(yè)的容器中。

例如自定義組件有train、test兩個輸入管道，其值分別為：oss://<YourOssBucket>.<OssEndpoint>/path-to-data/和oss://<YourOssBucket>.<OssEndpoint>/path-to-data/test.csv，則注入的環(huán)境變量如下：

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

讀取輸出管道數(shù)據(jù)

組件可以通過PAI_OUTPUT_{CHANNEL_NAME}環(huán)境變量，獲取到對應(yīng)的路徑。

例如自定義組件有model和checkpoints兩個輸出管道，則注入的環(huán)境變量如下：

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

讀取超參數(shù)據(jù)

通過以下環(huán)境變量讀取超參數(shù)據(jù)：

• PAI_USER_ARGS

  組件運行時，作業(yè)的所有超參信息會以PAI_USER_ARGS環(huán)境變量，使用--{hyperparameter_name} {hyperparameter_value}的形式，注入到訓練作業(yè)的容器中。

  例如訓練作業(yè)指定了超參{"epochs": 10, "batch-size": 32, "learning-rate": 0.001}，則PAI_USER_ARGS環(huán)境變量的值為：

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

• PAI_HPS_{HYPERPARAMETER_NAME}

  單個參數(shù)的值，也會以環(huán)境變量的形式注入到訓練作業(yè)的容器中。對于超參名中，環(huán)境變量中不支持的字符（僅支持字母、數(shù)字和下劃線）會被替換為下劃線。

  例如訓練作業(yè)指定了超參{"epochs": 10, "batch-size": 32, "train.learning_rate": 0.001}，對應(yīng)的環(huán)境變量信息如下：

  PAI_HPS_EPOCHS=10
  PAI_HPS_BATCH_SIZE=32
  PAI_HPS_TRAIN_LEARNING_RATE=0.001

• PAI_HPS

  訓練作業(yè)的超參信息會以JSON格式通過PAI_HPS環(huán)境變量注入到訓練作業(yè)的容器中。

  例如訓練作業(yè)傳遞了超參{"epochs": 10, "batch-size": 32}，則PAI_HPS環(huán)境變量的值為：

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

輸入輸出目錄結(jié)構(gòu)

在執(zhí)行代碼中，除了通過環(huán)境變量獲取輸入或輸出管道外，也可以直接通過容器內(nèi)掛載路徑進行訪問。組件提交的任務(wù)在容器內(nèi)執(zhí)行時，會按照以下規(guī)則創(chuàng)建相應(yīng)路徑：

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

• 超參配置文件：/ml/input/config/hyperparameters.json。

• 訓練作業(yè)的完整配置文件：/ml/input/config/training_job.json。

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

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

自定義組件執(zhí)行作業(yè)的輸入輸出目錄結(jié)構(gòu)完整示例如下：

/ml
|-- usercode                        # 用戶代碼加載到/ml/usercode目錄，這里也是用戶代碼的工作目錄. 可以通過環(huán)境變量PAI_WORKING_DIR獲得。
|   |-- requirements.txt
|   |-- main.py
|-- input                           # 作業(yè)輸入數(shù)據(jù)和配置信息
|   |-- config                      # config目錄包含了作業(yè)的配置信息, 可以通過PAI_CONFIG_DIR獲取。
|       |-- training_job.json       # 作業(yè)的完整配置。
|       |-- hyperparameters.json    # 訓練作業(yè)超參.
|   |-- data                        # 作業(yè)的InputChannels: 以下目錄包含了兩個channel: train_data和test_data。
|       |-- test_data
|       |   |-- test.csv
|       |-- train_data
|           |-- train.csv
|-- output                          # 作業(yè)的輸出Channels: 這里有model/checkpoints兩個輸出channel。
        |-- model                   # 通過環(huán)境變量PAI_OUTPUT_{OUTPUT_CHANNEL_NAME}可以獲輸出路徑。
        |-- checkpoints

如何判斷是否是GPU機器以及GPU卡數(shù)

任務(wù)啟動后，可以通過環(huán)境變量NVIDIA_VISIBLE_DEVICES來判斷當前機器是否具有GPU以及GPU卡數(shù)。例如：NVIDIA_VISIBLE_DEVICES=0,1,2,3表示當前機器具有4張GPU卡。