1. Introducción
En este codelab, ejecutarás tus dos primeros experimentos de AlphaEvolve en Google Cloud. AlphaEvolve es el framework de codificación evolutiva guiada por IA de Google DeepMind: usa Gemini para escribir y mejorar el código, que se califica con una métrica que defines. Comenzarás con el empaquetamiento de círculos, un pequeño problema de geometría en el que puedes ver cómo mejora el resultado, y luego lo repetirás en un problema más difícil del agente viajero para que se mantenga el patrón.
Ambos experimentos usan la evaluación local : el código candidato se ejecuta en tu propia máquina, por lo que no hay GPU ni clúster para administrar. El único uso de la nube es la API de AlphaEvolve que genera candidatos.
Actividades
- Configurar un experimento de AlphaEvolve en tu proyecto de Google Cloud
- Ejecutar una búsqueda evolutiva que mejore un algoritmo de empaquetamiento de círculos de forma local
- Leer la puntuación, la clasificación y la visualización del mejor programa evolucionado
- Repetir el bucle en un problema del agente viajero para generalizar el patrón
- Ajustar el presupuesto de búsqueda (candidatos, simultaneidad, modelo)
Requisitos
- Un navegador web, como Chrome
- Un proyecto de Google Cloud con la facturación habilitada.
- Python 3.9 o una versión posterior y
uv - Conocimientos básicos sobre Python y la línea de comandos
Este codelab está destinado a ingenieros y desarrolladores de IA/AA de todos los niveles. No se requiere experiencia en computación evolutiva.
Tiempo estimado para completar esta actividad: 45 a 60 minutos.
Costo: Este codelab usa la evaluación local (sin GPU, sin GKE). El único cargo es el uso de la API de AlphaEvolve para generar candidatos.
Probado con: la biblioteca cliente de Cloud de AlphaEvolve v0.1.0, Python 3.9+, en los ejemplos circle_packing y tsp.
2. Antes de comenzar
Selecciona tu proyecto y habilita la API
- En la consola de Google Cloud, selecciona o crea un proyecto con la facturación habilitada y, luego, configúralo en tu terminal:
gcloud config set project <YOUR_PROJECT_ID>
- Habilita la API de Discovery Engine, que entrega AlphaEvolve:
gcloud services enable discoveryengine.googleapis.com
Busca el ID de tu app de Gemini Enterprise
AlphaEvolve se entrega a través de Gemini Enterprise (la superficie REST subyacente es la API de Discovery Engine). Necesitas el ID de tu app, no su nombre visible, para la configuración de GE_APP_ID.
- Abre la página de apps de Gemini Enterprise para tu proyecto.
- Haz clic en tu app y copia el campo ID (por ejemplo,
gemini-enterprise-1234567890_1234567890123).
Autentica, clona y, luego, instala
- Autentica las credenciales predeterminadas de la aplicación:
gcloud auth application-default login
- Clona el repositorio de muestras y ábrelo. Ejecutarás todos los comandos desde la raíz de este repositorio:
git clone https://github.com/Google-Cloud-AI/alphaevolve-on-googlecloud.git
cd alphaevolve-on-googlecloud
- Crea un entorno virtual y, luego, instala la biblioteca cliente de AlphaEvolve en él:
uv venv
uv pip install -e ".[dev]"
uv venv crea un .venv en el repositorio; uv pip install -e ".[dev]" instala el paquete alpha_evolve (editable) y las herramientas de prueba. Lanzarás experimentos con uv run, que usa este entorno automáticamente.
3. Comprende el bucle de AlphaEvolve
Antes de ejecutar cualquier acción, comprende las tres partes que necesita AlphaEvolve. Este es el modelo mental que volverás a usar para cada experimento.
El programa inicial y el EVOLVE-BLOCK
AlphaEvolve solo vuelve a escribir el código entre dos marcadores. Todo lo demás en el archivo es un andamio fijo que no puede tocar. Abre examples/circle_packing/src/program.py. La semilla es un empaquetamiento simple de anillos concéntricos:
# 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
Todo lo que está fuera EVOLVE-BLOCK-START / EVOLVE-BLOCK-END , incluida la función evaluate() y las verificaciones de superposición, permanece congelado. Esa separación es todo el truco: Gemini puede proponer cualquier algoritmo de empaquetamiento que desee, pero no puede cambiar la forma en que se califica a un candidato.
El evaluador y la puntuación
examples/circle_packing/src/evaluate.py ejecuta cada candidato en un entorno de pruebas y devuelve una puntuación. Para el empaquetamiento de círculos, la métrica es sum_of_radii, y cuanto más alta sea, mejor:
CIRCLE_PACKING_EVALUATION_METRIC = "sum_of_radii"
CIRCLE_PACKING_EVALUATION_INPUTS = {"n": 26}
Si un candidato incumple una regla (los círculos se superponen o salen del cuadrado), el evaluador devuelve -inf más una estadística que explica qué salió mal. Esas estadísticas se envían a Gemini para que la próxima generación evite el mismo error.
4. Ejecuta tu primer experimento
Configura el experimento
Desde la raíz del repositorio, crea tu .env a partir de la plantilla de empaquetamiento de círculos:
cp examples/circle_packing/example.env .env
Abre .env y configura solo tu proyecto y el ID de la app. Todo lo demás tiene valores predeterminados que funcionan para una primera ejecución:
PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>
Los valores predeterminados generan candidatos con una combinación de modelos de Gemini (MODEL_1=gemini-3.5-flash con un peso de 0.7, MODEL_2=gemini-3.1-pro-preview en 0.3) y limitan la búsqueda a MAX_PROGRAMS_EVALUATED=10 con CONCURRENCY=4, lo suficiente para ver el bucle funcionar rápidamente.
Comienza la evolución
Ejecuta el experimento desde la raíz del repositorio:
uv run python -m examples.circle_packing.src.run_evolution
Esto sube el programa inicial, inicia la búsqueda y ejecuta el bucle de control local hasta que se hayan evaluado 10 candidatos. Como llamas al módulo directamente (sin wrapper), puedes ver exactamente lo que se ejecuta y editar el archivo para experimentar.
Deberías ver un resultado similar a este:
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).
Por lo general, los candidatos iniciales obtienen una puntuación en el rango de 0.8 a 1.0 ; la búsqueda mejora a partir de ahí. Cuando finaliza el bucle, imprime los programas clasificados y renderiza los empaquetamientos principales con matplotlib.
Nota: Solución de problemas: PERMISSION_DENIED o 403 suelen significar que la API de Discovery Engine no está habilitada en el proyecto. Vuelve a verificar el paso "Antes de comenzar". Una ejecución que finaliza de inmediato con "No se pudo crear el experimento" significa que las credenciales o GE_APP_ID en .env son incorrectas.
5. Lee los resultados
La ejecución imprime los programas principales clasificados por sum_of_radii (cuanto más alto sea, mejor). Hay dos cosas que debes buscar:
- Aumentó la puntuación. El mejor
sum_of_radiievolucionado debería superar el diseño de anillos concéntricos de la semilla. Por lo general, Gemini descubre que los círculos cerca de las esquinas y los bordes pueden crecer más y reequilibra el interior. - Se omiten los candidatos no válidos. Cualquier programa que haya producido círculos superpuestos o fuera de los límites obtuvo una puntuación de
-infy se omite en la clasificación. Ese es el funcionamiento de los comentarios de restricción, no un error.
Ahora tienes el bucle completo: semilla -> generar -> evaluar -> calificar -> repetir. Todo lo demás en AlphaEvolve es una variación de dónde se ejecuta la evaluación.
6. Evoluciona una búsqueda real: TSP
El empaquetamiento de círculos converge rápidamente. Para sentir que la búsqueda funciona en un problema más importante, evoluciona una heurística del problema del agente viajero. El patrón es idéntico: solo cambian la semilla y la métrica, y el ejemplo de TSP vuelve a usar tu .env (proyecto, presupuesto y simultaneidad).
- Aumenta el presupuesto en
.envpara que la búsqueda más larga tenga espacio para mejorar:
# in .env — raise the generation cap and the evaluation target together
MAX_PROGRAMS_GENERATED=20
MAX_PROGRAMS_EVALUATED=20
- Ejecútalo desde la raíz del repositorio:
uv run python -m examples.tsp.src.run_evolution
La semilla aquí es un recorrido de vecino más cercano por más de 50 ciudades; la métrica es neg_tour_length (longitud promedio negativa del recorrido en 5 instancias fijas, por lo que cuanto más alta sea, mejor). Abre examples/tsp/src/program.py y ten en cuenta que solo construct_tour(distances, n) está dentro del EVOLVE-BLOCK.
Los dos problemas son el mismo patrón con diferentes partes:
Problema | Idioma | Evaluación | Métrica (cuanto más alta sea, mejor) | Qué evoluciona |
| Python |
|
|
|
| Python |
|
|
|
A medida que se ejecuta la búsqueda, observa cómo aumenta neg_tour_length (se acerca a cero) a medida que Gemini va más allá del vecino más cercano hacia mejoras de estilo 2-opt o or-opt, estrategias que no escribiste.
7. Ajusta la búsqueda
Ahora que ambas ejecuciones funcionan, ajusta el presupuesto en .env:
MAX_PROGRAMS_EVALUATED: cuántos candidatos calificar. Más candidatos = una búsqueda más profunda y un costo/tiempo más alto.CONCURRENCY: cuántos candidatos se generan en tránsito a la vez.MODEL_1/MODEL_2(conMODEL_1_WEIGHT/MODEL_2_WEIGHT): la combinación ponderada de modelos de Gemini que generan candidatos en la ejecución de empaquetamiento de círculos (el módulo TSP lee un soloMODELen su lugar). Los valores permitidos songemini-3.5-flashygemini-3.1-pro-preview. Cambia el peso hacia el modelo más potente para encontrar mejores programas en menos generaciones.
Vuelve a ejecutar con uv run python -m examples.circle_packing.src.run_evolution (o el módulo tsp) después de cada cambio.
Nota: Aumentar MAX_PROGRAMS_EVALUATED y cambiar a un modelo más grande aumentan el costo. Como este codelab usa la evaluación local, no hay cargo por GPU, pero aún pagas por el uso de la API de AlphaEvolve por candidato generado. Empieza de a poco.
8. Limpia
Este codelab usa la evaluación local, por lo que no queda nada facturable en ejecución : no hay clústeres, ni GPUs ni servicios implementados. Para restablecer por completo tu confirmación de la compra, haz lo siguiente:
git clean -xfd # removes .env, .venv, and generated outputs
Nota: git clean -xfd borra tu .env (incluida la configuración del proyecto) y el .venv. Omítelo si quieres seguir experimentando.
Si creaste un proyecto solo para este codelab, bórralo en la consola para detener todos los cargos.
9. Felicitaciones
¡Felicitaciones! Ejecutaste tus primeros experimentos de AlphaEvolve en Google Cloud y evolucionaste dos algoritmos (un empaquetamiento de círculos y una heurística de TSP) usando solo un programa inicial, una función de puntuación y Gemini.
Qué aprendiste
- Cómo funciona el bucle de AlphaEvolve: semilla -> generar -> evaluar -> calificar -> repetir
- El contrato EVOLVE-BLOCK que permite que la búsqueda optimice una receta sin jugar con la métrica
- Cómo las puntuaciones y las estadísticas de fallas guían a la próxima generación
- Cómo configurar, ejecutar, leer y ajustar un experimento de evaluación local
Otros codelabs
Son independientes, por lo que puedes hacerlos en cualquier orden.
- Evoluciona el código compilado con un evaluador remoto: evoluciona un algoritmo de Rust/C++ calificado por un evaluador en contenedores en Cloud Run.
- Evoluciona el ajuste de LLM en GKE + Ray: ejecuta evaluaciones pesadas y paralelas de GPU en tu propio clúster.