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

如要使用預先建構的容器執行 Gemini Enterprise Agent Platform 無伺服器訓練，您必須建立包含訓練應用程式的 Python 原始碼發行版本，並上傳至 Google Cloud 專案可存取的 Cloud Storage bucket。

建立來源發行版本的替代方案

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

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

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

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

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

  • 如果您能以單一 Python 指令碼編寫訓練程式碼，則可使用 Agent Platform SDK for Python 的 CustomJob 類別建立自訂工作，或使用 CustomTrainingJob 類別建立自訂 TrainingPipeline。訓練程式碼會自動封裝為來源發行版本，並上傳至 Cloud Storage。

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

如果上述選項都不符合您的用途，或者您偏好手動將訓練應用程式封裝為來源發行版本，請按照本指南的其餘部分操作。

事前準備

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

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

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

  2. 在您打算使用 Agent Platform 的 Google Cloud 專案中，建立 Cloud Storage bucket。您會將訓練應用程式儲存在這個 bucket 中。(雖然可以使用不同Google Cloud bucket 中的 bucket，但這需要額外設定，不在本指南的範圍內)。

    為確保最佳效能，請確認 Cloud Storage bucket 位於您打算使用 Agent Platform 的位置。

  3. 瞭解訓練應用程式依賴的所有 Python 程式庫，無論是自訂依附元件，還是可透過 PyPI 自由取得的程式庫。

應用程式結構

使用預先建構的容器執行無伺服器訓練時，必須按照下列規定指定訓練程式碼：

  • 以一或多個 Python 原始碼發行套件的形式提供程式碼。

    如果您使用 Agent Platform API 啟動無伺服器訓練，請在 packageUris 欄位中指定這些項目。

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

    如果使用 Agent Platform API 啟動自訂訓練，請在 pythonModule 欄位中指定。

只要符合這些規定，您就能以任何方式建構訓練應用程式。不過，建議您按照下列結構 (Agent Platform 範例中常用) 整理程式碼，建構單一 Python 來源發行版本：

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

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

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

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

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

本指南的其餘部分假設您的程式碼是根據這個結構進行整理。

建立來源發布

建構 Python 來源發行版本是個廣泛的主題，大部分內容超出本說明文件的範圍。為方便起見，本節將概略說明如何使用 Setuptools 建構來源發行版本，以便與 Agent Platform 搭配使用。您也可以使用其他程式庫執行相同操作。

  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 指令碼中指定標準依附元件。Agent Platform 會使用 pip，在為工作分配的副本上安裝訓練應用程式。pip install 指令會尋找已設定的依附元件並加以安裝。

以下範例顯示的 setup.py 與前一節類似。不過，這個 setup.py 會指示 Agent Platform 在安裝訓練應用程式時，一併安裝 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 位置。Agent Platform 會使用 pip install 安裝自訂依附元件，因此 setup.py 指令碼中可以有自己的標準依附元件。

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

如果使用 Agent Platform API 啟動無伺服器訓練，請在 packageUris 欄位中，指定這些依附元件的 Cloud Storage URI 和訓練應用程式。

Python 模組

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

舉例來說，如果您按照前一節的建議結構，主要模組就是 task.py。由於該模組位於名為 trainer 的匯入套件 (含有 __init__.py 檔案的目錄) 中，因此這個模組的完整名稱為 trainer.task。因此，如果您使用 Agent Platform API 啟動自訂訓練，請將 moduleName 欄位設為 trainer.task。

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

將來源發行版本上傳至 Cloud Storage

您可以使用 gcloud CLI，將來源發行套件和任何自訂依附元件上傳至 Cloud Storage bucket。例如：

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

將 CLOUD_STORAGE_DIRECTORY 替換為 Cloud Storage 目錄的 URI (開頭為 gs://，結尾為 /)，該目錄位於Google Cloud 專案可存取的 bucket 中。

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

從 python_package_spec 遷移至 container_spec

PythonPackageSpec 設定 (executorImageUri) 僅接受官方支援的預先建構訓練容器。如果您的框架或執行階段已達到可用性終止 (EOA) 狀態 (例如 scikit-learn 或 XGBoost)，或者您需要較新的 Python 版本 (例如 Python 3.11 以上版本) 和外部系統程式庫，請將訓練工作負載遷移至 ContainerSpec。

與 python_package_spec 不同，ContainerSpec 沒有 package_uris 或 python_module 欄位。

如要將工作負載遷移至 container_spec，請選擇下列其中一種方法：

  • 將套件保留在 Cloud Storage：透過 args 或 env 將套件 URI 傳遞至容器中的進入點指令碼，該指令碼會下載套件、使用 pip 安裝套件，並執行 python -m <module>。

    例如，在容器的進入點指令碼中：

    #!/usr/bin/env bash
set -e

PACKAGE_URI="$1"
MODULE_NAME="$2"
shift 2

gcloud storage cp "${PACKAGE_URI}" ./package.tar.gz
pip install --no-cache-dir ./package.tar.gz
python -m "${MODULE_NAME}" "$@"

  • 將程式碼建構至映像檔：或者，您也可以在建構時，直接將訓練應用程式檔案和依附元件複製到 Docker 映像檔 (例如，在 Dockerfile 中使用 COPY 和 pip install)，並直接在映像檔中設定進入點。

後續步驟