本文件是 Google CloudDiscovery Engine 對話層下 AlphaEvolve Cloud API 的權威性、正式環境級 API 參考資料和系統規格。這項規格定義了精確的巢狀資源階層、REST 和 gRPC 端點、欄位層級限制、生命週期狀態機、錯誤診斷矩陣、安全沙箱規則，以及整合工作流程，這些都是建構全自動用戶端控制器和評估迴圈的必要元素。
統一生命週期狀態機器
AlphaEvolve 代理會協調兩個獨立的狀態機，監控實驗廣告活動進度，並管理個別程式變異的傳遞和執行。
實驗生命週期狀態
實驗代表整體最佳化廣告活動。系統會將其視為永久伺服器端資源處理，並在下列狀態之間轉換：
CREATED：初始化狀態。資源已宣告並設定，但尚未填入初始生成內容或調度 API 呼叫。RUNNING：有效的評估狀態。引擎會同時對父項候選項目進行取樣、透過 LLM 混合生成程式碼變異，並將工作串流至評估器。PAUSED：手動或透過自動保護idle_timeout觸發的暫時保留狀態。程式碼生成作業會停止，現有 worker 則會暫停傳送指標。COMPLETED：終端狀態，表示搜尋已成功達到max_programs目標分配，或達到結構生成限制。FAILED：終端錯誤狀態，表示系統環境問題 (例如未擷取的 API 憑證例外狀況、資料儲存庫損毀或連續執行器恐慌) 導致處理作業停止執行。
計畫狀態
執行階段驗證序列會套用至個別候選變化版本。
每個產生的程式碼變異都會做為獨立的程式實體，在母體資料庫中轉換一系列精細的操作狀態。
INITIALIZED：在資料庫中建立程式項目，追蹤其祖先譜系和父項程式連結。GENERATING：系統會主動將工作分派給語言模型混合後端，以草擬或變更特定功能程式碼區塊。EVALUATING：程式碼酬載會由評估工作站程序鎖定，並在隔離的測試控管工具環境中執行。COMPLETED：執行分數和描述性結構洞察資料會安全地提交至演化資料庫，並將程式新增至選取集區。
並行和鎖定機制
程式是由 worker 迴圈使用原子鎖權杖機制取得，以防止競爭狀況或分散式拓撲中的重複評分負擔。評估者必須提交最終評分架構，以及完全比對的鎖定權杖，才能成功將結果提交回資料庫。
設定和設定結構定義
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 小時 (86400 秒) | ISO 8601 dayTimeDuration 字串 最小值：>0，最大值：7 天 |
實驗停止前允許的總實際時間。 |
idleTimeout |
字串 | 5 小時 (美國/歐盟) 2 小時 (全球) |
ISO 8601 dayTimeDuration 字串 最小值：>0 最大值：位置預設值 |
自動轉換為PAUSED前的閒置時間長度。global 的預設值為 2 小時，區域位置 (us、eu) 的預設值為 5 小時。時間長度受限於位置的預設值，因此如果指定的值高於位置預設值 (例如 global 的 12 小時)，系統會忽略該值，並將值設為 2 小時 (不會顯示錯誤)。 |
生成設定
GenerationSettings 結構定義會控制提示組合、脈絡窗口和變異的模型設定：
context(字串)：使用者提供的選用參考文件、補充 API 或規則。強烈建議將數量控制在 200,000 個以下。如果脈絡大小超過 200,000 個詞元，模型注意力會分散，導致變異品質降低。includeFullProgramInPrompt(bool)：預設值為false。true：變異提示詞包含可變動的EVOLVE-BLOCK和周圍不可變動的樣板 (強烈建議用於複雜的結構推理)。false：只顯示可變區塊，節省詞元脈絡。
models(物件陣列)：選用。每個項目都會命名模型，並提供選用的weight，也就是該模型相對於其他項目的生成呼叫比例。如果省略models，AlphaEvolve 會在建立實驗時將其設為預設模型。隨著新版 Gemini 模型推出，預設值也會隨之變更；「Default model」(預設模型) 會列出各日期適用的模型。如要自行選擇模型，或在每次執行時使用相同模型，請設定models。以下範例會將約九成的生成呼叫傳送至第一個模型，其餘則傳送至第二個模型。權重是比率，因此總和不一定要等於 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。
預設模型
下表列出省略 models 時，AlphaEvolve 根據實驗建立日期使用的模型。
| 已建立實驗 | 預設模型 |
|---|---|
| 2026 年 10 月 26 日起 | gemini-4-argon |
| 2026 年 9 月 29 日至 2026 年 10 月 25 日 | gemini-3.8-flash |
| 2026 年 6 月 30 日至 2026 年 9 月 28 日 | gemini-3.5-flash |
| 2026 年 6 月 30 日前 | gemini-2.5-flash |
如要找出指派給實驗的模型，請查看實驗設定或建立回應中的 generationSettings.models。由於變更會在轉換當天生效，因此在這些日期建立的實驗可能會收到舊版或新版預設模型。2026 年 6 月 30 日前建立的實驗若未指定 models，這個欄位就不會有值。
由於模型會儲存在每項實驗中，因此變更預設值不會影響現有實驗。如要使用較新的預設模型，請建立新實驗。
進化設定
EvolutionSettings 結構定義會控制島嶼模型重新播種和父項取樣機率：
parentSamplingConfig→paretoSamplingConfig→paretoSamplingProbability(浮點數)：直接從有效柏拉圖前沿取樣父程式的機率 (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 個不同的浮點指標；過多的目標維度會降低多目標 Pareto 比較器的效能。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，直接在殼層中快速管理及監控廣告活動：
列出對話工作階段中的所有實驗：
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 項 AlphaEvolve 實驗 (
STARTED或RUNNING)。如果啟動或恢復的實驗超過這項限制，系統會傳回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 No Content)
傳回 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不會影響這項限制)。模型權杖配額：降低 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 區塊。 |
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 的程式碼酬載。程式總脈絡應保持在 150,000 到 200,000 個權杖以下。靜態、不可變動的大型樣板程式碼區塊會消耗模型注意力，並降低效能。將公用程式指令碼、資料擷取管道和繁重的驗證程式庫，完全移至用戶端評估工具。
先啟動初始程式
執行 AlphaEvolve 前，請使用標準程式碼代理，對種子程式碼集和評估工具進行偵錯：
準備種子：修正明顯的語法錯誤、編譯問題和極端案例。
驗證起始分數：確認基準分數合理，且評估器完全具有確定性 (相同程式碼 + 相同輸入 = 相同分數)。
使用無效輸入內容進行測試：故意使用有問題的函式執行評估器，確認評估器能找出編譯器問題、妥善處理無限迴圈，並傳回高負數懲罰分數。
避免過度最佳化基準
請勿將已高度最佳化的基準程式做為種子傳遞。如果初始程式已接近最佳狀態，AlphaEvolve 將難以進行爬山演算法，因為改進空間非常有限。一開始先採用合理但未達到最佳化的基準。這讓 AlphaEvolve 有空間探索和爬坡
用戶端執行工具防護措施
用戶端評估器必須實施嚴格的防護措施，防止惡意、耗用大量資源或無回應的候選項目拖慢平行工作站：
嚴格的逾時限制：強制執行 30 分鐘的嚴格執行截止時間 (或更短，視搜尋空間結構而定)。
逾時懲罰提交：如果候選程式變體超過逾時限制，請立即終止其執行執行緒。請勿讓候選程序失敗。請改為立即編譯並提交嚴重失敗懲罰分數 (例如
-100000.0)，以及描述性的偵錯深入分析，並將這些資訊傳回伺服器，以釋放程式的佇列鎖定。AST 安全性篩選器：編譯前，一律對傳入的原始碼酬載執行抽象語法樹 (AST) 檢查。如果偵測到受限的反射或執行原始碼 (例如
eval、exec、getattr或setattr)，請立即中止執行，並套用嚴重的失敗懲罰。
其他資源
詳情請參閱下列資源：