AlphaEvolve API-Referenz

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

Einheitliche Statusautomaten für den Lebenszyklus

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

Lebenszyklusstatus von Tests

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

  • CREATED:Der Initialisierungsstatus. Die Ressource wurde deklariert und konfiguriert, aber es wurden noch keine ersten Generationen 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 die Evaluatoren.

  • PAUSED:Ein vorübergehender Haltestatus, der manuell oder durch eine automatische Schutzmaßnahme (idle_timeout) ausgelöst wird. Die Codegenerierung wird beendet und vorhandene Worker pausieren die Messwertbereitstellung.

  • COMPLETED:Ein Endstatus, der angibt, dass die Suche ihr max_programs-Ziel erreicht oder das strukturelle Generierungslimit überschritten hat.

  • FAILED:Ein schwerwiegender Fehlerstatus, der angibt, dass die Verarbeitung aufgrund von systemischen Umgebungsproblemen beendet wurde, z. B. nicht abgefangene Ausnahmen für API-Anmeldedaten, Beschädigung des Datenspeichers oder aufeinanderfolgende Runner-Panik.

Programmstatus

Die Laufzeitvalidierungssequenz wird auf einzelne Kandidatenvarianten angewendet.

Jede generierte Code-Mutation verhält sich wie eine isolierte Programmeinheit, die in der Bevölkerungsdatenbank eine Reihe von detaillierten Betriebsstatus durchläuft.

  1. INITIALIZED:Der Programmeintrag wird in der Datenbank erstellt und seine Herkunft und Verknüpfungen zum übergeordneten Programm werden nachverfolgt.

  2. GENERATING:Eine Aufgabe wird aktiv an das Backend des Sprachmodell-Mix weitergeleitet, um die spezifischen funktionalen Codeblöcke zu entwerfen oder zu ändern.

  3. EVALUATING:Die Code-Nutzlast wird von einem Evaluierungs-Worker-Prozess gesperrt und in einer isolierten Testumgebung ausgeführt.

  4. COMPLETED:Die Ausführungsergebnisse und beschreibenden strukturellen Erkenntnisse werden sicher in der Evolutionsdatenbank gespeichert und das Programm wird dem Auswahlpool hinzugefügt.

Gleichzeitigkeit und Sperrmechanismen

Programme werden von Worker-Schleifen mithilfe eines Mechanismus für atomare Sperr-Tokens abgerufen, um Race-Bedingungen oder doppelten Scoring-Overhead in verteilten Topologien zu verhindern. Der Prüfer muss das endgültige Bewertungsschema zusammen mit dem genauen Abgleichsperrtoken einreichen, um die Ergebnisse erfolgreich in die Datenbank zu übertragen.

Konfigurations- und Einstellungsschemas

Übersicht über die wichtigsten Schemakonfigurationen, Parameter und Standardeinstellungen, 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 Max. 5.000 Zeichen Die formale Spezifikation des Problems. Sie werden direkt in Prompt-Kontexte eingefügt, um Regeln festzulegen.
programmingLanguage String Erforderlich Wert im freien Format Zielsprache des weiterentwickelten Quellcodes (z. B. "python", "cpp", "verilog", "cuda", "julia", "java").
runSettings Objekt Erforderlich Entspricht dem RunSettings-Schema Parameter für Taktung und Zeitüberschreitung
generationSettings Objekt Erforderlich Entspricht dem GenerationSettings-Schema Modellauswahl und Kontextparameter.
evolutionSettings Objekt Erforderlich Entspricht dem EvolutionSettings-Schema Parameter für die Auswahl der Eltern und die Vielfalt.
notes String Erforderlich Max. 1.000 Zeichen Optionale Anmerkungen für die Ausführungsdokumentation.

RunSettings

Steuert die Durchsatzsteuerung, Parallelisierungsgrenzen und automatischen Systemzeitüberschreitungen.

Feldname Typ Standard Einschränkungen / Wertgrenzen Technische Beschreibung
maxPrograms int32 100 Min.: 1, Max.: 100.000 Gesamtbudget für die Ausführung (Programme zum Generieren und Bewerten).
concurrency int32 1 Min.: 1, Max.: 30 Anzahl der parallelen Programmänderungen, die in der Warteschlange aktiv sind. Werte über 30 sind nicht zulässig.
maxDuration String null ISO 8601-String für die Dauer (Tag und Uhrzeit)
Min.: >=0, Max.: 7 Tage		 Die insgesamt zulässige Wanduhrzeit, bevor der Test beendet wird.
idleTimeout String null ISO 8601-String für die Tageszeitdauer
Min.: >=0, Max.: 24 Stunden		 Dauer der Inaktivität vor der automatischen Umstellung auf „PAUSED“

Einstellungen für die Generierung

Das GenerationSettings-Schema 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 mit mehr als 200.000 Tokens schwächen die Aufmerksamkeit des Modells und beeinträchtigen die Qualität der Mutationen.

  • includeFullProgramInPrompt (bool): Standardwert false.

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

    • false: Nur der veränderbare Block ist sichtbar, wodurch der Tokenkontext gespeichert wird.

Einstellungen für die Weiterentwicklung

Das EvolutionSettings-Schema steuert die Wahrscheinlichkeiten für das erneute Seeding von Inselmodellen und das Sampling von übergeordneten Elementen:

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (Gleitkommazahl): Die Wahrscheinlichkeit (0,0 bis 1,0), übergeordnete Programme direkt aus der aktiven Pareto-Grenze zu ziehen, anstatt die standardmäßige fitnessbasierte Auswahl zu verwenden. Dieser Parameter muss auf 0.0 (deaktiviert) festgelegt werden, wenn für die optimierten Messwerte nur ein einzelner skalierter Messwert zurückgegeben wird.

Kandidatenmodelle für Programmdaten

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

AlphaEvolveProgramContent

Definiert die Dateien und die strukturelle Zusammensetzung des Kandidatenprogramms.

  • files (Array von AlphaEvolveSourceFile): Eine Liste aller Dateien, aus denen die Kandidaten-Codebasis besteht. Diese Sammlung ist auf maximal 50 Dateien pro Kandidatenprogramm begrenzt.

  • description (string): Eine automatisch generierte Zusammenfassung der programmatischen Änderungen,die vom Generierungsmodell vorgeschlagen werden (maximal 1.000 Zeichen).

AlphaEvolveSourceFile

Stellt eine einzelne Quellcodedatei in der Codebasis dar.

  • path (String): Das Ziel des arbeitsbereichsbezogenen Pfads (max. 256 Zeichen). Wenn Sie einen Python-Arbeitsbereich konfigurieren, muss der primäre ausführbare Dateieinstiegspunkt genau "initial_program.py" heißen.

  • content (String): Der Rohquellcode-String, der die funktionalen Implementierungsblöcke umfasst. Die kumulative Gesamtgröße des Quellcodes aller Dateien darf 4.000 bis 5.000 Zeilen Code nicht überschreiten.

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

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

AlphaEvolveProgramEvaluation

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

  • scores (AlphaEvolveScores): Standardisierte, objektive numerische Messwerte. Best Practices empfehlen, dies auf 3 bis 5 unterschiedliche Gleitkomma-Messwerte zu beschränken. Zu viele Zieldimensionen beeinträchtigen die Leistung des Pareto-Vergleichs mit mehreren Zielvorhaben.

  • insights (Array von AlphaEvolveEvaluationInsight): Semantische Diagnoselabels und Ausführungstraces in natürlicher Sprache, die zurückgegeben werden, um die nachfolgenden Versuche des LLM zur Generierung von Mutationen zu unterstützen (empfohlenes Maximum von 10 Elementen).

Formulierung von Scores und Aufnahmeformate

Maximierungsregel

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

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

Aufnahmeschema für ein einzelnes Zielvorhaben

Verwenden Sie den folgenden JSON-Code, wenn Ihr Evaluierungs-Harness für eine einzelne skalare Zielfunktion optimiert wird.

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

Aufnahmeschema für mehrere Zielvorhaben

Verwenden Sie das folgende JSON, wenn Sie unabhängige Parameter für die Multi-Objective-Analyse übergeben, um serverseitige Pareto-Grenzoptimierungsroutinen 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ührungsstatistiken und den vollständigen Quellcode jeder generierten Mutation. So können Entwickler diesen Verlaufsdatenspeicher über die API oder CLI abfragen, um den Optimierungsfortschritt zu verfolgen und die leistungsstärksten Codekandidaten zu extrahieren.

Programmabruf über die REST API

Bewertete Programmressourcen können über den Standardendpunkt ListAlphaEvolvePrograms mit Filter- und Sortierparametern aus der Datenbank abgerufen werden:

  • Nach Status filtern: Programme abfragen, die einem bestimmten Lebenszyklusstatus entsprechen:

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

  • Messwertbasierte Sortierung: Sortierte Kandidaten anhand optimierter Messwerte abrufen:

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

Programmabruf über die Befehlszeile

Wenn Sie die besten abgeschlossenen Kandidaten direkt über Ihr Terminal abrufen möchten, führen Sie den folgenden Befehl aus:

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

Vollständige Beispiele für die CLI-Nutzung

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

  • Alle Tests in einer Unterhaltungssitzung auflisten:

    ae experiment list

  • Alle mutierten Kandidatenprogramme für einen bestimmten Test auflisten:

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

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen des Tests.

  • Die leistungsstärksten Kandidaten für abgeschlossenen Code abrufen:

    ae results best EXPERIMENT_NICKNAME --top 5

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen des Tests.

  • So setzen Sie eine pausierte Kampagne fort:

    ae experiment resume EXPERIMENT_NICKNAME

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen des Tests.

Verzeichnis der Core REST API-Endpunkt

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

Muster für den Pfad der übergeordneten Ressource

Der URI der echten geschachtelten übergeordneten Ressource ist so aufgebaut: projects/{project}/locations/{location}/collections/{collection}/ engines/{engine}/sessions/{session}

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",
    "notes": "Exploring convergence with Gemini 3.5 Flash.",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.5-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

  2. Beispiel für 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",
    "notes": "Exploring convergence with Gemini 3.5 Flash.",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.5-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

Test starten (POST)

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

  • Anfragetext: StartExperimentRequest

  • Hinweis zur Einstellung:Das Feld „body“ initialProgram wurde eingestellt und wird ignoriert.

  • Antwort:GoogleLongrunningOperation (LRO).

  • HTTP-Status:200 OK (Übergang vom Status CREATED zum Status RUNNING)

Beispiele für API-Nutzlasten

  1. Beispiel für 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 abrufen (POST)

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

  • Anfragetext: AcquireProgramsRequest

    • desiredProgramsCount (int32): Optionale Batchanzahl der abzurufenden geänderten 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 beispielsweise 15 Sekunden warten und es dann noch einmal versuchen.

Beispiele für API-Nutzlasten

  1. Beispiel für Anfragetext

    {
  "desiredProgramsCount": 1
}

  2. Beispiel für 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 wurde mit einem leeren Nutzlastkontext zurückgegeben.

Programm-Bewertungen einreichen (POST)

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

  • Anfragetext: SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (Array): Enthält übereinstimmende lockToken, den qualifizierten Pfad zur Programmressource und die Nutzlast für die Auswertung (Ergebnisse und Statistiken).

  • Antwort:SubmitProgramsEvaluationsResponse (leer).

  • HTTP-Status:200 OK (Speichert Ergebnisse, gibt die aktive Sperre frei und registriert Statistiken)

Beispiele für API-Nutzlasten

  1. Beispiel für 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 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 (Übergang vom Status PAUSED zurück zu RUNNING)

Beispiele für API-Nutzlasten

  1. Beispiel für 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 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 Aktion zur Risikominderung
400 INVALID_ARGUMENT Es fehlen die Kommentar-Tags # EVOLVE-BLOCK-START / # EVOLVE-BLOCK-END, die JSON-Schema-Syntax ist ungültig oder die Datei- oder Zeilenlimits wurden überschritten. Prüfen Sie, ob Blockkommentare mit gültiger Zielsprachensyntax in Funktionskörpern platziert sind. Prüfen Sie, ob die Dateianzahl und die LOC-Grenzwerte eingehalten werden.
403 PERMISSION_DENIED Das Nutzerkonto oder Dienstkonto hat nicht die Rolle „Discovery Engine-Nutzer“ oder eine zugewiesene Gemini Enterprise-Lizenz. Aktive Gemini Enterprise-Lizenzen prüfen. Prüfen Sie, ob die Standardanmeldedaten für Anwendungen sowohl für den Nutzer als auch für das Projekt richtig konfiguriert sind. Führen Sie dazu folgenden Befehl aus:

gcloud auth application-default login --project=<<PROJECT_ID>>

Hinweis:Model Armor wird in AlphaEvolve-Konfigurationen nicht unterstützt.
408 LOCK_TIMEOUT Die Ausführungsdauer des Client-Runners wurde überschritten. Die Programmsperre für die Warteschlange ist abgelaufen. Strenge clientseitige Zeitüberschreitungen von 30 Minuten erzwingen. Wenn das Limit überschritten wird, müssen Sie sofort Fehlerstrafen einreichen, um die Sperre der Warteschlange aufzuheben.
429 RESOURCE_EXHAUSTED Die Limits für die aktive gleichzeitige Ausführung oder die Modellkontingente wurden überschritten. Implementieren Sie den clientseitigen exponentiellen Backoff und konfigurieren Sie konservative Einstellungen für die Parallelität in RunSettings.
503 SERVICE_UNAVAILABLE Der Backend-Dienst ist überlastet oder wird gewartet. Implementieren Sie auf der Clientseite eine Wiederholungsschleife mit randomisiertem exponentiellen Backoff.

„Silent Drops“ beheben

Ein Sicherheitsfilter-Intercept (stiller Drop) tritt auf, wenn serverseitige Sprachmodelle mutierte Kandidaten-Prompts aufgrund sensibler Formulierungen oder Auslöser von Sicherheitsregeln kennzeichnen und verwerfen. Der Server unterdrückt die Ausgabe, sodass die Warteschlange leere Antworten zurückgibt und Client-Runner möglicherweise unbegrenzt warten.

Behebung des Workarounds:

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

  • Statistiken filtern:Rohausnahmetraces oder Terminal-stderr-Logs in der insights-Nutzlast parsen und kürzen, um zu verhindern, dass unsichere Systeminhalte wiedergegeben werden, die Downstream-Filter auslösen.

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

Best Practices für die clientseitige Auswertung

Der Engpass „Spaghetti-Code“

Eine suboptimale Quellformatierung beeinträchtigt die Optimierungsqualität: „Spaghetticode == Rauschen im Suchraum“. Bevor Sie EVOLVE-BLOCK-Markierungen platzieren:

  • Codeblöcke so umgestalten, dass Variablen und Funktionssignaturen eindeutig benannt sind.

  • Fügen Sie aussagekräftige, prägnante Docstrings hinzu, die erklären, was jede Funktion oder Variable tut und warum.

  • 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 von Kontextfenstern

Um die Kreativität der Mutationen zu maximieren, sollten Sie die an die API gesendete Code-Nutzlast begrenzen. Der gesamte Programmkontext sollte zwischen 150.000 und 200.000 Tokens liegen. Große Blöcke mit statischem, unveränderlichem Boilerplate-Text beanspruchen die Aufmerksamkeit des Modells und beeinträchtigen die Leistung. Verschieben Sie Hilfsskripts, Pipelines für die Datenerfassung und umfangreiche Validierungsbibliotheken vollständig in den clientseitigen Evaluator.

Zuerst das ursprüngliche Programm vorbereiten

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

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

  • Ausgangspunkt überprüfen:Prüfen Sie, ob der Ausgangspunkt angemessen ist und ob der Evaluator vollständig deterministisch ist (derselbe Code + dieselbe Eingabe = derselbe Wert).

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

Überoptimierte Baselines vermeiden

Übergeben Sie kein bereits stark optimiertes Baseline-Programm als Seed. Wenn Ihr ursprüngliches Programm bereits nahezu optimal ist, kann AlphaEvolve nur schwer eine Steigerung erzielen, da es nur sehr wenig Spielraum für Verbesserungen gibt. Beginnen Sie mit einer angemessenen, aber nicht maximal optimierten Baseline. So hat AlphaEvolve mehr Spielraum für die Suche und Optimierung.

Clientseitige Runner-Sicherheitsmaßnahmen

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

  • Strenge Zeitüberschreitungen:Erzwingen Sie eine strenge Ausführungszeit von 30 Minuten (oder weniger, je nach Struktur des Suchbereichs).

  • Einreichung mit Zeitüberschreitung: Wenn eine Kandidatenprogrammvariante das Zeitlimit überschreitet, beenden Sie den Ausführungsthread sofort. Der Kandidatenprozess darf nicht fehlschlagen. Kompiliere und sende stattdessen sofort einen schweren Fehler-Penalty-Score (z. B. -100000.0) zusammen mit einer aussagekräftigen Debug-Information zurück an den Server, 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-Payload durch. Die Ausführung muss sofort abgebrochen und eine schwere Fehlerstrafe verhängt werden, wenn eingeschränkte Reflexions- oder Ausführungsprimitive (z. B. eval, exec, getattr oder setattr) erkannt werden.

Weitere Ressourcen

Weitere Informationen finden Sie in den folgenden Ressourcen: