本文档是 AlphaEvolve Cloud API 在 Google CloudDiscovery Engine 对话层下的权威性生产级 API 参考文档和系统规范。它定义了精确的嵌套资源层次结构、REST 和 gRPC 端点、字段级限制、生命周期状态机、错误诊断矩阵、安全沙盒规则以及设计完全自动化的客户端控制器和评估循环所需的集成工作流。
统一的生命周期状态机
AlphaEvolve 代理会协调两个独立的状态机，以监控实验广告系列的进展情况，并管理各个程序突变的投放和执行。
实验生命周期状态
实验代表的是整体优化广告系列。它会作为持久性服务器端资源进行处理，并经历以下状态：
CREATED：初始化状态。资源已声明并配置，但尚未填充初始代或调度 API 调用。RUNNING：有效评估状态。该引擎同时对父候选对象进行抽样，通过 LLM 混合生成代码突变，并将任务流式传输到评估器。PAUSED：一种临时保留状态，可通过手动方式或通过自动保护性idle_timeout触发。代码生成停止，现有工作器暂停指标交付。COMPLETED：一种最终状态，表示搜索已成功实现其max_programs目标分配或达到其结构生成限制。FAILED：一种表示系统环境问题（例如未捕获的 API 凭据异常、数据存储区损坏或连续的 runner panic）导致处理执行停止的严重错误状态。
计划状态
运行时验证序列会应用于各个候选变体。
每个生成的代码突变都表现为一种隔离的程序实体，在种群数据库中经历一系列细粒度的操作状态。
INITIALIZED：在数据库中创建了计划条目，用于跟踪其祖先谱系和父计划关联。GENERATING：系统正在向语言模型混合后端主动调度任务，以起草或变异特定的功能代码块。EVALUATING：代码载荷由评估工作进程锁定，并在隔离的测试框架环境中执行。COMPLETED：执行得分和描述性结构洞见会安全地提交到进化数据库，并且该程序会添加到选择池中。
并发和锁定机制
工作器循环使用原子锁定令牌机制来获取程序，以防止在分布式拓扑中出现竞态条件或重复评分开销。评估者必须提交最终的评分架构以及完全匹配的锁定令牌，才能成功将结果提交回数据库。
配置和设置架构
AlphaEvolve 引擎运行时使用的核心架构配置、参数和默认值概览。
AlphaEvolveExperimentConfig
定义了进化实验运行的核心结构参数和程序化约束。
| 字段名称 | 类型 | 默认 | 限制条件 / 值边界 | 技术说明 |
|---|---|---|---|---|
title |
字符串 | 必需 | 最多 256 个字符 | 实验的唯一显示名称。 |
problemDescription |
字符串 | 必需 | 最多 5,000 个字符 | 问题的正式规范。它会直接注入到提示上下文中以建立规则。 |
programmingLanguage |
字符串 | 必需 | 自由格式值 | 演变后的代码库的目标语言（例如 "python"、"cpp"、"verilog"、"cuda"、"julia"、"java"）。 |
runSettings |
对象 | 必需 | 映射到 RunSettings 架构 |
投放节奏和超时参数。 |
generationSettings |
对象 | 必需 | 映射到 GenerationSettings 架构 |
模型选择和上下文参数。 |
evolutionSettings |
对象 | 必需 | 映射到 EvolutionSettings 架构 |
父级选择和多样性参数。 |
notes |
字符串 | 必需 | 最多 1,000 个字符 | 运行文档的可选注释。 |
RunSettings
控制吞吐量步调、并行化限制和自动系统超时。
| 字段名称 | 类型 | 默认 | 限制条件 / 值边界 | 技术说明 |
|---|---|---|---|---|
maxPrograms |
int32 | 100 | 最小值：1，最大值：100000 | 总执行预算（用于生成和评估的程序）。 |
concurrency |
int32 | 1 | 最小值：1，最大值：30 | 队列中处于活跃状态的并行程序突变数量。不允许使用大于 30 的值。 |
maxDuration |
字符串 | null | ISO 8601 dayTimeDuration 字符串 最小值：>=0，最大值：7 天 |
在实验停止之前允许的总实际运行时间。 |
idleTimeout |
字符串 | null | ISO 8601 dayTimeDuration 字符串 最小值：>=0，最大值：24 小时 |
自动转换为“PAUSED”之前的非活跃时长。 |
生成设置
GenerationSettings 架构控制着突变的提示组装、上下文窗口和模型配置：
context（字符串）：用户提供的可选参考文档、补充 API 或规则。强烈建议将令牌数量控制在 20 万以下。如果上下文大小超过 20 万个 token，就会稀释模型的注意力，并降低变异质量。includeFullProgramInPrompt（布尔值）：默认值为false。true：变异提示包含可变# EVOLVE-BLOCK和周围不可变的样板代码（强烈建议用于复杂的结构推理）。false：仅显示可变块，保存令牌上下文。
进化设置
EvolutionSettings 架构控制着岛屿模型重新播种和父级抽样概率：
parentSamplingConfig→paretoSamplingConfig→paretoSamplingProbability（浮点型）：直接从有效 Pareto 前沿抽样父计划（而不是使用基于标准适应度的选择）的概率（0.0 到 1.0）。如果优化后的指标仅返回单个标量指标，则此参数必须设置为0.0（已停用）。
候选计划数据模型
本部分概述了用于在人口数据库中定义和组织候选代码结构的数据架构和表示形式。
AlphaEvolveProgramContent
定义候选程序的组成文件和结构。
files（AlphaEvolveSourceFile的数组）：构成候选代码库的所有文件的列表。此集合严格限制为每个候选计划最多 50 个文件。description（字符串）：自动生成的摘要，概述了生成模型建议的程序化更改（最多 1,000 个字符）。
AlphaEvolveSourceFile
表示代码库中的单个源代码文件。
path（字符串）：工作区相对路径目的地（最多 256 个字符）。如果配置 Python 工作区，主可执行文件入口点必须命名为"initial_program.py"。content（字符串）：包含功能实现块的原始源代码字符串。所有文件的总累计代码库占用空间必须小于 4,000 到 5,000 行代码 (LOC)。programLanguage（字符串）：语言解析器映射标记。此字符串必须与父实验配置中指定的语言完全一致。description（字符串）：一个可选的摘要，用于概述文件的各个架构或用途，在变异传递期间会向 LLM 公开（最多 500 个字符）。
AlphaEvolveProgramEvaluation
客户端运行程序实例在运行时执行后提交回进化数据库的结构化载荷。
scores(AlphaEvolveScores)：标准化、客观的数值指标值。根据最佳实践，应将此数量限制为 3 到 5 个不同的浮点指标；过多的目标维度会降低多目标 Pareto 比较器的性能。insights（AlphaEvolveEvaluationInsight的数组）：传递回的诊断语义标签和自然语言执行轨迹，用于帮助 LLM 进行后续的突变生成尝试（建议最多 10 项）。
得分公式和注入格式
最大化规则
AlphaEvolve 从根本上来说是一种单调爬山算法，可严格最大限度地提高所有数值指标。如果评估流水线跟踪的是最小化目标（例如，以毫秒为单位最大限度缩短应用延迟时间或减少内存使用量），则必须先对该值取反，然后再将其提交回数据库：submitted_score = -latency_ms。
得分最好是连续的。布尔值或高度离散的指标无法提供足够的梯度信号，以实现有效的爬山探索。
单目标提取架构
当评估框架针对单个标量目标函数进行优化时，请使用以下 JSON。
```json
{
"scores": {
"scores": [
{
"metric": "accuracy",
"score": 0.95
}
]
},
"insights": {
"insights": [
{
"label": "validation",
"text": "Passed syntax and basic compilation."
}
]
}
}
```
多目标提取架构
在传递独立的多目标跟踪参数以激活服务器端 Pareto 前沿优化例程时，请使用以下 JSON。
{
"scores": {
"scores": [
{
"metric": "accuracy",
"score": 0.95
},
{
"metric": "latency",
"score": -42.5
}
]
},
"insights": {
"insights": [
{
"label": "verification",
"text": "Passed 5 out of 5 unit tests."
},
{
"label": "latency_warning",
"text": "Latency regression of 3% observed on large dataset."
}
]
}
}
提取和查询节目数据
AlphaEvolve 系统会记录每次生成的突变的遥测数据、执行指标和完整源代码，从而让开发者能够使用 API 或 CLI 查询此历史数据存储区，以跟踪优化进度并提取性能最高的候选代码。
使用 REST API 进行节目检索
可以使用标准 ListAlphaEvolvePrograms 端点以及过滤和排序查询参数从数据库中查询评估过的计划资源：
按状态过滤：查询符合特定生命周期状态的节目：
GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED基于指标的排序：根据优化后的指标检索排序后的候选人：
GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5
使用 CLI 检索节目
如需直接从终端拉取完成度最高的候选版本，请运行以下命令：
ae results best <experiment-nickname> --top 5
完整的 CLI 使用示例
AlphaEvolve CLI 可让开发者直接从 shell 快速管理和监控广告系列：
列出对话会话中的所有实验：
ae experiment list列出特定实验的所有变异候选程序：
ae program list EXPERIMENT_NICKNAME \ --state=COMPLETED \ --order_by="accuracy desc"将 EXPERIMENT_NICKNAME 替换为实验的名称。
检索效果最好的已完成代码候选方案：
ae results best EXPERIMENT_NICKNAME --top 5将 EXPERIMENT_NICKNAME 替换为实验的名称。
恢复已暂停的广告系列：
ae experiment resume EXPERIMENT_NICKNAME将 EXPERIMENT_NICKNAME 替换为实验的名称。
核心 REST API 端点目录
所有端点都位于 Google Cloud Discovery Engine API 的 v1alpha 下。
父级资源路径模式
真实的嵌套父级资源 URI 的结构如下：
projects/{project}/locations/{location}/collections/{collection}/
engines/{engine}/sessions/{session}
创建实验 (POST)
路径：
POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*}/alphaEvolveExperiments请求正文：
AlphaEvolveExperimentConfig（请参阅第 2.1 部分）响应：包含已初始化的广告系列的
AlphaEvolveExperiment资源。HTTP 状态：200 OK
API 载荷示例
请求正文示例 (POST /alphaEvolveExperiments)
{ "config": { "title": "Sorting Optimization Campaign", "problemDescription": "Optimize the custom_heuristic function.", "programLanguage": "python", "notes": "Exploring convergence with Gemini 3.5 Flash.", "runSettings": { "maxPrograms": 250, "concurrency": 8, "maxDuration": "86400s", "idleTimeout": "1800s" }, "generationSettings": { "context": "Ensure custom_heuristic is in-place.", "includeFullProgramInPrompt": true, "models": [ { "name": "gemini-3.5-flash", "weight": 1.0 } ] }, "evolutionSettings": { "parentSamplingConfig": { "paretoSamplingConfig": { "paretoSamplingProbability": 0.0 } } } } }响应正文示例 (200 OK)
{ "name": "projects/.../sort-opt-01", "state": "CREATED", "createTime": "2026-06-23T13:30:00Z", "config": { "title": "Sorting Optimization Campaign", "problemDescription": "Optimize the custom_heuristic function.", "programLanguage": "python", "notes": "Exploring convergence with Gemini 3.5 Flash.", "runSettings": { "maxPrograms": 250, "concurrency": 8, "maxDuration": "86400s", "idleTimeout": "1800s" }, "generationSettings": { "context": "Ensure custom_heuristic is in-place.", "includeFullProgramInPrompt": true, "models": [ { "name": "gemini-3.5-flash", "weight": 1.0 } ] }, "evolutionSettings": { "parentSamplingConfig": { "paretoSamplingConfig": { "paretoSamplingProbability": 0.0 } } } } }
启动实验 (POST)
路径：
POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:start请求正文：
StartExperimentRequest弃用警告：正文字段
initialProgram已弃用，系统会忽略该字段。回答：
GoogleLongrunningOperation(LRO)。HTTP 状态：200 OK（从
CREATED转换到RUNNING）
API 载荷示例
请求正文示例
{ "desiredProgramsCount": 1 }响应正文示例（200 OK - 长时间运行的操作）
{ "name": "projects/.../operations/start-op-7788", "metadata": { "@type": "type.googleapis.com/.../AlphaEvolveStartExperimentMetadata", "createTime": "2026-06-23T13:31:00Z" }, "done": false }
获取节目 (POST)
路径：
POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:acquirePrograms请求正文：
AcquireProgramsRequestdesiredProgramsCount(int32)：要检索的已变异程序的可选批次数量（未设置时默认为 1）。
回答状态：
200 OK：返回包含已锁定AlphaEvolveProgram资源的响应。204 No Content：队列为空或广告系列已暂停。Runner 必须休眠（例如 15 秒）并重试。
API 载荷示例
请求正文示例
{ "desiredProgramsCount": 1 }响应正文示例 (200 OK)
{ "programs": [ { "name": "projects/.../alphaEvolvePrograms/prog-102", "lockToken": "token_uuid_8877_x99", "state": "EVALUATING", "createTime": "2026-06-23T13:32:00Z", "content": { "description": "Mutated candidate program.", "files": [ { "path": "initial_program.py", "programLanguage": "python", "description": "Primary sorting executable.", "content": "def custom_heuristic(arr, _):\n ..." } ] } } ] }响应正文示例（204 无内容）
返回的 HTTP 状态代码为 204，且载荷上下文为空。
提交计划评估结果 (POST)
路径：
POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:submitProgramsEvaluations请求正文：
SubmitProgramsEvaluationsRequestevaluationSubmissions（数组）：包含匹配的lockToken（合格的节目资源路径）和评估载荷（得分和数据洞见）。
回答：
SubmitProgramsEvaluationsResponse（空）。HTTP 状态：200 OK（保存得分、释放有效锁定并注册数据洞见）
API 载荷示例
请求正文示例
{ "evaluationSubmissions": [ { "lockToken": "token_uuid_8877_x99", "program": "projects/.../alphaEvolvePrograms/prog-102", "evaluation": { "scores": { "scores": [ { "metric": "latency_performance", "score": evaluation_payload["score"] } ] }, "insights": { "insights": [ { "label": "benchmark", "text": "Completed test case in 12.45ms." } ] } } } ] }响应正文示例 (200 OK)
{}
继续实验 (POST)
路径：
POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:resume请求正文：
ResumeExperimentRequest回答：
GoogleLongrunningOperation(LRO)。HTTP 状态：200 OK（将状态从
PAUSED转换回RUNNING）
API 载荷示例
请求正文示例
{}响应正文示例（200 OK - 长时间运行的操作）
{
"name": "projects/.../operations/resume-op-9900",
"metadata": {
"@type": "type.googleapis.com/.../AlphaEvolveResumeExperimentMetadata",
"createTime": "2026-06-23T13:45:00Z"
},
"done": false
}
列出节目 (GET)
路径：
GET v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}/alphaEvolvePrograms查询参数：
stateFilter（字符串）：可选。标准列表过滤条件，例如stateFilter = 'COMPLETED'。orderBy（字符串）：可选。基于指标的排序，例如accuracy desc。
回答：
ListAlphaEvolveProgramsResponse。HTTP 状态：200 OK
API 载荷示例
请求查询网址示例
GET v1alpha/projects/.../alphaEvolveExperiments/sort-opt-01/ alphaEvolvePrograms?stateFilter=COMPLETED&orderBy=latency_performance%20desc &pageSize=1响应正文示例 (200 OK)
{ "alphaEvolvePrograms": [ { "name": "projects/.../alphaEvolvePrograms/prog-102", "state": "COMPLETED", "createTime": "2026-06-23T13:32:00Z", "evaluation": { "scores": { "scores": [ { "metric": "latency_performance", "score": -12.45 } ] }, "insights": { "insights": [ { "label": "benchmark", "text": "Completed test case in 12.45ms." } ] } } } ], "nextPageToken": "token_page_1_next" }
诊断代码和问题排查参考
API 诊断代码矩阵
| HTTP 状态 | 错误类型 | 系统原因 | 解决方法或缓解措施 |
|---|---|---|---|
| 400 | INVALID_ARGUMENT |
缺少 # EVOLVE-BLOCK-START / # EVOLVE-BLOCK-END 注释标记；JSON 架构语法无效；超出文件或 LOC 限制。 |
验证块注释是否使用有效的目标语言语法放置在函数正文内。检查文件数量和 LOC 边界是否得到遵守。 |
| 403 | PERMISSION_DENIED |
相应用户或服务账号没有 Discovery Engine User 角色，或者未获分配 Gemini Enterprise 许可。 | 验证有效的 Gemini Enterprise 许可。
运行以下命令，确保为用户和项目正确配置了应用默认凭据：gcloud auth
application-default login
--project=<<PROJECT_ID>>注意：AlphaEvolve 配置不支持 Model Armor。 |
| 408 | LOCK_TIMEOUT |
客户端运行程序超出了其执行时长；队列中的程序锁定已过期。 | 强制执行严格的 30 分钟客户端超时。如果超出，立即提交失败惩罚得分以清除队列锁定。 |
| 429 | RESOURCE_EXHAUSTED |
超出有效并发执行限制或模型配额。 | 实现客户端指数退避算法；在 RunSettings 中配置保守的并发设置。 |
| 503 | SERVICE_UNAVAILABLE |
后端服务过载或正在维护。 | 在客户端实现具有随机指数退避算法的重试循环。 |
修复“静默掉线”问题
当服务器端语言模型因敏感措辞或安全规则触发而标记并舍弃变异的候选提示时，就会发生安全过滤条件拦截（静默舍弃）。服务器会使输出静音，导致队列返回空响应，并且客户端运行程序可能会无限期等待。
临时解决方法：
清理上下文：从
problemDescription中移除带有强烈情绪色彩或对安全性敏感的短语。过滤数据洞见：解析并截断
insights载荷中的原始异常轨迹或终端 stderr 日志，以防止回显触发下游过滤器的不安全系统内容。本地化数据集：请勿将训练记录或大型文本语料库放置在提示中；在评估循环执行期间，在客户端环境中本地加载它们。
客户端评估最佳实践
“意大利面式代码”瓶颈
次优的源代码格式会降低优化质量：“意大利面式代码 == 嘈杂的搜索空间”。放置 EVOLVE-BLOCK 标记之前：
重构代码块，使变量和函数签名具有清晰的名称。
添加描述性强、简洁的文档字符串，说明每个函数或变量的作用和原因。
确保任何外部不可变依赖项（例如导入辅助模块或加载静态数据）都位于
# EVOLVE-BLOCK之外。
上下文窗口分配
为了最大限度地发挥变异创意，请限制发送到 API 的代码载荷。整个程序的上下文应保持在 15 万到 20 万个 token 之间。大量静态的不可变样板代码会消耗模型注意力并降低性能。将实用程序脚本、数据注入流水线和繁重的验证库完全移至客户端评估器。
先准备初始程序
在运行 AlphaEvolve 之前，请使用标准编码代理调试种子代码库和评估器：
准备初始版本：修复明显的语法 bug、编译问题和极端情况。
验证初始得分：验证基准得分是否合理，以及评估器是否完全确定（相同的代码 + 相同的输入 = 相同的得分）。
使用无效输入进行测试：运行包含故意损坏的函数的评估器，以确认它能捕获编译器问题、妥善处理无限循环并返回较高的负惩罚得分。
避免基准过度优化
请勿将已高度优化的基准计划作为初始计划传递。如果您的初始程序已经接近最佳状态，那么 AlphaEvolve 将难以进行爬山，因为改进空间非常小。从合理但未完全优化的基准开始。这为 AlphaEvolve 提供了探索和爬升的空间。
客户端运行程序安全措施
客户端评估器必须实施严格的保障措施，以防止恶意、资源密集型或无响应的候选者阻止并行工作器：
严格的超时时间：强制执行 30 分钟（或更短，具体取决于搜索空间结构）的严格执行截止时间。
超时惩罚提交：如果候选程序变体超出超时限制，立即终止其执行线程。不允许候选进程失败。相反，应立即编译并提交严重失败惩罚得分（例如
-100000.0），同时将描述性调试分析信息返回给服务器，以释放程序的队列锁定。AST 安全过滤条件：在编译之前，始终对传入的源代码载荷运行抽象语法树 (AST) 检查。如果检测到受限的反射或执行原语（例如
eval、exec、getattr或setattr），立即中止执行并应用严重失败惩罚。
更多资源
如需了解详情，请参阅以下资源：