环境和 API 访问权限设置

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

  1. 前提条件

  2. 设置 AlphaEvolve

前提条件

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

Google Cloud 项目和许可

  • Google Cloud 项目：创建一个专用 Google Cloud 项目。如需进行项目预配，请与您指定的 Google Cloud 客户支持团队协调。

  • Gemini Enterprise 许可：通过 Google Cloud 销售代表购买 Gemini Enterprise 许可。任何 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）。
服务账号 直接与 AlphaEvolve on Cloud API 服务对接的自动化身份。
  • roles/discoveryengine.editor 或 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. 设置 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}"

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

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

启用所需的 API

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

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

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

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (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 项目开始，其资源托管在特定位置（AlphaEvolve 支持的位置包括 global、us 和 eu）。在此基础结构中，集合充当相关资源的顶级组织容器。引擎在集合中预配，用于托管核心 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 项目中注册一个新引擎，并定义其唯一名称、显示名称和 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 了！