Agent Platform Vizier スタディを作成する

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

始める前に

  1. Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分も差し上げます。

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. ローカルシェルを使用している場合は、ユーザー アカウントのローカル認証情報を作成します。 

    gcloud auth application-default login

    Cloud Shell を使用している場合は、この操作を行う必要はありません。

    認証エラーが返され、外部 ID プロバイダ（IdP）を使用している場合は、 フェデレーション ID を使用して gcloud CLI にログインしていることを確認します。

  7. Agent Platform 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 を最大化することが目標です。この例では、パラメータが 1 つのみで、計算関数を使用した Agent Platform Vizier の使用方法が示されています。

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 コンソールの Gemini Enterprise Agent Platform セクションの [テスト] ページでスタディを確認できます。

[テスト] ページに移動

スタディを取得する

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

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

スタディを一覧表示する

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

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

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

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

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

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

suggest_trials は、トライアルを生成する長時間実行オペレーションを開始します。このレスポンスは、Agent Platform 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 }]
        }
    })

トライアルを完了する

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

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

最終的な測定値なし

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

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 リファレンスを確認する。