為預先建立的容器建構 Python 訓練應用程式

如要使用預先建構的容器執行自訂訓練，您必須先建立包含訓練應用程式的 Python 來源發行版本，並將其上傳至 Google Cloud 專案可存取的 Cloud Storage 值區。

建立來源發布內容的替代方案

本指南會逐步說明如何手動建立來源發布內容，並上傳至 Cloud Storage。按照本指南操作前，請先考慮下列替代工作流程，這些流程在某些情況下可能更方便：

  • 如要使用本機電腦上的程式碼進行訓練，並盡可能減少手動封裝工作，建議使用 Google Cloud CLI 的自動封裝功能。這項功能可讓您建構 Docker 容器映像檔、將其推送至 Artifact Registry，並根據容器映像檔建立 CustomJob 資源，所有作業只需一個指令即可完成。詳情請參閱建立 CustomJob 的指南。

    如要使用自動封裝功能，您必須在本機電腦上安裝 Docker。這個選項只能建立 CustomJob，無法建立 TrainingPipeline 或 HyperparameterTuningJob 資源。(瞭解自訂訓練資源之間的差異)。

  • 如要進一步自訂容器映像檔，並在 Vertex AI 上執行程式碼前，先在本機容器中執行程式碼，可以使用 gcloud CLI 的 local-run 指令將程式碼容器化，並在本機執行。然後，您可以手動將映像檔推送至 Artifact Registry。

    如要使用 local-run 指令，您必須在本機電腦上安裝 Docker。

  • 如果可以將訓練程式碼寫入單一 Python 指令碼，則可以使用 Python 適用的 Vertex AI SDK 的 CustomJob 類別建立自訂工作，或使用 CustomTrainingJob 類別建立自訂 TrainingPipeline。訓練程式碼會自動封裝為來源發布內容，並上傳至 Cloud Storage。

  • 如要享有最大彈性，可以手動建立自訂容器映像檔，並將其推送至 Artifact Registry。

如果上述選項都不符合您的使用案例，或者您偏好手動將訓練應用程式封裝為來源發布套件，請按照本指南的其餘內容操作。

事前準備

準備在雲端執行訓練應用程式之前，請先完成下列步驟：

  1. 使用 Vertex AI 預建訓練容器提供的機器學習 (ML) 架構，開發訓練應用程式。確認訓練應用程式符合訓練程式碼規定。

    如果您要從頭開始編寫訓練應用程式，建議您按照本文後續章節所述的應用程式結構來整理程式碼。

  2. 在您打算使用 Vertex AI 的「同一個」 Google Cloud 專案中建立 Cloud Storage 值區。您將訓練應用程式儲存在這個值區中。(雖然可以在不同的Google Cloud bucket 中使用 bucket，但這需要超出本指南範圍的額外設定)。

    為獲得最佳效能，請確保 Cloud Storage bucket 位於您打算使用 Vertex AI 的位置。

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

應用程式結構

使用預先建構的容器執行自訂訓練時，您必須根據下列規定指定訓練程式碼：

  • 以一或多個 Python 來源發布的形式提供程式碼。

    如果您使用 Vertex AI API 啟動自訂訓練，請在 packageUris 欄位中指定這些項目。

  • 在其中一個來源發布版本中建立模組，做為訓練的進入點。

    如果您使用 Vertex AI API 啟動自訂訓練作業，請在 pythonModule 欄位中指定這項設定。

只要符合這些規定，您可以用任何方式來建構訓練應用程式。不過，建議您按照下列結構整理程式碼，建構單一 Python 來源發布內容 (Vertex AI 範例中經常使用這種結構)：

  • 使用主專案目錄，其中包含 setup.py 檔案。如需這個檔案內容的相關指引，請參閱下一節。

  • 在主專案目錄中，建立名為 trainer/ 的子目錄，做為訓練程式碼的主要套件。

  • 在 trainer/ 中，建立名為 task.py 的模組，做為訓練程式碼的進入點。

  • 如要支援 trainer/task.py，請在 trainer/ 套件中建立任何所需的其他 Python 模組，並在主專案目錄中建立任何所需的其他子目錄和程式碼。

  • 在每個子目錄中建立 __init__.py 檔案，將子目錄設為套件。

本指南的其餘部分會假設您的程式碼是按照這個結構整理。

建立來源發布內容

建構 Python 來源發行版本是一個廣泛的主題，遠超過本說明文件的範圍。為便利起見，本節提供使用 Setuptools 建立來源發布套件的總覽，以搭配 Vertex AI 使用。您也可以使用其他程式庫來建立套件。

  1. 建立 setup.py 檔案，告知 Setuptools 如何建立來源發行版本。基本 setup.py 包含下列內容：

    • setuptools.find_packages 和 setuptools.setup 的匯入陳述式。

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

      • 將 name 設為來源發行版本的名稱。

      • 將 version 設為這個來源發布版本的版本號碼。

      • install_requires 設定為應用程式所需的依附元件清單，包含版本需求，例如 'docutils>=0.3'。

      • 「packages」已設為「find_packages()」。這會告知 Setuptools 將包含 __init__.py 檔案的父項目錄的所有子目錄納入為套件。

      • include_package_data已設為True。

    以下範例顯示訓練應用程式的基本 setup.py 檔案：

    from setuptools import find_packages
from setuptools import setup

setup(
    name='trainer',
    version='0.1',
    packages=find_packages(),
    include_package_data=True,
    description='My training application.'
)

  2. 執行下列指令，建立來源發布套件 dist/trainer-0.1.tar.gz：

    python setup.py sdist --formats=gztar

Python 應用程式依附元件

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

在自訂訓練工作中，每個副本的程式碼都會在容器中執行，且容器已安裝許多常見的 Python 依附元件。檢查您打算用於訓練的預先建構容器中包含的依附元件，並記下尚未安裝的依附元件。如果預先建構的容器中尚未安裝依附元件，才需要完成下列步驟。

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

  • 「標準」依附元件，也就是 PyPI 所提供的通用發布套件
  • 「自訂」依附元件，例如您自行開發的套件，或組織機構內部的套件。

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

標準 (PyPI) 依附元件

您可以將應用程式的標準依附元件指定為 setup.py 指令碼的一部分。Vertex AI 會使用 pip，在為工作分配的副本上安裝訓練應用程式。pip install 指令會尋找並安裝已設定的依附元件。

以下範例顯示的 setup.py 與上一節的類似。不過，這個 setup.py 會告知 Vertex AI 在安裝訓練應用程式時安裝 some_PyPI_package：

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.'
)

自訂依附元件

您可將依附元件的路徑做為工作設定的一部分來傳送，以指定應用程式的自訂依附元件。您需要每個依附元件的來源發行 URI。自訂的依附元件必須位於某個 Cloud Storage 位置。Vertex AI 會使用 pip install 安裝自訂依附元件，因此 setup.py 指令碼可擁有自己的標準依附元件。

您納入的每個 URI，都是已格式化為 tar 檔案 (.tar.gz) 或 wheel 檔 (.whl) 的來源發行版本路徑。Vertex AI 會在分配給訓練工作的每個副本上，使用 pip install 安裝每個依附元件。

如果您使用 Vertex AI API 啟動自訂訓練，請在 packageUris 欄位中，一併指定這些依附元件的 Cloud Storage URI 和訓練應用程式。

Python 模組

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

舉例來說，如果您按照上一節中的建議結構操作，則主模組為 task.py。由於該模組位於名為 trainer 的「匯入套件」(有 __init__.py 檔案的目錄) 中，它的完整名稱會是 trainer.task。因此，如果您使用 Vertex AI API 啟動自訂訓練，請將 moduleName 欄位設為 trainer.task。

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

將來源發布內容上傳至 Cloud Storage

您可以使用 gcloud CLI，將來源發布內容和任何自訂依附元件上傳到 Cloud Storage 值區。例如：

gcloud storage cp dist/trainer-0.1.tar.gz CLOUD_STORAGE_DIRECTORY

請將 CLOUD_STORAGE_DIRECTORY 改成值區中 Cloud Storage 目錄的 URI (開頭為 gs://，結尾為 /)，該值區必須可供您的Google Cloud 專案存取。

如要瞭解將來源發行套件上傳至 Cloud Storage 的其他方法，請參閱 Cloud Storage 說明文件中的「上傳物件」一節。

後續步驟