1. Introdução
Neste codelab, você vai executar seus dois primeiros experimentos do AlphaEvolve no Google Cloud. O AlphaEvolve é uma estrutura de codificação evolutiva orientada por IA do Google DeepMind: ele usa o Gemini para escrever e melhorar o código, classificado por uma métrica definida por você. Você começa com o empacotamento de círculos, um pequeno problema de geometria em que é possível observar o resultado melhorar, e depois repete em um problema mais difícil do caixeiro-viajante para que o padrão seja mantido.
Os dois experimentos usam a avaliação local : o código candidato é executado na sua máquina, então não há GPU nem cluster para gerenciar. O único uso da nuvem é a API AlphaEvolve, que gera candidatos.
Atividades deste laboratório
- Configurar um experimento do AlphaEvolve no seu projeto na nuvem do Google Cloud
- Executar uma pesquisa evolutiva que melhora um algoritmo de empacotamento de círculos localmente
- Ler a pontuação, a classificação e a visualização do melhor programa evoluído
- Repetir o loop em um problema do caixeiro-viajante para generalizar o padrão
- Ajustar o orçamento de pesquisa (candidatos, simultaneidade, modelo)
O que é necessário
- Um navegador da web, como o Chrome
- Tenha um projeto na nuvem do Google Cloud com o faturamento ativado.
- Python 3.9 ou mais recente e
uv - Conhecimento básico de Python e da linha de comando
Este codelab é destinado a engenheiros e desenvolvedores de IA/ML de todos os níveis. Não é necessário ter experiência em computação evolutiva.
Tempo estimado para conclusão: 45 a 60 minutos.
Custo: este codelab usa a avaliação local (sem GPU, sem GKE). As únicas cobranças são para gerar candidatos: uso da API AlphaEvolve e dos tokens do Gemini da Vertex AI que ela consome.
Testado com: a biblioteca de cliente do AlphaEvolve Cloud v0.1.0, Python 3.9 ou mais recente, nos exemplos circle_packing e tsp.
2. Antes de começar
Selecionar o projeto e ativar as APIs
- No console do Google Cloud, selecione ou crie um projeto com o faturamento ativado e defina-o no terminal:
gcloud config set project <YOUR_PROJECT_ID>
- Ative as duas APIs usadas neste codelab: a API Discovery Engine, que atende o AlphaEvolve, e a API Vertex AI, que atende os modelos do Gemini que geram candidatos:
gcloud services enable \
discoveryengine.googleapis.com \
aiplatform.googleapis.com
Encontrar o ID do app Gemini Enterprise
O AlphaEvolve é oferecido pelo Gemini Enterprise (a superfície REST subjacente é a API Discovery Engine). Você precisa do ID do app, não do nome de exibição, para a configuração GE_APP_ID.
- Abra a página de apps do Gemini Enterprise do seu projeto.
- Clique no app e copie o campo ID (por exemplo,
gemini-enterprise-1234567890_1234567890123).
Autenticar, clonar e instalar
- Autentique para o Application Default Credentials:
gcloud auth application-default login
- Clone o repositório de amostras e abra-o. Você vai executar todos os comandos dessa raiz do repositório:
git clone https://github.com/Google-Cloud-AI/alphaevolve-on-googlecloud.git
cd alphaevolve-on-googlecloud
- Crie um ambiente virtual e instale a biblioteca de cliente do AlphaEvolve nele:
uv venv
uv pip install -e ".[dev]"
uv venv cria um .venv no repositório; uv pip install -e ".[dev]" instala o pacote alpha_evolve (editável) e as ferramentas de teste. Você vai iniciar experimentos com uv run, que usa esse ambiente automaticamente.
3. Entender o loop do AlphaEvolve
Antes de executar qualquer coisa, entenda as três partes de que o AlphaEvolve precisa. Esse é o modelo mental que você vai reutilizar para cada experimento.
O programa de semente e o EVOLVE-BLOCK
O AlphaEvolve só reescreve o código entre dois marcadores. Todo o resto do arquivo é uma estrutura fixa que não pode ser modificada. Abra examples/circle_packing/src/program.py. A semente é um empacotamento simples de anéis 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
Tudo fora EVOLVE-BLOCK-START / EVOLVE-BLOCK-END, incluindo a função evaluate() e as verificações de sobreposição, permanece congelado. Essa separação é o truque: o Gemini pode propor qualquer algoritmo de empacotamento que quiser, mas não pode mudar a forma como um candidato é classificado.
O avaliador e a pontuação
examples/circle_packing/src/evaluate.py executa cada candidato em um ambiente de simulação e retorna uma pontuação. Para o empacotamento de círculos, a métrica é sum_of_radii, e quanto maior, melhor:
CIRCLE_PACKING_EVALUATION_METRIC = "sum_of_radii"
CIRCLE_PACKING_EVALUATION_INPUTS = {"n": 26}
Se um candidato quebrar uma regra (os círculos se sobrepõem ou saem do quadrado), o avaliador retornará -inf mais um insight explicando o que deu errado. Esses insights são enviados ao Gemini para que a próxima geração evite o mesmo erro.
4. Executar seu primeiro experimento
Configurar o experimento
Na raiz do repositório, crie seu .env com base no modelo de empacotamento de círculos:
cp examples/circle_packing/example.env .env
Abra .env e defina apenas o ID do projeto e do app. Todo o resto tem padrões de trabalho para uma primeira execução:
PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>
Os padrões geram candidatos com uma mistura de modelos do Gemini (MODEL_1=gemini-3.5-flash com peso 0.7, MODEL_2=gemini-3.1-pro-preview com 0.3) e limitam a pesquisa a MAX_PROGRAMS_EVALUATED=10 com CONCURRENCY=4, o suficiente para observar o loop funcionar rapidamente.
Iniciar a evolução
Execute o experimento na raiz do repositório:
uv run python -m examples.circle_packing.src.run_evolution
Isso faz o upload do programa de semente, inicia a pesquisa e executa o loop de controle local até que 10 candidatos sejam avaliados. Como você está chamando o módulo diretamente (sem wrapper), é possível ver exatamente o que é executado e editar o arquivo para fazer experimentos.
Você verá uma saída como:
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).
Os primeiros candidatos normalmente têm uma pontuação na faixa de 0,8 a 1,0 ; a pesquisa melhora a partir daí. Quando o loop termina, ele imprime os programas classificados e renderiza os principais empacotamentos com matplotlib.
Observação:solução de problemas: uma execução que termina imediatamente com FAILED_PRECONDITION e "O AlphaEvolve exige que a API Vertex AI esteja ativada neste projeto" significa que aiplatform.googleapis.com está ausente. Ative-o conforme mostrado em "Antes de começar". PERMISSION_DENIED ou 403 geralmente significa que a API Discovery Engine não está ativada. Uma mensagem de "Falha ao criar o experimento" sem nenhuma dessas opções significa que as credenciais ou o GE_APP_ID em .env estão incorretos.
5. Ler os resultados
A execução imprime os principais programas classificados por sum_of_radii (quanto maior, melhor). Duas coisas a serem observadas:
- A pontuação aumentou. O melhor
sum_of_radiievoluído precisa superar o layout de anéis concêntricos da semente. O Gemini normalmente descobre que os círculos próximos aos cantos e bordas podem crescer mais e reequilibra o interior. - Os candidatos inválidos são ignorados. Qualquer programa que tenha produzido círculos sobrepostos ou fora dos limites teve uma pontuação de
-infe foi ignorado na classificação. Esse é o feedback de restrição funcionando, não um erro.
Agora você tem o loop completo: semente -> gerar -> avaliar -> pontuar -> repetir. Todo o resto no AlphaEvolve é uma variação de onde a avaliação é executada.
6. Evoluir uma pesquisa real: TSP
O empacotamento de círculos converge rapidamente. Para sentir a pesquisa funcionar em um problema mais substancial, evolua uma heurística do problema do caixeiro-viajante. O padrão é idêntico. Apenas a semente e a métrica mudam, e o exemplo de TSP reutiliza seu .env (projeto, orçamento e simultaneidade).
- Aumente o orçamento em
.envpara que a pesquisa mais longa tenha espaço para melhorar:
# in .env — raise the generation cap and the evaluation target together
MAX_PROGRAMS_GENERATED=20
MAX_PROGRAMS_EVALUATED=20
- Execute-o na raiz do repositório:
uv run python -m examples.tsp.src.run_evolution
A semente aqui é um tour de vizinho mais próximo em 50 cidades. A métrica é neg_tour_length (comprimento médio negativo do tour em cinco instâncias fixas, então quanto maior, melhor). Abra examples/tsp/src/program.py e observe que apenas construct_tour(distances, n) está dentro do EVOLVE-BLOCK.
Os dois problemas são o mesmo padrão com partes diferentes:
Problema | Idioma | Avaliação | Métrica (quanto maior, melhor) | O que evolui |
| Python |
|
|
|
| Python |
|
|
|
À medida que a pesquisa é executada, observe neg_tour_length subir (aproximar-se de zero) à medida que o Gemini avança além do vizinho mais próximo em direção a melhorias de estilo 2-opt / or-opt, estratégias que você não escreveu.
7. Ajustar a pesquisa
Agora que as duas execuções funcionam, ajuste o orçamento em .env:
MAX_PROGRAMS_EVALUATED: quantos candidatos classificar. Mais candidatos = uma pesquisa mais profunda e maior custo/tempo.CONCURRENCY: quantos candidatos são gerados em trânsito de uma só vez.MODEL_1/MODEL_2(comMODEL_1_WEIGHT/MODEL_2_WEIGHT): a mistura ponderada de modelos do Gemini que geram candidatos na execução de empacotamento de círculos (o módulo TSP lê um únicoMODEL). Os valores permitidos sãogemini-3.5-flashegemini-3.1-pro-preview. Mude o peso para o modelo mais forte para encontrar programas melhores em menos gerações.
Execute novamente com uv run python -m examples.circle_packing.src.run_evolution (ou o módulo tsp) após cada mudança.
Observação:aumentar MAX_PROGRAMS_EVALUATED e mudar para um modelo maior aumentam o custo. Como este codelab usa a avaliação local, não há cobrança de GPU, mas você ainda paga pelo uso da API AlphaEvolve e pelos tokens do Gemini da Vertex AI por candidato gerado. Vá aos poucos.
8. Limpar
Este codelab usa a avaliação local, então não há nada faturável em execução : sem clusters, sem GPUs, sem serviços implantados. Para redefinir totalmente o checkout:
git clean -xfd # removes .env, .venv, and generated outputs
Observação: git clean -xfd exclui seu .env (incluindo as configurações do projeto) e o .venv. Pule se quiser continuar experimentando.
Se você criou um projeto apenas para este codelab, exclua-o no console para interromper todas as cobranças.
9. Parabéns
Parabéns! Você executou seus primeiros experimentos do AlphaEvolve no Google Cloud e evoluiu dois algoritmos (um empacotamento de círculos e uma heurística de TSP) usando apenas um programa de semente, uma função de pontuação e o Gemini.
O que você aprendeu
- Como o loop do AlphaEvolve funciona: semente -> gerar -> avaliar -> pontuar -> repetir
- O contrato EVOLVE-BLOCK que permite que a pesquisa otimize uma receita sem usar a métrica
- Como as pontuações e os insights de falha orientam a próxima geração
- Como configurar, executar, ler e ajustar um experimento de avaliação local
Outros codelabs
Eles são independentes. Faça-os em qualquer ordem.
- Evoluir código compilado com um avaliador remoto: evolua um algoritmo Rust/C++ classificado por um avaliador em contêiner no Cloud Run.
- Evoluir o ajuste fino de LLM no GKE + Ray: execute avaliações de GPU paralelas e pesadas no seu próprio cluster.