安裝及設定 AlphaEvolve

本頁說明初始化環境、佈建 API，以及設定使用者設定的必要步驟，讓您開始使用 AlphaEvolve。

1. 必要條件

   • Google Cloud 專案和授權

   • 使用者設定檔和 IAM 需求

   • 管理主機環境

2. 設定 AlphaEvolve

   • 環境初始化 (雲端管理員)

   • 設定 Discovery Engine 階層

   • 測試 API 存取權和驗證

必要條件

設定環境前，請確認貴機構已完成基本採購和基礎架構步驟。 Google Cloud

Google Cloud 專案和授權

• Google Cloud 專案：建立專屬的 Google Cloud (GCP) 專案，並啟用帳單連結。如要瞭解專案佈建或許可清單，請洽詢指派的 Google Cloud 帳戶團隊。

• Gemini Enterprise 授權：透過 Google Cloud 業務代表或 Google Cloud Marketplace 購買 Gemini Enterprise 授權。您可以將授權新增至 Google Workspace，或以獨立方案的形式提供授權。任何 Gemini Enterprise 方案 (包括試用授權) 都能存取 AlphaEvolve。

• 授權分配注意事項：系統會為每個透過服務帳戶模擬與 API 互動的系統使用者，分配一個 Gemini Enterprise 授權。 Google Cloud 服務帳戶不會耗用 Workspace 或 Cloud Identity 授權。

使用者設定檔和 IAM 需求

AlphaEvolve 生命週期會使用這三種不同的身分。

請確認專案符合下列強制存取控制角色：

設定檔	說明	必要角色和權限
雲端管理員	管理一次性初始環境設定、API 啟用和 IAM 指派作業。	roles/resourcemanager.projectCreator (機構/資料夾層級) roles/billing.user (帳單帳戶層級) roles/serviceusage.admin Workspace 或 Cloud Identity 管理員權限
系統使用者 (研究人員 / 科學家)	設定及執行最佳化實驗。嚴格透過服務帳戶模擬功能與 API 互動。	roles/iam.serviceAccountTokenCreator 授予服務帳戶資源。 選用： roles/iam.serviceAccountUser 如果要將服務帳戶附加至運算資源 (例如 Vertex AI Workbench)。
服務帳戶	自動化身分，可直接與 AlphaEvolve on Cloud Private Preview API 服務介接。	roles/discoveryengine.admin (限定於特定專案)

管理主機環境

管理 Linux 主機 (例如 Shell 或安全堡壘主機) 會執行設定指令碼和測試酬載。 Google Cloud 確認主機包含下列基礎公用程式：

• Google Cloud SDK：執行專案管理指令時必須使用。如果主機上沒有 gcloud CLI，請安裝。

• curl：驗證後端 API 端點的 HTTP 傳輸存取權。如果是 Debian 或 Ubuntu 發行版本，請透過套件管理工具安裝公用程式：

  sudo apt update && sudo apt install -y curl
  

設定 AlphaEvolve

設定 AlphaEvolve 時，雲端管理員和系統使用者必須協調合作。您必須完成下列安裝工作：

建立服務帳戶

請按照下列步驟，為最佳化實驗佈建服務帳戶。雲端管理員必須從管理主機執行下列指令：

1. 設定 Google Cloud 專案 ID：

   這個步驟會為目標專案宣告環境變數，確保後續指令在正確的環境中運作。 Google Cloud

   PROJECT_ID="my-gcp-project-id"
   

   或者，您也可以動態擷取進行中的 CLI 專案 ID：

   PROJECT_ID=$(gcloud config get project)
   

2. 選擇服務帳戶名稱：

   這個步驟會為服務帳戶的人類可讀取 ID 宣告環境變數，以供建立指令使用。

   SA_NAME="alpha-evolve-client"
   

3. 建立服務帳戶：

   這項指令會在 Google Cloud 專案中註冊新的服務帳戶，並定義其專屬名稱、顯示名稱，以及預期用途的簡短說明。

   gcloud iam service-accounts create "${SA_NAME}" \
     --description="Service Account to call AlphaEvolve on Cloud Private \
   Preview API service" \
     --display-name="AlphaEvolve Client SA" \
     --project=$PROJECT_ID
   

4. 擷取服務帳戶電子郵件字串：

   這項指令會根據顯示名稱查詢服務帳戶清單，並將正式電子郵件地址擷取為環境變數 (SERVICE_ACCOUNT_EMAIL)，以利資源的專屬識別。

   SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts list \
     --filter="displayName:AlphaEvolve Client SA" \
     --format='value(email)' \
     --project=$PROJECT_ID)
   
   echo "Newly created Service Account Email: ${SERVICE_ACCOUNT_EMAIL}"
   

注意： 這封電子郵件符合標準版面配置：PROJECT_ID.iam.gserviceaccount.com。

1. 將 Discovery Engine 角色指派給服務帳戶：

   執行下列 gcloud 指令，在專案層級將 roles/discoveryengine.admin 角色授予服務帳戶：

   gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
     --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
     --role="roles/discoveryengine.admin" \
     --project="${PROJECT_ID}"
   

   這項設定會套用下列技術邏輯參數：

   • --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}"：指定要授予管理員角色功能的主體。

   • --role="roles/discoveryengine.admin"：授予必要權限，以建立基礎 Discovery Engine 執行個體、對話工作階段和 AlphaEvolveExperiments 子項資源。

   • ${SERVICE_ACCOUNT_EMAIL}：識別主體可模擬的資源 (新服務帳戶)。

模擬服務帳戶

完成建立步驟後，請使用 gcloud 指令列工具，明確授予研究人員 (SYSTEM_USER) 模擬新建立服務帳戶的能力。

注意： 如要讓使用者身分或呼叫服務模擬服務帳戶，主體必須在目標服務帳戶資源本身上，獲派服務帳戶權杖建立者角色 (roles/iam.serviceAccountTokenCreator)。如果研究人員需要將這個服務帳戶直接附加至代管型運算執行個體 (例如 Vertex AI Workbench 筆記本環境)，則也需要 Service Account User 角色 (roles/iam.serviceAccountUser)。

1. 定義模擬主體：宣告變數目標字串。 將 SYSTEM_USER_EMAIL 替換為執行最佳化作業的研究人員公司身分或電子郵件地址。

   SYSTEM_USER="user:SYSTEM_USER_EMAIL"
   

2. 將權杖建立角色授予主體：執行下列指令，將短期憑證權杖鑄造功能對應至指定的系統使用者：

   gcloud iam service-accounts add-iam-policy-binding \
     "${SERVICE_ACCOUNT_EMAIL}" \
     --member="${SYSTEM_USER}" \
     --role="roles/iam.serviceAccountTokenCreator" \
     --project="${PROJECT_ID}"
   

   這項授權繫結可確保：

   • --member="${SYSTEM_USER}"：指定接收憑證核發授權的人類使用者。

   • --role="roles/iam.serviceAccountTokenCreator"：授予權限，可產生短期有效的 OAuth 2.0 存取權杖，以安全地模擬服務帳戶。

   • "${SERVICE_ACCOUNT_EMAIL}"：識別要繫結至傳入政策的目標服務帳戶資源。

   注意： 如要將這個服務帳戶附加至運算執行個體 (例如 Vertex AI Workbench)，請重複執行後者指令，並將目標角色定義參數換成 Service Account User 角色 (roles/iam.serviceAccountUser)。

啟用 Discovery Engine API

雲端管理員必須啟用 discoveryengine.googleapis.com API，才能與雲端私人搶先體驗版 API 端點上的 AlphaEvolve 介面互動。雲端管理員可以透過 Google Cloud 控制台 或 Linux 主機上的 Google Cloud SDK 執行這項操作：gcloud services enable discoveryengine.googleapis.com

建立 Discovery Engine 資源和工作階段

設定程序會從管理員身分設定，轉換為佈建核心應用程式資料層。在這個階段，您會建構基礎 API 要求的巢狀邏輯元件，以便管理、路由及追蹤程式碼變異實驗。

Discovery Engine 資源階層

Discovery Engine 資源的階層從Google Cloud 專案開始，資源會託管在特定位置 (區域) 中。在這個基礎結構中，集合是相關資源的頂層組織容器。系統會在集合內佈建引擎，用於代管核心 AI 應用程式，並設定助理資源，管理應用程式的生成式 AI 屬性和工具。引擎會將擷取到的個別使用者互動管理為工作階段物件。

AlphaEvolveExperiment 巢狀結構位於工作階段下方，代表單一演化式程式碼編寫代理程式的執行作業，用於在特定使用者互動的情境中探索及最佳化演算法。

佈建資源

1. 設定 Google Cloud 專案 ID：

   這個步驟會為目標 Google Cloud專案宣告環境變數，確保後續指令在正確的環境中運作：

   PROJECT_ID="my-gcp-project-id"
   

   或

   PROJECT_ID=$(gcloud config get project)
   

2. 定義引擎 ID：

   這個步驟會宣告引擎 ID 的網址友善專屬 ID 環境變數。

   ENGINE_ID="alpha-evolve-experiment-engine"
   

3. 建立引擎：

   這個指令會在 Google Cloud 專案中註冊新的引擎，並定義引擎的專屬名稱、顯示名稱和 SolutionType (SOLUTION_TYPE_GENERATIVE_CHAT)。

   URL="https://discoveryengine.googleapis.com/v1alpha"
   URL="${URL}/projects/${PROJECT_ID}/locations/global"
   URL="${URL}/collections/default_collection/engines"
   URL="${URL}?engineId=${ENGINE_ID}"
   curl -X POST "${URL}" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -d '{
       "display_name": "'"${ENGINE_ID}"'",
       "data_store_ids": [],
       "solution_type": "SOLUTION_TYPE_GENERATIVE_CHAT"
     }'
   

   注意： 建立新引擎是非同步作業，需要幾分鐘才能完成。

4. 定義助理 ID：

   這個步驟會為助理 ID 的網址友善專屬 ID 宣告環境變數。

   注意： Assistant Service 僅接受「default_assistant」做為專屬 ID。

   ASSISTANT_ID="default_assistant"
   

5. 建立助理：

   這項指令會在 Google Cloud 專案中註冊新的助理，並定義其專屬名稱、顯示名稱和簡短說明，指出助理的預期用途。

   URL="https://discoveryengine.googleapis.com/v1alpha"
   URL="${URL}/projects/${PROJECT_ID}/locations/global"
   URL="${URL}/collections/default_collection/engines"
   URL="${URL}/${ENGINE_ID}/assistants?assistantId=${ASSISTANT_ID}"
   curl -X POST "${URL}" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -d '{
       "display_name": "'"${ASSISTANT_ID}"'",
       "description": null,
       "generation_config": null,
       "web_grounding_type": "WEB_GROUNDING_TYPE_UNSPECIFIED",
       "enabled_actions": null,
       "customer_policy": null
     }'
   

測試 API 存取權

雲端管理員佈建必要身分、設定服務帳戶模擬，並驗證引擎版面配置後，研究系統使用者必須執行下列驗證步驟。這項程序可做為飛行前煙霧測試，用來確認端對端傳輸和授權，再啟動主動最佳化工作負載。

使用模擬產生存取權杖

執行下列指令，驗證政策是否正確繫結服務帳戶模擬作業。這項檢查可確保當地研究人員的身分安全地承擔自動執行身分。

  gcloud auth print-access-token \
    --impersonate-service-account="${SERVICE_ACCOUNT_EMAIL}"

使用存取權杖

這項指令會輸出原始的暫時性 OAuth 2.0 憑證字串。如果是多步驟驗證工作流程，請將這個權杖快取到短期有效的殼層變數中，或直接在傳輸呼叫中內嵌權杖，以查詢基礎專案中繼資料：

  TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account="${SERVICE_ACCOUNT_EMAIL}")
  curl -X GET \
    -H "Authorization: Bearer ${TOKEN}" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/${PROJECT_ID}"

注意： 產生的權杖是短期憑證，可讓模擬主體使用服務帳戶權限執行動作。

查看及刪除引擎

使用目前的存取權杖或模擬的服務帳戶，驗證、列出或刪除引擎：

  URL="https://discoveryengine.googleapis.com/v1alpha"
  URL="${URL}/projects/${PROJECT_ID}/locations/global"
  URL="${URL}/collections/default_collection/engines"
  curl -X GET "${URL}" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

  URL="https://discoveryengine.googleapis.com/v1alpha"
  URL="${URL}/projects/${PROJECT_ID}/locations/global"
  URL="${URL}/collections/default_collection/engines/${ENGINE_ID}"
  curl -X DELETE "${URL}" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

恭喜，您已完成設定步驟！現在您可以執行 AlphaEvolve V1 API 了！