AlphaEvolve API 参考文档

本文档是 AlphaEvolve Cloud API 在 Google CloudDiscovery Engine 对话层下的权威性生产级 API 参考文档和系统规范。它定义了精确的嵌套资源层次结构、REST 和 gRPC 端点、字段级限制、生命周期状态机、错误诊断矩阵、安全沙盒规则以及设计全自动客户端控制器和评估循环所需的集成工作流。

统一的生命周期状态机

AlphaEvolve 代理会协调两个独立的状态机，以监控实验广告系列的进展情况，并管理各个程序突变的投放和执行。

实验生命周期状态

实验代表的是整体优化广告系列。它会作为持久性服务器端资源进行处理，并经历以下状态：

  • CREATED：初始化状态。资源已声明并配置，但尚未填充初始代或调度 API 调用。

  • RUNNING: 活跃评估状态。该引擎同时对父候选对象进行抽样，通过 LLM 混合生成代码突变，并将任务流式传输到评估器。

  • PAUSED：一种临时保留状态，可通过手动方式或通过自动保护性 idle_timeout 触发。代码生成停止，现有工作器暂停指标交付。

  • COMPLETED：一种最终状态，表示搜索已成功实现其 max_programs 目标分配或达到其结构生成限制。

  • FAILED：一种表示系统环境问题（例如未捕获的 API 凭据异常、数据存储区损坏或连续的 runner panic）导致处理执行停止的严重错误状态。

计划状态

运行时验证序列会应用于各个候选变体。

每个生成的代码突变都表现为一个隔离的程序实体，在种群数据库中经历一系列细粒度的操作状态。

  1. INITIALIZED：系统会在数据库中创建节目条目，跟踪其祖先谱系和父节目链接。

  2. GENERATING：任务已主动调度到语言模型混合后端，以起草或变异特定的功能代码块。

  3. EVALUATING：代码载荷由评估工作进程锁定，并在隔离的测试框架环境中执行。

  4. 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 万以下。如果上下文大小超过 20 万个 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-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 载荷示例

  1. 请求正文示例 (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
        }
      }
    }
  }
}

  2. 响应正文示例 (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 载荷示例

  1. 请求正文示例

    {
  "desiredProgramsCount": 1
}

  2. 响应正文示例（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

  • 请求正文： AcquireProgramsRequest

    • desiredProgramsCount (int32)：要检索的已变异程序的可选批次数量（未设置时默认为 1）。

  • 回答状态：

    • 200 OK：返回包含已锁定 AlphaEvolveProgram 资源的响应。

    • 204 No Content：队列为空或广告系列已暂停。跑动器必须休眠（例如 15 秒）并重试。

API 载荷示例

  1. 请求正文示例

    {
  "desiredProgramsCount": 1
}

  2. 响应正文示例 (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    ..."
          }
        ]
      }
    }
  ]
}

  3. 响应正文示例 (204 No Content)

返回了 HTTP 状态 204，但载荷上下文为空。

提交计划评估结果 (POST)

  • 路径：

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:submitProgramsEvaluations

  • 请求正文： SubmitProgramsEvaluationsRequest

    • evaluationSubmissions（数组）：包含匹配的 lockToken（经过限定的程序资源路径）和评估载荷（得分和数据洞见）。该 API 每次调用仅接受一次评估提交。 将多次评估批量处理到单个请求中会被拒绝，并显示 INVALID_ARGUMENT。评估多个候选计划时，请单独提交每个计划。

  • 回答： SubmitProgramsEvaluationsResponse（空）。

  • HTTP 状态：200 OK（保存得分、释放有效锁定并注册数据洞见）

API 载荷示例

  1. 请求正文示例

    {
  "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."
            }
          ]
        }
      }
    }
  ]
}

  2. 响应正文示例 (200 OK)

    {}

继续实验 (POST)

  • 路径：

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:resume

  • 请求正文： ResumeExperimentRequest

  • 回答： GoogleLongrunningOperation (LRO)。

  • HTTP 状态：200 OK（将状态从 PAUSED 转换回 RUNNING）

API 载荷示例

  1. 请求正文示例

    {}

  2. 响应正文示例（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 载荷示例

  1. 请求查询网址示例

    GET v1alpha/projects/.../alphaEvolveExperiments/sort-opt-01/
  alphaEvolvePrograms?stateFilter=COMPLETED&orderBy=latency_performance%20desc
  &pageSize=1

  2. 响应正文示例 (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 标记格式有误（例如，内容与标记的行共享、嵌套块或缺少结束标记）。
  • 包含的演变块为空，仅包含注释或空白，没有可修改的代码。
  • maxPrograms 设置为小于 2。
  • 无法识别的配置字段。
  • 模型配置无效（模型数量超过 2 个、条目重复、权重为非正数或温度超出 [0.0, 2.0]）。
  • 在一次 submitProgramsEvaluations 调用中提交多个评估。
  • 项目是 Assured Workloads 项目。
 确保标记单独占一行，并且至少包含一行非注释代码。将 maxPrograms 设置为 2 或更高值。移除不属于 API 的字段，例如 API 预览版中存在的 notes。逐个提交评估。
403 PERMISSION_DENIED
  • 调用者未持有 Discovery Engine Editor 角色 (roles/discoveryengine.editor) 或 Admin 角色 (roles/discoveryengine.admin)。注意：roles/discoveryengine.user 不授予 AlphaEvolve 权限，并且 roles/discoveryengine.viewer 无法获取实验。
  • 调用方缺少对父会话资源的权限。
  • 未分配有效的 Gemini Enterprise 许可。
 在项目级授予 roles/discoveryengine.editor 或 roles/discoveryengine.admin，并验证对父会话的访问权限。验证有效的 Gemini Enterprise 许可。配置应用默认凭证：

gcloud auth application-default login --project=PROJECT_ID

注意：AlphaEvolve 配置不支持 Model Armor。
400 FAILED_PRECONDITION
  • 过时或过期的锁定令牌，或者程序状态不匹配（例如，在租约失效后重新获取或最终确定了候选版本）。
  • 在不受支持的地理位置（global、us 或 eu 以外的地理位置）创建的实验。
  • 项目未启用 Vertex AI API (aiplatform.googleapis.com)。
 准确回显 :acquirePrograms 返回的 lockToken。强制执行客户端超时（建议为 30 分钟），并在超时时提交失败惩罚得分。在支持的地区重新创建实验。启用 Vertex AI API：gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID。
429 RESOURCE_EXHAUSTED
  • 项目已达到每个位置 30 个并发有效实验的上限（STARTED / RUNNING）。
  • 后端模型生成令牌配额已用尽。
 对于有效实验数量上限：请先完成或停止正在运行的实验，然后再开始新实验（降低 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 标记显示在已打开的演变块内。 移除嵌套的开始标记；不支持嵌套的演变块。
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. 相应位置的项目已达到 30 个并发有效（STARTED 或 RUNNING）实验的配额。 在开始或恢复新实验之前，请先停止或完成现有实验。
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），立即中止执行并应用严重失败惩罚。

更多资源

如需了解详情，请参阅以下资源：