Inizia a utilizzare AlphaEvolve su Google Cloud

1. Introduzione

In questo codelab, eseguirai i primi due esperimenti AlphaEvolve su Google Cloud. AlphaEvolve è il framework di codifica evolutivo guidato dall'AI di Google DeepMind: utilizza Gemini per scrivere e migliorare il codice, valutato in base a una metrica che definisci. Inizia con il circle packing, un piccolo problema di geometria in cui puoi letteralmente vedere il risultato migliorare, quindi ripeti l'operazione su un problema più difficile del commesso viaggiatore in modo che il pattern rimanga.

Entrambi gli esperimenti utilizzano la valutazione locale : il codice candidato viene eseguito sulla tua macchina, quindi non è presente alcuna GPU né alcun cluster da gestire. L'unico utilizzo del cloud è l'API AlphaEvolve che genera i candidati.

In questo lab proverai a:

• Configurare un esperimento AlphaEvolve nel tuo progetto Google Cloud
• Eseguire una ricerca evolutiva che migliori localmente un algoritmo di circle packing
• Leggere il punteggio, la classificazione e la visualizzazione del programma evoluto migliore
• Ripetere il loop su un problema del commesso viaggiatore per generalizzare il pattern
• Ottimizzare il budget di ricerca (candidati, concorrenza, modello)

Che cosa ti serve

• Un browser web come Chrome
• Un progetto cloud Google Cloud con la fatturazione abilitata
• Python 3.9 o versioni successive e uv
• Una conoscenza di base di Python e della riga di comando

Questo codelab è rivolto a ML engineer e sviluppatori di AI/ML di tutti i livelli. Non è richiesta alcuna conoscenza di calcolo evolutivo.

Tempo stimato per completare il corso: 45-60 minuti.

Costo: questo codelab utilizza la valutazione locale (nessuna GPU, nessun GKE). Gli unici addebiti riguardano la generazione di candidati: l'utilizzo dell'API AlphaEvolve e i token Vertex AI Gemini che consuma.

Testato con: la libreria client AlphaEvolve Cloud v0.1.0, Python 3.9+, negli esempi circle_packing e tsp.

2. Prima di iniziare

Seleziona il progetto e abilita le API

1. Nella console Google Cloud, seleziona o crea un progetto con la fatturazione abilitata, quindi impostalo nel terminale:

gcloud config set project <YOUR_PROJECT_ID>

2. Abilita le due API utilizzate da questo codelab: l'API Discovery Engine, che gestisce AlphaEvolve, e l'API Vertex AI, che gestisce i modelli Gemini che generano i candidati:

gcloud services enable \
  discoveryengine.googleapis.com \
  aiplatform.googleapis.com

Trova l'ID dell'app Gemini Enterprise

AlphaEvolve viene gestito tramite Gemini Enterprise (la superficie REST sottostante è l'API Discovery Engine). Per l'impostazione GE_APP_ID è necessario l'ID dell'app, non il nome visualizzato.

1. Apri la pagina delle app Gemini Enterprise per il tuo progetto.
2. Fai clic sull'app e copia il campo ID (ad esempio, gemini-enterprise-1234567890_1234567890123).

Tieni a portata di mano questo ID, perché lo incollerai in .env a breve. Lascia ASSISTANT=default_assistant a meno che tu non abbia eseguito il provisioning di un assistente personalizzato.

Autenticati, clona e installa

1. Autenticati per le credenziali predefinite dell'applicazione:

gcloud auth application-default login

2. Clona il repository di esempio e aprilo. Esegui tutti i comandi dalla radice di questo repository:

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

3. Crea un ambiente virtuale e installa la libreria client AlphaEvolve:

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

uv venv crea un file .venv nel repository; uv pip install -e ".[dev]" installa il pacchetto alpha_evolve (modificabile) e gli strumenti di test. Avvierai gli esperimenti con uv run, che utilizza automaticamente questo ambiente.

3. Comprendi il loop AlphaEvolve

Prima di eseguire qualsiasi operazione, comprendi i tre elementi di cui AlphaEvolve ha bisogno. Questo è il modello mentale che riutilizzerai per ogni esperimento.

Il programma di seed e EVOLVE-BLOCK

AlphaEvolve riscrive solo il codice tra due indicatori. Tutto il resto nel file è scaffolding fisso che non può essere modificato. Apri examples/circle_packing/src/program.py : il seed è un semplice circle packing ad anelli concentrici:

# 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

Tutto ciò che si trova al di fuori EVOLVE-BLOCK-START / EVOLVE-BLOCK-END, inclusa la funzione evaluate() e i controlli di sovrapposizione, rimane invariato. Questa separazione è l'intero trucco: Gemini può proporre qualsiasi algoritmo di circle packing, ma non può modificare il modo in cui viene valutato un candidato.

L'evaluator e il punteggio

examples/circle_packing/src/evaluate.py esegue ogni candidato in una sandbox e restituisce un punteggio. Per il circle packing, la metrica è sum_of_radii e più alto è, meglio è:

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

Se un candidato viola una regola (i cerchi si sovrappongono o escono dal quadrato), l'evaluator restituisce -inf più un insight che spiega cosa è andato storto. Questi insight vengono inviati a Gemini in modo che la generazione successiva eviti lo stesso errore.

Questa è la forma che assume ogni problema di AlphaEvolve: codice che puoi esprimere in un EVOLVE-BLOCK, una valutazione automatizzabile e un singolo punteggio scalare da massimizzare.

4. Esegui il primo esperimento

Configura l'esperimento

Dalla radice del repository, crea il file .env dal modello di circle packing:

cp examples/circle_packing/example.env .env

Apri .env e imposta solo l'ID del progetto e dell'app. Tutto il resto ha valori predefiniti funzionanti per una prima esecuzione:

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

I valori predefiniti generano candidati con una combinazione di modelli Gemini (MODEL_1=gemini-3.5-flash con peso 0.7, MODEL_2=gemini-3.1-pro-preview con 0.3) e limitano la ricerca a MAX_PROGRAMS_EVALUATED=10 con CONCURRENCY=4, sufficiente per vedere il loop funzionare rapidamente.

Avvia l'evoluzione

Esegui l'esperimento dalla radice del repository:

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

Questa operazione carica il programma di seed, avvia la ricerca ed esegue il loop di controllo locale fino a quando non vengono valutati 10 candidati. Poiché stai chiamando il modulo direttamente (senza wrapper), puoi vedere esattamente cosa viene eseguito e modificare il file per sperimentare.

Dovresti visualizzare un output simile al seguente:

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).

I primi candidati in genere ottengono un punteggio compreso tra 0,8 e 1,0 ; la ricerca migliora da lì. Al termine del loop, vengono stampati i programmi classificati e vengono visualizzati i circle packing migliori con matplotlib.

Nota: risoluzione dei problemi: un'esecuzione che termina immediatamente con FAILED_PRECONDITION e "AlphaEvolve requires the Vertex AI API to be enabled in this project" significa che manca aiplatform.googleapis.com. Abilitalo come descritto in "Prima di iniziare". PERMISSION_DENIED o 403 di solito significa che l'API Discovery Engine non è abilitata. Un errore "Failed to create experiment" senza nessuno di questi significa che le credenziali o GE_APP_ID in .env non sono corrette.

5. Leggi i risultati

L'esecuzione stampa i programmi migliori classificati in base a sum_of_radii (più alto è, meglio è). Ecco due cose da cercare:

• Il punteggio è aumentato. Il miglior sum_of_radii evoluto dovrebbe superare il layout ad anelli concentrici del seed. In genere, Gemini rileva che i cerchi vicino agli angoli e ai bordi possono crescere e ribilancia l'interno.
• I candidati non validi vengono ignorati. Qualsiasi programma che ha prodotto cerchi sovrapposti o fuori dai limiti ha ottenuto un punteggio -inf e viene ignorato nella classificazione. Questo è il feedback dei vincoli che funziona, non un errore.

È normale e salutare vedere alcuni candidati con punteggio basso o ignorati all'inizio dell'esecuzione. Significa che Gemini sta esplorando e gli insight derivanti dagli errori guidano le generazioni successive.

Ora hai il loop completo: seed -> genera -> valuta -> punteggio -> ripeti. Tutto il resto in AlphaEvolve è una variazione del punto in cui viene eseguita la valutazione.

6. Evolvi una ricerca reale: TSP

Il circle packing converge rapidamente. Per vedere la ricerca funzionare su un problema più complesso, evolvi un'euristica del problema del commesso viaggiatore. Il pattern è identico: cambiano solo il seed e la metrica e l'esempio TSP riutilizza il file .env (progetto, budget e concorrenza).

1. Aumenta il budget in .env in modo che la ricerca più lunga abbia spazio per migliorare:

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

2. Esegui dalla radice del repository:

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

Il seed qui è un tour nearest-neighbor su 50 città; la metrica è neg_tour_length (lunghezza media negativa del tour su 5 istanze fisse, quindi più alto è, meglio è). Apri examples/tsp/src/program.py e nota che solo construct_tour(distances, n) si trova all'interno di EVOLVE-BLOCK.

I due problemi hanno lo stesso pattern con elementi diversi:

Problema	Lingua	Valutazione	Metrica (più alto è, meglio è)	Cosa si evolve
circle_packing	Python	exec() locale	sum_of_radii	construct_packing()
tsp	Python	exec() locale	neg_tour_length	construct_tour()

Durante l'esecuzione della ricerca, osserva neg_tour_length aumentare (avvicinarsi a zero) man mano che Gemini va oltre il nearest-neighbor verso miglioramenti di tipo 2-opt / or-opt, strategie che non hai scritto.

7. Ottimizza la ricerca

Ora che entrambe le esecuzioni funzionano, ottimizza il budget in .env:

• MAX_PROGRAMS_EVALUATED : quanti candidati valutare. Più candidati = una ricerca più approfondita e un costo/tempo maggiore.
• CONCURRENCY : quanti candidati vengono generati contemporaneamente.
• MODEL_1 / MODEL_2 (con MODEL_1_WEIGHT / MODEL_2_WEIGHT): la combinazione ponderata di modelli Gemini che generano candidati nell'esecuzione del circle packing (il modulo TSP legge invece un singolo MODEL). I valori consentiti sono gemini-3.5-flash e gemini-3.1-pro-preview. Sposta il peso verso il modello più potente per trovare programmi migliori in meno generazioni.

Esegui di nuovo con uv run python -m examples.circle_packing.src.run_evolution (o il modulo tsp) dopo ogni modifica.

Nota: l'aumento di MAX_PROGRAMS_EVALUATED e il passaggio a un modello più grande aumentano entrambi il costo. Poiché questo codelab utilizza la valutazione locale, non è previsto alcun addebito per la GPU, ma paghi comunque l'utilizzo dell'API AlphaEvolve e i token Vertex AI Gemini per ogni candidato generato. Inizia in piccolo:

8. Libera spazio

Questo codelab utilizza la valutazione locale, quindi non è rimasto in esecuzione nulla di fatturabile : nessun cluster, nessuna GPU, nessun servizio di cui è stato eseguito il deployment. Per reimpostare completamente il checkout:

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

Nota: git clean -xfd elimina il file .env (incluse le impostazioni progetto) e il file .venv. Salta questo passaggio se vuoi continuare a sperimentare.

Se hai creato un progetto solo per questo codelab, eliminalo nella console per interrompere tutti gli addebiti.

9. Complimenti

Complimenti! Hai eseguito i primi esperimenti AlphaEvolve su Google Cloud e hai evoluto due algoritmi, un circle packing e un'euristica TSP, utilizzando solo un programma di seed, una funzione di punteggio e Gemini.

Che cosa hai imparato

• Come funziona il loop di AlphaEvolve: seed -> genera -> valuta -> punteggio -> ripeti
• Il contratto EVOLVE-BLOCK che consente alla ricerca di ottimizzare una ricetta senza manipolare la metrica
• Come i punteggi e gli insight sugli errori guidano la generazione successiva
• Come configurare, eseguire, leggere e ottimizzare un esperimento di valutazione locale

Altri codelab

Questi sono autonomi, quindi puoi eseguirli in qualsiasi ordine.

• Evolvi il codice compilato con un evaluator remoto: evolvi un algoritmo Rust/C++ valutato da un evaluator containerizzato su Cloud Run.
• Evolvi il fine-tuning degli LLM su GKE + Ray: esegui valutazioni GPU parallele e pesanti sul tuo cluster.

Documenti di riferimento

• Guida per gli sviluppatori di AlphaEvolve
• Repository di esempio di AlphaEvolve
• Esempio di circle packing
• Esempio di TSP