本文件是 AlphaEvolve Cloud API 的正式版 API 參考資料和系統規格，適用於 Discovery Engine 對話層。 Google Cloud這項規格會定義精確的巢狀資源階層、REST 和 gRPC 端點、欄位層級限制、生命週期狀態機器、錯誤診斷矩陣、安全沙箱規則，以及設計全自動用戶端控制器和評估迴圈所需的整合工作流程。
統一生命週期狀態機器
AlphaEvolve 代理程式會協調兩個獨立的狀態機，監控實驗廣告活動的進展，並管理個別程式突變的放送和執行作業。
實驗生命週期狀態
實驗代表整體最佳化廣告活動。系統會將其視為永久的伺服器端資源，並經歷下列狀態：
CREATED：初始化狀態。資源已宣告及設定，但尚未填入初始世代或調度 API 呼叫。RUNNING：有效的評估狀態。引擎會同時對父項候選項目進行取樣、透過 LLM 混合生成程式碼突變，以及將工作串流至評估人員。PAUSED：手動或透過自動保護機制idle_timeout觸發的暫時保留狀態。程式碼生成作業會停止，現有工作人員也會暫停傳送指標。COMPLETED：終端狀態，表示搜尋已成功達成max_programs目標分配量，或達到結構生成限制。FAILED：終端錯誤狀態，表示系統環境問題 (例如未擷取的 API 憑證例外狀況、資料儲存空間損毀或連續執行程式恐慌) 導致處理作業停止執行。
計畫狀態
系統會對個別候選變體套用執行階段驗證序列。
每個產生的程式碼修改作業都會做為獨立的程式實體，在族群資料庫中經歷一連串的精細運作狀態。
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 小時 (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 或規則 (選用)。強烈建議不要超過 20 萬個權杖。如果脈絡大小超過 200,000 個符記，模型注意力會分散，突變品質也會下降。includeFullProgramInPrompt(bool)：預設值為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中指定，或建立新實驗。在以下範例中，系統會將大約十分之九的生成呼叫傳送至第一個模型，其餘則傳送至第二個模型。權重是比率，因此不必加總為 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(浮點數)：直接從有效帕累托前沿取樣父項程式，而非使用標準適應度選取的機率 (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，直接從殼層快速管理及監控廣告活動：
列出對話工作階段中的所有實驗：
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 端點目錄
所有端點都已納入 Discovery Engine API 的 v1alpha Google Cloud 版本控管。
父項資源路徑模式
真正的巢狀父項資源 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(長時間執行的作業)。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(長時間執行的作業)。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 |
|
有效實驗數量上限：請先完成或停止執行實驗，再開始新的實驗 (降低 concurrency 中的 runSettings 不會影響此上限)。模型權杖配額：降低 concurrency 中的 runSettings，並實作指數輪詢。
|
| 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> |
專案未啟用 Vertex AI API (aiplatform.googleapis.com)。 Google Cloud |
執行 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 的程式碼酬載。程式內容總詞元數應維持在 150,000 至 200,000 個之間。大量靜態、不可變動的樣板會耗用模型注意力，並降低效能。將公用程式指令碼、資料擷取管道和大量驗證程式庫完全移至用戶端評估工具。
先啟動初始程式
執行 AlphaEvolve 前，請先使用標準編碼代理，對種子程式碼集和評估工具進行偵錯：
準備種子：修正明顯的語法錯誤、編譯問題和極端情況。
驗證起始分數：確認基準分數合理，且評估工具完全具決定性 (相同程式碼 + 相同輸入 = 相同分數)。
使用無效輸入內容進行測試：執行評估工具，刻意中斷函式，確認工具會偵測到編譯器問題、妥善處理無限迴圈，並傳回高負分。
避免過度最佳化基準
請勿將已高度最佳化的基準計畫做為種子傳遞。如果初始程式已接近最佳狀態，AlphaEvolve 就很難進行爬山演算法，因為改善空間非常有限。一開始先設定合理的基準，但不要過度最佳化。讓 AlphaEvolve 有空間探索和爬山。
用戶端執行器安全防護措施
用戶端評估工具必須強制執行嚴格的防護措施，防止惡意、耗用大量資源或無回應的候選項目導致平行工作者停滯：
嚴格的逾時時間：強制執行 30 分鐘的嚴格執行時間限制 (或視搜尋空間結構而定，時間更短)。
逾時處罰提交：如果候選程式變體超過逾時限制，請立即終止其執行緒。請勿讓候選人程序失敗。請改為立即編譯並提交嚴重失敗處罰分數 (例如
-100000.0)，同時將描述性偵錯深入分析資料傳回伺服器，以釋放程式的佇列鎖定。AST 安全性篩選器：編譯前，請務必對傳入的原始碼酬載執行抽象語法樹 (AST) 檢查。如果偵測到受限的反射或執行基本體 (例如
eval、exec、getattr或setattr)，請立即中止執行並套用嚴重失敗懲罰。
其他資源
詳情請參閱下列資源：