Inizia a utilizzare AlphaEvolve su Google Cloud

1. Introduzione

In questo codelab, esegui i primi due esperimenti AlphaEvolve su Google Cloud. AlphaEvolve è il framework di programmazione evolutiva guidato dall'AI di Google DeepMind: utilizza Gemini per scrivere e migliorare il codice, valutato in base a una metrica che definisci. Si inizia con il problema di impacchettamento di cerchi, un piccolo problema di geometria in cui puoi letteralmente vedere il risultato migliorare, poi si ripete con un problema del commesso viaggiatore più difficile, in modo che il modello rimanga.

Entrambi gli esperimenti utilizzano la valutazione locale: il codice candidato viene eseguito sul tuo computer, quindi non è presente alcuna GPU e nessun cluster da gestire. L'unico utilizzo del cloud è l'API AlphaEvolve che genera candidati.

In questo lab proverai a:

• Configura un esperimento AlphaEvolve rispetto al tuo progetto Google Cloud
• Esegui una ricerca evolutiva che migliora localmente un algoritmo di impacchettamento circolare
• Leggi il punteggio, la classifica e la visualizzazione del miglior programma evoluto
• Ripeti il ciclo di un problema del commesso viaggiatore per generalizzare il pattern
• Ottimizza il budget di ricerca (candidati, concorrenza, modello)

Che cosa ti serve

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

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

Tempo stimato per il completamento: 45-60 minuti.

Costo: questo codelab utilizza la valutazione locale (nessuna GPU, nessun GKE). L'unico costo è l'utilizzo dell'API AlphaEvolve per generare candidati.

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 l'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 l'API Discovery Engine, che gestisce AlphaEvolve:

gcloud services enable discoveryengine.googleapis.com

Trovare l'ID dell'app Gemini Enterprise

AlphaEvolve viene fornito 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 App Gemini Enterprise per il tuo progetto.
2. Fai clic sulla tua app e copia il campo ID (ad esempio, gemini-enterprise-1234567890_1234567890123).

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

Autenticare, clonare e installare

1. Esegui l'autenticazione per le credenziali predefinite dell'applicazione:

gcloud auth application-default login

2. Clona il repository di esempi e aprilo. Esegui ogni comando 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 .venv nel repository; uv pip install -e ".[dev]" installa il pacchetto alpha_evolve (modificabile) più gli strumenti di test. Avvierai gli esperimenti con uv run, che utilizza automaticamente questo ambiente.

3. Comprendere il ciclo di AlphaEvolve

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

Il programma di seeding e EVOLVE-BLOCK

AlphaEvolve riscrive solo il codice tra due marcatori. Tutto il resto del file è una struttura fissa che non può essere modificata. Apri examples/circle_packing/src/program.py. Il seme è un semplice impacchettamento di 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 di EVOLVE-BLOCK-START / EVOLVE-BLOCK-END, inclusa la funzione evaluate() e i controlli di sovrapposizione, rimane invariato. Questa separazione è il trucco: Gemini può proporre qualsiasi algoritmo di raggruppamento, ma non può modificare il modo in cui viene assegnato un punteggio a un candidato.

Il valutatore 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 è il valore, 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), il valutatore restituisce -inf più un approfondimento che spiega cosa è andato storto. Questi approfondimenti vengono inviati a Gemini, in modo che la prossima generazione 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 unico punteggio scalare da massimizzare.

4. Esegui il tuo primo esperimento

Configurare 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 progetto e l'ID app. Tutto il resto ha valori predefiniti funzionanti per la 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 peso 0.3) e limitano la ricerca a MAX_PROGRAMS_EVALUATED=10 con CONCURRENCY=4, quanto basta per vedere il funzionamento del ciclo in modo rapido.

Inizia l'evoluzione

Esegui l'esperimento dalla radice del repository:

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

Viene caricato il programma iniziale, avviata la ricerca ed eseguito il ciclo di controllo locale fino a quando non sono stati valutati 10 candidati. Poiché chiami il modulo direttamente (senza wrapper), puoi vedere esattamente cosa viene eseguito e modificare il file per fare esperimenti.

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 questo punto in poi. Al termine del ciclo, stampa i programmi classificati e visualizza i pacchetti migliori con matplotlib.

Nota:risoluzione dei problemi: PERMISSION_DENIED o 403 di solito significa che l'API Discovery Engine non è abilitata nel progetto. Controlla di nuovo il passaggio "Prima di iniziare". Un'esecuzione che termina immediatamente con "Impossibile creare l'esperimento" indica che le credenziali o GE_APP_ID in .env non sono corrette.

5. Leggere i risultati

La corsa stampa i primi programmi in base al ranking per sum_of_radii (più alto è, meglio è). Due aspetti da controllare:

• Il punteggio è aumentato. Il miglior sum_of_radii evoluto dovrebbe battere il layout ad anelli concentrici del seme. In genere, Gemini rileva che i cerchi vicino agli angoli e ai bordi possono diventare più grandi 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 di -inf e viene ignorato nella classifica. Questo è il feedback sui vincoli in funzione, non un errore.

Vedere alcuni candidati con punteggio basso o saltati all'inizio dell'esecuzione è normale e positivo: significa che Gemini sta esplorando e che gli approfondimenti derivanti dagli errori guidano le generazioni successive.

Ora hai il ciclo completo: seme -> genera -> valuta -> assegna un punteggio -> ripeti. Tutto il resto in AlphaEvolve è una variante del luogo in cui viene eseguita la valutazione.

6. Evoluzione di una ricerca reale: TSP

Il riempimento del cerchio converge rapidamente. Per vedere la ricerca all'opera su un problema più complesso, sviluppa un'euristica per il problema del commesso viaggiatore. Il pattern è identico: cambiano solo il seed e la metrica e l'esempio TSP riutilizza .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 il comando dalla radice del repository:

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

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

I due problemi sono lo stesso schema con pezzi diversi:

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

Mentre la ricerca viene eseguita, osserva neg_tour_length salire (avvicinarsi a zero) man mano che Gemini va oltre il vicino più prossimo verso miglioramenti in stile 2-opt / or-opt, ovvero strategie che non hai scritto.

7. Ottimizzare la ricerca

Ora che entrambi gli scenari funzionano, regola il budget in .env:

• MAX_PROGRAMS_EVALUATED: quanti candidati valutare. Più opzioni = una ricerca più approfondita e costi/tempi più elevati.
• CONCURRENCY: il numero di candidati generati contemporaneamente durante il periodo di pubblicazione.
• MODEL_1 / MODEL_2 (con MODEL_1_WEIGHT / MODEL_2_WEIGHT): la combinazione ponderata di modelli Gemini che generano candidati nell'esecuzione di circle packing (il modulo TSP legge un singolo MODEL). I valori consentiti sono gemini-3.5-flash e gemini-3.1-pro-preview. Sposta la ponderazione verso il modello più efficace 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 i costi. Poiché questo codelab utilizza la valutazione locale, non è previsto alcun addebito per la GPU, ma paghi comunque l'utilizzo dell'API AlphaEvolve per ogni candidato generato. Inizia in piccolo:

8. Esegui la pulizia

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 pagamento:

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

Nota: git clean -xfd elimina .env (incluse le impostazioni del progetto) e .venv. Ignoralo 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 tuoi primi esperimenti AlphaEvolve su Google Cloud e hai sviluppato due algoritmi, uno per il riempimento di cerchi e uno per l'euristica TSP, utilizzando solo un programma seed, una funzione di punteggio e Gemini.

Cosa hai imparato

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

Altri codelab

Questi sono indipendenti, quindi puoi eseguirli in qualsiasi ordine.

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

Documenti di riferimento

• Guida per gli sviluppatori di AlphaEvolve
• Repository di esempi di AlphaEvolve
• Esempio di diagramma a pacchetto
• Esempio di TSP