Vertex AI Vizier スタディを作成する

このページでは、Python を使用して Vertex AI Vizier に API リクエストを行う方法について説明します。Vertex AI Vizier の仕組みについては、Vertex AI Vizier の概要をご覧ください。

より包括的なワークフローの一部として複数の目標を最適化する例を確認するには、次の環境のいずれかで「複数の目標の最適化」Jupyter ノートブックを実行します。

Colab で開く | Colab Enterprise で開く | Vertex AI Workbench ユーザー管理ノートブックで開く | GitHub で表示する

始める前に

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Enable the Vertex AI API.

   Enable the API

4. Create a service account:

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
   2. Select your project.

   3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

   4. Click Create and continue.

   5. Grant the Project > Owner role to the service account.

      To grant the role, find the Select a role list, then select Project > Owner.

      Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
   6. Click Continue.

   7. Click Done to finish creating the service account.

      Do not close your browser window. You will use it in the next step.

5. Create a service account key:

   1. In the Google Cloud console, click the email address for the service account that you created.
   2. Click Keys.
   3. Click Add key, and then click Create new key.
   4. Click Create. A JSON key file is downloaded to your computer.
   5. Click Close.

6. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Enable the Vertex AI API.

   Enable the API

9. Create a service account:

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
   2. Select your project.

   3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

   4. Click Create and continue.

   5. Grant the Project > Owner role to the service account.

      To grant the role, find the Select a role list, then select Project > Owner.

      Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
   6. Click Continue.

   7. Click Done to finish creating the service account.

      Do not close your browser window. You will use it in the next step.

10. Create a service account key:

    1. In the Google Cloud console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, and then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.
    5. Click Close.

11. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

    Example: Linux or macOS

    export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Replace KEY_PATH with the path of the JSON file that contains your credentials.

    For example:

    export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

    Example: Windows

    For PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Replace KEY_PATH with the path of the JSON file that contains your credentials.

    For example:

    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

    For command prompt:

    set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

    Replace KEY_PATH with the path of the JSON file that contains your credentials.

12. Vertex AI SDK for Python をインストールします。

定数を定義する

定数を定義するには、次のコマンドを実行します。REGION と PROJECT_ID は、リージョンとプロジェクト ID で置き換えます。独自のスタディ名を作成するか、提案された値を使用します。

import json
import datetime
from google.cloud import aiplatform

REGION = "REGION"
PROJECT_ID = "PROJECT_ID"

# The following placeholder variables are automatically filled in.
STUDY_DISPLAY_NAME = '{}_study_{}'.format(PROJECT_ID.replace('-', ''), datetime.datetime.now().strftime('%Y%m%d_%H%M%S')) #@param {type: 'string'}
ENDPOINT = REGION + '-aiplatform.googleapis.com'
PARENT = 'projects/{}/locations/{}'.format(PROJECT_ID, REGION)

API リクエストを作成する

以下のコマンドライン API リクエストは Python で記述されています。

スタディを作成する

スタディは、ハイパーパラメータまたはパラメータを最適化するための一連のテストまたはトライアルです。

次の例では、x が [-10. 10] の範囲内で y = x^2 を最大化することが目標です。Vertex AI Vizier の使用方法を説明するために、この例ではパラメータを 1 つのみ設定し、簡単に計算できる関数を使用しています。

param_x = {
    'parameter_id': 'x',
    'double_value_spec': {
        'min_value': -10.0,
        'max_value': 10.0
    }
}

metric_y = {
    'metric_id': 'y',
    'goal': 'MAXIMIZE'
}

study = {
    'display_name': STUDY_DISPLAY_NAME,
    'study_spec': {
      'algorithm': 'RANDOM_SEARCH',
      'parameters': [param_x],
      'metrics': [metric_y],
    }
}

スタディ構成を使用してスタディを作成するには、VizierServiceClient から次のリクエストを送信します。返された STUDY_NAME を使用して、スタディをクエリします。

vizier_client = aiplatform.gapic.VizierServiceClient(client_options=dict(api_endpoint=ENDPOINT))
study = vizier_client.create_study(parent=PARENT, study=study)
STUDY_NAME = study.name

スタディを表示する

スタディが作成されると、Google Cloud Console の [Vertex AI] セクションの [テスト] ページでスタディを確認できます。

[テスト] ページに移動

スタディを取得する

スタディを取得するには、次のリクエストを送信します。

vizier_client.get_study({'name': STUDY_NAME})

スタディを一覧表示する

特定のプロジェクトとリージョンのスタディを一覧表示するには、次のリクエストを送信します。

vizier_client.list_studies({'parent': PARENT})

提案されたトライアルを取得する

Vertex AI Vizier からトライアルの提案を取得するには、SUGGEST_COUNT と CLIENT_ID を含むリクエストを作成します。リクエストを送信して、この情報を Vertex AI Vizier に渡します。

次のコマンドを使用してリクエストを作成します。SUGGEST_COUNT は、各リクエストから取得する必要がある提案数に変更します。

suggest_response = vizier_client.suggest_trials({
    'parent': STUDY_NAME,
    'suggestion_count': SUGGEST_COUNT,
    'client_id': CLIENT_ID
    })

suggest_trials は、トライアルを生成する長時間実行オペレーションを開始します。レスポンスから、Vertex AI Vizier がトライアルの提案に取り掛かっていることがわかります。

結果が返されるのを待つには、result() 関数を使用します。

suggest_response.result().trials

次の形式は、トライアルの例です。このトライアルは、パラメータ x に値 0.1 を使用することを提案しています。

name: "TRIAL_ID"
state: ACTIVE
parameters {
  parameter_id: "x"
  value {
    number_value: 0.1
  }
}
start_time {
  seconds: 1618011215
}

前のレスポンスの TRIAL_ID を使用してトライアルを取得します。

vizier_client.get_trial({
        'name': TRIAL_ID
      })

結果を評価する

トライアルの提案を受け取ったら、各トライアルを評価し、各結果を測定値として記録します。

たとえば、最適化しようとしている関数が y = x^2 の場合は、トライアルの推奨値 x を使用して関数を評価します。推奨値の 0.1 が使用され、関数の評価は y = 0.1 * 0.1 となり、結果は 0.01 になります。

測定値を追加する

トライアルの提案を評価して測定値を取得したら、この測定値をトライアルに追加します。

次のコマンドを使用して、測定値を保存し、リクエストを送信します。この例では、RESULT を測定値に置き換えます。最適化する関数が y = x^2 で、x の推奨値が 0.1 の場合、結果は 0.01 になります。

vizier_client.add_trial_measurement({
        'trial_name': TRIAL_ID,
        'measurement': {
            'metrics': [{'metric_id': 'y', 'value':RESULT }]
        }
    })

注: 評価が複数のステップからなるプロセスで、複数の中間測定値を生成できる場合、異なる stepCount と metrics 値で、メソッドを複数回呼び出せます。たとえば、ML モデルをトレーニングしている場合、エポックごとに中間測定値をレポートできます。

トライアルを完了する

トライアルの測定値をすべて追加したら、コマンドを送信してトライアルを完了する必要があります。

トライアルが完了したら、トライアルのみを完了するコマンドを送信するコマンドか、最終的な測定値を追加してトライアルを完了するコマンドを送信できます。

最終的な測定値なし

最終的な測定値を追加せずにトライアルを完了するには、次のリクエストを送信します。

vizier_client.complete_trial({
      'name': TRIAL_ID
  })

最終的な測定値あり

トライアルを完了して最終的な測定値を含めるには、次のコマンドを使用します。RESULT は最終的な測定値に置き換えます。

vizier_client.complete_trial({
      'name': TRIAL_ID
      'final_measurement': {
        'metrics': [{'metric_id': 'y', 'value': RESULT}]
      }
  })

トライアルを一覧表示する

特定のスタディのトライアルを一覧表示するには、次のリクエストを送信します。

vizier_client.list_trials({
    'parent': STUDY_NAME
})

保留中のトライアルをすべて完了したら、suggestTrials を呼び出してトライアルの提案をさらに取得し、評価プロセスを繰り返すことができるようになります。

最適なトライアルを一覧表示する

次の例は list_optimal_trials を示しています。これは、複数目標スタディに対してパレート最適なトライアルを返すか、単一目標スタディに対して最適なトライアルを返します。

vizier_client.list_optimal_trials({
    'parent': STUDY_NAME
})

次のステップ

• studies の REST リファレンスを確認する。