建立自訂訓練工作

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：要使用的工作站備用資源數量。在大多數情況下，請將此值設為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 模組，您可能想使用這個選項。

安裝依附元件

使用自動封裝時，您可以在容器中安裝 Python 依附元件，方法與使用 gcloud CLI 的 local-run 指令時相同。如要瞭解安裝 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-spec 旗標，每個工作站集區一次。

如果您使用自動封裝功能，則只能在第一個工作人員集區中指定 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 資源。 不過，您可以建立 TrainingPipeline 資源，藉此建立 CustomJob。

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

1. 在 Google Cloud 控制台的 Vertex AI 專區中，前往「訓練管道」頁面。

   前往訓練管線

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

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

   1. 在「Dataset」(資料集) 下拉式清單中，選取「No managed dataset」(沒有代管資料集)。

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

   按一下「繼續」。

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

5. 在「訓練容器」步驟中，指定下列設定：

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

   2. 根據您的選擇，執行下列其中一項操作：

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

        1. 使用「模型架構」和「模型架構版本」下拉式清單，指定要使用的預先建構容器。

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

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

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

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

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

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

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

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

   按一下「繼續」。

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

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

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

   2. 在「工作站集區 0」部分，指定用於訓練的運算資源。

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

      如要執行分散式訓練，請按一下「新增更多工作站集區」，然後為每個所需的工作站集區指定一組額外的運算資源。

   按一下「繼續」。

8. 在「預測容器」步驟中，選取「無預測容器」。

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：要使用的工作站備用資源數量。在大多數情況下，請將此值設為1第一個工作站集區。
  • 如果訓練應用程式在自訂容器中執行，請指定下列項目：
    • CUSTOM_CONTAINER_IMAGE_URI：要在每個工作站副本上執行的 Artifact Registry 或 Docker Hub 容器映像檔 URI。/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

在試用這個範例之前，請先按照Java使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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

在試用這個範例之前，請先按照Node.js使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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,
    )