建立自訂訓練工作

gcloud

以下範例使用 gcloud ai custom-jobs create 指令。

如果訓練程式碼位於本機電腦上，建議您按照「自動封裝」一節的說明操作。或者，如果您已建立 Python 訓練應用程式或自訂容器映像檔，請直接跳至「不使用自動封裝」一節。

自動打包

如果本機電腦上有訓練程式碼，您可以使用單一指令執行下列操作：

• 根據您的程式碼建構自訂 Docker 映像檔。
• 將映像檔推送至 Artifact Registry。
• 根據圖片啟動 CustomJob。

結果與使用任何其他自訂容器建立 CustomJob 類似；如果這個指令版本對您的工作流程較方便，您可以使用這個版本。

事前準備

由於這個版本的指令會建構並推送 Docker 映像檔，因此您必須在本機電腦上執行下列設定：

1. 安裝 Docker Engine。

2. 如果您使用的是 Linux，請設定 Docker，以便在沒有 sudo 的情況下執行 Docker。

3. Enable the Artifact Registry API.

   Enable the API

4. 為 Docker 設定驗證機制，以便將 Docker 映像檔推送至 Artifact Registry：

   gcloud auth configure-docker
   

建構及推送 Docker 映像檔，並建立 CustomJob

下列指令會根據預先建構的訓練容器映像檔和本機 Python 程式碼建構 Docker 映像檔，將映像檔推送至 Artifact Registry，並建立 CustomJob。

gcloud ai custom-jobs create \
  --region=LOCATION \
  --display-name=JOB_NAME \
  --worker-pool-spec=machine-type=MACHINE_TYPE,replica-count=REPLICA_COUNT,executor-image-uri=EXECUTOR_IMAGE_URI,local-package-path=WORKING_DIRECTORY,script=SCRIPT_PATH

更改下列內容：

• LOCATION：容器或 Python 套件執行的區域。

• JOB_NAME：必填。CustomJob 的顯示名稱。

• MACHINE_TYPE：機器類型。請參閱可用訓練機器類型。

• REPLICA_COUNT：要使用的 worker 備用資源數量。在大多數情況下，請將此值設為第一個工作站集區的 1。

• EXECUTOR_IMAGE_URI：執行提供程式碼的容器映像檔 URI。請參閱可用於訓練的預先建構容器。

  這個映像檔會做為您使用此指令建構的新 Docker 映像檔的基本映像檔。

• WORKING_DIRECTORY：本機檔案系統中的目錄，其中包含執行訓練程式碼的進入點指令碼 (請參閱下列清單項目)。

  您可以使用指令碼的父目錄或更高層級的目錄。您可能需要使用較高層級的目錄，才能指定完整的 Python 模組名稱 (請參閱下列清單項目)。如果包含 requirements.txt 或 setup.py 檔案，您可能也需要使用較高層級的目錄。詳情請參閱「安裝依附元件」。

  請注意，即使您指定較高層級的目錄，這個指令仍只會將進入點指令碼的父目錄複製到 Docker 映像檔。

• SCRIPT_PATH：相對於本機檔案系統中的 WORKING_DIRECTORY 路徑，指向訓練程式碼的進入點指令碼。這個檔案可以是 Python 指令碼 (結尾為 .py) 或 Bash 指令碼。

  舉例來說，如果您要執行 /hello-world/trainer/task.py，而 WORKING_DIRECTORY 為 /hello-world，請使用 trainer/task.py 做為這個值。

  使用 python-module 取代 script

  您可以選擇將 script=SCRIPT_PATH 替換為 python-module=PYTHON_MODULE，藉此指定 WORKING_DIRECTORY 中的 Python 模組名稱，以便做為訓練的進入點執行。例如，您可以指定 python-module=trainer.task，而非 script=trainer/task.py。

  在這種情況下，產生的 Docker 容器會以模組形式載入程式碼，而非以指令碼形式載入。如果進入點指令碼會在 WORKING_DIRECTORY 中匯入其他 Python 模組，您可能會想使用這個選項。

安裝依附元件

使用自動封裝功能時，您可以使用 gcloud CLI 的 local-run 指令，在容器中安裝 Python 依附元件。如要瞭解安裝 Python 依附元件的各種方式，請參閱 local-run 指令指南中的「安裝依附元件」一節。

使用自動封裝功能時，指定依附元件的語法會與使用 local-run 指令時略有不同。您必須在 --worker-pool-spec 旗標的值中使用選項，而非使用指令列標記指定依附元件。此外，這些選項內的值必須以分號而非半形逗號分隔。具體來說，語法如下：

• 在 --worker-pool-spec 旗標的值中使用 local-package-path 選項，而非 local-run 指令的 --local-package-path 旗標。如果您使用這個選項指定的工作目錄含有 requirements.txt 或 setup.py 檔案，自動封裝會根據這個檔案安裝相依項。

  上述範例說明瞭這個語法。

• (選用) 在 --worker-pool-spec 旗標的值中，使用 requirements 選項，而非 --requirements 旗標。請改用分號，而非使用半形逗號分隔 PyPI 依附元件。

• (選用) 在 --worker-pool-spec 旗標的值中，使用 extra-packages 選項，而非 --extra-packages 旗標。請改用分號，而非使用半形逗號分隔本機依附元件。

• (選用) 在 --worker-pool-spec 標記的值中，使用 extra-dirs 選項，而非 --extra-dirs 標記。請改用分號，不要使用半形逗號分隔目錄路徑。

以下範例說明如何使用所有選用技巧安裝依附元件。(您可以指定其中任何子集)。為了示範分號語法，這個範例為每個選項指定兩個值。為了縮短範例長度，其他 --worker-pool-spec 選項會以 [...] 取代。

gcloud ai custom-jobs create \
  --region=LOCATION \
  --display-name=JOB_NAME \
  --worker-pool-spec=[...],requirements=PYPI_DEP_1;PYPI_DEP_2,extra-packages=LOCAL_DEP_1;LOCAL_DEP_2,extra-dirs=EXTRA_DIR_1;EXTRA_DIR_2

如要瞭解這些預留位置的適當值，請參閱 local-run 指令指南中的「安裝依附元件」。

不使用自動封裝

如果您不使用自動封裝功能，可以使用類似下列指令建立 CustomJob。視您建立 Python 訓練應用程式或自訂容器映像檔而定，請選擇下列其中一個分頁：

gcloud ai custom-jobs create \
  --region=LOCATION \
  --display-name=JOB_NAME \
  --python-package-uris=PYTHON_PACKAGE_URIS \
  --worker-pool-spec=machine-type=MACHINE_TYPE,replica-count=REPLICA_COUNT,executor-image-uri=EXECUTOR_IMAGE_URI,python-module=PYTHON_MODULE

gcloud ai custom-jobs create \
  --region=LOCATION \
  --display-name=JOB_NAME \
  --worker-pool-spec=machine-type=MACHINE_TYPE,replica-count=REPLICA_COUNT,container-image-uri=CUSTOM_CONTAINER_IMAGE_URI

分散式訓練

如要執行分散式訓練，請為每個 worker pool 指定 --worker-pool-spec 旗標多次。

如果您使用自動封裝功能，則只需在第一個 worker 集區中指定 local-package-path、script 和其他與自動封裝相關的選項即可。在後續工作站集區中省略與訓練程式碼相關的欄位，這些集區都會使用透過自動封裝建立的相同訓練容器。

舉例來說，下列指令會調整先前的自動封裝範例，以便使用第二個工作站集區：

gcloud ai custom-jobs create \
  --region=LOCATION \
  --display-name=JOB_NAME \
  --worker-pool-spec=machine-type=MACHINE_TYPE,replica-count=REPLICA_COUNT,executor-image-uri=EXECUTOR_IMAGE_URI,local-package-path=WORKING_DIRECTORY,script=SCRIPT_PATH \
  --worker-pool-spec=machine-type=SECOND_POOL_MACHINE_TYPE,replica-count=SECOND_POOL_REPLICA_COUNT

如果您未使用自動封裝功能，請完整且獨立地指定每個工作站集區，請勿省略任何欄位。

下列指令會調整先前的範例，以便使用第二個工作站集區：

gcloud ai custom-jobs create \
  --region=LOCATION \
  --display-name=JOB_NAME \
  --python-package-uris=PYTHON_PACKAGE_URIS \
  --worker-pool-spec=machine-type=MACHINE_TYPE,replica-count=REPLICA_COUNT,executor-image-uri=EXECUTOR_IMAGE_URI,python-module=PYTHON_MODULE \
  --worker-pool-spec=machine-type=SECOND_POOL_MACHINE_TYPE,replica-count=SECOND_POOL_REPLICA_COUNT,executor-image-uri=SECOND_POOL_EXECUTOR_IMAGE_URI,python-module=SECOND_POOL_PYTHON_MODULE

gcloud ai custom-jobs create \
  --region=LOCATION \
  --display-name=JOB_NAME \
  --worker-pool-spec=machine-type=MACHINE_TYPE,replica-count=REPLICA_COUNT,container-image-uri=CUSTOM_CONTAINER_IMAGE_URI \
  --worker-pool-spec=machine-type=SECOND_POOL_MACHINE_TYPE,replica-count=SECOND_POOL_REPLICA_COUNT,container-image-uri=SECOND_POOL_CUSTOM_CONTAINER_IMAGE_URI

進階設定

如果您想指定前述範例中未提供的設定選項，可以使用 --config 標記，在本機環境中指定 config.yaml 檔案的路徑，該檔案包含 CustomJobSpec 的欄位。例如：

gcloud ai custom-jobs create \
  --region=LOCATION \
  --display-name=JOB_NAME \
  --config=config.yaml

請參閱 config.yaml 檔案範例。

控制台

您無法在 Google Cloud 主控台中直接建立 CustomJob 資源。不過，您可以建立可建立 CustomJob 的 TrainingPipeline 資源。

以下操作說明說明如何建立 TrainingPipeline，以便建立 CustomJob 且不執行任何其他操作。如要使用其他 TrainingPipeline 功能，例如使用受管理的資料集進行訓練，或是在訓練結束後建立 Model 資源，請參閱「建立訓練管道」一文。

1. 在 Google Cloud 控制台的 Vertex AI 專區中，前往「Training pipelines」頁面。

   前往訓練管道

2. 按一下「建立」圖示 add_box，開啟「訓練新模型」窗格。

3. 在「訓練方法」步驟中，指定下列設定：

   1. 在「Dataset」下拉式清單中，選取「No managed dataset」。

   2. 選取「自訂訓練 (進階)」。

   按一下「繼續」。

4. 在「模型詳細資料」步驟中，選擇「訓練新模型」或「訓練新版本」。如果您選取「訓練新模型」，請為模型輸入所需名稱 MODEL_NAME。按一下「繼續」。

5. 在「Training container」步驟中，指定下列設定：

   1. 選取要使用預先建構的容器還是自訂容器進行訓練。

   2. 視您的選擇而定，請執行下列任一操作：

      • 如果您想使用預建容器進行訓練，請向 Vertex AI 提供所需資訊，讓系統使用您上傳至 Cloud Storage 的訓練套件：

        1. 使用「Model framework」和「Model framework version」下拉式清單，指定要使用的預先建構容器。

        2. 在「Package location」欄位中，指定您建立並上傳的 Python 訓練應用程式的 Cloud Storage URI。這個檔案通常結尾為 .tar.gz。

        3. 在「Python 模組」欄位中，輸入訓練應用程式進入點的模組名稱。

      • 如果您想使用自訂容器進行訓練，請在「Container image」欄位中指定容器映像檔的 Artifact Registry 或 Docker Hub URI。

   3. 在「模型輸出目錄」欄位中，您可以指定可存取的值區中目錄的 Cloud Storage URI。目錄尚不需要存在。

      這個值會在 baseOutputDirectory API 欄位中傳遞至 Vertex AI，該欄位會設定訓練應用程式在執行時可存取的多個環境變數。

   4. 選用：您可以在「引數」欄位中指定 Vertex AI 開始執行訓練程式碼時要使用的引數。所有引數的總長度上限為 100,000 個半形字元。這些引數的行為會因您使用的容器類型而有所不同：

      • 如果您使用的是預建容器，Vertex AI 會將引數做為指令列標記傳遞至 Python 模組。

      • 如果您使用的是自訂容器，Vertex AI 會使用引數覆寫容器的 CMD 指令。

   按一下「繼續」。

6. 在「超參數調整」步驟中，確認「啟用超參數調整」核取方塊未選取。按一下「繼續」。

7. 在「運算和定價」步驟中，指定下列設定：

   1. 在「區域」下拉式清單中，選取「支援自訂訓練的區域」。

   2. 在「Worker pool 0」部分，指定要用於訓練的運算資源。

      如果您指定加速器，請確認您選擇的加速器類型在所選區域可用。

      如要執行分散式訓練，請按一下「Add more worker pools」，然後為每個額外的工作站集區指定額外的運算資源組。

   按一下「繼續」。

8. 在「Prediction container」步驟中，選取「No prediction container」。

9. 按一下「開始訓練」，啟動自訂訓練管道。

REST

使用任何要求資料之前，請先替換以下項目：

• LOCATION：容器或 Python 套件執行的區域。
• PROJECT_ID：您的專案 ID。
• JOB_NAME：必填。CustomJob 的顯示名稱。
• 定義自訂訓練工作：
  • MACHINE_TYPE：機器類型。請參閱可用訓練機器類型。
  • ACCELERATOR_TYPE：(選填) 要附加至工作中的加速器類型。
  • ACCELERATOR_COUNT：(選填) 要附加至工作中的加速器數量。
  • DISK_TYPE：(選填) 用於工作的開機磁碟類型，可能是 pd-standard (預設) 或 pd-ssd。進一步瞭解磁碟類型。
  • DISK_SIZE：(選填) 要用於工作開機磁碟的大小 (以 GB 為單位)。預設值為 100。
  • REPLICA_COUNT：要使用的 worker 備用資源數量。在大多數情況下，請將此值設為第一個工作站集區的 1。
  • 如果訓練應用程式是在自訂容器中執行，請指定下列項目：
    • CUSTOM_CONTAINER_IMAGE_URI：Artifact Registry 或 Docker Hub 中容器映像檔的 URI，會在每個 worker 複本上執行。/li>
    • CUSTOM_CONTAINER_COMMAND：(選填) 啟動容器時要叫用的指令。這項指令會覆寫容器的預設進入點。
    • CUSTOM_CONTAINER_ARGS：(選填) 啟動容器時要傳遞的引數。
  • 如果訓練應用程式是預先建立容器中執行的 Python 套件，請指定下列項目：
    • EXECUTOR_IMAGE_URI：執行提供程式碼的容器映像檔 URI。請參閱可用訓練預先建構的容器。
    • PYTHON_PACKAGE_URIS：以半形逗號分隔的 Cloud Storage URI 清單，指定訓練程式及其依附套件的 Python 套件檔案。套件 URI 數量上限為 100。
    • PYTHON_MODULE：安裝套件後要執行的 Python 模組名稱。
    • PYTHON_PACKAGE_ARGS：(選填) 要傳遞至 Python 模組的指令列引數。
  • 瞭解工作排程選項。
  • TIMEOUT：(選填) 工作的最大執行時間。
• 為要套用至這項自訂工作的任何標籤指定 LABEL_NAME 和 LABEL_VALUE。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/customJobs

JSON 要求主體：

{
  "displayName": "JOB_NAME",
  "jobSpec": {
    "workerPoolSpecs": [
      {
        "machineSpec": {
          "machineType": MACHINE_TYPE,
          "acceleratorType": ACCELERATOR_TYPE,
          "acceleratorCount": ACCELERATOR_COUNT
        },
        "replicaCount": REPLICA_COUNT,
        "diskSpec": {
          "bootDiskType": DISK_TYPE,
          "bootDiskSizeGb": DISK_SIZE
        },

        // Union field task can be only one of the following:
        "containerSpec": {
          "imageUri": CUSTOM_CONTAINER_IMAGE_URI,
          "command": [
            CUSTOM_CONTAINER_COMMAND
          ],
          "args": [
            CUSTOM_CONTAINER_ARGS
          ]
        },
        "pythonPackageSpec": {
          "executorImageUri": EXECUTOR_IMAGE_URI,
          "packageUris": [
            PYTHON_PACKAGE_URIS
          ],
          "pythonModule": PYTHON_MODULE,
          "args": [
            PYTHON_PACKAGE_ARGS
          ]
        }
        // End of list of possible types for union field task.
      }
      // Specify one workerPoolSpec for single replica training, or multiple workerPoolSpecs
      // for distributed training.
    ],
    "scheduling": {
      "timeout": TIMEOUT
    }
  },
  "labels": {
    LABEL_NAME_1": LABEL_VALUE_1,
    LABEL_NAME_2": LABEL_VALUE_2
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/customJobs"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/customJobs" | Select-Object -Expand Content

回應內容包含規格和 JOB_ID 相關資訊。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/customJobs/JOB_ID",
  "displayName": "JOB_NAME",
  "trainingTaskInputs": {
    "workerPoolSpecs": [
      {
        "machineSpec": {
          "machineType": "n1-standard-4"
        },
        "replicaCount": "1",
        "pythonPackageSpec": {
          "executorImageUri": "us-docker.pkg.dev/vertex-ai/training/training-tf-cpu.2-1:latest",
          "packageUris": [
            "gs://BUCKET_NAME/training/hello-custom-training-1.0.tar.gz"
          ],
          "pythonModule": "trainer.task",
          "args": [
            "--model-dir=gs://BUCKET_NAME/output/"
          ]
        }
      }
    ]
  },
  "state": "JOB_STATE_PENDING",
  "createTime": "2020-09-15T19:09:54.342080Z",
  "startTime": "2020-09-15T19:13:42.991045Z",
}

Java

在試用這個範例之前，請先按照 Vertex AI 快速入門：使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Vertex AI Java API 參考說明文件。

如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import com.google.cloud.aiplatform.v1.AcceleratorType;
import com.google.cloud.aiplatform.v1.ContainerSpec;
import com.google.cloud.aiplatform.v1.CustomJob;
import com.google.cloud.aiplatform.v1.CustomJobSpec;
import com.google.cloud.aiplatform.v1.JobServiceClient;
import com.google.cloud.aiplatform.v1.JobServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.cloud.aiplatform.v1.MachineSpec;
import com.google.cloud.aiplatform.v1.WorkerPoolSpec;
import java.io.IOException;

// Create a custom job to run machine learning training code in Vertex AI
public class CreateCustomJobSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String displayName = "DISPLAY_NAME";

    // Vertex AI runs your training application in a Docker container image. A Docker container
    // image is a self-contained software package that includes code and all dependencies. Learn
    // more about preparing your training application at
    // https://cloud.google.com/vertex-ai/docs/training/overview#prepare_your_training_application
    String containerImageUri = "CONTAINER_IMAGE_URI";
    createCustomJobSample(project, displayName, containerImageUri);
  }

  static void createCustomJobSample(String project, String displayName, String containerImageUri)
      throws IOException {
    JobServiceSettings settings =
        JobServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (JobServiceClient client = JobServiceClient.create(settings)) {
      MachineSpec machineSpec =
          MachineSpec.newBuilder()
              .setMachineType("n1-standard-4")
              .setAcceleratorType(AcceleratorType.NVIDIA_TESLA_T4)
              .setAcceleratorCount(1)
              .build();

      ContainerSpec containerSpec =
          ContainerSpec.newBuilder().setImageUri(containerImageUri).build();

      WorkerPoolSpec workerPoolSpec =
          WorkerPoolSpec.newBuilder()
              .setMachineSpec(machineSpec)
              .setReplicaCount(1)
              .setContainerSpec(containerSpec)
              .build();

      CustomJobSpec customJobSpecJobSpec =
          CustomJobSpec.newBuilder().addWorkerPoolSpecs(workerPoolSpec).build();

      CustomJob customJob =
          CustomJob.newBuilder()
              .setDisplayName(displayName)
              .setJobSpec(customJobSpecJobSpec)
              .build();
      LocationName parent = LocationName.of(project, location);
      CustomJob response = client.createCustomJob(parent, customJob);
      System.out.format("response: %s\n", response);
      System.out.format("Name: %s\n", response.getName());
    }
  }
}

Node.js

在試用這個範例之前，請先按照 Vertex AI 快速入門：使用用戶端程式庫中的操作說明設定 Node.js。詳情請參閱 Vertex AI Node.js API 參考說明文件。

如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const customJobDisplayName = 'YOUR_CUSTOM_JOB_DISPLAY_NAME';
// const containerImageUri = 'YOUR_CONTAINER_IMAGE_URI';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

// Imports the Google Cloud Job Service Client library
const {JobServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const jobServiceClient = new JobServiceClient(clientOptions);

async function createCustomJob() {
  // Configure the parent resource
  const parent = `projects/${project}/locations/${location}`;
  const customJob = {
    displayName: customJobDisplayName,
    jobSpec: {
      workerPoolSpecs: [
        {
          machineSpec: {
            machineType: 'n1-standard-4',
            acceleratorType: 'NVIDIA_TESLA_T4',
            acceleratorCount: 1,
          },
          replicaCount: 1,
          containerSpec: {
            imageUri: containerImageUri,
            command: [],
            args: [],
          },
        },
      ],
    },
  };
  const request = {parent, customJob};

  // Create custom job request
  const [response] = await jobServiceClient.createCustomJob(request);

  console.log('Create custom job response:\n', JSON.stringify(response));
}
createCustomJob();

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件。

def create_custom_job_with_experiment_autologging_sample(
    project: str,
    location: str,
    staging_bucket: str,
    display_name: str,
    script_path: str,
    container_uri: str,
    service_account: str,
    experiment: str,
    experiment_run: Optional[str] = None,
) -> None:
    aiplatform.init(project=project, location=location, staging_bucket=staging_bucket, experiment=experiment)

    job = aiplatform.CustomJob.from_local_script(
        display_name=display_name,
        script_path=script_path,
        container_uri=container_uri,
        enable_autolog=True,
    )

    job.run(
        service_account=service_account,
        experiment=experiment,
        experiment_run=experiment_run,
    )