环境和 API 访问权限设置

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

1. 前提条件

   • Google Cloud 项目和许可

   • 用户个人资料和 IAM 要求

   • 管理主机环境

2. 设置 AlphaEvolve

   • 环境初始化（云管理员）

   • 设置 Discovery Engine 层次结构

   • 测试 API 访问权限和验证

前提条件

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

Google Cloud 项目和许可

• Google Cloud 项目： 创建一个专用 Google Cloud 云项目，并具有有效的结算链接。如需咨询项目预配或许可名单事宜， 请与您指定的 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 Administrator	管理一次性初始环境配置， IAM 分配，以及在 Vertex AI 中启用 Discovery Engine API 和 Gemini API。	roles/resourcemanager.projectCreator（组织/ 文件夹级） roles/billing.user（结算账号级） roles/serviceusage.admin Workspace 或 Cloud Identity 管理员权限
系统用户 （研究员 / 科学家）	配置和执行优化实验。严格通过服务帐号模拟与 API 交互。	roles/iam.serviceAccountTokenCreator 在服务账号资源上授予的。 可选： roles/iam.serviceAccountUser 如果将服务帐号附加到计算资源（例如 Vertex AI Workbench），则需要。
服务账号	自动身份，可直接与 Cloud 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 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..

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

注意： 如需让用户身份或调用服务模拟服务账号，必须向主账号授予目标服务帐号资源本身的 Service Account Token Creator 角色 (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）。

启用所需的 API

云管理员必须在项目中启用两个 API：

• Discovery Engine API (discoveryengine.googleapis.com)，用于提供 Cloud API 端点上的 AlphaEvolve。

• Vertex AI API (aiplatform.googleapis.com)，用于提供 Vertex AI 中的 Gemini API。AlphaEvolve 使用 Gemini 模型集合生成每个候选程序，因此系统用户必须先启用此 API，然后才能运行实验。

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已通过所有者角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

启用 API

或者，您也可以在 Linux 主机上使用 Google Cloud SDK 同时启用这两个 API：

gcloud services enable discoveryengine.googleapis.com \
  aiplatform.googleapis.com --project="${PROJECT_ID}"

确认这两个 API 均已启用：

gcloud services list --enabled --project="${PROJECT_ID}" \
  --filter="config.name:(discoveryengine.googleapis.com OR aiplatform.googleapis.com)"

创建 Discovery Engine 资源和会话

配置过程从管理身份设置过渡到预配核心应用数据层。在此阶段，您需要构建底层 API 所需的嵌套逻辑组件，以管理、路由和跟踪代码突变实验。

Discovery Engine 资源层次结构

Discovery Engine 资源的层次结构以 Google Cloud 项目开头，其资源托管在特定位置 （区域）内。在此基础结构中，集合充当相关资源的顶级组织容器。引擎在集合内预配，以托管核心 AI 应用，同时也是配置助理资源以管理应用的生成式 AI 属性和工具的位置。引擎管理以 会话 对象形式捕获的 各个用户互动。

AlphaEvolveExperiment 嵌套在会话下，表示在特定用户互动的上下文中用于算法发现和优化的进化编码代理的单次运行。

预配资源

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 Service 仅接受“default_assistant”作为 唯一标识符。

   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 访问权限

云管理员完成预配身份、设置服务帐号模拟和验证引擎布局后，请运行这些最终检查。此快速冒烟测试会在您运行活跃的优化工作负载之前验证您的授权和端到端连接。

查看和删除引擎

使用当前访问令牌或模拟的服务帐号来验证、列出或删除引擎：

  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！