建立超參數調整工作

超參數是控管模型訓練程序的變數，例如深層類神經網路中的批次大小或隱藏層數量。超參數調整工作會在一系列實驗中盡可能取得成效最高的指標值，找出最佳超參數值組合。指標是您在訓練程式中新增的純量摘要，例如模型準確率。

進一步瞭解如何在 Vertex AI 上調整超參數。如需逐步範例，請參閱 Vertex AI：超參數調整程式碼研究室。

本文說明如何：

準備訓練應用程式

在超參數調整工作中，Vertex AI 會使用不同的超參數組合建立訓練工作試驗，並使用您指定的指標評估試驗的有效性。Vertex AI 會將超參數值以指令列引數的形式傳遞至訓練應用程式。如要讓 Vertex AI 評估試驗的成效，訓練應用程式必須向 Vertex AI 回報指標。

以下各節說明：

  • Vertex AI 如何將超參數傳遞至訓練應用程式。
  • 可將指標從訓練應用程式傳遞至 Vertex AI 的選項。

如要進一步瞭解在 Vertex AI 上執行的自訂訓練應用程式需求，請參閱「訓練程式碼需求」。

處理您要調整的超參數的指令列引數

Vertex AI 會在呼叫訓練應用程式時設定指令列引數。請在程式碼中使用這些指令列引數：

  1. 定義每個超參數引數的名稱，然後使用您偏好的任一種引數剖析器 (例如 argparse) 來剖析引數。設定超參數訓練工作時，請使用相同的引數名稱。

    舉例來說，如果您的訓練應用程式是名為 my_trainer 的 Python 模組，且您要調整名為 learning_rate 的超參數，Vertex AI 會使用類似下列的指令啟動每次試驗：

    python3 -m my_trainer --learning_rate learning-rate-in-this-trial

    Vertex AI 會判斷 learning-rate-in-this-trial，並使用 learning_rate 引數傳遞該值。

  2. 將指令列引數中的值指派給訓練程式碼中的超參數。

進一步瞭解剖析命令列引數的規定。

向 Vertex AI 報告指標

如要將指標回報給 Vertex AI，請使用 cloudml-hypertunePython 套件。這個程式庫提供輔助函式，可將指標回報給 Vertex AI。

進一步瞭解如何回報超參數指標。

建立超參數調整工作

視要用來建立 HyperparameterTuningJob 的工具而定，選取下列任一分頁標籤：

控制台

在 Google Cloud 控制台中，您無法直接建立 HyperparameterTuningJob 資源。不過，您可以建立 TrainingPipeline 資源，藉此建立 HyperparameterTuningJob。

下列操作說明將說明如何建立 TrainingPipeline，以便建立 HyperparameterTuningJob，且不執行任何其他動作。如要使用其他 TrainingPipeline 功能，例如使用受管理資料集進行訓練，請參閱「建立訓練管道」。

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

    前往訓練管線

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

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

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

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

    按一下「繼續」。

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

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

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

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

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

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

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

    按一下「繼續」。

  6. 在「超參數調整」步驟中，選取「啟用超參數調整」核取方塊，並指定下列設定：

    1. 在「New Hyperparameter」(新增超參數) 區段中，指定要調整的超參數「Parameter name」(參數名稱) 和「Type」(類型)。視您指定的類型而定，設定顯示的其他超參數設定。

      進一步瞭解超參數類型及其設定。

    2. 如要調整多個超參數，請按一下「新增參數」，然後在新顯示的部分重複上一個步驟。

      針對要調整的每個超參數重複執行上述步驟。

    3. 在「要最佳化的指標」欄位和「目標」下拉式清單中，指定要最佳化的指標名稱和目標。

    4. 在「Maximum number of trials」(試驗次數上限) 欄位中，指定您希望 Vertex AI 為超參數調整工作執行的試驗次數上限。

    5. 在「同時執行的測試數量上限」欄位中，指定 Vertex AI 同時執行的測試數量上限。

    6. 在「搜尋演算法」下拉式清單中，指定 Vertex AI 要使用的搜尋演算法。

    7. 忽略「啟用提早中止訓練」切換鈕，因為這個切換鈕不會產生任何影響。

    按一下「繼續」。

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

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

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

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

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

    按一下「繼續」。

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

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

gcloud

下列步驟說明如何使用 Google Cloud CLI 建立 HyperparameterTuningJob，並採用相對簡單的設定。如要瞭解可用於這項工作的所有設定選項，請參閱 gcloud ai hp-tuning-jobs create 指令和 HyperparameterTuningJob API 資源的參考說明文件。

  1. 建立名為 config.yaml 的 YAML 檔案，其中包含要為新 HyerparameterTuningJob 指定的 API 欄位：

    config.yaml
    studySpec:
  metrics:
  - metricId: METRIC_ID
    goal: METRIC_GOAL
  parameters:
  - parameterId: HYPERPARAMETER_ID
    doubleValueSpec:
      minValue: DOUBLE_MIN_VALUE
      maxValue: DOUBLE_MAX_VALUE
trialJobSpec:
  workerPoolSpecs:
    - machineSpec:
        machineType: MACHINE_TYPE
      replicaCount: 1
      containerSpec:
        imageUri: CUSTOM_CONTAINER_IMAGE_URI

    更改下列內容：

  2. 在 config.yaml 檔案所在的目錄中，執行下列殼層指令：

    gcloud ai hp-tuning-jobs create \
    --region=LOCATION \
    --display-name=DISPLAY_NAME \
    --max-trial-count=MAX_TRIAL_COUNT \
    --parallel-trial-count=PARALLEL_TRIAL_COUNT \
    --config=config.yaml

    更改下列內容：

REST

請使用下列程式碼範例，透過 hyperparameterTuningJob 資源的 create 方法建立超參數調整工作。

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

  • LOCATION：要建立 HyperparameterTuningJob 的區域。使用支援自訂訓練的區域。
  • PROJECT：您的專案 ID。
  • DISPLAY_NAME：您為 HyperparameterTuningJob 選擇的易記顯示名稱。請參閱「REST 資源」。
  • 指定指標：
    • METRIC_ID：要最佳化的超參數指標名稱。訓練程式碼執行時，必須回報這項指標。
    • METRIC_GOAL：超參數指標的目標，可以是 MAXIMIZE 或 MINIMIZE。
  • 指定超參數：
    • HYPERPARAMETER_ID：要調整的超參數名稱。 訓練程式碼必須剖析具有這個名稱的指令列標記。
    • PARAMETER_SCALE：(選用)。參數的縮放方式。CATEGORICAL 參數請保留未設定狀態。可以是 UNIT_LINEAR_SCALE、UNIT_LOG_SCALE、UNIT_REVERSE_LOG_SCALE 或 SCALE_TYPE_UNSPECIFIED
    • 如果這個超參數的類型為 DOUBLE，請指定這個超參數的最小值 (DOUBLE_MIN_VALUE) 和最大值 (DOUBLE_MAX_VALUE)。
    • 如果這個超參數的類型為 INTEGER，請為這個超參數指定最小值 (INTEGER_MIN_VALUE) 和最大值 (INTEGER_MAX_VALUE)。
    • 如果這個超參數的類型為 CATEGORICAL，請將可接受的值 (CATEGORICAL_VALUES) 指定為字串陣列。
    • 如果這個超參數的類型為 DISCRETE，請將可接受的值 (DISCRETE_VALUES) 指定為數字陣列。
    • 指定條件超參數。當父項超參數的值符合您指定的條件時，系統會將條件超參數新增至試驗。進一步瞭解 條件式超參數。
      • CONDITIONAL_PARAMETER：條件式參數的 ParameterSpec。這項規格包括參數名稱、比例、值範圍，以及取決於這個超參數的任何條件參數。
      • 如果父項超參數的類型為 INTEGER，請將整數清單指定為 INTEGERS_TO_MATCH。如果父項超參數的值符合指定值之一，系統就會將這個條件式參數新增至試驗。
      • 如果父項超參數的類型為 CATEGORICAL，請將類別清單指定為 CATEGORIES_TO_MATCH。如果父項超參數的值符合指定值之一，系統就會將這個條件式參數新增至試驗。
      • 如果父項超參數的類型為 DISCRETE，請將整數清單指定為 DISCRETE_VALUES_TO_MATCH。如果父項超參數的值符合指定值之一，系統就會將這個條件式參數新增至試驗。
  • ALGORITHM：(選用)。要在這項超參數調整工作中使用的搜尋演算法。可以是 ALGORITHM_UNSPECIFIED、GRID_SEARCH 或 RANDOM_SEARCH。
  • MAX_TRIAL_COUNT：執行的試驗次數上限。
  • PARALLEL_TRIAL_COUNT：可同時執行的測試次數上限。
  • MAX_FAILED_TRIAL_COUNT：超參數調整工作失敗前可失敗的工作數量。
  • 定義試用自訂訓練工作：
    • MACHINE_TYPE：用於訓練的VM 類型。
    • ACCELERATOR_TYPE：(選用)。要附加至各項試驗的加速器類型。
    • ACCELERATOR_COUNT：(選用)。要附加至每個試驗的加速器數量。
    • REPLICA_COUNT：要用於每次試驗的工作站備用資源數量。
    • 如果訓練應用程式在自訂容器中執行，請指定下列項目：
      • CUSTOM_CONTAINER_IMAGE_URI：包含訓練程式碼的 Docker 容器映像檔 URI。瞭解如何建立自訂容器映像檔。
      • CUSTOM_CONTAINER_COMMAND：(選用)。容器啟動時要叫用的指令。這項指令會覆寫容器的預設進入點。
      • CUSTOM_CONTAINER_ARGS：(選用)。啟動容器時要傳遞的引數。
    • 如果訓練應用程式是可在預先建立的容器中執行的 Python 套件，請指定下列項目：
      • PYTHON_PACKAGE_EXECUTOR_IMAGE_URI：執行所提供 Python 套件的容器映像檔 URI。進一步瞭解用於訓練的預先建構容器。
      • PYTHON_PACKAGE_URIS：Python 套件檔案的 Cloud Storage 位置，這些檔案是訓練程式及其依附元件套件。套件 URI 數量上限為 100 個。
      • PYTHON_MODULE：安裝套件後要執行的 Python 模組名稱。
      • PYTHON_PACKAGE_ARGS：(選用)。要傳遞至 Python 模組的命令列引數。
    • SERVICE_ACCOUNT：(選用)。Vertex AI 用來執行程式碼的服務帳戶。進一步瞭解如何 附加自訂服務帳戶。
    • TIMEOUT：(選用)。每項試驗的最長執行時間。
  • 為要套用至這項超參數調整工作的任何標籤指定 LABEL_NAME 和 LABEL_VALUE。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/hyperparameterTuningJobs

JSON 要求主體：

{
  "displayName": DISPLAY_NAME,
  "studySpec": {
    "metrics": [
      {
        "metricId": METRIC_ID,
        "goal": METRIC_GOAL
      }
    ],
    "parameters": [
      {
        "parameterId": PARAMETER_ID,
        "scaleType": PARAMETER_SCALE,

        // Union field parameter_value_spec can be only one of the following:
        "doubleValueSpec": {
            "minValue": DOUBLE_MIN_VALUE,
            "maxValue": DOUBLE_MAX_VALUE
        },
        "integerValueSpec": {
            "minValue": INTEGER_MIN_VALUE,
            "maxValue": INTEGER_MAX_VALUE
        },
        "categoricalValueSpec": {
            "values": [
              CATEGORICAL_VALUES
            ]
        },
        "discreteValueSpec": {
            "values": [
              DISCRETE_VALUES
            ]
        }
        // End of list of possible types for union field parameter_value_spec.

        "conditionalParameterSpecs": [
            "parameterSpec": {
              CONDITIONAL_PARAMETER
            }

            // Union field parent_value_condition can be only one of the following:
            "parentIntValues": {
                "values": [INTEGERS_TO_MATCH]
            }
            "parentCategoricalValues": {
                "values": [CATEGORIES_TO_MATCH]
            }
            "parentDiscreteValues": {
                "values": [DISCRETE_VALUES_TO_MATCH]
            }
            // End of list of possible types for union field parent_value_condition.
        ]
      }
    ],
    "ALGORITHM": ALGORITHM
  },
  "maxTrialCount": MAX_TRIAL_COUNT,
  "parallelTrialCount": PARALLEL_TRIAL_COUNT,
  "maxFailedTrialCount": MAX_FAILED_TRIAL_COUNT,
  "trialJobSpec": {
      "workerPoolSpecs": [
        {
          "machineSpec": {
            "machineType": MACHINE_TYPE,
            "acceleratorType": ACCELERATOR_TYPE,
            "acceleratorCount": ACCELERATOR_COUNT
          },
          "replicaCount": REPLICA_COUNT,

          // 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": PYTHON_PACKAGE_EXECUTOR_IMAGE_URI,
            "packageUris": [
              PYTHON_PACKAGE_URIS
            ],
            "pythonModule": PYTHON_MODULE,
            "args": [
              PYTHON_PACKAGE_ARGS
            ]
          }
          // End of list of possible types for union field task.
        }
      ],
      "scheduling": {
        "TIMEOUT": TIMEOUT
      },
      "serviceAccount": SERVICE_ACCOUNT
  },
  "labels": {
    LABEL_NAME_1": LABEL_VALUE_1,
    LABEL_NAME_2": LABEL_VALUE_2
  }
}

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

您應該會收到如下的 JSON 回應：

{
  "name": "projects/12345/locations/us-central1/hyperparameterTuningJobs/6789",
  "displayName": "myHyperparameterTuningJob",
  "studySpec": {
    "metrics": [
      {
        "metricId": "myMetric",
        "goal": "MINIMIZE"
      }
    ],
    "parameters": [
      {
        "parameterId": "myParameter1",
        "integerValueSpec": {
          "minValue": "1",
          "maxValue": "128"
        },
        "scaleType": "UNIT_LINEAR_SCALE"
      },
      {
        "parameterId": "myParameter2",
        "doubleValueSpec": {
          "minValue": 1e-07,
          "maxValue": 1
        },
        "scaleType": "UNIT_LINEAR_SCALE"
      }
    ],
    "ALGORITHM": "RANDOM_SEARCH"
  },
  "maxTrialCount": 20,
  "parallelTrialCount": 1,
  "trialJobSpec": {
    "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://my-bucket/my-training-application/trainer.tar.bz2"
          ],
          "pythonModule": "my-trainer.trainer"
        }
      }
    ]
  }
}

Java

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

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

import com.google.cloud.aiplatform.v1.AcceleratorType;
import com.google.cloud.aiplatform.v1.CustomJobSpec;
import com.google.cloud.aiplatform.v1.HyperparameterTuningJob;
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.PythonPackageSpec;
import com.google.cloud.aiplatform.v1.StudySpec;
import com.google.cloud.aiplatform.v1.StudySpec.MetricSpec;
import com.google.cloud.aiplatform.v1.StudySpec.MetricSpec.GoalType;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.ConditionalParameterSpec;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.ConditionalParameterSpec.DiscreteValueCondition;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.DiscreteValueSpec;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.DoubleValueSpec;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.ScaleType;
import com.google.cloud.aiplatform.v1.WorkerPoolSpec;
import java.io.IOException;
import java.util.Arrays;

public class CreateHyperparameterTuningJobPythonPackageSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String displayName = "DISPLAY_NAME";
    String executorImageUri = "EXECUTOR_IMAGE_URI";
    String packageUri = "PACKAGE_URI";
    String pythonModule = "PYTHON_MODULE";
    createHyperparameterTuningJobPythonPackageSample(
        project, displayName, executorImageUri, packageUri, pythonModule);
  }

  static void createHyperparameterTuningJobPythonPackageSample(
      String project,
      String displayName,
      String executorImageUri,
      String packageUri,
      String pythonModule)
      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. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (JobServiceClient client = JobServiceClient.create(settings)) {
      // study spec
      MetricSpec metric =
          MetricSpec.newBuilder().setMetricId("val_rmse").setGoal(GoalType.MINIMIZE).build();

      // decay
      DoubleValueSpec doubleValueSpec =
          DoubleValueSpec.newBuilder().setMinValue(1e-07).setMaxValue(1).build();
      ParameterSpec parameterDecaySpec =
          ParameterSpec.newBuilder()
              .setParameterId("decay")
              .setDoubleValueSpec(doubleValueSpec)
              .setScaleType(ScaleType.UNIT_LINEAR_SCALE)
              .build();
      Double[] decayValues = {32.0, 64.0};
      DiscreteValueCondition discreteValueDecay =
          DiscreteValueCondition.newBuilder().addAllValues(Arrays.asList(decayValues)).build();
      ConditionalParameterSpec conditionalParameterDecay =
          ConditionalParameterSpec.newBuilder()
              .setParameterSpec(parameterDecaySpec)
              .setParentDiscreteValues(discreteValueDecay)
              .build();

      // learning rate
      ParameterSpec parameterLearningSpec =
          ParameterSpec.newBuilder()
              .setParameterId("learning_rate")
              .setDoubleValueSpec(doubleValueSpec) // Use the same min/max as for decay
              .setScaleType(ScaleType.UNIT_LINEAR_SCALE)
              .build();

      Double[] learningRateValues = {4.0, 8.0, 16.0};
      DiscreteValueCondition discreteValueLearning =
          DiscreteValueCondition.newBuilder()
              .addAllValues(Arrays.asList(learningRateValues))
              .build();
      ConditionalParameterSpec conditionalParameterLearning =
          ConditionalParameterSpec.newBuilder()
              .setParameterSpec(parameterLearningSpec)
              .setParentDiscreteValues(discreteValueLearning)
              .build();

      // batch size
      Double[] batchSizeValues = {4.0, 8.0, 16.0, 32.0, 64.0, 128.0};

      DiscreteValueSpec discreteValueSpec =
          DiscreteValueSpec.newBuilder().addAllValues(Arrays.asList(batchSizeValues)).build();
      ParameterSpec parameter =
          ParameterSpec.newBuilder()
              .setParameterId("batch_size")
              .setDiscreteValueSpec(discreteValueSpec)
              .setScaleType(ScaleType.UNIT_LINEAR_SCALE)
              .addConditionalParameterSpecs(conditionalParameterDecay)
              .addConditionalParameterSpecs(conditionalParameterLearning)
              .build();

      // trial_job_spec
      MachineSpec machineSpec =
          MachineSpec.newBuilder()
              .setMachineType("n1-standard-4")
              .setAcceleratorType(AcceleratorType.NVIDIA_TESLA_T4)
              .setAcceleratorCount(1)
              .build();

      PythonPackageSpec pythonPackageSpec =
          PythonPackageSpec.newBuilder()
              .setExecutorImageUri(executorImageUri)
              .addPackageUris(packageUri)
              .setPythonModule(pythonModule)
              .build();

      WorkerPoolSpec workerPoolSpec =
          WorkerPoolSpec.newBuilder()
              .setMachineSpec(machineSpec)
              .setReplicaCount(1)
              .setPythonPackageSpec(pythonPackageSpec)
              .build();

      StudySpec studySpec =
          StudySpec.newBuilder()
              .addMetrics(metric)
              .addParameters(parameter)
              .setAlgorithm(StudySpec.Algorithm.RANDOM_SEARCH)
              .build();
      CustomJobSpec trialJobSpec =
          CustomJobSpec.newBuilder().addWorkerPoolSpecs(workerPoolSpec).build();
      // hyperparameter_tuning_job
      HyperparameterTuningJob hyperparameterTuningJob =
          HyperparameterTuningJob.newBuilder()
              .setDisplayName(displayName)
              .setMaxTrialCount(4)
              .setParallelTrialCount(2)
              .setStudySpec(studySpec)
              .setTrialJobSpec(trialJobSpec)
              .build();
      LocationName parent = LocationName.of(project, location);
      HyperparameterTuningJob response =
          client.createHyperparameterTuningJob(parent, hyperparameterTuningJob);
      System.out.format("response: %s\n", response);
      System.out.format("Name: %s\n", response.getName());
    }
  }
}

Python

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

from google.cloud import aiplatform

from google.cloud.aiplatform import hyperparameter_tuning as hpt


def create_hyperparameter_tuning_job_sample(
    project: str,
    location: str,
    staging_bucket: str,
    display_name: str,
    container_uri: str,
):
    aiplatform.init(project=project, location=location, staging_bucket=staging_bucket)

    worker_pool_specs = [
        {
            "machine_spec": {
                "machine_type": "n1-standard-4",
                "accelerator_type": "NVIDIA_TESLA_K80",
                "accelerator_count": 1,
            },
            "replica_count": 1,
            "container_spec": {
                "image_uri": container_uri,
                "command": [],
                "args": [],
            },
        }
    ]

    custom_job = aiplatform.CustomJob(
        display_name='custom_job',
        worker_pool_specs=worker_pool_specs,
    )

    hpt_job = aiplatform.HyperparameterTuningJob(
        display_name=display_name,
        custom_job=custom_job,
        metric_spec={
            'loss': 'minimize',
        },
        parameter_spec={
            'lr': hpt.DoubleParameterSpec(min=0.001, max=0.1, scale='log'),
            'units': hpt.IntegerParameterSpec(min=4, max=128, scale='linear'),
            'activation': hpt.CategoricalParameterSpec(values=['relu', 'selu']),
            'batch_size': hpt.DiscreteParameterSpec(values=[128, 256], scale='linear')
        },
        max_trial_count=128,
        parallel_trial_count=8,
        labels={'my_key': 'my_value'},
    )

    hpt_job.run()

    print(hpt_job.resource_name)
    return hpt_job

超參數訓練工作設定

超參數調整工作會搜尋最佳超參數組合，盡可能提高指標值。超參數調整工作會使用不同的超參數組合，對訓練應用程式執行多項試驗，藉此找出最佳超參數組合。

設定超參數調整工作時，您必須指定下列詳細資料：

限制試驗次數

決定要讓服務執行的試驗數量，並在 HyperparameterTuningJob 物件中設定 maxTrialCount 值。

決定允許的試驗次數時，必須考慮兩項利益衝突：

  • 時間 (因此也包括費用)
  • 準確率

增加測試次數通常可以建立更優質的模型，但並非一概如此。通常在達到某個程度後，再增加測試次數對準確度幾乎沒有影響。開始執行大量試驗的工作前，建議先進行少量試驗，評估所選超參數對模型準確度的影響。

如要充分利用超參數調整，設定的上限值不得低於您使用的超參數數量的十倍。

平行試驗

您可以設定 HyperparameterTuningJob 中的 parallelTrialCount，指定可平行執行的試驗數量。

執行平行試驗的好處是可以縮減訓練工作所需的時間 (實際時間，因為所需的總處理時間通常不會改變)。但平行執行會降低調整工作整體效率。這是因為超參數調整使用之前試驗的結果來告知要指派給後續試驗中超參數的值。平行執行時，因為還在執行中的試驗未產生結果，所以部分試驗開始時無法知道之前的試驗結果，也就無法因此獲益。

如果使用平行試驗，超參數調整服務會佈建多個訓練處理叢集 (或在單一處理訓練程式的情況下佈建多台獨立機器)。您為工作設定的工作集區規格，會用於每個訓練叢集。

處理失敗的試用期

如果超參數調整試驗在結束時發生錯誤，您可能會希望提早結束訓練工作。在 HyperparameterTuningJob 中將 maxFailedTrialCount 欄位設為您允許的試驗失敗次數。一旦超過這個試驗失敗的次數，Vertex AI 就會結束訓練工作。maxFailedTrialCount 值必須小於或等於 maxTrialCount。

如未設定 maxFailedTrialCount 或將其設為 0，Vertex AI 會依照下列規則來處理失敗試驗：

  • 如果工作的第一個試驗失敗了，Vertex AI 就會立即結束工作。第一次試驗就失敗意味著您的訓練程式碼可能有問題，所以進一步的試驗也可能會失敗。您可以透過結束工作來診斷問題，而不用等到所有試驗都完成後再進行診斷，以免產生多餘的費用。
  • 如果第一個試驗成功了，但只要符合以下其中一個條件，Vertex AI 也可能會在後續試驗失敗後結束工作：
    • 失敗試驗的次數太多了。
    • 失敗試驗相對於成功試驗的比例太高了。

這些規則可能會隨時變動。為確保行為的一致性，請設定 maxFailedTrialCount 欄位。

管理超參數調整工作

以下各節說明如何管理超參數調整工作。

擷取超參數調整工作的相關資訊

下列程式碼範例示範如何擷取超參數調整工作。

gcloud

使用 gcloud ai hp-tuning-jobs describe 指令：

gcloud ai hp-tuning-jobs describe ID_OR_NAME \
    --region=LOCATION

更改下列內容：

  • ID_OR_NAME：HyperparameterTuningJob 的名稱或數字 ID。(ID 是名稱的最後一部分)。

    您在建立 HyperparameterTuningJob 時可能已看過 ID 或名稱。如果您不知道 ID 或名稱，可以執行 gcloud ai hp-tuning-jobs list 指令，然後尋找適當的資源。

  • LOCATION：建立 HyperparameterTuningJob 的區域。

REST

使用下列程式碼範例，透過 hyperparameterTuningJob 資源的 get 方法，擷取超參數調整工作。

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

  • LOCATION：建立 HyperparameterTuningJob 的區域。
  • NAME：超參數調整工作的名稱。工作名稱的格式如下： projects/{project}/LOCATIONS/{LOCATION}/hyperparameterTuningJobs/{hyperparameterTuningJob}。

HTTP 方法和網址：

GET https://LOCATION-aiplatform.googleapis.com/v1/NAME

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

您應該會收到如下的 JSON 回應：

{
  "name": "projects/12345/LOCATIONs/us-central1/hyperparameterTuningJobs/6789",
  "displayName": "my-hyperparameter-tuning-job",
  "studySpec": {
    "metrics": [
      {
        "metricId": "my_metric",
        "goal": "MINIMIZE"
      }
    ],
    "parameters": [
      {
        "parameterId": "my_parameter",
        "doubleValueSpec": {
          "minValue": 1e-05,
          "maxValue": 1
        }
      }
    ]
  },
  "maxTrialCount": 3,
  "parallelTrialCount": 1,
  "trialJobSpec": {
    "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://my-bucket/my-training-application/trainer.tar.bz2"
          ],
          "pythonModule": "my-trainer.trainer"
        }
      }
    ]
  },
  "trials": [
    {
      "id": "2",
      "state": "SUCCEEDED",
      "parameters": [
        {
          "parameterId": "my_parameter",
          "value": 0.71426874725564571
        }
      ],
      "finalMeasurement": {
        "stepCount": "2",
        "metrics": [
          {
            "metricId": "my_metric",
            "value": 0.30007445812225342
          }
        ]
      },
      "startTime": "2020-09-09T23:39:15.549112551Z",
      "endTime": "2020-09-09T23:47:08Z"
    },
    {
      "id": "3",
      "state": "SUCCEEDED",
      "parameters": [
        {
          "parameterId": "my_parameter",
          "value": 0.3078893356622992
        }
      ],
      "finalMeasurement": {
        "stepCount": "2",
        "metrics": [
          {
            "metricId": "my_metric",
            "value": 0.30000102519989014
          }
        ]
      },
      "startTime": "2020-09-09T23:49:22.451699360Z",
      "endTime": "2020-09-09T23:57:15Z"
    },
    {
      "id": "1",
      "state": "SUCCEEDED",
      "parameters": [
        {
          "parameterId": "my_parameter",
          "value": 0.500005
        }
      ],
      "finalMeasurement": {
        "stepCount": "2",
        "metrics": [
          {
            "metricId": "my_metric",
            "value": 0.30005377531051636
          }
        ]
      },
      "startTime": "2020-09-09T23:23:12.283374629Z",
      "endTime": "2020-09-09T23:36:56Z"
    }
  ],
  "state": "JOB_STATE_SUCCEEDED",
  "createTime": "2020-09-09T23:22:31.777386Z",
  "startTime": "2020-09-09T23:22:34Z",
  "endTime": "2020-09-10T01:31:24.271307Z",
  "updateTime": "2020-09-10T01:31:24.271307Z"
}

Java

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

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

import com.google.cloud.aiplatform.v1.HyperparameterTuningJob;
import com.google.cloud.aiplatform.v1.HyperparameterTuningJobName;
import com.google.cloud.aiplatform.v1.JobServiceClient;
import com.google.cloud.aiplatform.v1.JobServiceSettings;
import java.io.IOException;

public class GetHyperparameterTuningJobSample {

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

  static void getHyperparameterTuningJobSample(String project, String hyperparameterTuningJobId)
      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. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (JobServiceClient client = JobServiceClient.create(settings)) {
      HyperparameterTuningJobName name =
          HyperparameterTuningJobName.of(project, location, hyperparameterTuningJobId);
      HyperparameterTuningJob response = client.getHyperparameterTuningJob(name);
      System.out.format("response: %s\n", response);
    }
  }
}

Python

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

# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

from google.cloud import aiplatform


def get_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
):

    aiplatform.init(project=project, location=location)

    hpt_job = aiplatform.HyperparameterTuningJob.get(
        resource_name=hyperparameter_tuning_job_id,
    )

    return hpt_job

取消超參數調整工作

下列程式碼範例示範如何取消超參數調整作業。

gcloud

使用 gcloud ai hp-tuning-jobs cancel 指令：

gcloud ai hp-tuning-jobs cancel ID_OR_NAME \
    --region=LOCATION

更改下列內容：

  • ID_OR_NAME：HyperparameterTuningJob 的名稱或數字 ID。(ID 是名稱的最後一部分)。

    您在建立 HyperparameterTuningJob 時可能已看過 ID 或名稱。如果您不知道 ID 或名稱，可以執行 gcloud ai hp-tuning-jobs list 指令，然後尋找適當的資源。

  • LOCATION：建立 HyperparameterTuningJob 的區域。

REST

使用下列程式碼範例，透過 hyperparameterTuningJob 資源的 cancel 方法取消超參數調整工作。

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

  • LOCATION：建立 HyperparameterTuningJob 的區域。
  • NAME：超參數調整工作的名稱。工作名稱的格式如下： projects/{project}/locations/{location}/hyperparameterTuningJobs/{hyperparameterTuningJob}。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1/NAME:cancel

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

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

Python

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

from google.cloud import aiplatform


def cancel_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
):

    aiplatform.init(project=project, location=location)

    hpt_job = aiplatform.HyperparameterTuningJob.get(
        resource_name=hyperparameter_tuning_job_id,
    )

    hpt_job.cancel()

刪除超參數調整工作

下列程式碼範例示範如何使用 Vertex AI SDK for Python 和 REST API 刪除超參數調整作業。

REST

使用下列程式碼範例，透過 hyperparameterTuningJob 資源的 delete 方法刪除超參數調整工作。

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

  • LOCATION：您的區域。
  • NAME：超參數調整工作的名稱。工作名稱的格式如下： projects/{project}/LOCATIONs/{LOCATION}/hyperparameterTuningJobs/{hyperparameterTuningJob}。

HTTP 方法和網址：

DELETE https://LOCATION-aiplatform.googleapis.com/v1/NAME

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

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

Python

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

from google.cloud import aiplatform


def delete_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
):

    aiplatform.init(project=project, location=location)

    hpt_job = aiplatform.HyperparameterTuningJob.get(
        resource_name=hyperparameter_tuning_job_id,
    )

    hpt_job.delete()

後續步驟