环境和 API 访问权限设置

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

  1. 前提条件

  2. 设置 AlphaEvolve

前提条件

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

Google Cloud 项目和许可

  • Google Cloud 项目：创建具有有效结算关联的专用 Google Cloud 项目。如需咨询项目配置或许可名单事宜，请与您的指定 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 生命周期利用了这三种不同的身份。

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

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

管理主机环境

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

  • Google Cloud SDK：用于执行项目管理命令。如果主机上没有 gcloud CLI，请安装该 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. 选择服务账号名称：

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

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

  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，才能与 AlphaEvolve on Cloud API 端点进行交互。云管理员可以通过 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. 设置 Google Cloud 项目 ID：

    此步骤会为目标 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 项目中注册一个新的 Engine，并定义其唯一名称、显示名称和 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 访问权限

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

查看和删除引擎

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

  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 了！