Premiers pas avec AlphaEvolve sur Google Cloud

1. Introduction

Dans cet atelier de programmation, vous allez exécuter vos deux premiers tests AlphaEvolve sur Google Cloud. AlphaEvolve est le framework de codage évolutif guidé par l'IA de Google DeepMind : il utilise Gemini pour écrire et améliorer du code, noté par une métrique que vous définissez. Vous commencez par le problème d'empilement de cercles, un petit problème de géométrie où vous pouvez littéralement voir le résultat s'améliorer. Vous répétez ensuite l'opération sur un problème du voyageur de commerce plus difficile pour que le modèle reste en mémoire.

Les deux tests utilisent l'évaluation locale : le code candidat s'exécute sur votre propre machine. Il n'y a donc pas de GPU ni de cluster à gérer. La seule utilisation du cloud est l'API AlphaEvolve qui génère des candidats.

Objectifs de l'atelier

• Configurer un test AlphaEvolve par rapport à votre projet Google Cloud
• Exécuter une recherche évolutive qui améliore localement un algorithme d'empilement de cercles
• Lire le score, le classement et la visualisation du meilleur programme évolué
• Répéter la boucle sur un problème du voyageur de commerce pour généraliser le modèle
• Ajuster le budget de recherche (candidats, simultanéité, modèle)

Ce dont vous avez besoin

• Un navigateur Web (par exemple, Chrome)
• Un projet Google Cloud avec facturation activée
• Python 3.9 ou version ultérieure et uv
• Connaissances de base de Python et de la ligne de commande

Cet atelier de programmation s'adresse aux ingénieurs et développeurs en IA/ML de tous niveaux. Aucune connaissance en calcul évolutif n'est requise.

Temps estimé : 45 à 60 minutes.

Coût : cet atelier de programmation utilise l'évaluation locale (pas de GPU, pas de GKE). Les seuls frais sont liés à la génération de candidats : l'utilisation de l'API AlphaEvolve et les jetons Vertex AI Gemini qu'elle consomme.

Testé avec : la bibliothèque cliente Cloud AlphaEvolve v0.1.0, Python 3.9+, sur les exemples circle_packing et tsp.

2. Avant de commencer

Sélectionner votre projet et activer les API

1. Dans la console Google Cloud, sélectionnez ou créez un projet avec la facturation activée, puis définissez-le dans votre terminal :

gcloud config set project <YOUR_PROJECT_ID>

2. Activez les deux API utilisées par cet atelier de programmation : l'API Discovery Engine, qui sert AlphaEvolve, et l'API Vertex AI, qui sert les modèles Gemini qui génèrent des candidats :

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

Trouver l'ID de votre application Gemini Enterprise

AlphaEvolve est fourni via Gemini Enterprise (la surface REST sous-jacente est l'API Discovery Engine). Vous avez besoin de l'ID de votre application, et non de son nom à afficher, pour le paramètre GE_APP_ID.

1. Ouvrez la page des applications Gemini Enterprise pour votre projet.
2. Cliquez sur votre application et copiez le champ ID (par exemple, gemini-enterprise-1234567890_1234567890123).

Conservez cet ID à portée de main. Vous le collerez dans .env sous peu. Laissez ASSISTANT=default_assistant sauf si vous avez provisionné un assistant personnalisé.

S'authentifier, cloner et installer

1. Authentifiez-vous pour les identifiants par défaut de l'application :

gcloud auth application-default login

2. Clonez l'exemple de dépôt et ouvrez-le. Vous exécuterez chaque commande à partir de la racine de ce dépôt :

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

3. Créez un environnement virtuel et installez-y la bibliothèque cliente AlphaEvolve :

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

uv venv crée un .venv dans le dépôt. uv pip install -e ".[dev]" installe le package alpha_evolve (modifiable) ainsi que des outils de test. Vous lancerez des tests avec uv run, qui utilise automatiquement cet environnement.

3. Comprendre la boucle AlphaEvolve

Avant d'exécuter quoi que ce soit, comprenez les trois éléments dont AlphaEvolve a besoin. Il s'agit du modèle mental que vous réutiliserez pour chaque test.

Le programme source et le bloc EVOLVE-BLOCK

AlphaEvolve ne réécrit le code qu'entre deux marqueurs. Tout le reste du fichier est une structure fixe qu'il ne peut pas modifier. Ouvrez examples/circle_packing/src/program.py. La source est un simple empilement d'anneaux concentriques :

# 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

Tout ce qui se trouve en dehors EVOLVE-BLOCK-START / EVOLVE-BLOCK-END (y compris la fonction evaluate() et les vérifications de chevauchement) reste figé. Cette séparation est la clé : Gemini peut proposer n'importe quel algorithme d'empilement, mais il ne peut pas modifier la façon dont un candidat est noté.

L'évaluateur et le score

examples/circle_packing/src/evaluate.py exécute chaque candidat dans un bac à sable et renvoie un score. Pour l'empilement de cercles, la métrique est sum_of_radii, et plus la valeur est élevée, mieux c'est:

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

Si un candidat enfreint une règle (les cercles se chevauchent ou sortent du carré), l'évaluateur renvoie -inf plus un insight expliquant ce qui s'est mal passé. Ces insights sont renvoyés à Gemini afin que la génération suivante évite la même erreur.

C'est la forme que prend chaque problème AlphaEvolve : du code que vous pouvez exprimer dans un bloc EVOLVE-BLOCK, une évaluation automatisable et un score scalaire unique à maximiser.

4. Exécuter votre premier test

Configurer le test

À partir de la racine du dépôt, créez votre .env à partir du modèle d'empilement de cercles :

cp examples/circle_packing/example.env .env

Ouvrez .env et définissez uniquement votre projet et l'ID de votre application. Tout le reste a des valeurs par défaut fonctionnelles pour une première exécution :

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

Les valeurs par défaut génèrent des candidats avec un mélange de modèles Gemini (MODEL_1=gemini-3.5-flash avec un poids de 0.7, MODEL_2=gemini-3.1-pro-preview avec un poids de 0.3) et limitent la recherche à MAX_PROGRAMS_EVALUATED=10 avec CONCURRENCY=4, ce qui est suffisant pour voir la boucle fonctionner rapidement.

Démarrer l'évolution

Exécutez le test à partir de la racine du dépôt :

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

Cela importe le programme source, démarre la recherche et exécute la boucle de contrôle locale jusqu'à ce que 10 candidats aient été évalués. Comme vous appelez le module directement (sans wrapper), vous pouvez voir exactement ce qui s'exécute et modifier le fichier pour tester.

Un résultat semblable à celui-ci s'affiche :

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

Les premiers candidats obtiennent généralement un score compris entre 0,8 et 1,0. La recherche s'améliore ensuite. Lorsque la boucle se termine, elle affiche les programmes classés et affiche les meilleurs empilements avec matplotlib.

Remarque : Dépannage : une exécution qui se termine immédiatement par FAILED_PRECONDITION et "AlphaEvolve requires the Vertex AI API to be enabled in this project" (AlphaEvolve nécessite que l'API Vertex AI soit activée dans ce projet) signifie que aiplatform.googleapis.com est manquant. Activez-le comme indiqué dans "Avant de commencer". PERMISSION_DENIED ou 403 signifie généralement que l'API Discovery Engine n'est pas activée. Si le message "Failed to create experiment" (Échec de la création du test) s'affiche sans aucune de ces erreurs, cela signifie que les identifiants ou GE_APP_ID dans .env sont incorrects.

5. Lire les résultats

L'exécution affiche les meilleurs programmes classés par sum_of_radii (plus la valeur est élevée, mieux c'est). Deux éléments à rechercher :

• Le score a augmenté. Le meilleur sum_of_radii évolué doit être supérieur à la mise en page d'anneaux concentriques de la source. Gemini découvre généralement que les cercles situés près des angles et des bords peuvent s'agrandir, et rééquilibre l'intérieur.
• Les candidats non valides sont ignorés. Tout programme qui a produit des cercles qui se chevauchent ou qui sont hors limites a obtenu un score de -inf et est ignoré dans le classement. Il s'agit du fonctionnement du feedback de contrainte, et non d'une erreur.

Il est normal et sain de voir quelques candidats peu performants ou ignorés au début de l'exécution. Cela signifie que Gemini explore, et que les insights issus des échecs guident les générations ultérieures.

Vous disposez maintenant de la boucle complète : source -> générer -> évaluer -> noter -> répéter. Tout le reste dans AlphaEvolve est une variante de l'endroit où l'évaluation s'exécute.

6. Faire évoluer une recherche réelle : TSP

L'empilement de cercles converge rapidement. Pour que la recherche fonctionne sur un problème plus important, faites évoluer une heuristique du problème du voyageur de commerce. Le modèle est identique. Seuls la source et la métrique changent, et l'exemple TSP réutilise votre .env (projet, budget et simultanéité).

1. Augmentez le budget dans .env pour que la recherche plus longue ait de la marge pour s'améliorer :

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

2. Exécutez-le à partir de la racine du dépôt :

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

La source est ici un circuit voisin le plus proche sur 50 villes. La métrique est neg_tour_length (longueur moyenne négative du circuit sur cinq instances fixes, donc plus la valeur est élevée, mieux c'est). Ouvrez examples/tsp/src/program.py et notez que seul construct_tour(distances, n) se trouve dans le bloc EVOLVE-BLOCK.

Les deux problèmes suivent le même modèle, mais avec des éléments différents :

Problème	Langue	Évaluation	Métrique (plus la valeur est élevée, mieux c'est)	Ce qui évolue
circle_packing	Python	exec() local	sum_of_radii	construct_packing()
tsp	Python	exec() local	neg_tour_length	construct_tour()

Pendant l'exécution de la recherche, regardez neg_tour_length augmenter (se rapprocher de zéro) à mesure que Gemini passe du voisin le plus proche à des améliorations de style 2-opt / or-opt, des stratégies que vous n'avez pas écrites.

7. Ajuster la recherche

Maintenant que les deux exécutions fonctionnent, ajustez le budget dans .env :

• MAX_PROGRAMS_EVALUATED : nombre de candidats à noter. Plus il y a de candidats, plus la recherche est approfondie et plus le coût/temps est élevé.
• CONCURRENCY : nombre de candidats générés en vol à la fois.
• MODEL_1 / MODEL_2 (avec MODEL_1_WEIGHT / MODEL_2_WEIGHT) : mélange pondéré de modèles Gemini qui génèrent des candidats lors de l'exécution de l'empilement de cercles (le module TSP lit un seul MODEL à la place). Les valeurs autorisées sont gemini-3.5-flash et gemini-3.1-pro-preview. Déplacez le poids vers le modèle le plus puissant pour trouver de meilleurs programmes en moins de générations.

Réexécutez avec uv run python -m examples.circle_packing.src.run_evolution (ou le module tsp) après chaque modification.

Remarque : Augmenter MAX_PROGRAMS_EVALUATED et passer à un modèle plus grand augmente le coût. Comme cet atelier de programmation utilise l'évaluation locale, aucun frais de GPU n'est facturé, mais vous payez toujours l'utilisation de l'API AlphaEvolve et les jetons Vertex AI Gemini par candidat généré. Commencez petit.

8. Libérer de l'espace

Cet atelier de programmation utilise l'évaluation locale. Il n'y a donc plus rien de facturable en cours d'exécution : pas de clusters, pas de GPU, pas de services déployés. Pour réinitialiser complètement votre paiement :

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

Remarque : git clean -xfd supprime votre .env (y compris les paramètres de votre projet) et le .venv. Ignorez cette étape si vous souhaitez continuer à tester.

Si vous avez créé un projet uniquement pour cet atelier de programmation, supprimez-le dans la console pour arrêter tous les frais.

9. Félicitations

Félicitations ! Vous avez exécuté vos premiers tests AlphaEvolve sur Google Cloud et fait évoluer deux algorithmes (un empilement de cercles et une heuristique TSP) en utilisant uniquement un programme source, une fonction de notation et Gemini.

Connaissances acquises

• Fonctionnement de la boucle AlphaEvolve : source -> générer -> évaluer -> noter -> répéter
• Le contrat EVOLVE-BLOCK qui permet à la recherche d'optimiser une recette sans jouer avec la métrique
• Comment les scores et les insights d'échec guident la génération suivante
• Comment configurer, exécuter, lire et ajuster un test d'évaluation locale

Autres ateliers de programmation

Ils sont autonomes. Vous pouvez les suivre dans n'importe quel ordre.

• Faire évoluer du code compilé avec un évaluateur distant : faire évoluer un algorithme Rust/C++ noté par un évaluateur conteneurisé sur Cloud Run.
• Faire évoluer le réglage précis de LLM sur GKE + Ray : exécuter des évaluations GPU parallèles lourdes sur votre propre cluster.

Documents de référence

• Guide du développeur AlphaEvolve
• Exemples de dépôt AlphaEvolve
• Exemple d'empilement de cercles
• Exemple de TSP