开始在 Google Cloud 上使用 AlphaEvolve

1. 简介

在此 Codelab 中，您将在 Google Cloud 上运行前两个 AlphaEvolve 实验。AlphaEvolve 是 Google DeepMind 的 AI 引导的进化式编码框架：它使用 Gemini 编写和改进代码，并根据您定义的指标进行评分。您从圆堆积开始，这是一个小型几何问题，您可以直观地看到结果越来越好；然后，您在更难的旅行推销员问题上重复此过程，以便记住这种模式。

这两个实验都使用本地评估，候选代码在您自己的机器上运行，因此无需使用 GPU，也无需管理集群。唯一的云使用情况是生成候选对象的 AlphaEvolve API。

AlphaEvolve 本地循环：AlphaEvolve 代理（在 Google Cloud 中的 Gemini Enterprise 上）生成候选程序；您机器的进化循环 (run_evolution.py) 通过 acquire_programs() 获取这些程序，通过 evaluate.py 在本地 exec() 沙盒中对每个程序进行评分，并通过 submit_program_evaluations() 返回得分。

您将执行的操作

  • 针对 Google Cloud 云项目配置 AlphaEvolve 实验
  • 运行可局部改进圆形填充算法的进化搜索
  • 阅读最佳演化计划的分数、排名和可视化图表
  • 重复推销员问题的循环以概括模式
  • 调整搜索预算（候选对象、并发性、模型）

所需条件

  • 网络浏览器，例如 Chrome
  • 启用了结算功能的 Google Cloud 项目
  • Python 3.9 或更高版本和 uv
  • 基本熟悉 Python 和命令行

本 Codelab 适用于各种水平的 AI/机器学习工程师和开发者。无需具备进化计算方面的背景知识。

预计完成时间：45-60 分钟。

费用：此 Codelab 使用本地评估（不使用 GPU，不使用 GKE）。唯一需要付费的是生成候选方案，即 AlphaEvolve API 的使用情况及其消耗的 Vertex AI Gemini token。

已在 circle_packing 和 tsp 示例中测试过：AlphaEvolve Cloud 客户端库 v0.1.0、Python 3.9 及更高版本。

2. 准备工作

选择项目并启用 API

  1. 在 Google Cloud 控制台 中，选择或创建一个已启用结算功能的项目，然后在终端中设置该项目：
gcloud config set project <YOUR_PROJECT_ID>
  1. 启用此 Codelab 使用的两个 API：Discovery Engine API（用于提供 AlphaEvolve）和 Vertex AI API（用于提供生成候选结果的 Gemini 模型）：
gcloud services enable \
  discoveryengine.googleapis.com \
  aiplatform.googleapis.com

查找 Gemini Enterprise 应用 ID

AlphaEvolve 通过 Gemini Enterprise 提供（底层 REST 界面为 Discovery Engine API）。您需要应用的 ID（而非显示名称）才能使用 GE_APP_ID 设置。

  1. 打开您项目的 Gemini Enterprise 应用页面。
  2. 点击您的应用，然后复制 ID 字段（例如 gemini-enterprise-1234567890_1234567890123）。

进行身份验证、克隆和安装

  1. 针对应用默认凭据进行身份验证：
gcloud auth application-default login
  1. 克隆示例代码库并打开它。您将从该代码库根目录运行所有命令：
git clone https://github.com/Google-Cloud-AI/alphaevolve-on-googlecloud.git
cd alphaevolve-on-googlecloud
  1. 创建虚拟环境并将 AlphaEvolve 客户端库安装到该环境中：
uv venv
uv pip install -e ".[dev]"

uv venv 在代码库中创建 .venv；uv pip install -e ".[dev]" 安装 alpha_evolve 软件包（可编辑）以及测试工具。您将使用 uv run 启动实验，该工具会自动使用此环境。

3. 了解 AlphaEvolve 循环

在运行任何内容之前，请先了解 AlphaEvolve 需要的三部分内容。这是您将在每个实验中重复使用的心理模型。

种子计划和 EVOLVE-BLOCK

AlphaEvolve 仅重写两个标记之间的代码。文件中的其他所有内容都是无法触及的固定支架。打开 examples/circle_packing/src/program.py - 种子是简单的同心圆环填充：

# EVOLVE-BLOCK-START
"""Constructor-based circle packing for n=26 circles"""
import numpy as np


def construct_packing(n, random_seed: int):
    """Construct an arrangement of 26 circles in a unit square.

    The goal is to maximize the sum of their radii.
    Returns (centers, radii, sum_of_radii).
    """
    rng = np.random.default_rng(random_seed)
    centers = np.zeros((n, 2))

    # A simple starting pattern — evolution will improve this.
    centers[0] = [0.5, 0.5]                      # one circle in the center
    for i in range(8):                           # 8 in an inner ring
        angle = 2 * np.pi * i / 8
        centers[i + 1] = [0.5 + 0.3 * np.cos(angle), 0.5 + 0.3 * np.sin(angle)]
    for i in range(16):                          # 16 in an outer ring
        angle = 2 * np.pi * i / 16 * rng.uniform(0.9, 1.1)
        centers[i + 9] = [0.5 + 0.7 * np.cos(angle), 0.5 + 0.7 * np.sin(angle)]

    centers = np.clip(centers, 0.01, 0.99)       # keep everything in the square
    radii = compute_max_radii(centers, random_seed)
    return centers, radii, np.sum(radii)


def compute_max_radii(centers, random_seed: int):
    """Grow each circle to touch its nearest border or neighbor (no overlaps)."""
    # ... see src/program.py for the full helper ...
# EVOLVE-BLOCK-END

EVOLVE-BLOCK-START / EVOLVE-BLOCK-END 之外 的所有内容（包括 evaluate() 函数和重叠检查）都保持冻结状态。这种分离是整个技巧的关键：Gemini 可以提出任何它喜欢的打包算法，但不能更改候选人的得分方式。

评估器和得分

examples/circle_packing/src/evaluate.py 在沙盒中运行每个候选网络，并返回一个得分。对于圆形打包，该指标为 sum_of_radii，值越高越好：

CIRCLE_PACKING_EVALUATION_METRIC = "sum_of_radii"
CIRCLE_PACKING_EVALUATION_INPUTS = {"n": 26}

如果候选人违反了规则（圆圈重叠或超出正方形），评估器会返回 -inf，并提供分析来解释出了什么问题。这些反馈会提供给 Gemini，以便下一代模型避免犯同样的错误。

4. 运行您的第一个实验

配置实验

从代码库根目录中，基于圆填充模板创建 .env：

cp examples/circle_packing/example.env .env

打开 .env 并仅设置项目和应用 ID - 其他所有内容都具有可正常运行的默认值，可供首次运行：

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

默认设置会使用 Gemini 模型混合（MODEL_1=gemini-3.5-flash 的权重为 0.7，MODEL_2=gemini-3.1-pro-preview 的权重为 0.3）生成候选结果，并将搜索上限设置为 MAX_PROGRAMS_EVALUATED=10，并使用 CONCURRENCY=4，足以快速查看循环的运行情况。

开始演进

从代码库根目录运行实验：

uv run python -m examples.circle_packing.src.run_evolution

此命令会上传初始程序、开始搜索并运行本地控制循环，直到评估了 10 个候选程序。由于您直接调用模块（没有封装容器），因此可以准确了解运行的内容，并可修改文件以进行实验。

您看到的输出结果应该类似于以下内容：

INFO:alpha_evolve.experiment:Creating a new AlphaEvolve experiment
INFO:alpha_evolve.controller:Evolution loop started: 4 sampler(s), 32 evaluator(s), target=10 programs
INFO:alpha_evolve.controller:Waiting for the backend to generate candidates... (generated=0, evaluated=0/10, idle=10s)
INFO:alpha_evolve.workers:Candidate 1060655338894100 evaluated → sum_of_radii=0.8114
INFO:alpha_evolve.controller:Progress: generated=2, evaluated=1/10, queued=0
...
INFO:alpha_evolve.controller:Stopping criteria met (10/10 programs evaluated).

早期候选者的得分通常在 0.8-1.0 范围内；搜索效果会在此基础上有所提升。循环结束后，它会输出排名靠前的节目，并使用 matplotlib 呈现排名靠前的打包方案。

注意：问题排查：如果运行立即结束并显示 FAILED_PRECONDITION 和“AlphaEvolve requires the Vertex AI API to be enabled in this project”，则表示缺少 aiplatform.googleapis.com，请按照“准备工作”中的说明启用它。PERMISSION_DENIED 或 403 通常表示 Discovery Engine API 未启用。如果显示“未能创建实验”，但既不是上述原因，则表示 .env 中的凭据或 GE_APP_ID 有误。

5. 解读结果

运行会输出按 sum_of_radii 排名（值越高越好）靠前的计划。需要注意两点：

  • 得分提高了。最佳进化后的 sum_of_radii 应优于初始的同心圆布局。Gemini 通常会发现，靠近边角和边缘的圆圈可以变大，并重新平衡内部。
  • 系统会跳过无效候选人。任何生成重叠或超出范围的圆圈的程序都会获得 -inf 分，并在排名中被跳过 - 这是约束反馈在起作用，而不是错误。

现在，您已完成整个循环：种子 -> 生成 -> 评估 -> 评分 -> 重复。AlphaEvolve 中的所有其他内容都是评估运行位置的变体。

6. 演化真实搜索：TSP

圆填充收敛速度快。为了感受搜索在更复杂的问题上的效果，我们来开发一个旅行推销员问题的启发法。模式是相同的 - 只有种子和指标发生了变化，并且 TSP 示例会重复使用您的 .env（项目、预算和并发）。

  1. 在 .env 中提高预算，以便更长的搜索时间有改进空间：
# in .env — raise the generation cap and the evaluation target together
MAX_PROGRAMS_GENERATED=20
MAX_PROGRAMS_EVALUATED=20
  1. 从代码库根目录运行：
uv run python -m examples.tsp.src.run_evolution

此处的种子是 50 个城市的最近邻旅游路线；指标是 neg_tour_length（5 个固定实例的平均旅游路线长度的负值，因此值越高越好）。打开 examples/tsp/src/program.py，并注意只有 construct_tour(distances, n) 位于 EVOLVE-BLOCK 内。

这两个问题是具有不同块的相同图案：

问题

语言

评估

指标（值越高越好）

哪些方面会不断发展

circle_packing

Python

本地 exec()

sum_of_radii

construct_packing()

tsp

Python

本地 exec()

neg_tour_length

construct_tour()

随着搜索的运行，请注意 neg_tour_length 的攀升（越来越接近于零），因为 Gemini 会从最近邻搜索转向 2-opt / or-opt 风格的改进，而这些策略并非您编写的。

7. 调整搜索

现在，两次运行都正常，请在 .env 中调整预算：

  • MAX_PROGRAMS_EVALUATED - 要评分的候选数量。候选对象越多 = 搜索越深入，费用/时间越高。
  • CONCURRENCY - 一次性生成多少个候选内容。
  • MODEL_1 / MODEL_2（使用 MODEL_1_WEIGHT / MODEL_2_WEIGHT）- 在圆形填充运行中生成候选对象的 Gemini 模型的加权混合（TSP 模块读取单个 MODEL）。允许的值包括 gemini-3.5-flash 和 gemini-3.1-pro-preview。将权重向更强大的模型倾斜，以便在更少的代数中找到更好的程序。

每次更改后，使用 uv run python -m examples.circle_packing.src.run_evolution（或 tsp 模块）重新运行。

注意：提高 MAX_PROGRAMS_EVALUATED 和改用更大的模型都会增加费用。由于此 Codelab 使用本地评估，因此不会产生 GPU 费用，但您仍需为 AlphaEvolve API 使用情况和每个生成的候选方案的 Vertex AI Gemini token 付费。从小处着手。

8. 清理

此 Codelab 使用本地评估，因此没有任何可计费的资源在运行，包括集群、GPU 和已部署的服务。如需完全重置结账流程，请执行以下操作：

git clean -xfd   # removes .env, .venv, and generated outputs

注意： git clean -xfd 会删除您的 .env（包括项目设置）和 .venv。如果您想继续进行实验，请跳过此步骤。

如果您仅为此 Codelab 创建了一个项目，请在控制台中将其删除，以免产生任何费用。

9. 恭喜

恭喜！您在 Google Cloud 上运行了第一个 AlphaEvolve 实验，仅使用种子程序、评分函数和 Gemini 就进化出了两种算法：圆形填充和 TSP 启发式算法。

您学到的内容

  • AlphaEvolve 的循环运作方式：种子 -> 生成 -> 评估 -> 评分 -> 重复
  • EVOLVE-BLOCK 合同，可让搜索功能优化食谱，而不会操纵指标
  • 分数和失败数据分析如何引导下一代
  • 如何配置、运行、解读和调整本地评估实验

其他 Codelab

这些任务是独立的，您可以按任意顺序执行。

  • 使用远程评估器改进已编译的代码：改进由 Cloud Run 上容器化评估器评分的 Rust/C++ 算法。
  • 在 GKE + Ray 上改进 LLM 微调：在您自己的集群上运行繁重的并行 GPU 评估。

参考文档