Erste Schritte mit AlphaEvolve in Google Cloud

1. Einführung

In diesem Codelab führen Sie Ihre ersten beiden AlphaEvolve-Tests in Google Cloud aus. AlphaEvolve ist das KI-gestützte Framework für die evolutionäre Programmierung von Google DeepMind. Es verwendet Gemini, um Code zu schreiben und zu verbessern, der anhand einer von Ihnen definierten Messgröße bewertet wird. Sie beginnen mit dem Packen von Kreisen – einem kleinen geometrischen Problem, bei dem Sie buchstäblich beobachten können, wie sich das Ergebnis verbessert – und wiederholen das dann mit einem schwierigeren Problem des Handlungsreisenden, damit das Muster hängen bleibt.

Bei beiden Tests wird die lokale Auswertung verwendet. Der Kandidatencode wird auf Ihrem eigenen Computer ausgeführt. Es sind also keine GPU und kein Cluster zu verwalten. Die einzige Cloud-Nutzung ist die AlphaEvolve API, die Kandidaten generiert.

Aufgaben

• AlphaEvolve-Test für Ihr Google Cloud-Projekt konfigurieren
• Führen Sie eine evolutionäre Suche durch, die einen Circle-Packing-Algorithmus lokal verbessert.
• Bewertung, Ranking und Visualisierung des besten weiterentwickelten Programms ansehen
• Wiederholen Sie die Schleife für das Problem des Handlungsreisenden, um das Muster zu verallgemeinern.
• Suchbudget anpassen (Kandidaten, Parallelität, Modell)

Voraussetzungen

• Ein Webbrowser wie Chrome
• Ein Google Cloud-Projekt mit aktivierter Abrechnung
• Python 3.9 oder höher und uv
• Grundkenntnisse in Python und der Befehlszeile

Dieses Codelab richtet sich an KI-/ML-Engineers und Entwickler aller Erfahrungsstufen. Vorkenntnisse im Bereich der evolutionären Berechnung sind nicht erforderlich.

Geschätzte Dauer: 45–60 Minuten.

Kosten: In diesem Codelab wird die lokale Auswertung verwendet (keine GPU, kein GKE). Die einzige Gebühr fällt für die Nutzung der AlphaEvolve API zum Generieren von Kandidaten an.

Getestet mit: AlphaEvolve Cloud-Clientbibliothek v0.1.0, Python 3.9+, für die Beispiele circle_packing und tsp.

2. Hinweis

Projekt auswählen und API aktivieren

1. Wählen Sie in der Google Cloud Console ein Projekt aus oder erstellen Sie eines, für das die Abrechnung aktiviert ist. Legen Sie es dann in Ihrem Terminal fest:

gcloud config set project <YOUR_PROJECT_ID>

2. Aktivieren Sie die Discovery Engine API, die AlphaEvolve unterstützt:

gcloud services enable discoveryengine.googleapis.com

Gemini Enterprise-App-ID finden

AlphaEvolve wird über Gemini Enterprise bereitgestellt. Die zugrunde liegende REST-Oberfläche ist die Discovery Engine API. Für die Einstellung GE_APP_ID benötigen Sie die ID Ihrer App, nicht den Anzeigenamen.

1. Öffnen Sie die Seite Gemini Enterprise-Apps für Ihr Projekt.
2. Klicken Sie auf Ihre App und kopieren Sie das Feld ID (z. B. gemini-enterprise-1234567890_1234567890123).

Halten Sie diese ID bereit, da Sie sie gleich in .env einfügen müssen. Lassen Sie ASSISTANT=default_assistant unverändert, es sei denn, Sie haben einen benutzerdefinierten Assistenten bereitgestellt.

Authentifizieren, klonen und installieren

1. Authentifizieren Sie sich für die Standardanmeldedaten für Anwendungen:

gcloud auth application-default login

2. Klonen Sie das Beispiel-Repository und öffnen Sie es. Sie führen alle Befehle über dieses Repository-Stammverzeichnis aus:

git clone https://github.com/Google-Cloud-AI/alphaevolve-on-googlecloud.git
cd alphaevolve-on-googlecloud

3. Erstellen Sie eine virtuelle Umgebung und installieren Sie die AlphaEvolve-Clientbibliothek darin:

uv venv
uv pip install -e ".[dev]"

Mit uv venv wird ein .venv im Repository erstellt. Mit uv pip install -e ".[dev]" wird das Paket alpha_evolve (bearbeitbar) sowie Testtools installiert. Sie starten Tests mit uv run, wobei diese Umgebung automatisch verwendet wird.

3. AlphaEvolve-Schleife

Bevor Sie etwas ausführen, sollten Sie sich mit den drei Komponenten vertraut machen, die AlphaEvolve benötigt. Dieses mentale Modell wird für jeden Test wiederverwendet.

Das Seed-Programm und der EVOLVE-BLOCK

AlphaEvolve schreibt den Code nur zwischen zwei Markierungen neu. Alles andere in der Datei ist festes Gerüst, das nicht geändert werden kann. Öffnen Sie examples/circle_packing/src/program.py. Der Seed ist eine einfache konzentrische Ringpackung:

# EVOLVE-BLOCK-START
"""Constructor-based circle packing for n=26 circles"""
import numpy as np


def construct_packing(n, random_seed: int):
    """Construct an arrangement of 26 circles in a unit square.

    The goal is to maximize the sum of their radii.
    Returns (centers, radii, sum_of_radii).
    """
    rng = np.random.default_rng(random_seed)
    centers = np.zeros((n, 2))

    # A simple starting pattern — evolution will improve this.
    centers[0] = [0.5, 0.5]                      # one circle in the center
    for i in range(8):                           # 8 in an inner ring
        angle = 2 * np.pi * i / 8
        centers[i + 1] = [0.5 + 0.3 * np.cos(angle), 0.5 + 0.3 * np.sin(angle)]
    for i in range(16):                          # 16 in an outer ring
        angle = 2 * np.pi * i / 16 * rng.uniform(0.9, 1.1)
        centers[i + 9] = [0.5 + 0.7 * np.cos(angle), 0.5 + 0.7 * np.sin(angle)]

    centers = np.clip(centers, 0.01, 0.99)       # keep everything in the square
    radii = compute_max_radii(centers, random_seed)
    return centers, radii, np.sum(radii)


def compute_max_radii(centers, random_seed: int):
    """Grow each circle to touch its nearest border or neighbor (no overlaps)."""
    # ... see src/program.py for the full helper ...
# EVOLVE-BLOCK-END

Alles außerhalb von EVOLVE-BLOCK-START / EVOLVE-BLOCK-END, einschließlich der evaluate()-Funktion und der Überschneidungsprüfungen, bleibt unverändert. Genau das ist der Trick: Gemini kann beliebige Verpackungsalgorithmen vorschlagen, aber nicht ändern, wie ein Kandidat bewertet wird.

Der Evaluator und die Punktzahl

examples/circle_packing/src/evaluate.py führt jeden Kandidaten in einer Sandbox aus und gibt eine Punktzahl zurück. Für die Kreispackung ist der Messwert sum_of_radii und ein höherer Wert ist besser:

CIRCLE_PACKING_EVALUATION_METRIC = "sum_of_radii"
CIRCLE_PACKING_EVALUATION_INPUTS = {"n": 26}

Wenn ein Kandidat gegen eine Regel verstößt – Kreise überlappen sich oder verlassen das Quadrat –, gibt der Evaluator -inf zurück, zusammen mit einer Erkenntnis, in der erklärt wird, was falsch gelaufen ist. Diese Erkenntnisse werden an Gemini zurückgegeben, damit die nächste Generation denselben Fehler vermeidet.

So sieht jedes AlphaEvolve-Problem aus: Code, den Sie in einem EVOLVE-BLOCK ausdrücken können, eine automatisierbare Auswertung und ein einzelner Skalarwert, der maximiert werden soll.

4. Ersten Test ausführen

Test konfigurieren

Erstellen Sie im Stammverzeichnis des Repositorys Ihre .env aus der Vorlage für die Kreispackung:

cp examples/circle_packing/example.env .env

Öffnen Sie .env und legen Sie nur Ihre Projekt- und App-ID fest. Für alles andere gibt es funktionierende Standardeinstellungen für den ersten Lauf:

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

Mit den Standardeinstellungen werden Kandidaten mit einer Mischung aus Gemini-Modellen (MODEL_1=gemini-3.5-flash mit Gewichtung 0.7, MODEL_2=gemini-3.1-pro-preview mit 0.3) generiert und die Suche wird bei MAX_PROGRAMS_EVALUATED=10 mit CONCURRENCY=4 begrenzt – genug, um die Schleife schnell zu durchlaufen.

Entwicklung starten

Führen Sie den Test über das Stammverzeichnis des Repositorys aus:

uv run python -m examples.circle_packing.src.run_evolution

Dadurch wird das Ausgangsprogramm hochgeladen, die Suche gestartet und der lokale Kontrollzyklus ausgeführt, bis 10 Kandidaten bewertet wurden. Da Sie das Modul direkt aufrufen (ohne Wrapper), können Sie genau sehen, was ausgeführt wird, und die Datei bearbeiten, um zu experimentieren.

Die Ausgabe sollte etwa so aussehen:

INFO:alpha_evolve.experiment:Creating a new AlphaEvolve experiment
INFO:alpha_evolve.controller:Evolution loop started: 4 sampler(s), 32 evaluator(s), target=10 programs
INFO:alpha_evolve.controller:Waiting for the backend to generate candidates... (generated=0, evaluated=0/10, idle=10s)
INFO:alpha_evolve.workers:Candidate 1060655338894100 evaluated → sum_of_radii=0.8114
INFO:alpha_evolve.controller:Progress: generated=2, evaluated=1/10, queued=0
...
INFO:alpha_evolve.controller:Stopping criteria met (10/10 programs evaluated).

Die ersten Kandidaten erreichen in der Regel einen Wert zwischen 0,8 und 1,0. Die Suche wird dann immer besser. Wenn die Schleife abgeschlossen ist, werden die gerankten Programme ausgegeben und die besten Packungen mit matplotlib gerendert.

Hinweis:Fehlerbehebung: PERMISSION_DENIED oder 403 bedeutet in der Regel, dass die Discovery Engine API für das Projekt nicht aktiviert ist. Prüfen Sie den Schritt „Vorbereitung“ noch einmal. Wenn ein Lauf sofort mit „Failed to create experiment“ (Experiment konnte nicht erstellt werden) endet, sind die Anmeldedaten oder GE_APP_ID in .env falsch.

5. Ergebnisse lesen

Im Lauf werden die Top-Programme nach sum_of_radii sortiert ausgegeben (je höher, desto besser). Achten Sie auf Folgendes:

• Der Wert ist gestiegen. Die beste weiterentwickelte sum_of_radii sollte das konzentrische Ringlayout des Ausgangsbilds übertreffen. Gemini stellt in der Regel fest, dass Kreise in der Nähe der Ecken und Ränder größer werden können, und gleicht das Innere neu aus.
• Ungültige Kandidaten werden übersprungen. Programme, die sich überschneidende oder außerhalb des zulässigen Bereichs liegende Kreise erzeugt haben, wurden mit -inf bewertet und in der Rangfolge übersprungen. Das ist kein Fehler, sondern das Ergebnis der Constraint-Rückmeldung.

Es ist normal und gut, wenn zu Beginn des Laufs einige Kandidaten mit niedriger Punktzahl oder übersprungene Kandidaten angezeigt werden. Das bedeutet, dass Gemini verschiedene Möglichkeiten ausprobiert und die Erkenntnisse aus den Fehlern für spätere Generationen genutzt werden.

Sie haben jetzt den gesamten Zyklus durchlaufen: Seed –> Generieren –> Bewerten –> Bewerten –> Wiederholen. Alles andere in AlphaEvolve ist eine Variante davon, wo die Auswertung ausgeführt wird.

6. Echte Suche weiterentwickeln: TSP

Die Kreispakete konvergieren schnell. Um zu sehen, wie die Suche bei einem komplexeren Problem funktioniert, können Sie eine Heuristik für das Problem des Handlungsreisenden entwickeln. Das Muster ist identisch. Nur der Seed und der Messwert ändern sich. Im TSP-Beispiel werden Ihre .env (Projekt, Budget und Parallelität) wiederverwendet.

1. Erhöhen Sie das Budget in .env, damit die längere Suche optimiert werden kann:

# in .env — raise the generation cap and the evaluation target together
MAX_PROGRAMS_GENERATED=20
MAX_PROGRAMS_EVALUATED=20

2. Führen Sie den Befehl über das Stammverzeichnis des Repositorys aus:

uv run python -m examples.tsp.src.run_evolution

Der Ausgangspunkt ist eine Nearest-Neighbor-Tour über 50 Städte. Der Messwert ist neg_tour_length (negative durchschnittliche Tourlänge über 5 festgelegte Instanzen, also je höher, desto besser). Öffnen Sie examples/tsp/src/program.py. Beachten Sie, dass sich nur construct_tour(distances, n) im EVOLVE-BLOCK befindet.

Die beiden Probleme sind dasselbe Muster mit unterschiedlichen Teilen:

Problem	Sprache	Bewertung	Messwert (je höher, desto besser)	Was sich weiterentwickelt
circle_packing	Python	Ortszeit exec()	sum_of_radii	construct_packing()
tsp	Python	Ortszeit exec()	neg_tour_length	construct_tour()

Beobachten Sie, wie neg_tour_length steigt (sich null annähert), wenn Gemini über die Nearest-Neighbor-Methode hinausgeht und Verbesserungen im Stil von 2-opt oder or-opt vornimmt – Strategien, die Sie nicht selbst geschrieben haben.

7. Suche optimieren

Nachdem beide Läufe funktionieren, passen Sie das Budget in .env an:

• MAX_PROGRAMS_EVALUATED: Anzahl der zu bewertenden Kandidaten. Mehr Kandidaten = gründlichere Suche und höhere Kosten/mehr Zeit.
• CONCURRENCY: Die Anzahl der Kandidaten, die gleichzeitig generiert werden.
• MODEL_1 / MODEL_2 (mit MODEL_1_WEIGHT / MODEL_2_WEIGHT): Die gewichtete Mischung von Gemini-Modellen, die Kandidaten im Circle-Packing-Lauf generieren (das TSP-Modul liest stattdessen einen einzelnen MODEL). Zulässige Werte sind gemini-3.5-flash und gemini-3.1-pro-preview. Gewichten Sie das stärkere Modell stärker, um in weniger Generationen bessere Programme zu finden.

Führen Sie den Vorgang nach jeder Änderung mit uv run python -m examples.circle_packing.src.run_evolution (oder dem Modul tsp) noch einmal aus.

Hinweis:Wenn Sie MAX_PROGRAMS_EVALUATED erhöhen und zu einem größeren Modell wechseln, steigen die Kosten. Da in diesem Codelab die lokale Auswertung verwendet wird, fallen keine GPU-Gebühren an. Sie zahlen jedoch weiterhin für die Nutzung der AlphaEvolve API pro generiertem Kandidaten. für frische Motivation.

8. Bereinigen

In diesem Codelab wird die lokale Auswertung verwendet. Es werden also keine kostenpflichtigen Ressourcen mehr ausgeführt – keine Cluster, keine GPUs, keine bereitgestellten Dienste. So setzen Sie den Bezahlvorgang vollständig zurück:

git clean -xfd   # removes .env, .venv, and generated outputs

Hinweis : Mit git clean -xfd werden Ihre .env (einschließlich Ihrer Projekteinstellungen) und die .venv gelöscht. Wenn Sie weiter experimentieren möchten, können Sie diesen Schritt überspringen.

Wenn Sie ein Projekt nur für dieses Codelab erstellt haben, löschen Sie es in der Console, um alle Gebühren zu beenden.

9. Glückwunsch

Glückwunsch! Sie haben Ihre ersten AlphaEvolve-Tests in Google Cloud ausgeführt und zwei Algorithmen weiterentwickelt – einen Algorithmus für die Kreispackung und eine TSP-Heuristik – und dabei nur ein Seed-Programm, eine Scoring-Funktion und Gemini verwendet.

Das haben Sie gelernt

• So funktioniert der AlphaEvolve-Zyklus: Seed –> Generieren –> Bewerten –> Bewerten –> Wiederholen
• Der EVOLVE-BLOCK-Vertrag, mit dem die Suche ein Rezept optimieren kann, ohne den Messwert zu manipulieren
• Wie sich die nächste Generation von Creatorn und Künstlern von Punktzahlen und Fehlerstatistiken leiten lässt
• Lokale Tests konfigurieren, ausführen, auswerten und optimieren

Weitere Codelabs

Sie sind unabhängig voneinander und können in beliebiger Reihenfolge ausgeführt werden.

• Kompilierten Code mit einem Remote-Evaluator weiterentwickeln: Entwickeln Sie einen Rust-/C++-Algorithmus weiter, der von einem containerisierten Evaluator in Cloud Run bewertet wird.
• LLM-Feinabstimmung in GKE + Ray weiterentwickeln: Führen Sie umfangreiche, parallele GPU-Bewertungen in Ihrem eigenen Cluster aus.

Referenzdokumente

• Entwicklerleitfaden für AlphaEvolve
• AlphaEvolve-Beispiel-Repository
• Beispiel für ein Kreispackdiagramm
• TSP-Beispiel