Riferimento API AlphaEvolve

Questo documento funge da riferimento API autorevole e di livello di produzione e da specifica di sistema per l'API AlphaEvolve Cloud nei livelli conversazionali di Google Cloud Discovery Engine. Definisce le gerarchie di risorse nidificate precise, gli endpoint REST e gRPC, i vincoli a livello di campo, le macchine a stati del ciclo di vita, le matrici di diagnostica degli errori, le regole di sandboxing di sicurezza e i workflow di integrazione necessari per progettare un controller e un ciclo di valutazione lato client completamente automatizzati.

Macchine a stati del ciclo di vita unificate

L'agente AlphaEvolve coordina due macchine a stati indipendenti per monitorare l'avanzamento della campagna sperimentale e gestire la pubblicazione e l'esecuzione di singole mutazioni del programma.

Stati del ciclo di vita dell'esperimento

Un esperimento rappresenta la campagna di ottimizzazione complessiva. Viene elaborato come una risorsa lato server persistente e passa attraverso i seguenti stati:

  • CREATED: lo stato di inizializzazione. La risorsa è dichiarata e configurata, ma non ha ancora compilato le generazioni iniziali o inviato chiamate API.

  • RUNNING: lo stato di valutazione attivo. Il motore esegue contemporaneamente il campionamento dei candidati principali, la generazione di mutazioni del codice tramite la combinazione di LLM e lo streaming delle attività ai valutatori.

  • PAUSED: uno stato di attesa temporaneo attivato manualmente o tramite una idle_timeout protettiva automatica. La generazione del codice si interrompe e i worker esistenti mettono in pausa la distribuzione delle metriche.

  • COMPLETED: uno stato terminale che indica che la ricerca ha soddisfatto correttamente l'allocazione del target max_programs o ha raggiunto il limite di generazione strutturale.

  • FAILED: uno stato di errore terminale che indica che l'esecuzione dell'elaborazione è stata interrotta a causa di problemi sistemici dell'ambiente, ad esempio eccezioni non rilevate delle credenziali API, danneggiamento dell'archivio dati o panico consecutivo del runner.

Stati del programma

La sequenza di convalida in fase di runtime viene applicata alle singole varianti candidate.

Ogni mutazione del codice generato si comporta come un'entità di programma isolata che passa attraverso una sequenza di stati operativi granulari all'interno del database della popolazione.

  1. INITIALIZED: la voce del programma viene creata nel database, monitorando la sua genealogia ancestrale e i collegamenti al programma genitore.

  2. GENERATING: un'attività viene inviata attivamente al backend di combinazione di modelli linguistici per creare o modificare i blocchi di codice funzionali specifici.

  3. EVALUATING: il payload del codice è bloccato da un processo di valutazione del worker ed eseguito all'interno di un ambiente di test isolato.

  4. COMPLETED: i punteggi di esecuzione e gli approfondimenti strutturali descrittivi vengono salvati in modo sicuro nel database evolutivo e il programma viene aggiunto al pool di selezione.

Meccanismi di concorrenza e blocco

I programmi vengono acquisiti dai loop dei worker utilizzando un meccanismo di token di blocco atomico per evitare race condition o overhead di punteggio duplicato nelle topologie distribuite. Per eseguire il commit dei risultati nel database, il valutatore deve inviare lo schema di punteggio finalizzato insieme al token di blocco della corrispondenza esatta.

Schemi di configurazione e impostazioni

Panoramica delle configurazioni, dei parametri e dei valori predefiniti dello schema principale utilizzati dal runtime del motore AlphaEvolve.

AlphaEvolveExperimentConfig

Definisce i parametri strutturali di base e i vincoli programmatici dell'esecuzione dell'esperimento evolutivo.

Nome campo Tipo Predefinito Vincoli / Limiti di valore Descrizione tecnica
title string Obbligatorio Massimo 256 caratteri Nome visualizzato univoco dell'esperimento.
problemDescription string Obbligatorio Massimo 5000 caratteri La specifica formale del problema. Viene inserito direttamente nei contesti dei prompt per stabilire le regole.
programLanguage string Obbligatorio Valore in formato libero Lingua di destinazione del codebase evoluto (ad esempio, "python", "cpp", "verilog", "cuda", "julia", "java").
runSettings oggetto Obbligatorio Mappatura allo schema RunSettings Parametri di pacing e timeout.
generationSettings oggetto Optional Mappatura allo schema GenerationSettings Selezione del modello e parametri di contesto.
evolutionSettings oggetto Optional Mappatura allo schema EvolutionSettings Parametri di selezione dei genitori e di diversità.

RunSettings

Regola la velocità effettiva, i limiti di parallelizzazione e i timeout automatici del sistema.

Nome campo Tipo Predefinito Vincoli / Limiti di valore Descrizione tecnica
maxPrograms int32 100 Min: 2, Max: 100000 Budget totale di esecuzione (programmi da generare e valutare). Deve essere superiore a 1.
concurrency int32 1 Min: 1, Max: 30 Numero di mutazioni parallele del programma attive nella coda. Non sono consentiti valori superiori a 30.
maxDuration string 24 ore (86.400 secondi) Stringa dayTimeDuration ISO 8601
Min: >0, Max: 7 giorni		 Tempo totale di esecuzione consentito prima dell'interruzione dell'esperimento.
idleTimeout string 5 ore (Stati Uniti/Europa)
2 ore (globale)		 Stringa dayTimeDuration ISO 8601
Min: >0
Max: il valore predefinito della località		 Durata dell'inattività prima della transizione automatica a PAUSED. Il valore predefinito è 2 ore in global e 5 ore nelle località regionali (us, eu). La durata è limitata dal valore predefinito della località, quindi specificare un valore superiore al valore predefinito della località (ad esempio, 12 ore in global) viene ignorato e il valore è 2 ore (senza errori).

Impostazioni di generazione

Lo schema GenerationSettings controlla l'assemblaggio dei prompt, le finestre contestuali e le configurazioni del modello per le mutazioni:

  • context (stringa): documentazione di riferimento, API supplementari o regole facoltative fornite dall'utente. È vivamente consigliato di non superare i 200.000 token. Le dimensioni del contesto superiori a 200.000 token diluiscono l'attenzione del modello e peggiorano la qualità della mutazione.

  • includeFullProgramInPrompt (booleano): valore predefinito false.

    • true: Il prompt di mutazione include EVOLVE-BLOCK modificabile e il boilerplate immutabile circostante (altamente consigliato per il ragionamento strutturale complesso).

    • false: è visibile solo il blocco modificabile, salvando il contesto del token.

  • models (array di oggetti): facoltativo. Ogni voce indica un modello e gli assegna un weight facoltativo, ovvero la quota di chiamate di generazione del modello rispetto alle altre voci. Se ometti models, AlphaEvolve sceglie il modello predefinito quando crea l'esperimento: il modello Gemini che Google consiglia per la generazione di codice con AlphaEvolve. Questo consiglio cambia con il rilascio di modelli più recenti. A partire dal 29 settembre 2026, il valore predefinito è gemini-3.8-flash. Per utilizzare un modello diverso, specifica quello che vuoi in models. Per bloccare lo stesso modello a ogni esecuzione, imposta models.

    Poiché AlphaEvolve risolve il valore predefinito quando crea l'esperimento, gli esperimenti creati prima della modifica del modello predefinito mantengono il modello registrato nella configurazione. Per spostare un esperimento esistente su Gemini 3.8 Flash, specificalo in models o crea un nuovo esperimento.

    L'esempio seguente invia circa nove chiamate di generazione su dieci al primo modello e il resto al secondo. I pesi sono rapporti, quindi non devono sommare 1.

    "models": [
  {
    "name": "gemini-3.8-flash",
    "weight": 0.9
  },
  {
    "name": "gemini-3.1-pro-preview",
    "weight": 0.1
  }
]

Modelli supportati

Imposta models[].name su uno dei seguenti valori. Puoi combinare al massimo due modelli in un singolo esperimento.

Nome modello Regioni di pubblicazione
gemini-3.8-flash (predefinito) global, us, eu
gemini-3.7-flash global, us, eu
gemini-3.5-flash global, us, eu
gemini-3.1-pro-preview global

AlphaEvolve convalida models quando crea l'esperimento e restituisce INVALID_ARGUMENT per un nome di modello che non è presente in questa tabella o che non è disponibile nella regione che hai richiesto.

Impostazioni di evoluzione

Lo schema EvolutionSettings controlla la generazione di nuovi valori del modello a isole e le probabilità di campionamento dell'elemento padre:

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (float): la probabilità (da 0,0 a 1,0) di campionare i programmi principali direttamente dalla frontiera di Pareto attiva anziché utilizzare la selezione standard basata sull'idoneità. Questo parametro deve essere impostato su 0.0 (disattivato) se le metriche ottimizzate restituiscono una sola metrica scalare.

Modelli di dati dei programmi candidati

Questa sezione descrive gli schemi e le rappresentazioni dei dati utilizzati per definire e organizzare le strutture del codice candidato all'interno del database della popolazione.

AlphaEvolveProgramContent

Definisce i file e la composizione strutturale del programma candidato.

  • files (array di AlphaEvolveSourceFile): un elenco di tutti i file che compongono la base di codice candidata. Il payload deve contenere almeno un file sorgente. Google consiglia di mantenere il numero totale di file a 50 per programma candidato, in modo da garantire un'attenzione ottimale del modello e un'efficienza della finestra contestuale.

  • description (stringa): un riepilogo generato automaticamente che descrive le modifiche programmatiche suggerite dal modello di generazione (max 1000 caratteri).

AlphaEvolveSourceFile

Rappresenta un singolo file di codice sorgente nel codebase.

  • path (stringa): il percorso di destinazione relativo allo spazio di lavoro (obbligatorio, massimo 256 caratteri). Ogni voce del file di origine deve specificare un percorso non vuoto. Se configuri un workspace Python, il punto di ingresso del file eseguibile principale deve essere denominato esattamente "initial_program.py".

  • content (stringa): la stringa del codice sorgente non elaborato che comprende i blocchi di implementazione funzionale. Google consiglia di mantenere le dimensioni cumulative del codebase in tutti i file tra 4000 e 5000 righe di codice (LOC). Questo è ottimale per l'attenzione del modello e le prestazioni di generazione delle mutazioni.

  • programLanguage (stringa): il tag di mappatura del parser della lingua. Questa stringa deve corrispondere esplicitamente alla lingua designata nella configurazione dell'esperimento principale.

  • description (stringa): un riepilogo facoltativo che delinea l'architettura o lo scopo individuale del file, che viene esposto all'LLM durante i passaggi di mutazione (massimo 500 caratteri).

AlphaEvolveProgramEvaluation

Il payload strutturato inviato dalle istanze del runner client al database evolutivo dopo l'esecuzione del runtime.

  • scores (AlphaEvolveScores): valori numerici standardizzati e oggettivi. Le best practice prevedono di limitare questo valore a 3-5 metriche di virgola mobile distinte; un numero eccessivo di dimensioni target peggiora le prestazioni del comparatore Pareto multi-obiettivo.

  • insights (array di AlphaEvolveEvaluationInsight): etichette semantiche diagnostiche e tracce di esecuzione in linguaggio naturale restituite per assistere i successivi tentativi di generazione di mutazioni dell'LLM (massimo 10 elementi consigliati).

Formati di formulazione e importazione dei punteggi

La regola di massimizzazione

AlphaEvolve funziona fondamentalmente come un algoritmo di salita della collina monotono e massimizza rigorosamente tutte le metriche numeriche. Se la pipeline di valutazione monitora un target di minimizzazione (ad esempio, la minimizzazione della latenza dell'applicazione in millisecondi o la riduzione della memoria utilizzata), devi negare il valore prima di inviarlo di nuovo al database: submitted_score = -latency_ms.

Idealmente, i punteggi dovrebbero essere continui. Le metriche booleane o altamente discrete non forniscono un segnale di gradiente sufficiente per un'esplorazione efficace.

Schema di importazione con un solo obiettivo

Utilizza il seguente JSON quando l'evaluation harness esegue l'ottimizzazione in base a una singola funzione obiettivo scalare.

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "validation",
        "text": "Passed syntax and basic compilation."
      }
    ]
  }
}

Schema di importazione multi-obiettivo

Utilizza il seguente JSON quando passi parametri di monitoraggio multi-obiettivo indipendenti per attivare le routine di ottimizzazione della frontiera di Pareto lato server.

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

Recupero ed esecuzione di query sui dati dei programmi

Il sistema AlphaEvolve registra la telemetria, le metriche di esecuzione e il codice sorgente completo di ogni mutazione generata, consentendo agli sviluppatori di eseguire query su questo datastore storico utilizzando l'API o la CLI per monitorare l'avanzamento dell'ottimizzazione ed estrarre i candidati al codice con il rendimento migliore.

Recupero dei programmi tramite l'API REST

È possibile eseguire query sulle risorse del programma valutate dal database utilizzando l'endpoint ListAlphaEvolvePrograms standard con parametri di query di filtro e ordinamento:

  • Filtro per stato: esegui query sui programmi che corrispondono a uno stato del ciclo di vita specifico:

    GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED

  • Ordinamento basato sulle metriche: recupera i candidati ordinati in base alle metriche ottimizzate:

    GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5

Recupero dei programmi utilizzando l'interfaccia a riga di comando

Per estrarre i candidati con il maggior numero di completamenti direttamente dal terminale, esegui il seguente comando:

ae results best <experiment-nickname> --top 5

Esempi di utilizzo completi dell'interfaccia a riga di comando

La CLI AlphaEvolve offre agli sviluppatori un controllo amministrativo rapido e il monitoraggio delle campagne direttamente dalla shell:

  • Elenca tutti gli esperimenti in una sessione conversazionale:

    ae experiment list

  • Elenca tutti i programmi candidati mutati per un esperimento specifico:

    ae program list EXPERIMENT_NICKNAME \
  --state=COMPLETED \
  --order_by="accuracy desc"

    Sostituisci EXPERIMENT_NICKNAME con il nome dell'esperimento.

  • Recupera i candidati al codice completato con il rendimento migliore:

    ae results best EXPERIMENT_NICKNAME --top 5

    Sostituisci EXPERIMENT_NICKNAME con il nome dell'esperimento.

  • Riprendere una campagna in pausa:

    ae experiment resume EXPERIMENT_NICKNAME

    Sostituisci EXPERIMENT_NICKNAME con il nome dell'esperimento.

Directory degli endpoint API REST principali

Tutti gli endpoint sono versionati in v1alpha dell' Google Cloud API Discovery Engine.

Pattern del percorso della risorsa padre

L'URI della risorsa padre nidificata effettiva è strutturato come segue: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

  • AlphaEvolve è disponibile in global, us e eu. La creazione di esperimenti in altre posizioni restituisce FAILED_PRECONDITION.
  • I progetti Assured Workloads non sono supportati.
  • Un progetto è limitato a 30 esperimenti AlphaEvolve attivi contemporaneamente (STARTED o RUNNING) per località. L'avvio o la ripresa di un esperimento che supera questo limite restituisce RESOURCE_EXHAUSTED.

Crea esperimento (POST)

  • Percorso:

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

  • Corpo della richiesta: AlphaEvolveExperimentConfig (vedi sezione 2.1)

  • Risposta: risorsa AlphaEvolveExperiment contenente la campagna inizializzata.

  • Stato HTTP: 200 OK

Esempi di payload API

  1. Esempio di corpo della richiesta (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. Esempio di corpo della risposta (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
        }
      }
    }
  }
}

Avvia esperimento (POST)

  • Percorso:

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

  • Corpo della richiesta: StartExperimentRequest

  • Avviso di ritiro: il campo del corpo initialProgram è ritirato e ignorato.

  • Risposta: GoogleLongrunningOperation (LRO).

  • Stato HTTP:200 OK (lo stato passa da CREATED a RUNNING)

Esempi di payload API

  1. Esempio di corpo della richiesta

    {
  "desiredProgramsCount": 1
}

  2. Esempio di corpo della risposta (200 OK - operazione a lunga esecuzione)

    {
  "name": "projects/.../operations/start-op-7788",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveStartExperimentMetadata",
    "createTime": "2026-06-23T13:31:00Z"
  },
  "done": false
}

Acquisire programmi (POST)

  • Percorso:

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

  • Corpo della richiesta: AcquireProgramsRequest

    • desiredProgramsCount (int32): conteggio batch facoltativo dei programmi modificati da recuperare (il valore predefinito è 1 se non impostato).

  • Stati della risposta

    • 200 OK: restituisce la risposta contenente le risorse AlphaEvolveProgram bloccate.

    • 204 No Content: La coda è vuota o la campagna è in pausa. I corridori devono dormire (ad esempio, per 15 secondi) e riprovare.

Esempi di payload API

  1. Esempio di corpo della richiesta

    {
  "desiredProgramsCount": 1
}

  2. Esempio di corpo della risposta (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. Esempio di corpo della risposta (204 No Content)

Codice di stato HTTP 204 restituito con un contesto di payload vuoto.

Inviare valutazioni dei programmi (POST)

  • Percorso:

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

  • Corpo della richiesta: SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (array): contiene lockToken corrispondenti, il percorso della risorsa di programma qualificata e il payload di valutazione (punteggi e approfondimenti). L'API accetta esattamente un invio di valutazione per chiamata. Il raggruppamento di più valutazioni in un'unica richiesta viene rifiutato con INVALID_ARGUMENT. Quando valuti più candidati, invia ogni programma singolarmente.

  • Risposta: SubmitProgramsEvaluationsResponse (vuota).

  • Stato HTTP: 200 OK (salva i punteggi, rilascia il blocco attivo e registra gli approfondimenti)

Esempi di payload API

  1. Esempio di corpo della richiesta

    {
  "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. Esempio di corpo della risposta (200 OK)

    {}

Riprendi esperimento (POST)

  • Percorso:

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

  • Corpo della richiesta: ResumeExperimentRequest

  • Risposta: GoogleLongrunningOperation (LRO).

  • Stato HTTP:200 OK (lo stato passa da PAUSED a RUNNING)

Esempi di payload API

  1. Esempio di corpo della richiesta

    {}

  2. Esempio di corpo della risposta (200 OK - operazione a lunga esecuzione)

    {
  "name": "projects/.../operations/resume-op-9900",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveResumeExperimentMetadata",
    "createTime": "2026-06-23T13:45:00Z"
  },
  "done": false
}

Elenca programmi (GET)

  • Percorso:

    GET v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}/alphaEvolvePrograms

  • Parametri di query:

    • stateFilter (stringa): facoltativo. Filtro standard dell'elenco, ad esempio stateFilter = 'COMPLETED'.

    • orderBy (stringa): facoltativo. Ordinamento basato sulle metriche, ad esempio accuracy desc.

  • Risposta: ListAlphaEvolveProgramsResponse.

  • Stato HTTP: 200 OK

Esempi di payload API

  1. Esempio di URL di query di richiesta

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

  2. Esempio di corpo della risposta (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"
}

Codice diagnostico e riferimento per la risoluzione dei problemi

Matrice dei codici di diagnostica dell'API

Stato HTTP Tipo di errore Causa di sistema Soluzione alternativa o azione di mitigazione
400 INVALID_ARGUMENT
  • Marcatori EVOLVE-BLOCK-START / EVOLVE-BLOCK-END con formato non valido (ad esempio, contenuti che condividono la riga del marcatore, blocchi nidificati o marcatore di fine mancante).
  • Blocco Evolve vuoto contenente solo commenti o spazi vuoti senza codice modificabile.
  • maxPrograms impostato su meno di 2.
  • Campi di configurazione non riconosciuti.
  • Configurazione del modello non valida (più di due modelli, voci duplicate, pesi non positivi o temperatura al di fuori di [0.0, 2.0]).
  • Invio di più valutazioni in una singola chiamata submitProgramsEvaluations.
  • Il progetto è un progetto Assured Workloads.
 Assicurati che i marcatori si trovino da soli sulla riga e racchiudano almeno una riga di codice non di commento. Imposta maxPrograms su 2 o più. Rimuovi i campi che non fanno parte dell'API, ad esempio notes, che era presente nella versione di anteprima dell'API. Invia le valutazioni singolarmente, una alla volta.
403 PERMISSION_DENIED
  • Il chiamante non dispone del ruolo Editor Discovery Engine (roles/discoveryengine.editor) o Amministratore (roles/discoveryengine.admin). Nota: roles/discoveryengine.user non concede le autorizzazioni AlphaEvolve e roles/discoveryengine.viewer non può ottenere esperimenti.
  • Il chiamante non dispone dell'autorizzazione per la risorsa sessione padre.
  • Non è assegnata alcuna licenza Gemini Enterprise attiva.
 Concedi roles/discoveryengine.editor o roles/discoveryengine.admin a livello di progetto e verifica l'accesso alla sessione padre. Verifica le licenze Gemini Enterprise attive. Configura le credenziali predefinite dell'applicazione:

gcloud auth application-default login --project=PROJECT_ID

Nota: Model Armor non è supportato nelle configurazioni AlphaEvolve.
400 FAILED_PRECONDITION
  • Token di blocco obsoleto o scaduto o mancata corrispondenza dello stato del programma (ad esempio, il candidato è stato riacquisito o finalizzato dopo la scadenza del contratto).
  • Esperimento creato in una località non supportata (al di fuori di global, us o eu).
  • L'API Vertex AI (aiplatform.googleapis.com) non è abilitata nel progetto.
 Ripeti esattamente l'lockToken restituito da :acquirePrograms. Applica timeout lato client (consigliato 30 minuti) e invia i punteggi di penalità per errore al momento del timeout. Ricrea l'esperimento in una località supportata. Abilita l'API Vertex AI: gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
429 RESOURCE_EXHAUSTED
  • Il progetto ha raggiunto il limite di 30 esperimenti attivi contemporaneamente (STARTED / RUNNING) per località.
  • Quota di token di generazione del modello di backend esaurita.
 Per il limite di esperimenti attivi: completa o interrompi gli esperimenti in corso prima di avviarne uno nuovo (la riduzione di concurrency in runSettings non influisce su questo limite). Per la quota di token del modello: riduci concurrency in runSettings e implementa il backoff esponenziale.
503 SERVICE_UNAVAILABLE Il classificatore di sicurezza di input non è disponibile o il servizio di backend è temporaneamente sovraccarico. Implementa un ciclo di nuovi tentativi con backoff esponenziale randomizzato lato client.

Messaggi di errore comuni e relative soluzioni

Il seguente elenco di riferimento riporta i messaggi di errore comuni restituiti dall'API, le cause sottostanti e i passaggi di risoluzione.

Errori di analisi del programma iniziale e di EVOLVE-BLOCK

Messaggio di errore Causa di sistema Soluzione alternativa o azione di mitigazione
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. I marcatori EVOLVE-BLOCK-START e EVOLVE-BLOCK-END vengono visualizzati sulla stessa riga. Posiziona i marcatori di inizio e fine su righe separate.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. Il codice, il testo o i caratteri finali condividono la riga con un marcatore EVOLVE-BLOCK-START o EVOLVE-BLOCK-END. Assicurati che l'indicatore sia da solo sulla riga (preceduto solo dal prefisso del commento, ad esempio # EVOLVE-BLOCK-START).
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. Un marcatore EVOLVE-BLOCK-START viene visualizzato all'interno di un blocco Evolve già aperto. Rimuovi i marcatori di inizio nidificati. I blocchi evolve nidificati non sono supportati.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. Un marcatore EVOLVE-BLOCK-END viene visualizzato senza un EVOLVE-BLOCK-START precedente. Assicurati che ogni indicatore di fine sia preceduto da un indicatore di inizio corrispondente.
Parsing error: Evolve block started but not ended. È stato trovato un marcatore EVOLVE-BLOCK-START senza un marcatore di chiusura EVOLVE-BLOCK-END corrispondente. Aggiungi un indicatore di chiusura EVOLVE-BLOCK-END.

Errori relativi alla struttura e ai contenuti del programma

Messaggio di errore Causa di sistema Soluzione alternativa o azione di mitigazione
Program content must contain at least one source file. program_content.source_files è vuoto. Fornisci almeno un file di origine.
source_files entries must have a non-empty path. Una voce del file di origine ha una stringa path vuota. Specifica un percorso relativo valido per ogni file di origine.
source_files entry has empty content; path: <path> Una voce del file di origine contiene contenuti di stringa vuota. Compila i contenuti del file.
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). I blocchi Evolve contengono solo commenti, docstring o spazi vuoti, senza codice modificabile. Includi almeno una riga di codice modificabile (ad esempio definizioni di funzioni o logica dell'algoritmo) all'interno del blocco.

Errori di convalida della configurazione e del modello

Messaggio di errore Causa di sistema Soluzione alternativa o azione di mitigazione
unsupported model: <model_name> Il modello richiesto non è supportato o non è abilitato per il tuo progetto. Utilizza modelli supportati. Consulta le impostazioni di generazione.
model '<model_name>' is not served from domain shard '<location>'. Il modello non è disponibile nella località regionale specificata. Per i modelli e le località supportati, consulta Impostazioni di generazione.
generation_settings.models must contain at most 2 distinct models; got <count>. In generation_settings.models sono state specificate più di due configurazioni del modello. Specifica al massimo due modelli nella miscela.
generation_settings.models contains duplicate entry: <model_name> Lo stesso nome del modello viene visualizzato più di una volta in generation_settings.models. Rimuovi le voci del modello duplicate.
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. Il peso del campionamento del modello è negativo, zero o non finito. Imposta un peso positivo o rimuovi la voce.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. La temperatura del modello non rientra nell'intervallo valido [0.0, 2.0]. Regola la temperatura su un valore compreso tra 0.0 e 2.0.
RunSettings.max_programs is required and must be greater than 1. max_programs è stato omesso o impostato su 1 o meno. Imposta max_programs su 2 o più (è richiesto un minimo di 2 per ammettere i candidati evoluti).
RunSettings.concurrency is required and must be positive. concurrency è stato omesso o impostato su 0 o un valore inferiore. Imposta concurrency su un numero intero positivo (in genere 1-30).
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. pareto_sampling_probability non rientra in [0.0, 1.0]. Imposta una probabilità compresa tra 0.0 e 1.0.

Errori relativi ai prerequisiti del progetto e al ciclo di vita dell'esperimento

Messaggio di errore Causa di sistema Soluzione alternativa o azione di mitigazione
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> L'API Vertex AI (aiplatform.googleapis.com) non è abilitata nel progetto Google Cloud . Esegui 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. Il progetto ha raggiunto la quota di 30 esperimenti attivi contemporaneamente (STARTED o RUNNING) in quella località. Interrompi o completa gli esperimenti esistenti prima di avviare o riprendere un nuovo esperimento.
Cannot <action> experiment from state <current_state> Tentativo di transizione di stato non valida (ad esempio, avvio di un esperimento già in esecuzione o ripresa di un esperimento appena creato). Assicurati che gli esperimenti seguano le transizioni standard del ciclo di vita: 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. Un'operazione di avvio o ripristino precedente è ancora in corso. Attendi il completamento della consegna in attesa o chiama il numero STOP per svuotare i messaggi in attesa.
AlphaEvolve is not available for this project. Il progetto è bloccato o è un profilo di conformità non supportato. Consulta il profilo di conformità e sicurezza.

Errori di acquisizione e valutazione del programma

Messaggio di errore Causa di sistema Soluzione alternativa o azione di mitigazione
Exactly one evaluation submission is required. Più invii di valutazione sono stati raggruppati in un'unica richiesta submitProgramsEvaluations. Invia le valutazioni singolarmente, una per chiamata API.
Program is required for each evaluation submission./submission.program is required. Il percorso della risorsa program non è stato fornito nell'invio della valutazione. Passa il percorso completo della risorsa del programma.
Lock token is required for each evaluation submission./submission.lock_token is required. Il lock_token restituito durante acquirePrograms è stato omesso. Trasmetti la stringa lock_token esatta restituita al momento dell'acquisizione del programma.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' Il token di blocco inviato nella richiesta non corrisponde al lease del server attivo (ad esempio, il lease è scaduto e un altro worker lo ha acquisito oppure è stato fornito un token errato). Ripeti esattamente lockToken da acquirePrograms e invia i risultati prima dei timeout del client.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> Il programma è già stato valutato, annullato o non fa più parte di EVALUATION_IN_PROGRESS. Ignora la valutazione obsoleta o acquisisci nuovamente il candidato, se disponibile.
The request was rejected by a safety policy. La descrizione del problema di input, il codice iniziale o le metriche di valutazione hanno attivato le policy di classificazione della sicurezza. Sanitizza il testo del prompt e le descrizioni dei problemi per rimuovere tracce o parole chiave sensibili.
The input safety classifier is currently unavailable. Il servizio di classificazione della sicurezza non è temporaneamente raggiungibile o è sovraccarico (chiusura non riuscita). Implementa la logica di nuovi tentativi con backoff esponenziale.

Correzione dei "rilasci silenziosi"

Un'intercettazione del filtro di sicurezza (eliminazione silenziosa) si verifica quando i modelli linguistici lato server segnalano ed eliminano i prompt candidati modificati a causa di formulazioni sensibili o attivazioni di regole di sicurezza. Il server disattiva l'output, facendo in modo che la coda restituisca risposte vuote e i runner client potrebbero attendere all'infinito.

Correzione della soluzione temporanea:

  • Sanitizza contesto: rimuovi frasi cariche di emotività o sensibili alla sicurezza da problemDescription.

  • Filtra approfondimenti:analizza e tronca le tracce di eccezioni non elaborate o i log stderr del terminale nel payload insights per evitare di riprodurre contenuti di sistema non sicuri che attivano filtri downstream.

  • Localizza i set di dati:non inserire record di addestramento o grandi corpora di testo all'interno dei prompt; caricali localmente nell'ambiente client durante l'esecuzione del ciclo di valutazione.

Best practice per la valutazione lato client

Il collo di bottiglia del "codice spaghetti"

La formattazione non ottimale del codice sorgente peggiora la qualità dell'ottimizzazione: "Spaghetti code == Noisy search space". Prima di inserire i marcatori EVOLVE-BLOCK:

  • Rifattorizza i blocchi di codice in modo che le variabili e le firme delle funzioni siano denominate in modo chiaro.

  • Aggiungi docstring descrittive e concise che spieghino cosa fa e perché ogni funzione o variabile. Assicurati che le docstring si trovino accanto al codice funzionale effettivo; l'inserimento solo di una docstring o di commenti all'interno di un EVOLVE-BLOCK viene rifiutato come blocco vuoto.

  • Assicurati che i marcatori di commento EVOLVE-BLOCK-START e EVOLVE-BLOCK-END siano posizionati da soli sulle rispettive righe, ad eccezione degli spazi bianchi iniziali e dei prefissi dei commenti (ad esempio # o //).

  • Assicurati che tutte le dipendenze esterne e immutabili (come l'importazione di moduli helper o il caricamento di dati statici) si trovino al di fuori di EVOLVE-BLOCK.

Allocazione della finestra contestuale

Per massimizzare la creatività delle mutazioni, limita il payload del codice inviato all'API. Il contesto totale del programma deve rimanere tra 150.000 e 200.000 token. Grandi blocchi di boilerplate statici e immutabili consumano l'attenzione del modello e peggiorano le prestazioni. Sposta gli script di utilità, le pipeline di importazione dati e le librerie di convalida pesanti interamente nell'evaluator lato client.

Inizializza prima il programma iniziale

Prima di eseguire AlphaEvolve, utilizza un agente di codifica standard per eseguire il debug sia della base di codice iniziale sia dell'evaluator:

  • Prepara il seme:correggi i bug di sintassi evidenti, i problemi di compilazione e i casi limite.

  • Verifica il punteggio iniziale:verifica che il punteggio di base sia ragionevole e che il valutatore sia completamente deterministico (stesso codice + stesso input = stesso punteggio).

  • Test con input non validi:esegui il valutatore con funzioni intenzionalmente interrotte per verificare che rilevi i problemi del compilatore, gestisca correttamente i loop infiniti e restituisca punteggi di penalità negativi elevati.

Evita baseline eccessivamente ottimizzate

Non utilizzare come seme un programma di base già altamente ottimizzato. Se il tuo programma iniziale è già quasi ottimale, AlphaEvolve avrà difficoltà a migliorare perché il margine di miglioramento è molto ridotto. Inizia con una baseline ragionevole, ma non ottimizzata al massimo. In questo modo, AlphaEvolve ha spazio per esplorare e superare le salite.

Misure di sicurezza del runner lato client

I valutatori lato client devono applicare salvaguardie rigorose per impedire che i candidati dannosi, che richiedono molte risorse o che non rispondono, blocchino i worker paralleli:

  • Timeout rigorosi: applica un limite di esecuzione rigoroso di 30 minuti (o meno, a seconda della struttura dello spazio di ricerca).

  • Invio della penalità per timeout: se una variante del programma candidato supera il limite di timeout, termina immediatamente il thread di esecuzione. Non consentire l'interruzione del processo candidato. Invece, compila e invia immediatamente un punteggio di penalità per errore grave (ad esempio, -100000.0) insieme a un insight di debug descrittivo al server per sbloccare la coda del programma.

  • Filtri di sicurezza AST:esegui sempre un controllo di ispezione dell'albero della sintassi astratta (AST) sul payload del codice sorgente in entrata prima della compilazione. Interrompi immediatamente l'esecuzione e applica una penalità per errore grave se vengono rilevati primitivi di esecuzione o reflection con limitazioni (ad esempio eval, exec, getattr o setattr).

Ulteriori risorse

Per maggiori informazioni, consulta le seguenti risorse: