安装和配置 AlphaEvolve

本页介绍了初始化环境、预配 API 以及配置用户设置以开始使用 AlphaEvolve 所需的步骤。

  1. 前提条件

  2. 设置 AlphaEvolve

前提条件

在配置环境之前，请验证您的 Google Cloud 组织是否已完成基础采购和基础架构步骤。

Google Cloud 项目和许可

  • Google Cloud 项目： 创建一个具有 有效结算链接的专用 Google Cloud (GCP) 项目。如需咨询项目预配或许可名单事宜， 请与您指定的 Google Cloud 客户团队协调。

  • Gemini Enterprise 许可： 通过您的销售代表或 Google Cloud Marketplace 购买 Gemini Enterprise 许可。 Google Cloud 您可以将许可添加到 Google Workspace，也可以将其作为独立产品预配。任何 Gemini Enterprise 层级（包括试用许可）都可授予对 AlphaEvolve 的访问权限。

  • 许可分配注意事项：系统要求每位通过服务帐号模拟与 API 交互的系统用户拥有一个 Gemini Enterprise 许可。 Google Cloud 服务账号不会 占用 Workspace 或 Cloud Identity 许可。

用户个人资料和 IAM 要求

AlphaEvolve 生命周期使用三个不同的身份。

确保您的项目符合以下强制性访问权限控制角色：

个人资料 说明 所需的角色和权限
Cloud 管理员 管理一次性初始环境配置、API 启用、 和 IAM 分配。
  • roles/resourcemanager.projectCreator（组织/ 文件夹级）
  • roles/billing.user（结算账号级）
  • roles/serviceusage.admin
  • Workspace 或 Cloud Identity 管理员权限
系统用户
（研究员 / 科学家）		 配置和执行优化实验。严格通过服务帐号模拟与 API 交互。
  • roles/iam.serviceAccountTokenCreator 在服务账号资源上授予的。
  • 可选： roles/iam.serviceAccountUser 如果将服务帐号附加到计算资源（例如 Vertex AI Workbench），则需要。
服务账号 自动身份，可直接与 Cloud Private Preview API 服务上的 AlphaEvolve 对接。
  • roles/discoveryengine.admin（项目级）

管理主机环境

管理 Linux 主机（例如 Google Cloud Shell 或安全堡垒 主机）运行配置脚本和测试载荷。验证您的主机是否包含以下基础实用程序：

  • Google Cloud SDK：执行项目管理命令所必需。如果主机上没有 gcloud CLI，请安装 它。

  • curl：验证对后端 API 端点的 HTTP 传输访问权限。对于 Debian 或 Ubuntu 发行版，请通过软件包管理器安装该实用程序：

    sudo apt update && sudo apt install -y curl

设置 AlphaEvolve

设置 AlphaEvolve 需要云管理员和系统用户之间的协调。您必须完成以下安装任务：

创建服务帐号

按照以下步骤为优化实验预配服务帐号。云管理员必须从管理主机执行以下命令：

  1. 设置项目 ID： Google Cloud

    此步骤会为目标 Google Cloud 项目声明一个环境变量，确保后续命令在正确的上下文中运行。

    PROJECT_ID="my-gcp-project-id"

    或者，您也可以动态检索活跃的 CLI 项目 ID：

    PROJECT_ID=$(gcloud config get project)

  2. 选择服务帐号名称：

    此步骤会为服务帐号的人类可读标识符声明一个环境变量，该变量将用于创建命令。

    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}"

  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) 授予明确模拟新创建的服务帐号的能力。

  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}"：标识要绑定到传入政策的目标服务帐号 资源。

启用 Discovery Engine API

云管理员必须启用 discoveryengine.googleapis.com API，才能与 Cloud Private Preview 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 嵌套在会话下，表示在特定用户互动的上下文中用于算法发现和优化的进化编码代理的单次运行。

Discovery Engine 层次结构

预配资源

  1. 设置项目 ID： Google Cloud

    此步骤会为目标 Google Cloud 项目声明一个环境变量，确保后续命令在正确的上下文中运行：

    PROJECT_ID="my-gcp-project-id"

    或

    PROJECT_ID=$(gcloud config get project)

  2. 定义引擎 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 的网址友好型唯一标识符声明一个环境变量。

    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 凭据字符串。对于多步验证工作流，请将此令牌缓存在短期有效的 Shell 变量中，或直接将其内嵌在传输调用中，以查询基础项目元数据：

  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！