本文件是 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 個字元 | 問題的正式規格。這項資訊會直接插入提示情境，建立規則。 |
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 萬以下。如果脈絡大小超過 200,000 個符記，模型注意力就會分散，導致突變品質下降。includeFullProgramInPrompt(bool)：預設值為false。true：變動提示包含可變動的# EVOLVE-BLOCK和周圍不可變動的樣板 (強烈建議用於複雜的結構推理)。false：只會顯示可變動的區塊，並儲存權杖內容。
演化設定
EvolutionSettings 結構定義會控制島嶼模型重新播種和父項取樣機率：
parentSamplingConfig→paretoSamplingConfig→paretoSamplingProbability(浮點數)：直接從有效帕累托前沿取樣父項程式，而非使用標準適應度選取的機率 (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 行。programLanguage(字串)：語言剖析器對應標記。這個字串必須與父項實驗設定中指定的語言完全相符。description(字串)：可選的摘要，說明檔案的個別架構或用途，會在變動傳遞期間向 LLM 公開 (最多 500 個字元)。
AlphaEvolveProgramEvaluation
用戶端執行個體在執行階段後提交至演化資料庫的結構化酬載。
scores(AlphaEvolveScores)：標準化客觀的數值指標。最佳做法是將此限制為 3 到 5 個不同的浮動指標；目標維度過多會降低多目標帕累托比較工具的效能。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."
}
]
}
}
```
多目標擷取架構
如要傳遞獨立的多目標追蹤參數，啟用伺服器端帕累托前沿最佳化常式，請使用下列 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}
建立實驗 (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：佇列為空或廣告活動已暫停。執行者必須休眠 (例如 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、符合資格的程式資源路徑，以及評估酬載 (分數和洞察資料)。
回覆：
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 範圍符合規定。 |
| 403 | PERMISSION_DENIED |
使用者或服務帳戶沒有 Discovery Engine 使用者角色，或未獲派 Gemini Enterprise 授權。 | 確認有效的 Gemini Enterprise 授權。
請執行下列指令，確保使用者和專案的應用程式預設憑證設定正確：gcloud auth
application-default login
--project=<<PROJECT_ID>>注意：Model Armor 不支援 AlphaEvolve 設定。 |
| 408 | LOCK_TIMEOUT |
用戶端執行器超出執行時間；佇列中的程式鎖定已過期。 | 強制執行嚴格的用戶端逾時 (30 分鐘)。如果超過上限，請立即提交失敗處罰分數，清除佇列鎖定。 |
| 429 | RESOURCE_EXHAUSTED |
超過有效並行執行限制或模型配額。 | 實作用戶端指數輪詢；在 RunSettings 內設定保守的並行設定。 |
| 503 | SERVICE_UNAVAILABLE |
後端服務超載或正在進行維護。 | 在用戶端實作重試迴圈，並採用隨機指數輪詢策略。 |
修正「無聲掉線」問題
如果伺服器端語言模型因敏感用語或觸發安全規則而標記並捨棄變異的候選提示，就會發生安全篩選器攔截 (無聲捨棄) 情況。伺服器會將輸出內容設為靜音，導致佇列傳回空白回應，而用戶端執行器可能會無限期等待。
解決方法：
清除情境：從
problemDescription中移除情緒激動或涉及安全性的片語。篩選洞察資料：剖析並截斷
insights酬載中的原始例外狀況追蹤或終端機 stderr 記錄，防止系統回傳不安全的內容，進而觸發下游篩選器。將資料集在地化：請勿在提示中放置訓練記錄或大型文字語料庫，而是在評估迴圈執行期間，於用戶端環境中在本機載入。
用戶端評估最佳做法
「義大利麵式程式碼」瓶頸
來源格式不佳會降低最佳化品質：「義大利麵式程式碼 ==
雜訊搜尋空間」。放置 EVOLVE-BLOCK 標記前，請注意下列事項：
重構程式碼區塊，清楚命名變數和函式簽章。
新增簡潔的說明文件字串，說明每個函式或變數的用途和原因。
請確保所有外部不可變動的依附元件 (例如匯入輔助模組或載入靜態資料) 都位於
# EVOLVE-BLOCK之外。
脈絡窗口分配
為盡量發揮突變創意，請限制傳送至 API 的程式碼酬載。整個程式的總情境應維持在 150,000 到 200,000 個權杖之間。大量靜態、不可變動的樣板會消耗模型注意力，並降低效能。將公用程式指令碼、資料擷取管道和大量驗證程式庫完全移至用戶端評估工具。
先啟動初始程式
執行 AlphaEvolve 之前，請先使用標準編碼代理程式，對種子程式碼庫和評估工具進行偵錯：
準備種子：修正明顯的語法錯誤、編譯問題和極端情況。
驗證起始分數：確認基準分數合理，且評估工具完全具備決定性 (相同程式碼 + 相同輸入內容 = 相同分數)。
使用無效輸入進行測試：執行評估工具，並刻意中斷函式，確認工具是否會偵測到編譯器問題、妥善處理無限迴圈，以及傳回高負分。
避免過度最佳化基準
請勿將已高度最佳化的基準程式做為種子傳遞。如果初始程式已接近最佳狀態，AlphaEvolve 就很難進行爬山演算法，因為幾乎沒有改善空間。一開始先設定合理的基準，但不要過度最佳化。這讓 AlphaEvolve 有空間可以探索和爬山。
用戶端執行器安全防護措施
用戶端評估人員必須嚴格執行防護措施，防止惡意、耗用大量資源或無回應的候選項目導致平行工作人員停滯：
嚴格的逾時時間：強制執行 30 分鐘的嚴格執行截止時間 (或視搜尋空間結構而定，時間更短)。
逾時處置：如果候選程式變體超過逾時限制，請立即終止其執行緒。請勿讓候選程序失敗。請改為立即編譯並提交嚴重失敗處罰分數 (例如
-100000.0)，以及描述性偵錯深入分析資料，傳回伺服器以釋放程式的佇列鎖定。AST 安全性篩選器：編譯前，請務必對傳入的原始碼酬載執行抽象語法樹 (AST) 檢查。如果偵測到受限的反射或執行基本類型 (例如
eval、exec、getattr或setattr)，請立即中止執行作業，並套用嚴重失敗處置。
其他資源
詳情請參閱下列資源：