本文档是 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 个字符 | 问题的正式规范。它会直接注入到提示上下文中，以建立规则。 |
programLanguage |
字符串 | 必需 | 自由格式值 | 演进后的代码库的目标语言（例如 "python"、"cpp"、"verilog"、"cuda"、"julia"、"java"）。 |
runSettings |
对象 | 必需 | 映射到 RunSettings 架构 |
投放节奏和超时参数。 |
generationSettings |
对象 | 可选 | 映射到 GenerationSettings 架构 |
模型选择和上下文参数。 |
evolutionSettings |
对象 | 可选 | 映射到 EvolutionSettings 架构 |
父代选择和多样性参数。 |
RunSettings
控制吞吐量节奏、并行化限制和自动系统超时。
| 字段名称 | 类型 | 默认 | 限制条件 / 值边界 | 技术说明 |
|---|---|---|---|---|
maxPrograms |
int32 | 100 | 下限：2，上限：100000 | 总执行预算（要生成和评估的程序）。必须大于 1。 |
concurrency |
int32 | 1 | 最小值：1，最大值：30 | 队列中处于活跃状态的并行程序突变数量。不允许使用大于 30 的值。 |
maxDuration |
字符串 | 24 小时（86,400 秒） | ISO 8601 dayTimeDuration 字符串 最小值：>0，最大值：7 天 |
实验停止前允许的总实际时间。 |
idleTimeout |
字符串 | 5 小时（美国/欧盟） 2 小时（全球） |
ISO 8601 dayTimeDuration 字符串 最小值：>0 最大值：相应位置的默认值 |
自动过渡到 PAUSED 之前的非活跃时长。默认情况下，global 中的值为 2 小时，区域位置（us、eu）中的值为 5 小时。持续时间受位置默认值的限制，因此指定高于位置默认值的值（例如 global 中的 12 小时）会被忽略，并且该值会变为 2 小时（不会出错）。 |
生成设置
GenerationSettings 架构控制突变的提示组装、上下文窗口和模型配置：
context（字符串）：用户提供的可选参考文档、补充 API 或规则。强烈建议您将令牌数量控制在 20 万以下。上下文大小超过 200,000 个 token 会分散模型的注意力，并降低变异质量。includeFullProgramInPrompt（布尔值）：默认值为false。true：变异提示包含可变EVOLVE-BLOCK和周围不可变的样板（强烈建议用于复杂的结构推理）。false：只有可变块可见，从而节省了词元上下文。
models（对象数组）：可选。每个条目都会命名一个模型，并为其提供一个可选的weight，该值表示相应模型相对于其他条目的生成调用份额。如果您省略models，AlphaEvolve 会在创建实验时选择默认模型：Google 推荐用于通过 AlphaEvolve 生成代码的 Gemini 模型。随着新模型的发布， 该建议也会发生变化。自 2026 年 9 月 29 日起，默认值为gemini-3.8-flash。如需使用其他模型，请在models中指定所需的模型。如需在每次运行时固定同一模型，请自行设置models。由于 AlphaEvolve 在创建实验时会解析默认值，因此在默认模型更改之前创建的实验会保留其配置中记录的模型。如需将现有实验移至 Gemini 3.8 Flash，请在
models中指定该实验，或创建新实验。以下示例会将大约 90% 的生成调用发送到第一个模型，其余调用发送到第二个模型。权重是比率，因此不必加起来等于 1。
"models": [ { "name": "gemini-3.8-flash", "weight": 0.9 }, { "name": "gemini-3.1-pro-preview", "weight": 0.1 } ]
支持的模型
将 models[].name 设置为以下某个值。在单个实验中，您最多可以组合两个模型。
| 模型名称 | 服务区域 |
|---|---|
gemini-4-argon |
global、us、eu |
gemini-3.8-flash（默认） |
global、us、eu |
gemini-3.7-flash |
global、us、eu |
gemini-3.5-flash |
global、us、eu |
gemini-3.1-pro-preview |
global |
AlphaEvolve 会在创建实验时验证 models，并针对不在此表中的模型名称或您请求的区域中不可用的模型名称返回 INVALID_ARGUMENT。
进化设置
EvolutionSettings 架构控制岛屿模型重新播种和父级采样概率：
parentSamplingConfig→paretoSamplingConfig→paretoSamplingProbability（浮点型）：直接从有效 Pareto 前沿对父程序进行抽样（而不是使用基于标准适应度的选择）的概率（0.0 到 1.0）。如果优化后的指标仅返回单个标量指标，则此参数必须设置为0.0（停用）。
候选计划数据模型
本部分概述了用于定义和整理人口数据库中候选代码结构的数据架构和表示形式。
AlphaEvolveProgramContent
定义候选程序的各个文件和结构组成。
files（AlphaEvolveSourceFile数组）：构成候选代码库的所有文件的列表。载荷必须至少包含一个源文件。Google 建议将每个候选程序的总文件数控制在 50 个以内，这样可以实现最佳的模型注意力和上下文窗口效率。description（字符串）：自动生成的摘要，概述了生成模型建议的程序化更改（最多 1,000 个字符）。
AlphaEvolveSourceFile
表示代码库中的单个源代码文件。
path（字符串）：相对于工作区的路径目标（必需，最多 256 个字符）。每个源文件条目都必须指定一个非空路径。如果配置 Python 工作区，则主可执行文件入口点必须命名为"initial_program.py"。content（字符串）：包含功能实现块的原始源代码字符串。Google 建议将所有文件的累计代码库大小保持在 4,000 到 5,000 行代码 (LOC) 以下；这对于模型注意力和突变生成性能来说是最佳的。programLanguage（字符串）：语言解析器映射标记。此字符串必须与父实验配置中指定的语言完全一致。description（字符串）：一个可选的摘要，用于概述文件的各个架构或用途，在变异传递期间会向 LLM 公开（最多 500 个字符）。
AlphaEvolveProgramEvaluation
客户端运行程序实例在运行时执行后提交回进化数据库的结构化载荷。
scores(AlphaEvolveScores)：标准化的客观数值指标值。根据最佳实践，应将此值限制为 3 到 5 个不同的浮点指标；过多的目标维度会降低多目标帕累托比较器的性能。insights（AlphaEvolveEvaluationInsight数组）：传递回来的诊断语义标签和自然语言执行轨迹，用于帮助 LLM 进行后续的突变生成尝试（建议最多 10 项）。
得分公式和注入格式
最大化规则
AlphaEvolve 从根本上来说是一种单调爬山算法，可严格最大限度地提高所有数值指标。如果评估流水线跟踪的是最小化目标（例如，以毫秒为单位最大限度缩短应用延迟时间或减少内存用量），您必须先对该值取反，然后再将其提交回数据库：submitted_score = -latency_ms。
理想情况下，得分应该是连续的。布尔值或高度离散的指标无法提供足够的梯度信号，无法进行有效的爬山探索。
单目标注入架构
当评估框架针对单个标量目标函数进行优化时，请使用以下 JSON。
{
"scores": {
"scores": [
{
"metric": "accuracy",
"score": 0.95
}
]
},
"insights": {
"insights": [
{
"label": "validation",
"text": "Passed syntax and basic compilation."
}
]
}
}
多目标提取架构
传递独立的多目标跟踪参数时，请使用以下 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}
- AlphaEvolve 适用于
global、us和eu。在其他位置创建实验会返回FAILED_PRECONDITION。 - 不支持 Assured Workloads 项目。
- 每个位置的每个项目最多只能同时运行 30 个有效（
STARTED或RUNNING）AlphaEvolve 实验。启动或恢复超出此限制的实验会返回RESOURCE_EXHAUSTED。
创建实验 (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", "runSettings": { "maxPrograms": 250, "concurrency": 8, "maxDuration": "86400s", "idleTimeout": "1800s" }, "generationSettings": { "context": "Ensure custom_heuristic is in-place.", "includeFullProgramInPrompt": true, "models": [ { "name": "gemini-3.8-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", "runSettings": { "maxPrograms": 250, "concurrency": 8, "maxDuration": "86400s", "idleTimeout": "1800s" }, "generationSettings": { "context": "Ensure custom_heuristic is in-place.", "includeFullProgramInPrompt": true, "models": [ { "name": "gemini-3.8-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：队列为空或广告系列已暂停。运行程序必须休眠（例如 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、限定的计划资源路径和评估载荷（分数和数据分析）。该 API 每次调用仅接受一个评估提交。将多次评估批量处理到单个请求中会被拒绝，并显示INVALID_ARGUMENT。评估多个候选程序时，请单独提交每个程序。
回答：
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 |
|
确保标记单独成行，并至少包含一行非注释代码。将 maxPrograms 设置为 2 或更大值。移除不属于该 API 的字段，例如该 API 预览版中存在的 notes。逐个提交评估。
|
| 403 | PERMISSION_DENIED |
|
在项目级授予 roles/discoveryengine.editor 或 roles/discoveryengine.admin，并验证对父会话的访问权限。验证有效的 Gemini Enterprise 许可。配置应用默认凭证：gcloud auth application-default login --project=PROJECT_ID注意：AlphaEvolve 配置不支持 Model Armor。 |
| 400 | FAILED_PRECONDITION |
|
回显 :acquirePrograms 返回的确切 lockToken。强制执行客户端超时（建议为 30 分钟），并在超时时提交失败惩罚得分。在受支持的位置重新创建实验。启用 Vertex AI API：gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID。
|
| 429 | RESOURCE_EXHAUSTED |
|
对于正在运行的实验数量上限：请先完成或停止正在运行的实验，然后再开始新实验（降低 runSettings 中的 concurrency 不会影响此上限）。对于模型 token 配额：降低 runSettings 中的 concurrency 并实现指数退避算法。 |
| 503 | SERVICE_UNAVAILABLE |
输入内容安全分类器不可用或后端服务暂时过载。 | 在客户端实现具有随机指数退避算法的重试循环。 |
常见出错提示和解决方法
以下参考文档列出了 API 返回的常见出错提示、其根本原因和解决步骤。
初始程序和 EVOLVE-BLOCK 解析错误
| 出错提示 | 系统原因 | 解决方法或缓解措施 |
|---|---|---|
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. |
EVOLVE-BLOCK-START 和 EVOLVE-BLOCK-END 标记出现在同一行。 |
将开始和结束标记放在单独的行中。 |
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. |
代码、文本或尾随字符与 EVOLVE-BLOCK-START 或 EVOLVE-BLOCK-END 标记位于同一行。 |
确保标记单独位于一行（前面仅有注释前缀，例如 # EVOLVE-BLOCK-START）。 |
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. |
EVOLVE-BLOCK-START 标记出现在已打开的 evolve 块内。 |
请移除嵌套的开始标记；不支持嵌套的 evolve 代码块。 |
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. |
EVOLVE-BLOCK-END 标记显示时前面没有 EVOLVE-BLOCK-START。 |
确保每个结束标记前面都有一个匹配的开始标记。 |
Parsing error: Evolve block started but not ended. |
找到了 EVOLVE-BLOCK-START 标记，但没有找到匹配的结束 EVOLVE-BLOCK-END 标记。 |
添加结束 EVOLVE-BLOCK-END 标记。 |
计划内容和结构错误
| 出错提示 | 系统原因 | 解决方法或缓解措施 |
|---|---|---|
Program content must contain at least one source file. |
program_content.source_files 为空。 |
提供至少一个源文件。 |
source_files entries must have a non-empty path. |
源文件条目包含空 path 字符串。 |
请为每个源文件指定有效的相对路径。 |
source_files entry has empty content; path: <path> |
源文件条目包含空字符串内容。 | 填充文件内容。 |
Program content must contain at least one EVOLVE-BLOCK-START / EVOLVE-BLOCK-END region with editable code between the markers (whitespace and comment-only regions don't count -- AlphaEvolve has nothing to mutate). |
Evolve 代码块仅包含注释、文档字符串或空白，不包含可编辑的代码。 | 在代码块中添加至少一行可编辑的代码（例如函数定义或算法逻辑）。 |
配置和模型验证错误
| 出错提示 | 系统原因 | 解决方法或缓解措施 |
|---|---|---|
unsupported model: <model_name> |
所请求的模型不受支持或未针对您的项目启用。 | 使用支持的型号。请参阅生成设置。 |
model '<model_name>' is not served from domain shard '<location>'. |
该模型在指定的区域位置不可用。 | 如需了解支持的模型和位置，请参阅生成设置。 |
generation_settings.models must contain at most 2 distinct models; got <count>. |
在 generation_settings.models 中指定了两个以上的模型配置。 |
在混合模型中最多指定两个模型。 |
generation_settings.models contains duplicate entry: <model_name> |
同一模型名称在 generation_settings.models 中多次出现。 |
移除重复的模型条目。 |
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. |
模型抽样权重为负数、零或非有限值。 | 请设置正权重或移除该条目。 |
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. |
模型温度不在有效范围 [0.0, 2.0] 内。 |
将温度调整为介于 0.0 和 2.0 之间的值。 |
RunSettings.max_programs is required and must be greater than 1. |
max_programs 被省略或设置为 1 或更小的值。 |
将 max_programs 设置为 2 或更大值（至少需要 2 才能接纳进化后的候选者）。 |
RunSettings.concurrency is required and must be positive. |
concurrency 被省略或设置为 0 或更小。 |
将 concurrency 设置为正整数（通常为 1-30）。 |
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. |
pareto_sampling_probability不在[0.0, 1.0]内。 |
请设置一个介于 0.0 和 1.0 之间的概率。 |
项目前提条件和实验生命周期错误
| 出错提示 | 系统原因 | 解决方法或缓解措施 |
|---|---|---|
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> |
Google Cloud 项目未启用 Vertex AI API (aiplatform.googleapis.com)。 |
运行 gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID。 |
Project has reached the limit of 30 concurrently active AlphaEvolve experiments in location <location>. Stop or wait for a running experiment to finish before starting or resuming another. |
相应项目已达到该位置同时有效（STARTED 或 RUNNING）实验的配额上限 30 个。 |
在开始或恢复新实验之前，请先停止或完成现有实验。 |
Cannot <action> experiment from state <current_state> |
尝试了无效的状态转换（例如，启动已在运行的实验，或恢复新创建的实验）。 | 确保实验遵循标准生命周期转换：CREATED → START、PAUSED/COMPLETED → RESUME、STARTED/RUNNING → STOP。 |
Cannot resume experiment: a start or watchdog message is already pending. Stop the experiment first to drain it, or wait for the pending delivery to complete. |
之前的启动或恢复操作仍在进行中。 | 等待待处理的传送完成，或调用 STOP 来排空待处理的消息。 |
AlphaEvolve is not available for this project. |
项目已被屏蔽或是不受支持的合规性配置文件。 | 请参阅合规性和安全配置文件。 |
计划获取和评估错误
| 出错提示 | 系统原因 | 解决方法或缓解措施 |
|---|---|---|
Exactly one evaluation submission is required. |
在单个 submitProgramsEvaluations 请求中批量提交了多项评估。 |
单独提交评估，每次 API 调用提交一个。 |
Program is required for each evaluation submission./submission.program is required. |
评估提交中未提供 program 资源路径。 |
传递完整的计划资源路径。 |
Lock token is required for each evaluation submission./submission.lock_token is required. |
省略了 acquirePrograms 期间返回的 lock_token。 |
传递获取相应计划时返回的确切 lock_token 字符串。 |
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' |
提交中发送的锁定令牌与有效服务器租约不匹配（例如，租约已过期，并且已被其他工作器获取，或者提供的令牌不正确）。 | 回显 acquirePrograms 中的确切 lockToken，并在客户端超时之前提交结果。 |
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> |
该计划已完成评估、取消或从EVALUATION_IN_PROGRESS中移出。 |
舍弃过时的评估，或重新获取候选对象（如有）。 |
The request was rejected by a safety policy. |
输入的问题描述、初始代码或评估指标触发了安全分类政策。 | 清理提示文本和问题描述，以移除敏感关键字或痕迹。 |
The input safety classifier is currently unavailable. |
安全性分类服务暂时无法访问或过载（故障时关闭）。 | 实现指数退避算法重试逻辑。 |
修复“静默丢弃”
当服务器端语言模型因敏感措辞或安全规则触发而标记并舍弃变异的候选提示时，会发生安全过滤条件拦截（静默舍弃）。服务器会静默输出，导致队列返回空响应，客户端运行器可能会无限期等待。
临时修复方法：
清理上下文：从
problemDescription中移除带有强烈情感色彩或对安全性敏感的短语。过滤数据分析：解析并截断
insights载荷中的原始异常跟踪记录或终端 stderr 日志，以防止回显触发下游过滤器的不安全系统内容。本地化数据集：请勿在提示中放置训练记录或大型文本语料库；在评估循环执行期间，在客户端环境中本地加载这些内容。
客户端评估最佳实践
“面条式代码”瓶颈
不理想的源代码格式会降低优化质量：“意大利面条式代码 == 嘈杂的搜索空间”。放置 EVOLVE-BLOCK 标记之前：
重构代码块，使变量和函数签名具有清晰的名称。
添加描述性、简洁的文档字符串，解释每个函数或变量的作用和原因。确保文档字符串与实际功能代码位于同一位置；如果
EVOLVE-BLOCK中仅包含文档字符串或注释，则会被拒绝，因为这会被视为空代码块。确保
EVOLVE-BLOCK-START和EVOLVE-BLOCK-END注释标记单独位于各自的行上，但开头空格和注释前缀（例如#或//）除外。确保任何外部不可变依赖项（例如导入辅助模块或加载静态数据）都位于
EVOLVE-BLOCK之外。
上下文窗口分配
为了最大限度地提高变异创造力，请限制发送到 API 的代码载荷。整个程序上下文应保持在 15 万到 20 万个 token 之间。大量静态、不可变的样板代码会消耗模型注意力并降低性能。将实用程序脚本、数据注入流水线和繁重的验证库完全移至客户端评估器。
先启动初始程序
在运行 AlphaEvolve 之前，请使用标准编码智能体调试种子代码库和评估器：
准备种子：修复明显的语法 bug、编译问题和极端情况。
验证初始得分：验证基准得分是否合理，以及评估器是否完全确定（相同代码 + 相同输入 = 相同得分）。
使用无效输入进行测试：使用故意损坏的函数运行评估器，以确认它能捕获编译器问题、妥善处理无限循环，并返回较高的负惩罚分数。
避免过度优化的基准
请勿将已经过高度优化的基准程序作为种子传递。如果您的初始程序已经接近最佳状态，AlphaEvolve 将难以进行爬山，因为改进空间非常小。从合理但未最大程度优化的基准开始。这为 AlphaEvolve 提供了探索和爬山的空间。
客户端运行程序安全措施
客户端评估器必须实施严格的保护措施，以防止恶意、资源密集型或无响应的候选模型导致并行工作器停滞：
严格的超时时间：强制执行 30 分钟（或更短，具体取决于搜索空间结构）的严格执行截止时间。
超时惩罚提交：如果候选程序变体超出超时限制，请立即终止其执行线程。请勿让候选进程失败。而是立即编译并提交严重失败惩罚分数（例如
-100000.0）以及描述性调试数据分析，并将其返回给服务器以释放程序的队列锁。AST 安全过滤条件：在编译之前，始终对传入的源代码载荷运行抽象语法树 (AST) 检查。如果检测到受限的反射或执行原语（例如
eval、exec、getattr或setattr），则立即中止执行并施加严重失败惩罚。
更多资源
如需了解详情，请参阅以下资源：