AlphaEvolve API-Referenz

Dieses Dokument dient als maßgebliche, produktionsreife API-Referenz und Systemspezifikation für die AlphaEvolve Cloud API unter den konversationellen Ebenen der Google CloudDiscovery Engine. Sie definiert die genauen verschachtelten Ressourcenhierarchien, REST- und gRPC-Endpunkte, Einschränkungen auf Feldebene, Zustandsautomaten für den Lebenszyklus, Fehlerdiagnosematrizen, Regeln für Sicherheits-Sandboxing und Integrationsworkflows, die für die Entwicklung eines vollständig automatisierten clientseitigen Controllers und einer Evaluierungsschleife erforderlich sind.

Einheitliche Lebenszyklus-Zustandsautomaten

Der AlphaEvolve-Agent koordiniert zwei unabhängige Zustandsmaschinen, um den Fortschritt der Testkampagne zu überwachen und die Bereitstellung und Ausführung einzelner Programmmutationen zu verwalten.

Lebenszyklusstatus von Tests

Ein Test steht für die gesamte Optimierungskampagne. Sie wird als persistente serverseitige Ressource verarbeitet und durchläuft die folgenden Status:

  • CREATED: Der Initialisierungsstatus. Die Ressource ist deklariert und konfiguriert, hat aber noch keine ersten Generierungen erstellt oder API-Aufrufe gesendet.

  • RUNNING: Der aktive Bewertungsstatus. Die Engine führt gleichzeitig Stichproben von übergeordneten Kandidaten durch, generiert Code-Mutationen über die LLM-Mischung und streamt Aufgaben an Evaluatoren.

  • PAUSED: Ein temporärer Haltestatus, der manuell oder durch eine automatisierte Schutz-idle_timeout ausgelöst wird. Die Codegenerierung wird beendet und vorhandene Worker pausieren die Messwertbereitstellung.

  • COMPLETED: Ein Endzustand, der angibt, dass die Suche die Zielzuweisung von max_programs erfolgreich erfüllt oder das Limit für die strukturelle Generierung erreicht hat.

  • FAILED: Ein endgültiger Fehlerstatus, der darauf hinweist, dass systemische Umgebungsprobleme wie nicht abgefangene API-Anmeldedatenausnahmen, Beschädigung des Datenspeichers oder aufeinanderfolgende Runner-Panics die Verarbeitungsausführung angehalten haben.

Programmstatus

Die Laufzeitvalidierungssequenz wird auf einzelne Kandidatenvarianten angewendet.

Jede generierte Codemutation verhält sich wie eine isolierte Programmentität, die eine Reihe von detaillierten Betriebszuständen innerhalb der Populationsdatenbank durchläuft.

  1. INITIALIZED: Der Programmeintrag wird in der Datenbank erstellt, wobei die Abstammung und die Verknüpfungen mit übergeordneten Programmen erfasst werden.

  2. GENERATING: Eine Aufgabe wird aktiv an das Backend der Language Model Mixture gesendet, um die spezifischen funktionalen Codeblöcke zu entwerfen oder zu ändern.

  3. EVALUATING: Die Code-Nutzlast wird von einem Worker-Prozess für die Bewertung gesperrt und in einer isolierten Test-Harnisch-Umgebung ausgeführt.

  4. COMPLETED: Die Ausführungswerte und beschreibenden strukturellen Informationen werden sicher in der evolutionären Datenbank gespeichert und das Programm wird dem Auswahlpool hinzugefügt.

Mechanismen für Nebenläufigkeit und Sperren

Programme werden von Worker-Schleifen mithilfe eines atomaren Sperrtoken-Mechanismus erfasst, um Race-Bedingungen oder doppelten Scoring-Overhead in verteilten Topologien zu verhindern. Der Evaluator muss das endgültige Bewertungsschema zusammen mit dem genau passenden Sperrtoken einreichen, damit die Ergebnisse erfolgreich in die Datenbank übernommen werden können.

Konfigurations- und Einstellungsschemas

Übersicht über die wichtigsten Schemakonfigurationen, Parameter und Standardwerte, die von der AlphaEvolve-Engine-Laufzeit verwendet werden.

AlphaEvolveExperimentConfig

Definiert die wichtigsten strukturellen Parameter und programmatischen Einschränkungen des evolutionären Testlaufs.

Feldname Typ Standard Einschränkungen / Wertgrenzen Technische Beschreibung
title String Erforderlich Max. 256 Zeichen Eindeutiger Anzeigename des Tests.
problemDescription String Erforderlich Maximal 5.000 Zeichen Die formale Spezifikation des Problems. Sie wird direkt in Prompt-Kontexte eingefügt, um Regeln festzulegen.
programLanguage String Erforderlich Freiformwert Zielsprache der weiterentwickelten Codebasis (z. B. "python", "cpp", "verilog", "cuda", "julia", "java").
runSettings Objekt Erforderlich Wird dem Schema RunSettings zugeordnet Taktungs- und Zeitüberschreitungsparameter.
generationSettings Objekt Optional Wird dem Schema GenerationSettings zugeordnet Modellauswahl und Kontextparameter.
evolutionSettings Objekt Optional Wird dem Schema EvolutionSettings zugeordnet Parameter für die Auswahl der Eltern und die Vielfalt.

RunSettings

Steuert die Durchsatzgeschwindigkeit, die Parallelisierungslimits und die automatischen Systemzeitüberschreitungen.

Feldname Typ Standard Einschränkungen / Wertgrenzen Technische Beschreibung
maxPrograms int32 100 Min.: 2, Max.: 100.000 Gesamtbudget für die Ausführung (zu generierende und zu bewertende Programme). Muss größer als 1 sein.
concurrency int32 1 Min.: 1, Max.: 30 Anzahl der aktiven parallelen Programmmutationen in der Warteschlange. Werte über 30 sind nicht zulässig.
maxDuration String 24 Std. (86.400 Sek.) ISO 8601-dayTimeDuration-String
Min: >0, Max: 7 Tage		 Zulässige Gesamtzeit, bevor der Test beendet wird.
idleTimeout String 5 Std. (USA/EU)
2 Std. (global)		 ISO 8601-dayTimeDuration-String
Min.: > 0
Max.: Standardwert des Standorts		 Dauer der Inaktivität vor der automatischen Umstellung auf PAUSED. Der Standardwert ist 2 Stunden in global und 5 Stunden in regionalen Standorten (us, eu). Die Dauer ist durch den Standardwert des Standorts begrenzt. Wenn Sie einen Wert über dem Standardwert des Standorts angeben (z. B. 12 Stunden in global), wird er ignoriert und der Wert beträgt 2 Stunden (ohne Fehler).

Einstellungen für die Generierung

Das Schema GenerationSettings steuert die Prompt-Zusammenstellung, Kontextfenster und Modellkonfigurationen für Mutationen:

  • context (String): Optionale, vom Nutzer bereitgestellte Referenzdokumentation, zusätzliche APIs oder Regeln. Es wird dringend empfohlen,unter 200.000 Tokens zu bleiben. Kontextgrößen von mehr als 200.000 Tokens verwässern die Aufmerksamkeit des Modells und beeinträchtigen die Qualität der Mutation.

  • includeFullProgramInPrompt (bool): Standard: false.

    • true: Der Mutations-Prompt enthält den veränderbaren EVOLVE-BLOCK und den umgebenden unveränderlichen Boilerplate-Code (sehr empfohlen für komplexe strukturelle Argumentation).

    • false: Nur der änderbare Block ist sichtbar, wodurch Token-Kontext gespart wird.

  • models (Array von Objekten): Optional. In jedem Eintrag wird ein Modell benannt und ein optionaler weight-Wert angegeben. Dieser Wert entspricht dem Anteil des Modells an den Generierungsaufrufen im Verhältnis zu den anderen Einträgen. Wenn Sie models weglassen, wird es von AlphaEvolve beim Erstellen des Tests auf das Standardmodell gesetzt. Der Standardwert ändert sich, wenn neuere Gemini-Modelle veröffentlicht werden. Unter Standardmodell ist aufgeführt, welches Modell an welchem Datum gilt. Wenn Sie das Modell selbst auswählen oder bei jeder Ausführung dasselbe Modell verwenden möchten, legen Sie models fest.

    Im folgenden Beispiel werden etwa neun von zehn Generierungsaufrufen an das erste Modell und der Rest an das zweite Modell gesendet. Gewichtungen sind Verhältnisse, sodass sie nicht zusammen 1 ergeben müssen.

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

Unterstützte Modelle

Legen Sie für models[].name einen der folgenden Werte fest. Sie können maximal zwei Modelle in einem einzelnen Test kombinieren.

Modellname Bereitstellungsregionen
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 validiert models, wenn das Experiment erstellt wird, und gibt INVALID_ARGUMENT für einen Modellnamen zurück, der nicht in dieser Tabelle enthalten oder in der von Ihnen angeforderten Region nicht verfügbar ist.

Standardmodell

In der folgenden Tabelle sind die Modelle aufgeführt, die AlphaEvolve verwendet, wenn Sie models weglassen, sortiert nach dem Erstellungsdatum des Experiments.

Test erstellt Standardmodell
Am oder nach dem 24. Oktober 2026 gemini-4-argon
29. September 2026 bis 23. Oktober 2026 gemini-3.8-flash
30. Juni 2026 bis 28. September 2026 gemini-3.5-flash
Vor dem 30. Juni 2026 gemini-2.5-flash

Um das einem Test zugewiesene Modell zu identifizieren, prüfen Sie generationSettings.models in der Testkonfiguration oder der Antwort auf die Erstellung. Da die Änderungen im Laufe des Umstellungstags wirksam werden, erhalten Tests, die an diesen Tagen erstellt werden, möglicherweise entweder das alte oder das neue Standardmodell. Tests, die vor dem 30. Juni 2026 ohne models erstellt wurden, enthalten keinen Wert für dieses Feld.

Da das Modell in jedem Test gespeichert wird, hat eine Änderung der Standardeinstellung keine Auswirkungen auf bereits vorhandene Tests. Wenn Sie ein neueres Standardmodell verwenden möchten, erstellen Sie einen neuen Test.

Evolution-Einstellungen

Das EvolutionSettings-Schema steuert das Reseeding des Inselmodells und die Wahrscheinlichkeiten für die Stichprobenerhebung von übergeordneten Elementen:

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (Gleitkommazahl): Die Wahrscheinlichkeit (0,0 bis 1,0), dass übergeordnete Programme direkt aus der aktiven Pareto-Grenze ausgewählt werden, anstatt die standardmäßige fitnessbasierte Auswahl zu verwenden. Dieser Parameter muss auf 0.0 (deaktiviert) gesetzt werden, wenn die optimierten Messwerte nur einen einzelnen skalaren Messwert zurückgeben.

Datenmodelle für Kandidatenprogramme

In diesem Abschnitt werden die Datenschemas und Darstellungen beschrieben, die zum Definieren und Organisieren von Kandidatencodestrukturen in der Populationsdatenbank verwendet werden.

AlphaEvolveProgramContent

Definiert die Dateien und die Struktur des Kandidatenprogramms.

  • files (Array von AlphaEvolveSourceFile): Eine Liste aller Dateien, die die Kandidaten-Codebasis bilden. Die Nutzlast muss mindestens eine Quelldatei enthalten. Google empfiehlt, die Gesamtzahl der Dateien pro Kandidatenprogramm auf 50 Dateien zu beschränken. Dadurch werden die Aufmerksamkeit des Modells und die Effizienz des Kontextfensters optimiert.

  • description (String): Eine automatisch generierte Zusammenfassung,in der die vom Generierungsmodell vorgeschlagenen programmatischen Änderungen beschrieben werden (maximal 1.000 Zeichen).

AlphaEvolveSourceFile

Stellt eine einzelne Quellcodedatei in der Codebasis dar.

  • path (String): Das Ziel des relativen Pfads im Arbeitsbereich (erforderlich, max. 256 Zeichen). Für jeden Quelldateieintrag muss ein Pfad angegeben werden, der nicht leer ist. Wenn Sie einen Python-Arbeitsbereich konfigurieren, muss der Einstiegspunkt der primären ausführbaren Datei genau "initial_program.py" heißen.

  • content (String): Der Rohquellcode-String, der die funktionalen Implementierungsblöcke enthält. Google empfiehlt, die kumulative Größe der Codebasis über alle Dateien hinweg unter 4.000 bis 5.000 Zeilen Code zu halten. Dies ist optimal für die Modellaufmerksamkeit und die Leistung bei der Mutationsgenerierung.

  • programLanguage (String): Das Tag für die Zuordnung des Sprachparsers. Dieser String muss explizit mit der Sprache übereinstimmen, die in der Konfiguration des übergeordneten Tests festgelegt ist.

  • description (String): Eine optionale Zusammenfassung, die die individuelle Architektur oder den Zweck der Datei beschreibt und dem LLM während der Mutationsdurchläufe zur Verfügung gestellt wird (maximal 500 Zeichen).

AlphaEvolveProgramEvaluation

Die strukturierte Nutzlast, die von Client-Runner-Instanzen nach der Laufzeitausführung an die evolutionäre Datenbank zurückgesendet wird.

  • scores (AlphaEvolveScores): Standardisierte, objektive numerische Messwerte. Best Practices zufolge sollte die Anzahl auf 3 bis 5 verschiedene Gleitkomma-Messwerte beschränkt werden. Zu viele Zieldimensionen beeinträchtigen die Leistung des Pareto-Komparators für mehrere Ziele.

  • insights (Array von AlphaEvolveEvaluationInsight): Semantische Diagnoselabels und Ausführungstraces in natürlicher Sprache, die zurückgegeben werden, um die nachfolgenden Versuche des LLM zur Mutationsgenerierung zu unterstützen (empfohlen maximal 10 Elemente).

Formulierung von Bewertungen und Aufnahmeformate

Die Maximierungsregel

AlphaEvolve funktioniert im Wesentlichen als monotoner Hill-Climbing-Algorithmus und maximiert alle numerischen Messwerte strikt. Wenn Ihre Bewertungspipeline ein Minimierungsziel verfolgt (z. B. die Minimierung der Anwendungslatenz in Millisekunden oder die Reduzierung der Arbeitsspeichernutzung), müssen Sie den Wert negieren, bevor Sie ihn an die Datenbank senden: submitted_score = -latency_ms.

Die Werte sollten idealerweise kontinuierlich sein. Boolesche oder stark diskrete Messwerte liefern kein ausreichendes Gradientensignal für eine effektive Hill-Climbing-Exploration.

Aufnahmeschema mit einem Ziel

Verwenden Sie die folgende JSON-Datei, wenn Ihr Bewertungssystem für eine einzelne skalare Zielfunktion optimiert wird.

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

Schema für die Aufnahme mehrerer Zielvorhaben

Verwenden Sie den folgenden JSON-Code, wenn Sie unabhängige Tracking-Parameter für das Multi-Objective-Tracking übergeben, um serverseitige Optimierungsroutinen für die Pareto-Grenze zu aktivieren.

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

Programmdaten abrufen und abfragen

Das AlphaEvolve-System protokolliert die Telemetrie, Ausführungsmesswerte und den vollständigen Quellcode jeder generierten Mutation. Entwickler können diesen historischen Datenspeicher über die API oder die Befehlszeile abfragen, um den Optimierungsfortschritt zu verfolgen und die leistungsstärksten Codekandidaten zu extrahieren.

Programmabruf mit der REST API

Ausgewertete Programmressourcen können mit dem Standardendpunkt ListAlphaEvolvePrograms mit Filter- und Sortierabfrageparametern aus der Datenbank abgefragt werden:

  • Zustandsfilterung: Programme abfragen, die einem bestimmten Lebenszyklusstatus entsprechen:

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

  • Messwertbasierte Sortierung: Sortierte Kandidaten basierend auf optimierten Messwerten abrufen:

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

Programmabruf über die Befehlszeile

Führen Sie den folgenden Befehl aus, um die besten abgeschlossenen Kandidaten direkt aus Ihrem Terminal abzurufen:

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

Vollständige Beispiele für die Verwendung der Befehlszeile

Mit der AlphaEvolve-Befehlszeile können Entwickler Kampagnen direkt über die Shell verwalten und überwachen:

  • Alle Experimente in einer konversationellen Sitzung auflisten:

    ae experiment list

  • Alle mutierten Kandidatenprogramme für ein bestimmtes Experiment auflisten:

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

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen Ihres Tests.

  • Rufen Sie die leistungsstärksten abgeschlossenen Codekandidaten ab:

    ae results best EXPERIMENT_NICKNAME --top 5

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen Ihres Tests.

  • So setzen Sie eine pausierte Kampagne fort:

    ae experiment resume EXPERIMENT_NICKNAME

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen Ihres Tests.

Verzeichnis der wichtigsten REST API-Endpunkt

Alle Endpunkte sind unter v1alpha der Google Cloud Discovery Engine API versioniert.

Muster für den Pfad der übergeordneten Ressource

Der tatsächliche verschachtelte übergeordnete Ressourcen-URI ist so strukturiert: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

  • AlphaEvolve ist in global, us und eu verfügbar. Wenn Sie Tests an anderen Standorten erstellen, wird FAILED_PRECONDITION zurückgegeben.
  • Assured Workloads-Projekte werden nicht unterstützt.
  • Ein Projekt ist auf 30 gleichzeitig aktive (STARTED oder RUNNING) AlphaEvolve-Experimente pro Standort beschränkt. Wenn Sie ein Experiment starten oder fortsetzen, das dieses Limit überschreitet, wird RESOURCE_EXHAUSTED zurückgegeben.

Test erstellen (POST)

  • Pfad:

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

  • Anfragetext: AlphaEvolveExperimentConfig (siehe Abschnitt 2.1)

  • Antwort: AlphaEvolveExperiment-Ressource mit der initialisierten Kampagne.

  • HTTP-Status: 200 OK

Beispiele für API-Nutzlasten

  1. Beispiel für einen Anfragetext (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. Beispiel für einen Antworttext (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
        }
      }
    }
  }
}

Test starten (POST)

  • Pfad:

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

  • Anfragetext: StartExperimentRequest

  • Warnung zur Einstellung: Das Textfeld initialProgram wurde eingestellt und wird ignoriert.

  • Antwort: GoogleLongrunningOperation (LRO).

  • HTTP-Status: 200 OK (Status wird von CREATED zu RUNNING geändert)

Beispiele für API-Nutzlasten

  1. Beispiel für einen Anfragetext

    {
  "desiredProgramsCount": 1
}

  2. Beispiel für Antworttext (200 OK – Vorgang mit langer Ausführungszeit)

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

Programme erwerben (POST)

  • Pfad:

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

  • Anfragetext: AcquireProgramsRequest

    • desiredProgramsCount (int32): Optionale Batchanzahl der abzurufenden mutierten Programme (Standardwert ist 1, wenn nicht festgelegt).

  • Antwortstatus:

    • 200 OK: Gibt eine Antwort mit gesperrten AlphaEvolveProgram-Ressourcen zurück.

    • 204 No Content: Die Warteschlange ist leer oder die Kampagne ist pausiert. Runner müssen pausieren (z. B. 15 Sekunden) und es dann noch einmal versuchen.

Beispiele für API-Nutzlasten

  1. Beispiel für einen Anfragetext

    {
  "desiredProgramsCount": 1
}

  2. Beispiel für einen Antworttext (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. Beispiel für Antworttext (204 No Content)

HTTP-Status 204 mit einem leeren Nutzlastkontext zurückgegeben.

Programmbewertungen einreichen (POST)

  • Pfad:

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

  • Anfragetext: SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (Array): Enthält die übereinstimmende lockToken, den qualifizierten Programmressourcenpfad und die Nutzlast der Bewertung (Scores und Statistiken). Die API akzeptiert genau eine Bewertungseinreichung pro Aufruf. Das Zusammenfassen mehrerer Bewertungen in einer einzelnen Anfrage wird mit INVALID_ARGUMENT abgelehnt. Wenn Sie mehrere Kandidaten bewerten, reichen Sie jedes Programm einzeln ein.

  • Antwort: SubmitProgramsEvaluationsResponse (leer).

  • HTTP-Status: 200 OK (speichert Ergebnisse, hebt aktive Sperre auf und registriert Statistiken)

Beispiele für API-Nutzlasten

  1. Beispiel für einen Anfragetext

    {
  "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. Beispiel für einen Antworttext (200 OK)

    {}

Test fortsetzen (POST)

  • Pfad:

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

  • Anfragetext: ResumeExperimentRequest

  • Antwort: GoogleLongrunningOperation (LRO).

  • HTTP-Status: 200 OK (Status wird von PAUSED zurück zu RUNNING geändert)

Beispiele für API-Nutzlasten

  1. Beispiel für einen Anfragetext

    {}

  2. Beispiel für Antworttext (200 OK – Vorgang mit langer Ausführungszeit)

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

Programme auflisten (GET)

  • Pfad:

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

  • Abfrageparameter:

    • stateFilter (String): Optional. Standard-Listenfilter, z. B. stateFilter = 'COMPLETED'.

    • orderBy (String): Optional. Messwertbasierte Sortierung, z. B. accuracy desc.

  • Antwort: ListAlphaEvolveProgramsResponse.

  • HTTP-Status: 200 OK

Beispiele für API-Nutzlasten

  1. Beispiel für eine Anfrage-URL

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

  2. Beispiel für einen Antworttext (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"
}

Diagnosecode und Referenz zur Fehlerbehebung

Matrix der API-Diagnosecodes

HTTP-Status Fehlertyp Systemursache Problemumgehung oder Maßnahme zur Aussetzung von Maßnahmen
400 INVALID_ARGUMENT
  • Fehlerhafte EVOLVE-BLOCK-START- oder EVOLVE-BLOCK-END-Markierungen (z. B. Inhalte, die sich die Zeile der Markierung teilen, verschachtelte Blöcke oder fehlende Endmarkierung).
  • Leerer evolve-Block, der nur Kommentare oder Leerzeichen ohne bearbeitbaren Code enthält.
  • maxPrograms ist auf weniger als 2 festgelegt.
  • Unbekannte Konfigurationsfelder.
  • Ungültige Modellkonfiguration (mehr als zwei Modelle, doppelte Einträge, nicht positive Gewichtungen oder Temperatur außerhalb von [0.0, 2.0]).
  • Mehrere Bewertungen in einem einzigen submitProgramsEvaluations-Aufruf senden.
  • Das Projekt ist ein Assured Workloads-Projekt.
 Achten Sie darauf, dass die Markierungen allein in ihrer Zeile stehen und mindestens eine Codezeile enthalten, die kein Kommentar ist. Legen Sie für maxPrograms mindestens 2 fest. Entfernen Sie Felder, die nicht Teil der API sind, z. B. notes, das in der Vorabversion der API vorhanden war. Reichen Sie Bewertungen einzeln ein.
403 PERMISSION_DENIED
  • Der Aufrufer hat nicht die Rolle „Discovery Engine-Bearbeiter“ (roles/discoveryengine.editor) oder „Administrator“ (roles/discoveryengine.admin). Hinweis: roles/discoveryengine.user gewährt keine AlphaEvolve-Berechtigungen und roles/discoveryengine.viewer kann keine Tests abrufen.
  • Der Aufrufer hat keine Berechtigung für die übergeordnete Sitzungsressource.
  • Es ist keine aktive Gemini Enterprise-Lizenz zugewiesen.
 Gewähren Sie roles/discoveryengine.editor oder roles/discoveryengine.admin auf Projektebene und prüfen Sie den Zugriff auf die übergeordnete Sitzung. Aktive Gemini Enterprise-Lizenzen überprüfen. Konfigurieren Sie die Standardanmeldedaten für Anwendungen:

gcloud auth application-default login --project=PROJECT_ID

Hinweis: Model Armor wird in AlphaEvolve-Konfigurationen nicht unterstützt.
400 FAILED_PRECONDITION
  • Veraltetes oder abgelaufenes Sperrtoken oder nicht übereinstimmender Programmstatus (z. B. wurde der Kandidat nach Ablauf des Leasingvertrags neu erworben oder finalisiert).
  • Das Experiment wurde an einem nicht unterstützten Standort erstellt (außerhalb von global, us oder eu).
  • Die Vertex AI API (aiplatform.googleapis.com) ist im Projekt nicht aktiviert.
 Geben Sie die genaue lockToken zurück, die von :acquirePrograms zurückgegeben wurde. Erzwingen Sie clientseitige Zeitlimits (empfohlen: 30 Minuten) und senden Sie bei Zeitüberschreitung Fehlerstrafen. Erstellen Sie den Test an einem unterstützten Standort neu. Aktivieren Sie die Vertex AI API: gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
429 RESOURCE_EXHAUSTED
  • Das Projekt hat das Limit von 30 gleichzeitig aktiven (STARTED / RUNNING) Tests pro Standort erreicht.
  • Tokenkontingent für die Backend-Modellgenerierung erschöpft.
 Limit für aktive Tests: Schließen Sie laufende Tests ab oder beenden Sie sie, bevor Sie einen neuen starten. Das Senken von concurrency in runSettings hat keine Auswirkungen auf dieses Limit. Für das Modelltokenkontingent: Verringern Sie concurrency in runSettings und implementieren Sie einen exponentiellen Backoff.
503 SERVICE_UNAVAILABLE Der Sicherheitsklassifikator für Eingaben ist nicht verfügbar oder der Backend-Dienst ist vorübergehend überlastet. Implementieren Sie auf der Clientseite eine Wiederholungsschleife mit randomisiertem exponentiellem Backoff.

Häufige Fehlermeldungen und Lösungen

In der folgenden Referenz sind häufige Fehlermeldungen der API, ihre Ursachen und Schritte zur Behebung aufgeführt.

Parsing-Fehler im ursprünglichen Programm und im EVOLVE-BLOCK

Fehlermeldung Systemursache Problemumgehung oder Maßnahme zur Aussetzung von Maßnahmen
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. Sowohl die Markierung EVOLVE-BLOCK-START als auch die Markierung EVOLVE-BLOCK-END werden in derselben Zeile angezeigt. Platzieren Sie die Start- und Endmarkierungen in separaten Zeilen.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. Code, Text oder nachgestellte Zeichen befinden sich in derselben Zeile wie eine EVOLVE-BLOCK-START- oder EVOLVE-BLOCK-END-Markierung. Achten Sie darauf, dass die Markierung allein in der Zeile steht (nur mit einem Kommentarpräfix wie # EVOLVE-BLOCK-START davor).
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. In einem bereits geöffneten Entwicklungsblock wird eine EVOLVE-BLOCK-START-Markierung angezeigt. Entfernen Sie verschachtelte Startmarkierungen. Verschachtelte evolve-Blöcke werden nicht unterstützt.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. Eine EVOLVE-BLOCK-END-Markierung wird ohne vorangestelltes EVOLVE-BLOCK-START angezeigt. Achten Sie darauf, dass jedem Endmarker ein passender Startmarker vorangestellt ist.
Parsing error: Evolve block started but not ended. Es wurde eine EVOLVE-BLOCK-START-Markierung ohne entsprechende schließende EVOLVE-BLOCK-END-Markierung gefunden. Fügen Sie eine schließende EVOLVE-BLOCK-END-Markierung hinzu.

Fehler bei Programminhalten und -struktur

Fehlermeldung Systemursache Problemumgehung oder Maßnahme zur Aussetzung von Maßnahmen
Program content must contain at least one source file. program_content.source_files ist leer. Geben Sie mindestens eine Quelldatei an.
source_files entries must have a non-empty path. Ein Quelldateieintrag hat einen leeren path-String. Geben Sie für jede Quelldatei einen gültigen relativen Pfad an.
source_files entry has empty content; path: <path> Ein Quelldateieintrag enthält einen leeren String. Fügen Sie den Dateiinhalt ein.
Program content must contain at least one EVOLVE-BLOCK-START / EVOLVE-BLOCK-END region with editable code between the markers (whitespace and comment-only regions don't count -- AlphaEvolve has nothing to mutate). Evolve-Blöcke enthalten nur Kommentare, Docstrings oder Leerzeichen, aber keinen bearbeitbaren Code. Fügen Sie mindestens eine Zeile bearbeitbaren Code (z. B. Funktionsdefinitionen oder Algorithmuslogik) in den Block ein.

Fehler bei der Konfigurations- und Modellvalidierung

Fehlermeldung Systemursache Problemumgehung oder Maßnahme zur Aussetzung von Maßnahmen
unsupported model: <model_name> Das angeforderte Modell wird für Ihr Projekt nicht unterstützt oder ist nicht aktiviert. Verwenden Sie unterstützte Modelle. Weitere Informationen finden Sie unter Generierungseinstellungen.
model '<model_name>' is not served from domain shard '<location>'. Das Modell ist am angegebenen regionalen Standort nicht verfügbar. Informationen zu unterstützten Modellen und Standorten finden Sie unter Einstellungen für die Generierung.
generation_settings.models must contain at most 2 distinct models; got <count>. In generation_settings.models wurden mehr als zwei Modellkonfigurationen angegeben. Geben Sie maximal zwei Modelle in der Mischung an.
generation_settings.models contains duplicate entry: <model_name> Der gleiche Modellname wird in generation_settings.models mehrmals verwendet. Entfernen Sie doppelte Modelleinträge.
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. Die Stichprobengewichtung des Modells ist negativ, null oder nicht endlich. Legen Sie eine positive Gewichtung fest oder entfernen Sie den Eintrag.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. Die Modelltemperatur liegt außerhalb des gültigen Bereichs [0.0, 2.0]. Passe die Temperatur auf einen Wert zwischen 0.0 und 2.0 an.
RunSettings.max_programs is required and must be greater than 1. max_programs wurde weggelassen oder auf 1 oder weniger gesetzt. Legen Sie für max_programs einen Wert von mindestens 2 fest. Ein Wert von mindestens 2 ist erforderlich, um weiterentwickelte Kandidaten zuzulassen.
RunSettings.concurrency is required and must be positive. concurrency wurde weggelassen oder auf 0 oder weniger gesetzt. Legen Sie für concurrency eine positive Ganzzahl fest (normalerweise 1–30).
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. pareto_sampling_probability liegt außerhalb von [0.0, 1.0]. Legen Sie eine Wahrscheinlichkeit zwischen 0.0 und 1.0 fest.

Projektvoraussetzungen und Fehler im Testlebenszyklus

Fehlermeldung Systemursache Problemumgehung oder Maßnahme zur Aussetzung von Maßnahmen
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> Die Vertex AI API (aiplatform.googleapis.com) ist im Projekt Google Cloud nicht aktiviert. Führen Sie gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID aus.
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. Das Projekt hat das Kontingent von 30 gleichzeitig aktiven Tests (STARTED oder RUNNING) an diesem Standort erreicht. Beenden Sie vorhandene Tests, bevor Sie einen neuen Test starten oder fortsetzen.
Cannot <action> experiment from state <current_state> Es wurde versucht, eine ungültige Statusänderung vorzunehmen (z. B. einen bereits laufenden Test zu starten oder einen neu erstellten Test fortzusetzen). Achten Sie darauf, dass Tests den Standardübergängen im Lebenszyklus folgen: 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. Ein vorheriger Start- oder Fortsetzungsvorgang wird noch ausgeführt. Warten Sie, bis die ausstehende Zustellung abgeschlossen ist, oder rufen Sie STOP auf, um ausstehende Nachrichten zu leeren.
AlphaEvolve is not available for this project. Das Projekt ist blockiert oder es handelt sich um ein nicht unterstütztes Compliance-Profil. Weitere Informationen finden Sie unter Compliance- und Sicherheitsprofil.

Fehler bei der Programmerfassung und ‑bewertung

Fehlermeldung Systemursache Problemumgehung oder Maßnahme zur Aussetzung von Maßnahmen
Exactly one evaluation submission is required. Mehrere Bewertungen wurden in einer einzigen submitProgramsEvaluations-Anfrage zusammengefasst. Senden Sie Bewertungen einzeln, eine pro API-Aufruf.
Program is required for each evaluation submission./submission.program is required. Der Ressourcenpfad program wurde in der eingereichten Bewertung nicht angegeben. Übergeben Sie den vollständigen Ressourcenpfad des Programms.
Lock token is required for each evaluation submission./submission.lock_token is required. Der während acquirePrograms zurückgegebene lock_token wurde weggelassen. Übergeben Sie den genauen lock_token-String, der beim Erwerb des Programms zurückgegeben wurde.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' Das in der Einreichung gesendete Sperrtoken stimmt nicht mit der aktiven Server-Lease überein (z. B. ist die Lease abgelaufen und ein anderer Worker hat sie erworben oder es wurde ein falsches Token angegeben). Geben Sie die genaue lockToken aus acquirePrograms zurück und senden Sie die Ergebnisse, bevor die Zeitüberschreitung des Clients erreicht wird.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> Das Programm wurde bereits ausgewertet, abgebrochen oder aus EVALUATION_IN_PROGRESS entfernt. Verwerfen Sie die veraltete Bewertung oder rufen Sie den Kandidaten noch einmal ab, falls verfügbar.
The request was rejected by a safety policy. Die eingegebene Problembeschreibung, der ursprüngliche Code oder die Bewertungsmesswerte haben Sicherheitsklassifizierungsrichtlinien ausgelöst. Bereinigen Sie Prompt-Text und Problembeschreibungen, um vertrauliche Keywords oder Spuren zu entfernen.
The input safety classifier is currently unavailable. Der Dienst zur Sicherheitsklassifizierung ist vorübergehend nicht erreichbar oder überlastet (Fail-Closed). Implementieren Sie eine Wiederholungslogik mit exponentiellem Backoff.

Beheben von „unbemerkten Abbrüchen“

Ein Sicherheitsfilter-Abfangen (stilles Verwerfen) tritt auf, wenn serverseitige Sprachmodelle mutierte Kandidaten-Prompts aufgrund sensibler Formulierungen oder Sicherheitsregelauslöser markieren und verwerfen. Der Server unterdrückt die Ausgabe, sodass die Warteschlange leere Antworten zurückgibt und Client-Runner möglicherweise unbegrenzt warten.

Workaround:

  • Kontext bereinigen: Entfernen Sie emotional aufgeladene oder sicherheitsrelevante Formulierungen aus dem problemDescription.

  • Filterstatistiken: Parsen und kürzen Sie Roh-Ausnahme-Traces oder Terminal-stderr-Logs in der insights-Nutzlast, um zu verhindern, dass unsichere Systeminhalte wiedergegeben werden, die nachgelagerte Filter auslösen.

  • Datasets lokalisieren: Platzieren Sie keine Trainingsdatensätze oder großen Textkorpora in Prompts. Laden Sie sie während der Ausführung der Bewertungsschleife lokal in der Clientumgebung.

Best Practices für die clientseitige Bewertung

Der Engpass „Spaghetticode“

Eine suboptimale Quellformatierung beeinträchtigt die Optimierungsqualität: „Spaghetticode == unübersichtlicher Suchbereich“. Bevor Sie EVOLVE-BLOCK-Markierungen platzieren:

  • Refaktorieren Sie Codeblöcke, damit Variablen und Funktionssignaturen eindeutig benannt sind.

  • Fügen Sie aussagekräftige, prägnante Docstrings hinzu, die erklären, was die einzelnen Funktionen oder Variablen tun und warum. Docstrings müssen sich neben dem eigentlichen funktionalen Code befinden. Wenn Sie nur einen Docstring oder Kommentare in einem EVOLVE-BLOCK platzieren, wird dies als leerer Block abgelehnt.

  • Achten Sie darauf, dass die Kommentarmarkierungen EVOLVE-BLOCK-START und EVOLVE-BLOCK-END allein in ihren jeweiligen Zeilen stehen, mit Ausnahme von vorangestellten Leerzeichen und Kommentarpräfixen (z. B. # oder //).

  • Achten Sie darauf, dass alle externen, unveränderlichen Abhängigkeiten (z. B. das Importieren von Hilfsmodulen oder das Laden statischer Daten) außerhalb von EVOLVE-BLOCK liegen.

Zuweisung des Kontextfensters

Wenn Sie die Kreativität der Mutation maximieren möchten, begrenzen Sie die an die API gesendete Code-Nutzlast. Der gesamte Programmkontext sollte unter 150.000 bis 200.000 Tokens bleiben. Große Blöcke mit statischem, unveränderlichem Boilerplate-Code beanspruchen die Aufmerksamkeit des Modells und beeinträchtigen die Leistung. Verschieben Sie Hilfsskripts, Pipelines für die Datenaufnahme und umfangreiche Validierungsbibliotheken vollständig in den clientseitigen Evaluator.

Zuerst das erste Programm vorbereiten

Bevor Sie AlphaEvolve ausführen, sollten Sie einen Standard-Coding-Agenten verwenden, um sowohl Ihre Seed-Codebasis als auch Ihren Evaluator zu debuggen:

  • Seed vorbereiten: Beheben Sie offensichtliche Syntaxfehler, Kompilierungsprobleme und Grenzfälle.

  • Ausgangswert prüfen: Prüfen Sie, ob der Ausgangswert angemessen ist und ob der Evaluator vollständig deterministisch ist (gleicher Code + gleiche Eingabe = gleicher Wert).

  • Mit ungültigen Eingaben testen: Führen Sie den Evaluator mit absichtlich fehlerhaften Funktionen aus, um zu prüfen, ob er Compilerprobleme erkennt, Endlosschleifen ordnungsgemäß verarbeitet und hohe negative Strafwerte zurückgibt.

Überoptimierte Baselines vermeiden

Übergeben Sie kein bereits hochgradig optimiertes Baseline-Programm als Seed. Wenn Ihr ursprüngliches Programm bereits nahezu optimal ist, wird es AlphaEvolve schwerfallen, die Leistung zu verbessern, da es nur wenig Raum für Optimierungen gibt. Beginnen Sie mit einer angemessenen, aber nicht maximal optimierten Baseline. So hat AlphaEvolve die Möglichkeit, verschiedene Ansätze zu erkunden und zu optimieren.

Schutzmaßnahmen für clientseitige Runner

Clientseitige Evaluatoren müssen strenge Sicherheitsmaßnahmen erzwingen, um zu verhindern, dass bösartige, ressourcenintensive oder nicht reagierende Kandidaten parallele Worker blockieren:

  • Strikte Zeitlimits: Erzwingen Sie ein striktes Zeitlimit von 30 Minuten (oder weniger, je nach Struktur des Suchbereichs).

  • Zeitüberschreitungsstrafe: Wenn eine Kandidatenprogrammvariante das Zeitlimit überschreitet, wird ihr Ausführungsthread sofort beendet. Lassen Sie den Kandidatenprozess nicht scheitern. Stattdessen sollten Sie sofort eine Strafe für einen schwerwiegenden Fehler (z. B. -100000.0) zusammen mit einem beschreibenden Debug-Insight an den Server senden, um die Warteschlangensperre des Programms aufzuheben.

  • AST-Sicherheitsfilter: Führen Sie vor der Kompilierung immer eine AST-Prüfung (Abstract Syntax Tree) für die eingehende Quellcode-Nutzlast durch. Die Ausführung wird sofort abgebrochen und eine Strafe für einen schwerwiegenden Fehler verhängt, wenn eingeschränkte Reflexions- oder Ausführungsprimitive (wie eval, exec, getattr oder setattr) erkannt werden.

Weitere Ressourcen

Weitere Informationen finden Sie in den folgenden Ressourcen: