Começar a usar o AlphaEvolve no Google Cloud

1. Introdução

Neste codelab, você vai executar seus dois primeiros experimentos do AlphaEvolve no Google Cloud. O AlphaEvolve é uma estrutura de programação evolutiva guiada por IA do Google DeepMind. Ele usa o Gemini para escrever e melhorar o código, que é avaliado 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 ver o resultado melhorar. Depois, repete em um problema mais difícil do caixeiro viajante para que o padrão fique gravado.

Os dois experimentos usam avaliação local. O código candidato é executado na sua própria 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 do Google Cloud
• Execute uma pesquisa evolutiva que melhora um algoritmo de empacotamento de círculos localmente
• Leia a pontuação, a classificação e a visualização do melhor programa evoluído
• Repita o loop em um problema do caixeiro viajante para generalizar o padrão.
• Ajuste o orçamento de pesquisa (candidatos, simultaneidade, modelo)

O que é necessário

• Um navegador da web, como o Chrome
• Tenha um projeto 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 a conclusão: 45 a 60 minutos.

Custo: este codelab usa a avaliação local (sem GPU, sem GKE). A única cobrança é pelo uso da API AlphaEvolve para gerar candidatos.

Testado com: biblioteca de cliente do Cloud AlphaEvolve v0.1.0, Python 3.9 ou mais recente, nos exemplos circle_packing e tsp.

2. Antes de começar

Selecionar seu projeto e ativar a API

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

2. Ative a API Discovery Engine, que veicula o AlphaEvolve:

gcloud services enable discoveryengine.googleapis.com

Encontrar o ID do app Gemini Enterprise

O AlphaEvolve é veiculado pelo Gemini Enterprise. A superfície REST subjacente é a API Discovery Engine. Você precisa do ID do app, e não do nome de exibição, para a configuração GE_APP_ID.

1. Abra a página Apps do Gemini Enterprise do seu projeto.
2. Clique no app e copie o campo ID (por exemplo, gemini-enterprise-1234567890_1234567890123).

Guarde esse ID, porque você vai colá-lo em .env em breve. Deixe ASSISTANT=default_assistant, a menos que você tenha provisionado um assistente personalizado.

Autenticar, clonar e instalar

1. Autentique para credenciais padrão do aplicativo:

gcloud auth application-default login

2. Clone e abra o repositório de amostras. Você vai executar todos os comandos da raiz deste repositório:

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

3. Crie um ambiente virtual e instale a biblioteca de cliente AlphaEvolve nele:

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

O uv venv cria um .venv no repositório. O 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 em todos os experimentos.

O programa de propagação e o EVOLVE-BLOCK

O AlphaEvolve só reescreve o código entre dois marcadores. Todo o resto no arquivo é um scaffolding fixo que não pode ser tocado. 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 de 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 todo: o Gemini pode propor qualquer algoritmo de empacotamento que quiser, mas não pode mudar a forma como um candidato é avaliado.

O avaliador e a pontuação

O examples/circle_packing/src/evaluate.py executa cada candidato em um sandbox 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 violar uma regra (os círculos se sobrepõem ou saem do quadrado), o avaliador vai 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.

Esta é a forma que todo problema do AlphaEvolve assume: código que pode ser expresso em um EVOLVE-BLOCK, uma avaliação automatizável e uma única pontuação escalar a ser maximizada.

4. Executar seu primeiro experimento

Configurar o experimento

Na raiz do repositório, crie seu .env com base no modelo de agrupamento circular:

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 funcionais 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 combinação 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 ver o loop funcionar rapidamente.

Comece a evolução

Execute o experimento na raiz do repositório:

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

Isso faz upload do programa de sementes, 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 está sendo executado e editar o arquivo para testar.

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 candidatos iniciais geralmente têm uma pontuação entre 0,8 e 1,0, e a pesquisa melhora a partir daí. Quando o loop termina, ele imprime os programas classificados e renderiza os principais pacotes com matplotlib.

Observação:solução de problemas: PERMISSION_DENIED ou 403 geralmente significa que a API Discovery Engine não está ativada no projeto. Verifique novamente a etapa "Antes de começar". Uma execução que termina imediatamente com "Falha ao criar o experimento" significa que as credenciais ou GE_APP_ID em .env estão incorretos.

5. Ler os resultados

A execução mostra os principais programas classificados por sum_of_radii (quanto maior, melhor). Duas coisas para procurar:

• A pontuação aumentou. O melhor sum_of_radii evoluído precisa superar o layout de anel concêntrico da semente. O Gemini geralmente descobre que os círculos perto dos cantos e das bordas podem crescer mais e reequilibra o interior.
• Os candidatos inválidos são ignorados. Qualquer programa que produziu círculos sobrepostos ou fora dos limites recebeu a pontuação -inf e foi ignorado no ranking. Esse é o feedback de restrição funcionando, não um erro.

É normal e saudável ver alguns candidatos com pontuação baixa ou ignorados no início da execução. Isso significa que o Gemini está explorando, e os insights dos erros orientam as gerações posteriores.

Agora você tem o ciclo completo: geração de ideias -> 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 o trabalho de pesquisa em um problema mais complexo, desenvolva 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).

1. Aumente o orçamento em .env para 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

2. 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 por 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 peças diferentes:

Problema	Idioma	Avaliação	Métrica (quanto maior, melhor)	O que evolui
circle_packing	Python	local exec()	sum_of_radii	construct_packing()
tsp	Python	local exec()	neg_tour_length	construct_tour()

À medida que a pesquisa é executada, observe neg_tour_length subir (chegar mais perto de zero) conforme o Gemini vai além do vizinho mais próximo em direção a melhorias de 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 serão avaliados. Mais candidatos = uma pesquisa mais detalhada e maior custo/tempo.
• CONCURRENCY: quantos candidatos são gerados de uma só vez.
• MODEL_1 / MODEL_2 (com MODEL_1_WEIGHT / MODEL_2_WEIGHT): a combinação ponderada de modelos do Gemini que geram candidatos na execução de empacotamento de círculos. O módulo TSP lê um único MODEL. Os valores permitidos são gemini-3.5-flash e gemini-3.1-pro-preview. Mude o peso para o modelo mais forte e encontre 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 por candidato gerado. Vá aos poucos.

8. Limpar

Este codelab usa a avaliação local. Portanto, não há nada faturável em execução: nenhum cluster, nenhuma GPU, nenhum serviço implantado. Para redefinir totalmente o processo de finalização da compra:

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

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 desenvolveu dois algoritmos (um de 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: seed -> generate -> evaluate -> score -> repeat
• O contrato EVOLVE-BLOCK que permite que a pesquisa otimize uma receita sem manipular 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

Elas são independentes e podem ser feitas em qualquer ordem.

• Evoluir código compilado com um avaliador remoto: evolua um algoritmo Rust/C++ avaliado por um avaliador em contêiner no Cloud Run.
• Evolua o ajuste fino de LLMs no GKE + Ray: execute avaliações pesadas e paralelas de GPU no seu próprio cluster.

Documentos de referência

• Guia do desenvolvedor do AlphaEvolve
• Repositório de exemplos do AlphaEvolve
• Exemplo de agrupamento circular
• Exemplo de TSP