Mulai menggunakan AlphaEvolve di Google Cloud

1. Pengantar

Dalam codelab ini, Anda akan menjalankan dua eksperimen AlphaEvolve pertama di Google Cloud. AlphaEvolve adalah framework coding evolusioner yang dipandu AI dari Google DeepMind: framework ini menggunakan Gemini untuk menulis dan meningkatkan kualitas kode, yang diberi skor berdasarkan metrik yang Anda tentukan. Anda mulai dengan pengemasan lingkaran — masalah geometri kecil yang hasilnya dapat Anda lihat secara harfiah menjadi lebih baik — lalu ulangi pada Masalah Salesman Keliling yang lebih sulit sehingga polanya melekat.

Kedua eksperimen menggunakan evaluasi lokal — kode kandidat berjalan di komputer Anda sendiri, sehingga tidak ada GPU dan tidak ada cluster yang perlu dikelola. Satu-satunya penggunaan cloud adalah AlphaEvolve API yang menghasilkan kandidat.

Yang akan Anda lakukan

• Konfigurasi eksperimen AlphaEvolve terhadap project Google Cloud Anda
• Menjalankan penelusuran evolusioner yang meningkatkan algoritma pengemasan lingkaran secara lokal
• Baca skor, peringkat, dan visualisasi program yang paling berkembang
• Ulangi loop pada Masalah Salesman Keliling untuk menggeneralisasi pola
• Sesuaikan anggaran penelusuran (kandidat, konkurensi, model)

Yang Anda butuhkan

• Browser web seperti Chrome
• Project Google Cloud yang mengaktifkan penagihan
• Python 3.9 atau yang lebih baru dan uv
• Pemahaman dasar tentang Python dan command line

Codelab ini ditujukan bagi engineer dan developer AI/ML dari semua tingkat keahlian. Tidak diperlukan latar belakang komputasi evolusioner.

Estimasi waktu penyelesaian: 45–60 menit.

Biaya: codelab ini menggunakan evaluasi lokal (tanpa GPU, tanpa GKE). Satu-satunya biaya adalah untuk membuat kandidat — penggunaan AlphaEvolve API dan token Vertex AI Gemini yang digunakan.

Diuji dengan: library klien AlphaEvolve Cloud v0.1.0, Python 3.9+, pada contoh circle_packing dan tsp.

2. Sebelum memulai

Pilih project Anda dan aktifkan API

1. Di Konsol Google Cloud, pilih atau buat project dengan penagihan diaktifkan, lalu tetapkan di terminal Anda:

gcloud config set project <YOUR_PROJECT_ID>

2. Aktifkan dua API yang digunakan codelab ini — Discovery Engine API, yang melayani AlphaEvolve, dan Vertex AI API, yang melayani model Gemini yang membuat kandidat:

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

Menemukan ID aplikasi Gemini Enterprise Anda

AlphaEvolve ditayangkan melalui Gemini Enterprise (REST API yang mendasarinya adalah Discovery Engine API). Anda memerlukan ID aplikasi Anda — bukan nama tampilannya — untuk setelan GE_APP_ID.

1. Buka halaman aplikasi Gemini Enterprise untuk project Anda.
2. Klik aplikasi Anda dan salin kolom ID (misalnya, gemini-enterprise-1234567890_1234567890123).

Simpan ID ini — Anda akan menempelkannya ke .env sebentar lagi. Biarkan ASSISTANT=default_assistant kecuali jika Anda telah menyediakan asisten kustom.

Mengautentikasi, meng-clone, dan menginstal

1. Melakukan autentikasi untuk kredensial default aplikasi:

gcloud auth application-default login

2. Buat clone repo contoh dan buka. Anda akan menjalankan setiap perintah dari root repo ini:

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

3. Buat lingkungan virtual dan instal library klien AlphaEvolve ke dalamnya:

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

uv venv membuat .venv di repo; uv pip install -e ".[dev]" menginstal paket alpha_evolve (dapat diedit) plus alat pengujian. Anda akan meluncurkan eksperimen dengan uv run, yang menggunakan lingkungan ini secara otomatis.

3. Memahami loop AlphaEvolve

Sebelum menjalankan apa pun, pahami tiga bagian yang dibutuhkan AlphaEvolve. Ini adalah model mental yang akan Anda gunakan kembali untuk setiap eksperimen.

Program seed dan EVOLVE-BLOCK

AlphaEvolve hanya menulis ulang kode di antara dua penanda. Semua hal lain dalam file adalah perancah tetap yang tidak dapat disentuh. Buka examples/circle_packing/src/program.py — seed adalah pengemasan cincin konsentris sederhana:

# 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

Semua yang di luar EVOLVE-BLOCK-START / EVOLVE-BLOCK-END — termasuk fungsi evaluate() dan pemeriksaan tumpang-tindih — tetap dibekukan. Pemisahan tersebut adalah triknya: Gemini dapat mengusulkan algoritma pengemasan apa pun yang diinginkannya, tetapi tidak dapat mengubah cara pemberian skor kandidat.

Evaluator dan skor

examples/circle_packing/src/evaluate.py menjalankan setiap kandidat di sandbox dan menampilkan skor. Untuk pengemasan lingkaran, metriknya adalah sum_of_radii, dan makin tinggi makin baik:

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

Jika kandidat melanggar aturan — lingkaran tumpang-tindih atau keluar dari persegi — evaluator akan menampilkan -inf ditambah insight yang menjelaskan apa yang salah. Insight tersebut dikirim kembali ke Gemini sehingga generasi berikutnya tidak melakukan kesalahan yang sama.

Inilah bentuk setiap masalah AlphaEvolve: kode yang dapat Anda ekspresikan dalam EVOLVE-BLOCK, evaluasi yang dapat diotomatisasi, dan skor skalar tunggal untuk dimaksimalkan.

4. Menjalankan eksperimen pertama

Mengonfigurasi eksperimen

Dari root repo, buat .env Anda dari template pengemasan lingkaran:

cp examples/circle_packing/example.env .env

Buka .env dan tetapkan project dan ID aplikasi Anda saja — semuanya memiliki default yang berfungsi untuk menjalankan pertama kali:

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

Setelan default menghasilkan kandidat dengan campuran model Gemini (MODEL_1=gemini-3.5-flash dengan bobot 0.7, MODEL_2=gemini-3.1-pro-preview dengan 0.3) dan membatasi penelusuran hingga MAX_PROGRAMS_EVALUATED=10 dengan CONCURRENCY=4 — cukup untuk melihat cara kerja loop dengan cepat.

Mulai evolusi

Jalankan eksperimen dari root repo:

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

Proses ini mengupload program awal, memulai penelusuran, dan menjalankan loop kontrol lokal hingga 10 kandidat telah dievaluasi. Karena Anda memanggil modul secara langsung (tanpa wrapper), Anda dapat melihat dengan tepat apa yang berjalan — dan mengedit file untuk bereksperimen.

Anda akan melihat output yang mirip dengan:

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

Kandidat awal biasanya memiliki skor dalam rentang 0,8–1,0; penelusuran akan meningkat dari sana. Setelah loop selesai, program akan mencetak program yang diberi peringkat dan merender paket teratas dengan matplotlib.

Catatan: Pemecahan masalah: jika eksekusi langsung berakhir dengan FAILED_PRECONDITION dan "AlphaEvolve requires the Vertex AI API to be enabled in this project", berarti aiplatform.googleapis.com tidak ada — aktifkan seperti yang ditunjukkan di "Sebelum memulai". PERMISSION_DENIED atau 403 biasanya berarti Discovery Engine API tidak diaktifkan. "Gagal membuat eksperimen" tanpa salah satu dari keduanya berarti kredensial atau GE_APP_ID di .env salah.

5. Membaca hasilnya

Run mencetak program teratas yang diberi peringkat berdasarkan sum_of_radii (makin tinggi makin baik). Dua hal yang perlu diperhatikan:

• Skornya naik. sum_of_radii yang berevolusi terbaik harus mengalahkan tata letak cincin konsentris seed. Gemini biasanya menemukan bahwa lingkaran di dekat sudut dan tepi dapat tumbuh lebih besar, dan menyeimbangkan kembali bagian dalamnya.
• Kandidat yang tidak valid akan dilewati. Program apa pun yang menghasilkan lingkaran yang tumpang-tindih atau di luar batas diberi skor -inf dan dilewati dalam peringkat — itulah cara kerja masukan batasan, bukan error.

Melihat beberapa kandidat yang dilewati atau memiliki skor rendah di awal proses adalah hal yang normal dan baik. Artinya, Gemini sedang melakukan eksplorasi, dan insight dari kegagalan akan memandu generasi berikutnya.

Sekarang Anda memiliki loop penuh: inisiasi -> buat -> evaluasi -> beri skor -> ulangi. Semua hal lainnya di AlphaEvolve adalah variasi tempat evaluasi berjalan.

6. Mengembangkan penelusuran nyata: TSP

Pengemasan lingkaran menyatu dengan cepat. Untuk merasakan cara kerja penelusuran pada masalah yang lebih rumit, kembangkan heuristik Masalah Rute Terpendek. Pola ini identik — hanya seed dan metrik yang berubah, dan contoh TSP menggunakan kembali .env (project, anggaran, dan konkurensi).

1. Naikkan anggaran di .env agar penelusuran yang lebih lama dapat ditingkatkan:

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

2. Jalankan dari root repo:

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

Seed di sini adalah tur nearest-neighbor di lebih dari 50 kota; metriknya adalah neg_tour_length (panjang tur rata-rata negatif di 5 instance tetap, jadi makin tinggi makin baik). Buka examples/tsp/src/program.py dan perhatikan bahwa hanya construct_tour(distances, n) yang ada di dalam EVOLVE-BLOCK.

Kedua masalah tersebut adalah pola yang sama dengan bagian yang berbeda:

Masalah	Language	Evaluasi	Metrik (makin tinggi makin baik)	Yang berkembang
circle_packing	Python	lokal exec()	sum_of_radii	construct_packing()
tsp	Python	lokal exec()	neg_tour_length	construct_tour()

Saat penelusuran berjalan, lihat neg_tour_length naik (mendekati nol) saat Gemini bergerak melampaui tetangga terdekat menuju peningkatan gaya 2-opt / or-opt — strategi yang tidak Anda tulis.

7. Menyesuaikan penelusuran

Setelah kedua proses berjalan, sesuaikan anggaran di .env:

• MAX_PROGRAMS_EVALUATED — jumlah kandidat yang akan diberi skor. Lebih banyak kandidat = penelusuran yang lebih mendalam dan biaya/waktu yang lebih tinggi.
• CONCURRENCY — berapa banyak kandidat yang dihasilkan sekaligus saat proses berlangsung.
• MODEL_1 / MODEL_2 (dengan MODEL_1_WEIGHT / MODEL_2_WEIGHT) — campuran berbobot model Gemini yang menghasilkan kandidat dalam proses pengemasan lingkaran (modul TSP membaca satu MODEL). Nilai yang diizinkan adalah gemini-3.5-flash dan gemini-3.1-pro-preview. Mengalihkan bobot ke model yang lebih kuat untuk menemukan program yang lebih baik dalam lebih sedikit generasi.

Jalankan ulang dengan uv run python -m examples.circle_packing.src.run_evolution (atau modul tsp) setelah setiap perubahan.

Catatan: Menaikkan MAX_PROGRAMS_EVALUATED dan beralih ke model yang lebih besar akan meningkatkan biaya. Karena codelab ini menggunakan evaluasi lokal, tidak ada biaya GPU, tetapi Anda tetap membayar penggunaan AlphaEvolve API dan token Gemini Vertex AI per kandidat yang dihasilkan. Mulai dari yang kecil.

8. Pembersihan

Codelab ini menggunakan evaluasi lokal, jadi tidak ada lagi yang dapat ditagih — tidak ada cluster, tidak ada GPU, tidak ada layanan yang di-deploy. Untuk mereset checkout sepenuhnya:

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

Catatan: git clean -xfd menghapus .env Anda (termasuk setelan project) dan .venv. Lewati jika Anda ingin terus bereksperimen.

Jika Anda membuat project hanya untuk codelab ini, hapus project tersebut di Konsol untuk menghentikan semua tagihan.

9. Selamat

Selamat! Anda menjalankan eksperimen AlphaEvolve pertama di Google Cloud dan mengembangkan dua algoritma — pengemasan lingkaran dan heuristik TSP — hanya dengan menggunakan program awal, fungsi penilaian, dan Gemini.

Yang telah Anda pelajari

• Cara kerja loop AlphaEvolve: seed -> buat -> evaluasi -> beri skor -> ulangi
• Kontrak EVOLVE-BLOCK yang memungkinkan penelusuran mengoptimalkan resep tanpa memanipulasi metrik
• Cara skor dan insight kegagalan memandu generasi berikutnya
• Cara mengonfigurasi, menjalankan, membaca, dan menyesuaikan eksperimen evaluasi lokal

Codelab lainnya

Langkah-langkah ini bersifat mandiri — lakukan dalam urutan apa pun.

• Mengembangkan kode yang dikompilasi dengan evaluator jarak jauh: mengembangkan algoritma Rust/C++ yang diberi skor oleh evaluator dalam container di Cloud Run.
• Mengembangkan penyesuaian LLM di GKE + Ray: jalankan evaluasi GPU paralel yang berat di cluster Anda sendiri.

Dokumen referensi

• Panduan developer AlphaEvolve
• Repo contoh AlphaEvolve
• Contoh pengemasan lingkaran
• Contoh TSP