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 le code, qui est ensuite évalué à l'aide d'une métrique que vous définissez. Vous commencez par le packing 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 de voyageur de commerce plus difficile pour que le modèle s'imprègne.

Les deux expériences 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 concerne l'API AlphaEvolve qui génère des candidats.

Objectifs de l'atelier

• Configurer un test AlphaEvolve dans votre projet Google Cloud
• Exécuter une recherche évolutive qui améliore localement un algorithme de packing circulaire
• Lire le score, le classement et la visualisation du meilleur programme optimisé
• Répétez la boucle sur un problème du voyageur de commerce pour généraliser le modèle.
• Régler le budget de recherche (candidats, simultanéité, modèle)

Prérequis

• 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 évolutionnaire n'est requise.

Estimation du temps nécessaire : 45 à 60 minutes.

Coût : cet atelier de programmation utilise l'évaluation locale (sans GPU ni GKE). La seule facturation concerne l'utilisation de l'API AlphaEvolve pour générer des candidats.

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

2. Avant de commencer

Sélectionner votre projet et activer l'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 l'API Discovery Engine, qui sert AlphaEvolve :

gcloud services enable discoveryengine.googleapis.com

Trouver l'ID de votre application Gemini Enterprise

AlphaEvolve est proposé 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 Applications Gemini Enterprise pour votre projet.
2. Cliquez sur votre application, puis copiez le champ ID (par exemple, gemini-enterprise-1234567890_1234567890123).

Conservez cet ID à portée de main, car 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 le dépôt d'exemples 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 les 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 de sources et 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 graine est un simple packing 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 de EVOLVE-BLOCK-START / EVOLVE-BLOCK-END, y compris la fonction evaluate() et les vérifications de chevauchement, reste figé. C'est là tout l'intérêt de cette séparation : Gemini peut proposer l'algorithme de packing de son choix, mais il ne peut pas modifier la façon dont un candidat est évalué.

L'évaluateur et le score

examples/circle_packing/src/evaluate.py exécute chaque candidat dans un bac à sable et renvoie un score. Pour le packing 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 ainsi qu'un insight expliquant le problème. Ces insights sont renvoyés à Gemini pour que la prochaine génération évite la même erreur.

Chaque problème AlphaEvolve se présente sous la forme suivante : code que vous pouvez exprimer dans un 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 de packing circulaire :

cp examples/circle_packing/example.env .env

Ouvrez .env et définissez uniquement votre ID de projet et d'application. Tout le reste fonctionne par défaut 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 que la boucle fonctionne rapidement.

Lancer l'évolution

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

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

Cette commande permet d'importer le programme de départ, de lancer la recherche et d'exécuter 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 faire des tests.

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. Une fois la boucle terminée, elle imprime les programmes classés et affiche les meilleurs emballages avec matplotlib.

Remarque : Dépannage : PERMISSION_DENIED ou 403 signifie généralement que l'API Discovery Engine n'est pas activée dans le projet. Revérifiez l'étape "Avant de commencer". Si une exécution se termine immédiatement par le message "Échec de la création de l'expérience", 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). Voici deux éléments à vérifier :

• Le score a augmenté. La meilleure sum_of_radii évoluée doit battre la disposition en anneaux concentriques de la graine. 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 ayant produit des cercles qui se chevauchent ou qui sont hors limites a obtenu -inf et a été ignoré dans le classement. Il s'agit d'un retour sur les contraintes, et non d'une erreur.

Il est normal et sain de voir quelques candidats ayant obtenu un score faible ou ayant été ignorés au début de l'exécution. Cela signifie que Gemini explore et que les insights issus des échecs orientent les générations ultérieures.

Vous disposez désormais de la boucle complète : graine → générer → évaluer → score → répéter. Tout le reste dans AlphaEvolve est une variante de l'endroit où l'évaluation s'exécute.

6. Faire évoluer une véritable recherche : TSP

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

1. Augmentez le budget dans .env pour que la recherche plus longue puisse 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 graine est ici une tournée plus proche voisin dans 50 villes. La métrique est neg_tour_length (longueur moyenne négative de la tournée 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.

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

Problème	Langue	Évaluation	Métriques (plus la valeur est élevée, mieux c'est)	Ce qui évolue
circle_packing	Python	local exec()	sum_of_radii	construct_packing()
tsp	Python	local exec()	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 de la méthode du plus proche voisin à des améliorations de type 2-opt / or-opt, des stratégies que vous n'avez pas écrites.

7. Régler la recherche

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

• MAX_PROGRAMS_EVALUATED : nombre de candidats à évaluer. Plus il y a de candidats, plus la recherche est approfondie, et plus le coût et le temps sont élevés.
• CONCURRENCY : nombre de candidats générés en même temps.
• MODEL_1 / MODEL_2 (avec MODEL_1_WEIGHT / MODEL_2_WEIGHT) : mélange pondéré des modèles Gemini qui génèrent des candidats lors de l'exécution du circle packing (le module TSP lit un seul MODEL). 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 performant pour trouver de meilleurs programmes en moins de générations.

Exécutez à nouveau 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 augmentent tous deux les coûts. Comme cet atelier de programmation utilise l'évaluation locale, aucun frais de GPU ne s'applique. Toutefois, vous payez toujours l'utilisation de l'API AlphaEvolve pour chaque candidat généré. en faisant de belles économies.

8. Effectuer un nettoyage

Cet atelier de programmation utilise l'évaluation locale. Il n'y a donc plus rien de facturable en cours d'exécution : aucun cluster, aucun GPU, aucun service déployé. 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-le si vous souhaitez continuer à expérimenter.

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 premières expériences AlphaEvolve sur Google Cloud et fait évoluer deux algorithmes (un algorithme de packing de cercles et une heuristique TSP) en utilisant uniquement un programme de départ, une fonction de scoring et Gemini.

Connaissances acquises

• Fonctionnement de la boucle AlphaEvolve : seed -> génération -> évaluation -> score -> répétition
• Le contrat EVOLVE-BLOCK qui permet à la recherche d'optimiser une recette sans manipuler la métrique
• Comment les scores et les insights sur les échecs orientent la nouvelle génération
• Configurer, exécuter, lire et ajuster un test d'évaluation locale

Autres ateliers de programmation

Elles sont indépendantes. Vous pouvez les effectuer dans n'importe quel ordre.

• Faire évoluer le code compilé avec un évaluateur à distance : faire évoluer un algorithme Rust/C++ évalué par un évaluateur conteneurisé sur Cloud Run.
• Faites évoluer le fine-tuning des LLM sur GKE et Ray : exécutez des évaluations GPU parallèles et intensives sur votre propre cluster.

Documents de référence

• Guide du développeur AlphaEvolve
• Dépôt d'exemples AlphaEvolve
• Exemple de graphique en cercles
• Exemple de TSP