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 evolutionäre Programmierframework von Google DeepMind. Es verwendet Gemini, um Code zu schreiben und zu verbessern, der anhand eines von Ihnen definierten Messwerts bewertet wird. Sie beginnen mit dem Packen von Kreisen – einem kleinen Geometrieproblem, bei dem Sie buchstäblich beobachten können, wie sich das Ergebnis verbessert. Anschließend wiederholen Sie den Vorgang mit einem schwierigeren Problem des Handlungsreisenden, damit sich das Muster einprägt.

Bei beiden Tests wird die lokale Bewertung verwendet. Der Kandidatencode wird auf Ihrem eigenen Computer ausgeführt, sodass keine GPU und kein Cluster verwaltet werden müssen. Die einzige Cloud-Nutzung ist die AlphaEvolve API, die Kandidaten generiert.

Aufgaben

• Einen AlphaEvolve-Test für Ihr Google Cloud-Projekt konfigurieren
• Eine evolutionäre Suche ausführen , die einen Algorithmus zum Packen von Kreisen lokal verbessert
• Die Bewertung, das Ranking und die Visualisierung des besten entwickelten Programms lesen
• Den Loop mit einem Problem des Handlungsreisenden wiederholen , um das Muster zu verallgemeinern
• Das 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
• Grundlegende Kenntnisse in Python und der Befehlszeile

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

Geschätzte Dauer: 45–60 Minuten

Kosten: In diesem Codelab wird die lokale Bewertung verwendet (keine GPU, kein GKE). Die einzigen Kosten fallen für die Generierung von Kandidaten an – die Nutzung der AlphaEvolve API und die Vertex AI Gemini-Tokens, die dabei verbraucht werden.

Getestet mit: AlphaEvolve Cloud-Clientbibliothek v0.1.0, Python 3.9+ und den Beispielen circle_packing und tsp.

2. Hinweis

Projekt auswählen und APIs aktivieren

1. Wählen Sie in der Google Cloud Console ein Projekt mit aktivierter Abrechnung aus oder erstellen Sie eines und legen Sie es dann in Ihrem Terminal fest:

gcloud config set project <YOUR_PROJECT_ID>

2. Aktivieren Sie die beiden APIs, die in diesem Codelab verwendet werden: die Discovery Engine API, die AlphaEvolve bereitstellt, und die Vertex AI API, die die Gemini-Modelle bereitstellt, mit denen Kandidaten generiert werden:

gcloud services enable \
  discoveryengine.googleapis.com \
  aiplatform.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 ihren 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. Sie fügen sie gleich in .env ein. 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 Standardanmeldedaten für Anwendungen:

gcloud auth application-default login

2. Klonen Sie das Repository mit den Beispielen und öffnen Sie es. Sie führen alle Befehle im Stammverzeichnis dieses Repositorys 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 eine .venv-Datei 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-Loop verstehen

Bevor Sie etwas ausführen, sollten Sie die drei Komponenten verstehen, die AlphaEvolve benötigt. Dies ist das mentale Modell, das Sie für jeden Test wiederverwenden.

Das Seed-Programm und der EVOLVE-BLOCK

AlphaEvolve schreibt nur den Code zwischen zwei Markierungen neu. Alles andere in der Datei ist ein festes Gerüst, das nicht geändert werden kann. Öffnen Sie examples/circle_packing/src/program.py. Das Seed-Programm ist ein einfaches Packen von konzentrischen Ringen:

# 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 Funktion evaluate() und der Überlappungsprüfungen – bleibt unverändert. Diese Trennung ist der ganze Trick: Gemini kann einen beliebigen Packalgorithmus vorschlagen, aber nicht ändern, wie ein Kandidat bewertet wird.

Der Evaluator und die Bewertung

examples/circle_packing/src/evaluate.py führt jeden Kandidaten in einer Sandbox aus und gibt eine Bewertung zurück. Für das Packen von Kreisen ist der Messwert sum_of_radii und höher 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 sowie eine Insight zurück, in der erklärt wird, was falsch gelaufen ist. Diese Insights 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 Bewertung und eine einzelne skalare Bewertung, die maximiert werden soll.

4. Ersten Test ausführen

Test konfigurieren

Erstellen Sie im Stammverzeichnis des Repositorys Ihre .env-Datei aus der Vorlage für das Packen von Kreisen:

cp examples/circle_packing/example.env .env

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

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

Mit den Standardwerten werden Kandidaten mit einer Mischung aus Gemini-Modellen generiert (MODEL_1=gemini-3.5-flash mit Gewichtung 0.7, MODEL_2=gemini-3.1-pro-preview mit 0.3). Die Suche wird mit MAX_PROGRAMS_EVALUATED=10 und CONCURRENCY=4 begrenzt. Das reicht aus, um den Loop schnell zu beobachten.

Evolution starten

Führen Sie den Test im Stammverzeichnis des Repositorys aus:

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

Dadurch wird das Seed-Programm hochgeladen, die Suche gestartet und der lokale Kontroll-Loop 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 erzielen in der Regel eine Bewertung im Bereich von 0,8–1,0. Die Suche verbessert sich von dort aus. Wenn der Loop abgeschlossen ist, werden die Programme nach Rangfolge ausgegeben und die besten Packungen mit matplotlib gerendert.

Hinweis:Fehlerbehebung: Wenn ein Lauf sofort mit FAILED_PRECONDITION und „AlphaEvolve requires the Vertex AI API to be enabled in this project“ endet, fehlt aiplatform.googleapis.com. Aktivieren Sie es wie unter „Hinweis“ beschrieben. PERMISSION_DENIED oder 403 bedeutet in der Regel, dass die Discovery Engine API nicht aktiviert ist. Wenn „Failed to create experiment“ angezeigt wird und keine dieser beiden Ursachen zutrifft, sind die Anmeldedaten oder GE_APP_ID in .env falsch.

5. Ergebnisse lesen

Bei der Ausführung werden die besten Programme nach sum_of_radii sortiert ausgegeben (höher ist besser). Achten Sie auf Folgendes:

• Die Bewertung ist gestiegen. Die beste entwickelte sum_of_radii sollte das konzentrische Ringlayout des Seed-Programms ü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 aus.
• Ungültige Kandidaten werden übersprungen. Jedes Programm, das überlappende oder außerhalb des Bereichs liegende Kreise erzeugt hat, wurde mit -inf bewertet und im Ranking übersprungen. Das ist das Feedback zu den Einschränkungen, kein Fehler.

Es ist normal und gesund, wenn zu Beginn der Ausführung einige Kandidaten mit niedriger Bewertung oder übersprungene Kandidaten angezeigt werden. Das bedeutet, dass Gemini verschiedene Möglichkeiten ausprobiert und die Erkenntnisse aus den Fehlern spätere Generationen steuern.

Sie haben jetzt den vollständigen Loop: Seed -> Generieren -> Bewerten -> Bewertung -> Wiederholen. Alles andere in AlphaEvolve ist eine Variation davon, wo die Bewertung ausgeführt wird.

6. Eine echte Suche entwickeln: TSP

Das Packen von Kreisen konvergiert schnell. Um die Suche mit einem anspruchsvolleren Problem zu testen, entwickeln Sie eine Heuristik für das Problem des Handlungsreisenden. Das Muster ist identisch. Nur das Seed-Programm und der Messwert ändern sich. Das TSP-Beispiel verwendet Ihre .env-Datei (Projekt, Budget und Parallelität).

1. Erhöhen Sie das Budget in .env, damit die längere Suche Raum für Verbesserungen hat:

# 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 im Stammverzeichnis des Repositorys aus:

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

Das Seed-Programm ist hier eine Nearest-Neighbor -Tour durch 50 Städte. Der Messwert ist neg_tour_length (negative durchschnittliche Tourlänge über 5 feste Instanzen, also höher ist besser). Öffnen Sie examples/tsp/src/program.py und beachten Sie, dass sich nur construct_tour(distances, n) innerhalb des EVOLVE-BLOCK befindet.

Die beiden Probleme haben dasselbe Muster, aber unterschiedliche Komponenten:

Problem	Sprache	Bewertung	Messwert (höher ist besser)	Was sich entwickelt
circle_packing	Python	lokal exec()	sum_of_radii	construct_packing()
tsp	Python	lokal exec()	neg_tour_length	construct_tour()

Beobachten Sie, wie neg_tour_length während der Suche steigt (sich Null nähert), während Gemini über den Nearest-Neighbor-Ansatz hinausgeht und Verbesserungen im Stil von 2-opt oder or-opt vornimmt – Strategien, die Sie nicht selbst geschrieben haben.

7. Suche anpassen

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

• MAX_PROGRAMS_EVALUATED : Anzahl der zu bewertenden Kandidaten. Mehr Kandidaten bedeuten eine tiefere Suche und höhere Kosten/Zeit.
• CONCURRENCY : Anzahl der Kandidaten, die gleichzeitig generiert werden.
• MODEL_1 / MODEL_2 (mit MODEL_1_WEIGHT / MODEL_2_WEIGHT): gewichtete Mischung aus Gemini-Modellen, die Kandidaten im Lauf zum Packen von Kreisen generieren (das TSP-Modul liest stattdessen ein einzelnes MODEL). Zulässige Werte sind gemini-3.5-flash und gemini-3.1-pro-preview. Verschieben Sie die Gewichtung in Richtung des stärkeren Modells, um in weniger Generationen bessere Programme zu finden.

Führen Sie nach jeder Änderung mit uv run python -m examples.circle_packing.src.run_evolution (oder dem tsp-Modul) einen neuen Lauf 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 Bewertung verwendet wird, fallen keine GPU-Kosten an. Sie zahlen jedoch weiterhin für die Nutzung der AlphaEvolve API und die Vertex AI Gemini-Tokens pro generiertem Kandidaten. Beginnen Sie mit einem kleinen Budget.

8. Bereinigen

In diesem Codelab wird die lokale Bewertung verwendet, sodass keine kostenpflichtigen Ressourcen mehr ausgeführt werden – keine Cluster, keine GPUs, keine bereitgestellten Dienste. So setzen Sie Ihren Direktkauf vollständig zurück:

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

Hinweis: git clean -xfd löscht Ihre .env (einschließlich Ihrer Projekteinstellungen) und die .venv. Überspringen Sie diesen Schritt, wenn Sie weiter experimentieren möchten.

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

9. Glückwunsch

Glückwunsch! Sie haben Ihre ersten AlphaEvolve-Tests in Google Cloud ausgeführt und zwei Algorithmen entwickelt – einen zum Packen von Kreisen und eine TSP-Heuristik – und dabei nur ein Seed-Programm, eine Bewertungsfunktion und Gemini verwendet.

Lerninhalte

• So funktioniert der Loop von AlphaEvolve: Seed -> Generieren -> Bewerten -> Bewertung -> Wiederholen
• Der EVOLVE-BLOCK -Vertrag, mit dem die Suche ein Rezept optimieren kann, ohne den Messwert zu manipulieren
• Wie Bewertungen und Erkenntnisse aus Fehlern die nächste Generation steuern
• So konfigurieren, ausführen, lesen und optimieren Sie einen Test mit lokaler Bewertung

Weitere Codelabs

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

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

Referenzdokumente

• Entwicklerleitfaden für AlphaEvolve
• Repository mit AlphaEvolve-Beispielen
• Beispiel für das Packen von Kreisen
• TSP-Beispiel