封裝訓練應用程式

在使用 AI Platform 執行訓練應用程式之前,您必須先將程式碼和任何依附元件上傳至 Google Cloud Platform 專案可存取的 Cloud Storage 值區。本頁面說明如何在雲端中封裝和暫存應用程式。

如要獲得最佳結果,在您將訓練應用程式上傳到雲端之前,請先在本機上測試這個應用程式。使用 AI Platform 執行訓練時,系統會依照使用的資源向您的帳戶收費

事前準備

您必須先完成下列步驟,才能將訓練應用程式移到雲端:

  1. 按照入門指南所述,設定您的開發環境。
  2. 按照指南設定 Cloud Storage 值區,以儲存訓練應用程式的資料和檔案。

  3. 瞭解訓練應用程式依附的所有 Python 程式庫。這些程式庫可以是自訂套件,或可透過 PyPI 免費取得。

本文件討論影響應用程式的封裝以及上傳到 Cloud Storage 的因素,如下:

  • 使用 gcloud 工具 (建議),或自行撰寫解決方案程式碼。
  • 必要時手動建立封裝。
  • 如何納入使用的 AI Platform 執行階段沒有安裝的其他依附元件。

    如要封裝應用程式並與依附元件一起上傳,最簡單的方法就是使用 gcloud 工具。您可以使用相同的指令 (gcloud ai-platform jobs submit training) 來封裝及上傳應用程式,以及提交您的第一個訓練工作。

    將設定值定義為環境變數十分便利且有用。下列變數包含用於暫存應用程式套件的值:

    TRAINER_PACKAGE_PATH="/path/to/your/application/sources"
    MAIN_TRAINER_MODULE="trainer.task"
    PACKAGE_STAGING_PATH="gs://your/chosen/staging/path"
    

    此外,下列變數定義了執行工作時使用的值:

    now=$(date +"%Y%m%d_%H%M%S")
    JOB_NAME="your_name_$now"
    JOB_DIR="gs://your/chosen/job/output/path"
    REGION="us-east1"
    

    下列範例顯示封裝應用程式及提交訓練工作的 gcloud ai-platform jobs submit training 指令:

    gcloud ai-platform jobs submit training $JOB_NAME \
        --staging-bucket $PACKAGE_STAGING_PATH \
        --job-dir $JOB_DIR  \
        --package-path $TRAINER_PACKAGE_PATH \
        --module-name $MAIN_TRAINER_MODULE \
        --region $REGION \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    
    • --staging-bucket 指定用於暫存訓練和依附元件套件的 Cloud Storage 位置。您的 GCP 專案必須能存取此 Cloud Storage 值區,而且值區應位於執行工作的地區。請參閱 AI Platform 服務的可用地區。如未指定暫存值區,AI Platform 會將您的封裝儲存在 job-dir 參數中指定的位置。

    • --job-dir 指定訓練工作輸出檔案使用的 Cloud Storage 位置。您的 GCP 專案必須能存取此 Cloud Storage 值區,而且值區應位於執行工作的地區。請參閱 AI Platform 服務的可用地區

    • --package-path 指定應用程式根目錄的本機路徑。請參閱建議的專案結構

    • --module-name 會使用套件的命名空間點記號來指定應用程式主模組的名稱。您將執行這個 Python 檔案來啟動應用程式。例如,如果您的主模組是 .../my_application/trainer/task.py (請參閱建議的專案結構),則模組名稱是 trainer.task

    • 如果您在設定檔 (config.yaml) 中指定選項,且將選項做為指令列標記,則指令列上的值會覆寫設定檔內的值。
    • 空白的 -- 標記是用來標示 gcloud 特定標記的結尾,以及您要傳送到應用程式的 USER_ARGS 開頭。
    • AI Platform 的特定標記,例如 --module-name--runtime-version--job-dir,必須放在空白的 -- 標記之前。AI Platform 服務會解讀這些標記。
    • 由於 AI Platform 會使用 --job-dir 來驗證路徑,因此如有指定 --job-dir 標記,則必須放在空白的 -- 標記之前。
    • 您的應用程式也必須處理 --job-dir 標記 (如有指定)。即使標記位於空白的 -- 之前,--job-dir 也會做為指令列標記傳送到應用程式。
    • 您可以定義所需的 USER_ARGS 數量。AI Platform 會將 --user_first_arg--user_second_arg 等標記傳送到您的應用程式。

    您可在執行訓練工作指南中找到關於工作提交標記的詳細資訊。

    使用依附元件

    依附元件是您 import 到程式碼的套件。您的應用程式可能包含許多依附元件,沒有這些依附元件,應用程式將無法正常運作。

    在 AI Platform 上執行訓練工作時,工作會在已安裝許多通用 Python 套件的「訓練執行個體」(特別設定的虛擬機器) 上執行。請檢查您用於訓練的執行階段版本中的套件,並記下尚未安裝的依附元件。

    您需要新增的依附元件有兩種類型:

    • 「標準」依附元件,PyPI 上提供的通用 Python 套件。
    • 「自訂」套件,例如您自行開發的套件,或組織機構內部的套件。

    下列章節說明每個類型的程序。

    新增標準的 (PyPI) 依附元件

    您可將套件的標準依附元件指定為其 setup.py 指令碼的一部分。AI Platform 使用 pip 將您的套件安裝在為您的工作分配的訓練執行個體上。pip install 指令會尋找已設定的依附元件並進行安裝。

    在應用程式的根目錄中建立名為 setup.py 的檔案 (如果您按照建議的模式進行,根目錄即是 trainer 目錄上一層的目錄)。

    setup.py 中輸入下列指令碼,並插入您自己的值:

    from setuptools import find_packages
    from setuptools import setup
    
    REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']
    
    setup(
        name='trainer',
        version='0.1',
        install_requires=REQUIRED_PACKAGES,
        packages=find_packages(),
        include_package_data=True,
        description='My training application package.'
    )
    

    如果您使用 gcloud 指令列工具來提交訓練工作,它會自動使用您的 setup.py 檔案來建立套件。

    如果您不使用 gcloud 來提交訓練工作,請使用下列指令來執行程式碼:

    python setup.py sdist
    

    詳情請參閱關於手動封裝您的訓練應用程式一節。

    新增自訂的依附元件

    您可將依附元件的路徑做為工作設定的一部分來傳送,以指定應用程式的自訂依附元件。您需要 URI 來封裝每一個依附元件。自訂的依附元件必須位於 Cloud Storage 位置。AI Platform 使用 pip install 安裝自訂的依附元件,以便在 setup.py 指令碼中擁有自己的標準依附元件。

    如果您使用 gcloud 工具來執行訓練工作,您可以指定本機目錄,工具就會在雲端中暫存本機目錄。執行 gcloud ai-platform jobs submit training 指令:

    • 設定 package-path 標記,將您的訓練應用程式指定為儲存原始碼的目錄路徑,或指定為已建立套件的路徑。

    • 設定 --packages 標記,將依附元件納入逗號分隔的清單中。

    您納入的每個 URI 都是套件的路徑,經格式化為 tarball (*.tar.gz) 或 wheel 檔。AI Platform 會使用 pip install 在為訓練工作分配的每個虛擬機器上安裝套件。

    下列範例指定名為 dep1.tar.gzdep2.whl 的封裝依附元件 (分屬不同的支援套件類型),以及應用程式原始碼的路徑:

    gcloud ai-platform jobs submit training $JOB_NAME \
        --staging-bucket $PACKAGE_STAGING_PATH \
        --package-path /Users/mluser/models/faces/trainer \
        --module-name $MAIN_TRAINER_MODULE \
        --packages dep1.tar.gz,dep2.whl \
        --region us-central1 \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    

    同理,下列範例指定名為 dep1.tar.gzdep2.whl 的封裝依附元件 (分屬不同的支援套件類型),以及已建立的訓練應用程式:

    gcloud ai-platform jobs submit training $JOB_NAME \
        --staging-bucket $PACKAGE_STAGING_PATH \
        --module-name $MAIN_TRAINER_MODULE \
        --packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
        --region us-central1 \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    

    如果您直接使用 AI Platform Training 和 Prediction API 來執行訓練工作,您必須自行在 Cloud Storage 位置暫存依附套件,然後使用這個位置中的套件路徑。

    手動建立您的套件

    封裝 Python 程式碼是一個廣泛的主題,遠超過本說明文件的範圍。為便利起見,本節提供使用 Setuptools 來建立套件的總覽,您也可以使用其他程式庫來建立套件。

    請按照下列步驟,手動建立套件:

    1. 在應用程式套件的每一個目錄中,納入名為 __init__.py 的檔案,此檔案可能是空白的,或含有程式碼,會在匯入該套件 (該目錄中的任何模組) 時執行。

    2. 在套件的根目錄 (如果您按照建議的模式進行,則該目錄是 trainer 目錄上一層的目錄) 中納入名為 setup.pySetuptools 檔案,該檔案包含:

      • setuptools.find_packagessetuptools.setup 的匯入陳述式。

      • 呼叫 setuptools.setup,並 (至少) 設定下列參數:

        • _name_ 設定為套件命名空間的名稱。

        • _version_ 設定為此套件版本的版本號碼。

        • _install_requires_ 設定為應用程式所需的套件清單,包含版本需求,例如 ‘docutils>=0.3'

        • _packages_ 設定為 find_packages()

        • _include_package_data_ 設定為 True

    3. 執行 python setup.py sdist 以建立套件。

    建議的專案結構

    您可以用任何方式來建構您的訓練應用程式。下列結構常用於 AI Platform 範例,若您的專案組織結構與範例類似,將較易於依循範例進行。

    • 使用主專案目錄,其中包含 setup.py 檔案。

    • 使用名為 trainer 的子目錄,儲存主要的應用程式模組。

    • 為主要的應用程式模組 task.py 命名。

    • 在您要實作應用程式的主專案目錄中,建立其他子目錄。

    • 在每一個子目錄中建立 __init__.py 檔案。這些檔案由 Setuptools 使用,可識別含有要封裝的程式碼的目錄,這些檔案也可能是空白的。

    在 AI Platform 範例中,trainer 目錄通常包含以下來源檔案:

    • task.py 包含管理訓練工作的應用程式邏輯。

    • model.py 包含 TensorFlow 圖形程式碼,也就是模型的邏輯。

    • util.py (若有),包含執行訓練應用程式的程式碼。

    訓練應用程式專案的建議結構

    如果您使用 gcloud 工具來封裝應用程式,就不需要建立 setup.py 或任何 __init__.py 檔案。當您執行 gcloud ai-platform jobs submit training 時,您可以將 --package_path 標記設定至您的主專案目錄路徑,或者也可以從該目錄執行工具並完全省略該標記。

    Python 模組

    應用程式套件可以包含多個模組 (Python 檔案)。您必須識別含有應用程式進入點的模組。訓練服務會叫用 Python 以執行該模組,就像您在本機上執行模組一樣。

    您將應用程式納入 Python 套件內時,會建立命名空間。例如,如果建立名為 trainer 的套件,且主模組名為 task.py,請以 trainer.task 名稱來指定該套件。因此,執行 gcloud ai-platform jobs submit training 時,請將 --module-name 標記設定至 trainer.task

    如要進一步瞭解模組,請參閱 Python 套件指南

    使用 gcloud 工具上傳現有套件

    如果您自行建立套件,可使用 gcloud 工具來上傳。執行 gcloud ai-platform jobs submit training 指令:

    • --packages 標記設定為封裝應用程式的路徑。

    • 使用套件的命名空間點記號,將 --module-name 標記設定為應用程式主模組的名稱。您將執行這個 Python 檔案來啟動應用程式。例如,如果您的主模組是 .../my_application/trainer/task.py (請參閱建議的專案結構),則模組名稱是 trainer.task

    下列範例顯示如何使用在執行指令的目錄內的已壓縮 tarball 套件 (在此名為 trainer-0.0.1.tar.gz)。主功能位於名為 task.py: 的模組中。

    gcloud ai-platform jobs submit training $JOB_NAME \
        --staging-bucket $PACKAGE_STAGING_PATH \
        --job-dir $JOB_DIR \
        --packages trainer-0.0.1.tar.gz \
        --module-name $MAIN_TRAINER_MODULE \
        --region us-central1 \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    

    使用 gcloud 工具來使用雲端中現有的套件

    如果您要自行建立套件,並上傳到 Cloud Storage 位置,可使用 gcloud 來上傳。執行 gcloud ai-platform jobs submit training 指令:

    • --packages 標記設定為封裝應用程式的路徑。

    • 使用套件的命名空間點記號,將 --module-name 標記設定為應用程式主模組的名稱。您將執行這個 Python 檔案來啟動應用程式。例如,如果您的主模組是 .../my_application/trainer/task.py (請參閱建議的專案結構),則模組名稱是 trainer.task

    下列範例顯示如何使用 Cloud Storage 值區中的已壓縮 tarball 套件:

    gcloud ai-platform jobs submit training $JOB_NAME \
        --job-dir $JOB_DIR \
        --packages $PATH_TO_PACKAGED_TRAINER \
        --module-name $MAIN_TRAINER_MODULE \
        --region us-central1 \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    

    其中 $PATH_TO_PACKAGED_TRAINER 是環境變數,代表雲端中現存套件的路徑。例如,路徑可指向下列 Cloud Storage 位置,其中包含名為 trainer-0.0.1.tar.gz 的已壓縮 tarball 套件:

    PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz
    

    手動上傳套件

    如有必要,您可以手動上傳套件。通常選擇這麼做的原因是您想要直接呼叫 AI Platform Training 和 Prediction API 以啟動訓練工作。如要手動上傳套件與任何自訂依附元件到 Cloud Storage 值區,最簡單的方法就是使用 gsutil 工具:

    gsutil cp /local/path/to/package.tar.gz  gs://bucket/path/
    

    不過,如果您可以使用指令列進行這項作業,您應在設定訓練工作的過程中直接使用 gcloud ai-platform jobs submit training 上傳您的套件。如果無法使用指令列,可使用 Cloud Storage 用戶端程式庫以透過程式上傳

    後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
TensorFlow 適用的 AI Platform