本頁面的部分或所有資訊可能不適用於 S3NS 的 Cloud de Confiance。詳情請參閱「與 Google Cloud 的差異」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

建立 Agent Platform Vizier 研究

本頁面說明如何使用 Python 向 Agent Platform Vizier 發出 API 要求。如要瞭解 Agent Platform Vizier 的運作方式，請參閱「Agent Platform Vizier 總覽」。

事前準備

In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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.
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
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

為使用者帳戶建立本機驗證憑證：
```
gcloud auth application-default login
```
如果系統傳回驗證錯誤，請確認您已使用聯合身分登入 gcloud CLI。
安裝 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 編寫。

建立研究

研究是一系列實驗或試驗，可協助您最佳化超參數或參數。

在以下範例中，目標是盡可能提高 y = x^2，且 x 的範圍為 [-10. 10]。這個範例只有一個參數，並使用計算函式，協助示範如何使用 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

查看研究

建立研究後，您可以在Cloud de Confiance 控制台的 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
})

後續步驟

請參閱研究的 REST 參考資料。