开始在 Google Cloud 上使用 AlphaEvolve

1. 简介

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

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

您将执行的操作

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

所需条件

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

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

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

费用：此 Codelab 使用本地评估（不使用 GPU，不使用 GKE）。唯一需要付费的是用于生成候选方案的 AlphaEvolve API 使用量。

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

2. 准备工作

选择您的项目并启用 API

1. 在 Google Cloud 控制台 中，选择或创建一个已启用结算功能的项目，然后在终端中设置该项目：

gcloud config set project <YOUR_PROJECT_ID>

2. 启用 Discovery Engine API，该 API 可为 AlphaEvolve 提供服务：

gcloud services enable discoveryengine.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）。

请妥善保存此 ID，您很快就会将其粘贴到 .env 中。除非您已配置自定义助理，否则请保留 ASSISTANT=default_assistant。

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

1. 针对应用默认凭据进行身份验证：

gcloud auth application-default login

2. 克隆示例代码库并打开它。您将从该代码库根目录运行所有命令：

git clone https://github.com/Google-Cloud-AI/alphaevolve-on-googlecloud.git
cd alphaevolve-on-googlecloud

3. 创建虚拟环境并将 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，以便下一代模型避免犯同样的错误。

每个 AlphaEvolve 问题都具有以下形式：可使用 EVOLVE-BLOCK 表示的代码、可自动化的评估，以及要尽可能提高的单个标量得分。

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 渲染最佳打包方案。

注意：问题排查：PERMISSION_DENIED 或 403 通常表示项目中未启用 Discovery Engine API。重新检查“准备工作”步骤。如果运行立即结束并显示“Failed to create experiment”，则表示 .env 中的凭据或 GE_APP_ID 有误。

5. 解读结果

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

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

在运行初期看到一些得分较低或被跳过的候选方案是正常且健康的现象，这意味着 Gemini 正在探索，而失败带来的经验会引导后续的生成。

现在，您已完成整个循环：种子 -> 生成 -> 评估 -> 得分 -> 重复。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

2. 从代码库根目录运行：

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 使用费。从小处着手。

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 评估。

参考文档

• AlphaEvolve 开发者指南
• AlphaEvolve 示例代码库
• 圆图示例
• TSP 示例