Riferimento API AlphaEvolve

Questo documento funge da riferimento API autorevole e di livello di produzione e da specifica di sistema per l'API Cloud AlphaEvolve nei livelli di conversazione 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 della sicurezza e i workflow di integrazione necessari per progettare un controller lato client e un ciclo di valutazione 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 distribuzione e l'esecuzione delle singole mutazioni del programma.

Stati del ciclo di vita degli esperimenti

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

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

  • RUNNING: lo stato di valutazione attivo. Il motore campiona contemporaneamente i candidati principali, genera mutazioni del codice tramite la combinazione di LLM e trasmette le attività in streaming ai valutatori.

  • PAUSED: Uno stato di mantenimento temporaneo attivato manualmente o tramite un meccanismo di protezione automatizzato idle_timeout. La generazione del codice viene interrotta e i worker esistenti mettono in pausa l'invio delle metriche.

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

  • FAILED: uno stato di errore terminale che indica che problemi sistemici dell'ambiente, come eccezioni delle credenziali API non rilevate, danneggiamento del datastore o panico consecutivo del runner, hanno interrotto l'esecuzione dell'elaborazione.

Stati del programma

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

Ogni mutazione del codice generata 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 il suo pedigree ancestrale e i collegamenti con il programma principale.

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

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

  4. COMPLETED: i punteggi di esecuzione e gli insight 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 duplicati tra topologie distribuite. Il valutatore deve inviare lo schema di punteggio finalizzato insieme al token di blocco con corrispondenza esatta per eseguire correttamente il commit dei risultati nel database.

Schemi di configurazione e impostazioni

Panoramica delle configurazioni, dei parametri e dei valori predefiniti dello schema di base 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 dei valori 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 Mappa allo schema RunSettings Parametri di pacing e timeout.
generationSettings oggetto Optional Mappa allo schema GenerationSettings Selezione del modello e parametri di contesto.
evolutionSettings oggetto Optional Mappa allo schema EvolutionSettings Parametri di selezione dei genitori e di diversità.

RunSettings

Regola il pacing del throughput, i limiti di parallelizzazione e i timeout automatici del sistema.

Nome campo Tipo Predefinito Vincoli / limiti dei valori Descrizione tecnica
maxPrograms int32 100 Min: 2, Max: 100.000 Budget di esecuzione totale (programmi da generare e valutare). Deve essere superiore a 1.
concurrency int32 1 Min: 1, Max: 30 Numero di mutazioni del programma parallelo attive nella coda. I valori superiori a 30 non sono consentiti.
maxDuration string 24h (86400s) Stringa dayTimeDuration ISO 8601
Min: >0, Max: 7 giorni		 Tempo totale di clock consentito prima dell'interruzione dell'esperimento.
idleTimeout string 5 ore (US/EU)
2 ore (globale)		 Stringa dayTimeDuration ISO 8601
Min: >0
Max: 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 se specifichi un valore superiore al valore predefinito della località (ad esempio, 12 ore in global), questo 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 facoltativa fornita dall'utente, API supplementari o regole. Ti consigliamo vivamente di non superare i 200.000 token. Le dimensioni del contesto superiori a 200.000 token diluiscono l'attenzione del modello e riducono la qualità della mutazione.

  • includeFullProgramInPrompt (bool): valore predefinito false.

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

    • false: è visibile solo il blocco modificabile, risparmiando contesto dei token.

  • models (array di oggetti): facoltativo. Ogni voce indica un modello e gli assegna un valore weight facoltativo, che rappresenta la quota di chiamate di generazione di quel modello rispetto alle altre voci. Se ometti models, AlphaEvolve lo imposta sul modello predefinito quando crea l'esperimento. Il valore predefinito cambia con il rilascio di nuovi modelli Gemini; Modello predefinito elenca quale modello si applica in quale data. Per scegliere il modello manualmente o per mantenere lo stesso modello in ogni esecuzione, imposta models.

    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 necessariamente dare come somma 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-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 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 richiesta.

Modello predefinito

La tabella seguente elenca il modello utilizzato da AlphaEvolve quando ometti models, in base alla data di creazione dell'esperimento.

Esperimento creato Modello predefinito
A partire dal 24 ottobre 2026 gemini-4-argon
Dal 29 settembre 2026 al 23 ottobre 2026 gemini-3.8-flash
Dal 30 giugno 2026 al 28 settembre 2026 gemini-3.5-flash
Prima del 30 giugno 2026 gemini-2.5-flash

Per identificare il modello assegnato a un esperimento, controlla generationSettings.models nella configurazione dell'esperimento o nella risposta alla creazione. Poiché le modifiche diventano effettive nel corso del giorno della transizione, gli esperimenti creati in queste date potrebbero ricevere il modello predefinito precedente o quello nuovo. Gli esperimenti creati senza models prima del 30 giugno 2026 non contengono un valore per questo campo.

Poiché il modello è memorizzato in ogni esperimento, una modifica al valore predefinito non influisce sugli esperimenti già esistenti. Per utilizzare un modello predefinito più recente, crea un nuovo esperimento.

Impostazioni di evoluzione

Lo schema EvolutionSettings controlla il riavvio del modello a isola e le probabilità di campionamento dei genitori:

  • 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 dei dati dei programmi dei candidati

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

AlphaEvolveProgramContent

Definisce i file e la struttura del programma candidato.

  • files (array di AlphaEvolveSourceFile): un elenco di tutti i file che compongono il codebase candidato. Il payload deve contenere almeno un file di origine. Google consiglia di mantenere il numero totale di file a 50 per programma candidato; in questo modo, l'attenzione del modello e l'efficienza della finestra contestuale sono ottimali.

  • description (stringa): un riepilogo generato automaticamente che descrive le modifiche programmatiche suggerite dal modello di generazione (massimo 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, l'entry point 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 complessive del codebase in tutti i file al di sotto di 4000-5000 righe di codice (LOC); questo è ottimale per le prestazioni di attenzione del modello e di generazione delle mutazioni.

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

  • description (stringa): un riepilogo facoltativo che descrive 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 client runner al database evolutivo dopo l'esecuzione del runtime.

  • scores (AlphaEvolveScores): valori delle metriche numeriche oggettive standardizzate. Le best practice suggeriscono di limitare questo numero a 3-5 metriche float distinte; dimensioni target eccessive riducono le prestazioni del comparatore di Pareto multiobiettivo.

  • 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 consigliato di 10 elementi).

Formulazione del punteggio e formati di importazione

La regola di massimizzazione

AlphaEvolve opera fondamentalmente come un algoritmo di hill climbing monotonico 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 nuovamente 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 con l'algoritmo hill climbing.

Schema di importazione con un solo obiettivo

Utilizza il seguente JSON quando il framework di valutazione 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 multiobiettivo 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 l'interfaccia a riga di comando per monitorare l'avanzamento dell'ottimizzazione ed estrarre i candidati di codice con il rendimento più elevato.

Recupero dei programmi utilizzando 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 su metriche: recupera i candidati ordinati in base a metriche ottimizzate:

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

Recupero del programma tramite l'interfaccia a riga di comando

Per estrarre i candidati completati principali direttamente dal terminale, esegui il seguente comando:

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

Esempi completi di utilizzo dell'interfaccia a riga di comando

L'interfaccia a riga di comando di AlphaEvolve offre agli sviluppatori un controllo amministrativo e un monitoraggio rapidi delle campagne direttamente dalla shell:

  • Elenca tutti gli esperimenti in una sessione di conversazione:

    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 di codice completati con il rendimento migliore:

    ae results best EXPERIMENT_NICKNAME --top 5

    Sostituisci EXPERIMENT_NICKNAME con il nome dell'esperimento.

  • Ripristina 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 sottoposti a controllo delle versioni in v1alpha dell'API Google Cloud Discovery Engine.

Pattern del percorso della risorsa padre

L'URI della risorsa padre nidificata true è 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 località 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 la sezione 2.1)

  • Risposta: risorsa AlphaEvolveExperiment contenente la campagna inizializzata.

  • Stato HTTP: 200 OK

Esempi di payload dell'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 è deprecato e ignorato.

  • Risposta: GoogleLongrunningOperation (LRO).

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

Esempi di payload dell'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
}

Acquisisci programmi (POST)

  • Percorso:

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

  • Corpo della richiesta: AcquireProgramsRequest

    • desiredProgramsCount (int32): numero di batch facoltativo di programmi mutati da recuperare (il valore predefinito è 1 se non impostato).

  • Stati delle risposte:

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

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

Esempi di payload dell'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)

Stato HTTP 204 restituito con un contesto di payload vuoto.

Invia le 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 del programma qualificato e il payload di valutazione (punteggi e insight). 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 (vuoto).

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

Esempi di payload dell'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 dell'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 i 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 dell'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"
}

Riferimento per i codici di diagnostica e la risoluzione dei problemi

Matrice dei codici di diagnostica dell'API

Stato HTTP Tipo di errore Causa del sistema Soluzione alternativa o azione di mitigazione
400 INVALID_ARGUMENT
  • Marcatori EVOLVE-BLOCK-START / EVOLVE-BLOCK-END non corretti (ad esempio, contenuti che condividono la riga del marcatore, blocchi nidificati o marcatore finale 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 gli indicatori siano 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 Discovery Engine Editor (roles/discoveryengine.editor) o del ruolo 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 della sessione padre.
  • Nessuna licenza Gemini Enterprise attiva assegnata.
 Concedi roles/discoveryengine.editor o roles/discoveryengine.admin a livello di progetto e verifica l'accesso alla sessione principale. 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 non aggiornato o scaduto oppure mancata corrispondenza dello stato del programma (ad esempio, il candidato è stato riacquisito o finalizzato dopo la scadenza del lease).
  • 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 l'esatto lockToken restituito da :acquirePrograms. Applica i timeout lato client (consigliati 30 minuti) e invia i punteggi di penalità per errore al 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 Classificatore di sicurezza di input non disponibile o servizio di backend temporaneamente sovraccarico. Implementa un ciclo di nuovi tentativi con backoff esponenziale randomizzato sul lato client.

Messaggi di errore comuni e relative soluzioni

Il seguente riferimento elenca i messaggi di errore comuni restituiti dall'API, le relative cause sottostanti e i passaggi per la risoluzione.

Errori di analisi del programma iniziale e di EVOLVE-BLOCK

Messaggio di errore Causa del sistema Soluzione alternativa o azione di mitigazione
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. Gli indicatori EVOLVE-BLOCK-START e EVOLVE-BLOCK-END vengono visualizzati sulla stessa riga. Posiziona gli indicatori 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 indicatore 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 indicatore EVOLVE-BLOCK-START viene visualizzato all'interno di un blocco di evoluzione già aperto. Rimuovi i marker di inizio nidificati; i blocchi evolve nidificati non sono supportati.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. Viene visualizzato un indicatore EVOLVE-BLOCK-END senza un indicatore 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 indicatore EVOLVE-BLOCK-START senza un indicatore di chiusura EVOLVE-BLOCK-END corrispondente. Aggiungi un indicatore di chiusura EVOLVE-BLOCK-END.

Errori relativi ai contenuti e alla struttura del programma

Messaggio di errore Causa del 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 vuoti. 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 del sistema Soluzione alternativa o azione di mitigazione
unsupported model: <model_name> Il modello richiesto non è supportato o non è abilitato per il tuo progetto. Utilizza i 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. Consulta le impostazioni di generazione per i modelli e le località supportati.
generation_settings.models must contain at most 2 distinct models; got <count>. Sono state specificate più di due configurazioni del modello in generation_settings.models. Specifica al massimo due modelli nella combinazione.
generation_settings.models contains duplicate entry: <model_name> Lo stesso nome del modello appare più di una volta in generation_settings.models. Rimuovi le voci duplicate del modello.
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 di 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 un valore superiore (è 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 è al di fuori di [0.0, 1.0]. Imposta una probabilità compresa tra 0.0 e 1.0.

Prerequisiti del progetto ed errori del ciclo di vita degli esperimenti

Messaggio di errore Causa del 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> È stata tentata una transizione di stato non valida (ad esempio, l'avvio di un esperimento già in esecuzione o il ripristino 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 ripresa precedente è ancora in corso. Attendi il completamento della consegna in attesa o chiama 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 Profilo di conformità e sicurezza.

Errori di acquisizione e valutazione del programma

Messaggio di errore Causa del 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 valore lock_token restituito durante acquirePrograms è stato omesso. Passa 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 nell'invio 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 l'esatto lockToken da acquirePrograms e invia i risultati prima del 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 rimosso da 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. Sanifica il testo dei prompt e le descrizioni dei problemi per rimuovere parole chiave o tracce sensibili.
The input safety classifier is currently unavailable. Il servizio di classificazione della sicurezza è temporaneamente non raggiungibile o sovraccarico (fails closed). Implementa la logica di ripetizione del backoff esponenziale.

Risoluzione dei "drop 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 frasi sensibili o attivatori di regole di sicurezza. Il server silenzia l'output, facendo sì che la coda restituisca risposte vuote, e i runner client potrebbero attendere a tempo indeterminato.

Correzione con soluzione alternativa:

  • Sanifica il contesto: rimuovi le frasi emotivamente cariche o sensibili alla sicurezza dal problemDescription.

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

  • Localizza i set di dati: non inserire record di addestramento o corpus di testo di grandi dimensioni nei prompt; caricali localmente nell'ambiente client durante l'esecuzione del loop di valutazione.

Best practice per la valutazione lato client

Il collo di bottiglia dello "spaghetti code"

La formattazione non ottimale del codice sorgente riduce la qualità dell'ottimizzazione: "Codice spaghetti == spazio di ricerca rumoroso". Prima di posizionare gli indicatori EVOLVE-BLOCK:

  • Rifattorizza i blocchi di codice in modo che le variabili e le firme delle funzioni abbiano nomi chiari.

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

  • Assicurati che gli indicatori di commento EVOLVE-BLOCK-START e EVOLVE-BLOCK-END siano posizionati da soli sulle rispettive righe, ad eccezione degli spazi vuoti iniziali e dei prefissi dei commenti (come # 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 al di sotto di 150.000-200.000 token. Blocchi di grandi dimensioni di boilerplate statico e immutabile consumano l'attenzione del modello e riducono le prestazioni. Sposta completamente gli script di utilità, le pipeline di importazione dati e le librerie di convalida pesanti nel valutatore lato client.

Prepara prima il programma iniziale

Prima di eseguire AlphaEvolve, utilizza un agente di programmazione standard per eseguire il debug sia del codebase di seed sia dell'evaluator:

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

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

  • Esegui test con input non validi: esegui l'evaluator con funzioni intenzionalmente interrotte per verificare che rilevi i problemi del compilatore, gestisca i loop infiniti in modo corretto e restituisca punteggi di penalità negativi elevati.

Evita baseline eccessivamente ottimizzate

Non passare un programma di riferimento già altamente ottimizzato come seed. Se il tuo programma iniziale è già quasi ottimale, AlphaEvolve avrà difficoltà a eseguire l'hill climbing perché lo spazio di miglioramento è molto ridotto. Inizia con una baseline ragionevole, ma non ottimizzata al massimo. In questo modo, AlphaEvolve ha spazio per esplorare e ottimizzare.

Misure di protezione per i runner lato client

I valutatori lato client devono applicare misure di protezione rigorose per impedire che candidati dannosi, ad alta intensità di risorse o non reattivi 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à di timeout: se una variante del programma candidato supera il limite di timeout, termina immediatamente il suo thread di esecuzione. Non consentire l'errore 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 rilasciare il blocco della coda del programma.

  • Filtri di sicurezza AST: esegui sempre un controllo di ispezione dell'Abstract Syntax Tree (AST) sul payload del codice sorgente in entrata prima della compilazione. Interrompi immediatamente l'esecuzione e applica una penalità per errore grave se vengono rilevate primitive di riflessione o esecuzione limitate (come eval, exec, getattr o setattr).

Ulteriori risorse

Per maggiori informazioni, consulta le seguenti risorse: