Pierwsze kroki z AlphaEvolve w Google Cloud

1. Wprowadzenie

W tym ćwiczeniu uruchomisz pierwsze 2 eksperymenty AlphaEvolve w Google Cloud. AlphaEvolve to oparta na AI platforma do ewolucyjnego kodowania Google DeepMind. Wykorzystuje ona Gemini do pisania i ulepszania kodu, który jest oceniany na podstawie zdefiniowanego przez Ciebie wskaźnika. Zaczniesz od problemu pakowania kół – prostego zadania geometrycznego, w którym możesz dosłownie obserwować, jak wynik się poprawia. Następnie powtórzysz ten proces w przypadku trudniejszego problemu komiwojażera, aby utrwalić wzorzec.

W obu eksperymentach używana jest lokalna ocena – kod kandydata jest uruchamiany na Twoim komputerze, więc nie ma GPU ani klastra do zarządzania. Jedynym użyciem chmury jest interfejs AlphaEvolve API, który generuje kandydatów.

Jakie zadania wykonasz

• Skonfigurujesz eksperyment AlphaEvolve w projekcie Google Cloud.
• Uruchomisz wyszukiwanie ewolucyjne, które lokalnie ulepsza algorytm pakowania kół.
• Odczytasz wynik, ranking i wizualizację najlepszego rozwiniętego programu.
• Powtórzysz pętlę w przypadku problemu komiwojażera, aby uogólnić wzorzec.
• Dostosujesz budżet wyszukiwania (kandydaci, współbieżność, model).

Czego potrzebujesz

• Przeglądarka internetowa, np. Chrome.
• Projekt Google Cloud z włączonymi rozliczeniami.
• Python w wersji 3.9 lub nowszej oraz uv
• Podstawowa znajomość Pythona i wiersza poleceń.

To ćwiczenie jest przeznaczone dla inżynierów i programistów AI/ML na wszystkich poziomach. Nie jest wymagana znajomość obliczeń ewolucyjnych.

Szacowany czas ukończenia: 45–60 minut.

Koszt: to ćwiczenie korzysta z lokalnej oceny (bez GPU, bez GKE). Opłaty są naliczane tylko za generowanie kandydatów – za korzystanie z interfejsu AlphaEvolve API i tokeny Vertex AI Gemini, które zużywa.

Testowane z: biblioteką klienta AlphaEvolve Cloud w wersji 0.1.0, Pythonem w wersji 3.9 lub nowszej, na przykładach circle_packing i tsp.

2. Zanim zaczniesz

Wybieranie projektu i włączanie interfejsów API

1. W konsoli Google Cloud wybierz lub utwórz projekt z włączonymi rozliczeniami, a następnie ustaw go w terminalu:

gcloud config set project <YOUR_PROJECT_ID>

2. Włącz 2 interfejsy API używane w tym ćwiczeniu – interfejs Discovery Engine API, który obsługuje AlphaEvolve, oraz interfejs Vertex AI API, który obsługuje modele Gemini generujące kandydatów:

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

Znajdowanie identyfikatora aplikacji Gemini Enterprise

AlphaEvolve jest obsługiwany przez Gemini Enterprise (podstawowy interfejs REST to Discovery Engine API). W przypadku ustawienia GE_APP_ID potrzebujesz identyfikatora aplikacji, a nie jej wyświetlanej nazwy.

1. Otwórz stronę aplikacji Gemini Enterprise w swoim projekcie.
2. Kliknij aplikację i skopiuj pole ID (np. gemini-enterprise-1234567890_1234567890123).

Zachowaj ten identyfikator pod ręką – za chwilę wkleisz go do pliku .env. Pozostaw ASSISTANT=default_assistant, chyba że masz skonfigurowanego asystenta niestandardowego.

Uwierzytelnianie, klonowanie i instalowanie

1. Uwierzytelnij się za pomocą domyślnych danych logowania aplikacji:

gcloud auth application-default login

2. Sklonuj repozytorium z przykładami i otwórz je. Wszystkie polecenia będziesz uruchamiać z głównego katalogu tego repozytorium:

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

3. Utwórz środowisko wirtualne i zainstaluj w nim bibliotekę klienta AlphaEvolve:

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

uv venv tworzy w repozytorium katalog .venv; uv pip install -e ".[dev]" instaluje pakiet alpha_evolve (z możliwością edycji) oraz narzędzia testowe. Eksperymenty będziesz uruchamiać za pomocą polecenia uv run, które automatycznie korzysta z tego środowiska.

3. Omówienie pętli AlphaEvolve

Zanim cokolwiek uruchomisz, zapoznaj się z 3 elementami, których potrzebuje AlphaEvolve. Jest to model mentalny, którego będziesz używać w każdym eksperymencie.

Program początkowy i EVOLVE-BLOCK

AlphaEvolve przepisuje tylko kod między 2 znacznikami. Wszystko inne w pliku to stała struktura, której nie można modyfikować. Otwórz examples/circle_packing/src/program.py – program początkowy to proste pakowanie w koncentryczne pierścienie:

# 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

Wszystko poza EVOLVE-BLOCK-START / EVOLVE-BLOCK-END – w tym funkcja evaluate() i sprawdzanie nakładania się – pozostaje niezmienione. To jest cały trik: Gemini może zaproponować dowolny algorytm pakowania, ale nie może zmienić sposobu oceniania kandydata.

Oceniający i wynik

examples/circle_packing/src/evaluate.py uruchamia każdego kandydata w piaskownicy i zwraca wynik. W przypadku pakowania kół wskaźnikiem jest sum_of_radii, a im wyższy wynik, tym lepiej:

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

Jeśli kandydat narusza regułę – koła się nakładają lub wychodzą poza kwadrat – oceniający zwraca -inf oraz obserwację wyjaśniającą, co poszło nie tak. Te obserwacje są przekazywane do Gemini, dzięki czemu następna generacja unika tego samego błędu.

Każdy problem AlphaEvolve ma taką postać: kod, który można wyrazić w EVOLVE-BLOCK, zautomatyzowana ocena i pojedynczy wynik skalarny do zmaksymalizowania.

4. Uruchamianie pierwszego eksperymentu

Konfigurowanie eksperymentu

W głównym katalogu repozytorium utwórz plik .env na podstawie szablonu pakowania kół:

cp examples/circle_packing/example.env .env

Otwórz plik .env i ustaw tylko identyfikator projektu i aplikacji – wszystko inne ma działające wartości domyślne na potrzeby pierwszego uruchomienia:

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

Wartości domyślne generują kandydatów za pomocą mieszanki modeli Gemini (MODEL_1=gemini-3.5-flash z wagą 0.7, MODEL_2=gemini-3.1-pro-preview z wagą 0.3) i ograniczają wyszukiwanie do MAX_PROGRAMS_EVALUATED=10 z CONCURRENCY=4 – wystarczy, aby szybko zobaczyć działanie pętli.

Rozpoczynanie ewolucji

Uruchom eksperyment z głównego katalogu repozytorium:

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

Spowoduje to przesłanie programu początkowego, rozpoczęcie wyszukiwania i uruchomienie lokalnej pętli sterowania do momentu ocenienia 10 kandydatów. Ponieważ wywołujesz moduł bezpośrednio (bez otoki), możesz dokładnie zobaczyć, co się uruchamia, i edytować plik, aby eksperymentować.

Dane wyjściowe powinny być podobne do tych:

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

Wczesni kandydaci zwykle uzyskują wynik w zakresie 0,8–1,0 ; wyszukiwanie poprawia się od tego momentu. Po zakończeniu pętli wyświetla ona programy w rankingu i renderuje najlepsze pakiety za pomocą biblioteki matplotlib.

Uwaga: rozwiązywanie problemów: jeśli uruchomienie natychmiast kończy się komunikatem FAILED_PRECONDITION i „AlphaEvolve wymaga włączenia interfejsu Vertex AI API w tym projekcie”, oznacza to, że brakuje aiplatform.googleapis.com – włącz go zgodnie z instrukcjami w sekcji „Zanim zaczniesz”. Komunikat PERMISSION_DENIED lub 403 zwykle oznacza, że nie jest włączony interfejs Discovery Engine API. Jeśli pojawi się komunikat „Nie udało się utworzyć eksperymentu” i nie wystąpi żaden z tych błędów, oznacza to, że dane logowania lub GE_APP_ID w pliku .env są nieprawidłowe.

5. Odczytywanie wyników

Uruchomienie wyświetla najlepsze programy uszeregowane według sum_of_radii (im wyższy wynik, tym lepiej). Zwróć uwagę na 2 rzeczy:

• Wynik wzrósł. Najlepszy rozwinięty sum_of_radii powinien być lepszy niż układ koncentrycznych pierścieni programu początkowego. Gemini zwykle odkrywa, że koła w pobliżu rogów i krawędzi mogą być większe, i ponownie równoważy wnętrze.
• Nieprawidłowi kandydaci są pomijani. Każdy program, który wygenerował nakładające się lub wykraczające poza granice koła, uzyskał wynik -inf i jest pomijany w rankingu – to nie jest błąd, tylko działanie opinii o ograniczeniach.

Jeśli na początku uruchomienia zobaczysz kilku kandydatów z niskim wynikiem lub pominiętych, jest to normalne i zdrowe – oznacza to, że Gemini eksploruje, a obserwacje z niepowodzeń kierują późniejszymi generacjami.

Masz teraz pełną pętlę: program początkowy -> generowanie -> ocena -> wynik -> powtórzenie. Wszystko inne w AlphaEvolve to wariacja na temat tego, gdzie jest uruchamiana ocena.

6. Rozwijanie prawdziwego wyszukiwania: TSP

Pakowanie kół szybko się zbiega. Aby zobaczyć, jak wyszukiwanie działa w przypadku bardziej złożonego problemu, rozwiń heurystykę problemu komiwojażera. Wzorzec jest identyczny – zmienia się tylko program początkowy i wskaźnik, a przykład TSP ponownie wykorzystuje plik .env (projekt, budżet i współbieżność).

1. Zwiększ budżet w pliku .env, aby dłuższe wyszukiwanie miało miejsce na poprawę:

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

2. Uruchom go z głównego katalogu repozytorium:

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

Program początkowy to trasa najbliższego sąsiada obejmująca 50 miast; wskaźnik to neg_tour_length (ujemna średnia długość trasy w 5 stałych instancjach, więc im wyższy wynik, tym lepiej). Otwórz examples/tsp/src/program.py i zwróć uwagę, że tylko construct_tour(distances, n) znajduje się w EVOLVE-BLOCK.

Te 2 problemy mają ten sam wzorzec, ale różne elementy:

Problem	Język	Ocena	Wskaźnik (im wyższy wynik, tym lepiej)	Co się rozwija
circle_packing	Python	lokalne exec()	sum_of_radii	construct_packing()
tsp	Python	lokalne exec()	neg_tour_length	construct_tour()

Podczas wyszukiwania obserwuj, jak neg_tour_length rośnie (zbliża się do zera), gdy Gemini przechodzi od najbliższego sąsiada do ulepszeń w stylu 2-opt / or-opt – strategii, których nie napisałeś.

7. Dostrajanie wyszukiwania

Teraz, gdy oba uruchomienia działają, dostosuj budżet w pliku .env:

• MAX_PROGRAMS_EVALUATED – liczba kandydatów do ocenienia. Więcej kandydatów = głębsze wyszukiwanie i wyższy koszt/czas.
• CONCURRENCY – liczba kandydatów generowanych jednocześnie.
• MODEL_1 / MODEL_2 (z MODEL_1_WEIGHT / MODEL_2_WEIGHT) – ważona mieszanka modeli Gemini, która generuje kandydatów w uruchomieniu pakowania kół (moduł TSP odczytuje zamiast tego pojedynczy MODEL). Dozwolone wartości to gemini-3.5-flash i gemini-3.1-pro-preview. Przesuń wagę w kierunku silniejszego modelu, aby znaleźć lepsze programy w mniejszej liczbie generacji.

Po każdej zmianie uruchom ponownie za pomocą polecenia uv run python -m examples.circle_packing.src.run_evolution (lub modułu tsp).

Uwaga: zwiększenie MAX_PROGRAMS_EVALUATED i przejście na większy model zwiększa koszt. Ponieważ to ćwiczenie korzysta z lokalnej oceny, nie ma opłat za GPU, ale nadal płacisz za korzystanie z interfejsu AlphaEvolve API i tokeny Vertex AI Gemini za każdego wygenerowanego kandydata. Zacznij od małych kroków.

8. Zwalnianie miejsca

To ćwiczenie korzysta z lokalnej oceny, więc nie ma żadnych rozliczanych elementów – żadnych klastrów, GPU ani wdrożonych usług. Aby całkowicie zresetować płatność:

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

Uwaga: git clean -xfd usuwa plik .env (w tym ustawienia projektu) i katalog .venv. Jeśli chcesz kontynuować eksperymentowanie, pomiń ten krok.

Jeśli projekt został utworzony tylko na potrzeby tego ćwiczenia, usuń go w konsoli, aby zatrzymać wszystkie opłaty.

9. Gratulacje

Gratulacje! Udało Ci się uruchomić pierwsze eksperymenty AlphaEvolve w Google Cloud i rozwinąć 2 algorytmy – pakowanie kół i heurystykę TSP – używając tylko programu początkowego, funkcji oceniania i Gemini.

Czego się nauczysz

• Jak działa pętla AlphaEvolve: program początkowy -> generowanie -> ocena -> wynik -> powtórzenie.
• Umowa EVOLVE-BLOCK , która pozwala wyszukiwaniu optymalizować przepis bez manipulowania wskaźnikiem.
• Jak wyniki i obserwacje dotyczące niepowodzeń kierują następną generacją.
• Jak skonfigurować, uruchomić, odczytać i dostroić eksperyment z lokalną oceną.

Inne ćwiczenia

Są to samodzielne ćwiczenia, które można wykonywać w dowolnej kolejności.

• Rozwijanie skompilowanego kodu za pomocą zdalnego oceniającego: rozwijanie algorytmu Rust/C++ ocenianego przez oceniającego w kontenerze w Cloud Run.
• Rozwijanie dostrajania LLM w GKE + Ray: uruchamianie złożonych, równoległych ocen GPU we własnym klastrze.

Dokumentacja źródłowa

• Przewodnik dla programistów AlphaEvolve
• Repozytorium z przykładami AlphaEvolve
• Przykład pakowania kół
• Przykład TSP