Mulai menggunakan AlphaEvolve di Google Cloud

1. Pengantar

Dalam codelab ini, Anda akan menjalankan dua eksperimen AlphaEvolve pertama di Google Cloud. AlphaEvolve adalah framework pengkodean 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 akan memulai dengan pengemasan lingkaran — masalah geometri kecil yang memungkinkan Anda melihat hasilnya menjadi lebih baik — lalu ulangi pada Masalah Penjual Keliling yang lebih sulit sehingga polanya tetap.

Kedua eksperimen menggunakan evaluasi lokal — kode kandidat berjalan di mesin 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

• Mengonfigurasi eksperimen AlphaEvolve terhadap project Google Cloud Anda
• Menjalankan penelusuran evolusioner yang meningkatkan kualitas algoritma pengemasan lingkaran secara lokal
• Membaca skor, peringkat, dan visualisasi program berevolusi terbaik
• Mengulangi loop pada Masalah Penjual Keliling untuk menggeneralisasi pola
• Menyesuaikan anggaran penelusuran (kandidat, konkurensi, model)

Yang akan 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 untuk engineer dan developer AI/ML dari semua tingkat keahlian. Tidak diperlukan latar belakang komputasi evolusioner.

Perkiraan waktu penyelesaian: 45–60 menit.

Biaya: codelab ini menggunakan evaluasi lokal (tanpa GPU, tanpa GKE). Satu-satunya biaya adalah penggunaan AlphaEvolve API untuk menghasilkan kandidat.

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

2. Sebelum memulai

Memilih project dan mengaktifkan API

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

gcloud config set project <YOUR_PROJECT_ID>

2. Aktifkan Discovery Engine API, yang menyediakan AlphaEvolve:

gcloud services enable discoveryengine.googleapis.com

Menemukan ID aplikasi Gemini Enterprise

AlphaEvolve disediakan melalui Gemini Enterprise (REST surface yang mendasarinya adalah Discovery Engine API). Anda memerlukan ID aplikasi — 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.

Melakukan autentikasi, meng-clone, dan menginstal

1. Lakukan autentikasi untuk kredensial default aplikasi:

gcloud auth application-default login

2. Clone repo sampel 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) beserta 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 diperlukan AlphaEvolve. Ini adalah model mental yang akan Anda gunakan kembali untuk setiap eksperimen.

Program awal dan EVOLVE-BLOCK

AlphaEvolve hanya menulis ulang kode di antara dua penanda. Semua hal lainnya dalam file adalah scaffolding tetap yang tidak dapat disentuh. Buka examples/circle_packing/src/program.py — awal 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 hal di luar EVOLVE-BLOCK-START / EVOLVE-BLOCK-END — termasuk fungsi evaluate() dan pemeriksaan tumpang-tindih — tetap dibekukan. Pemisahan tersebut adalah keseluruhan triknya: Gemini dapat mengusulkan algoritma pengemasan apa pun yang diinginkannya, tetapi tidak dapat mengubah cara pemberian skor pada 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 semakin tinggi semakin 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 memberikan masukan kepada Gemini sehingga generasi berikutnya menghindari kesalahan yang sama.

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

4. Menjalankan eksperimen pertama

Mengonfigurasi eksperimen

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

cp examples/circle_packing/example.env .env

Buka .env dan tetapkan hanya project dan ID aplikasi Anda — semua hal lainnya memiliki nilai default yang berfungsi untuk menjalankan pertama kali:

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

Nilai 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 pada MAX_PROGRAMS_EVALUATED=10 dengan CONCURRENCY=4 — cukup untuk melihat loop berfungsi dengan cepat.

Memulai evolusi

Jalankan eksperimen dari root repo:

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

Tindakan ini akan 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 mendapat skor dalam rentang 0,8–1,0 ; penelusuran akan meningkat dari sana. Saat loop selesai, program akan mencetak program yang diberi peringkat dan merender pengemasan teratas dengan matplotlib.

Catatan: Pemecahan masalah: PERMISSION_DENIED atau 403 biasanya berarti Discovery Engine API tidak diaktifkan di project. Periksa kembali langkah "Sebelum memulai". Run yang segera berakhir dengan "Failed to create experiment" berarti kredensial atau GE_APP_ID di .env salah.

5. Membaca hasil

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

• Skornya naik. sum_of_radii berevolusi terbaik harus mengalahkan tata letak cincin konsentris awal. 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 akan diberi skor -inf dan dilewati dalam peringkat — itulah masukan batasan yang berfungsi, bukan error.

Melihat beberapa kandidat dengan skor rendah atau dilewati di awal run adalah hal yang normal dan sehat — artinya Gemini sedang menjelajahi, dan insight dari kegagalan akan mengarahkan generasi berikutnya.

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

6. Mengembangkan penelusuran yang sebenarnya: TSP

Pengemasan lingkaran menyatu dengan cepat. Untuk merasakan penelusuran berfungsi pada masalah yang lebih substansial, kembangkan heuristik Masalah Penjual Keliling. Polanya identik — hanya awal dan metrik yang berubah, dan contoh TSP menggunakan kembali .env Anda (project, anggaran, dan konkurensi).

1. Tingkatkan anggaran di .env sehingga penelusuran yang lebih lama memiliki ruang untuk 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

Awal di sini adalah tur tetangga terdekat di lebih dari 50 kota; metriknya adalah neg_tour_length (panjang tur rata-rata negatif di 5 instance tetap, sehingga semakin tinggi semakin baik). Buka examples/tsp/src/program.py dan perhatikan bahwa hanya construct_tour(distances, n) yang berada di dalam EVOLVE-BLOCK.

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

Masalah	Language	Evaluasi	Metrik (semakin tinggi semakin baik)	Yang berevolusi
circle_packing	Python	exec() lokal	sum_of_radii	construct_packing()
tsp	Python	exec() lokal	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 / atau-opt — strategi yang tidak Anda tulis.

7. Menyesuaikan penelusuran

Setelah kedua run berfungsi, sesuaikan anggaran di .env:

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

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

Catatan: Meningkatkan 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 per kandidat yang dihasilkan. Mulai dari yang kecil.

8. Pembersihan

Codelab ini menggunakan evaluasi lokal, sehingga tidak ada yang dapat ditagih yang masih berjalan — 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 (termasuk setelan project Anda) dan .venv. Lewati jika Anda ingin terus bereksperimen.

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

9. Selamat

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

Yang telah Anda pelajari

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

Codelab lainnya

Codelab 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 penyetelan LLM di GKE + Ray: menjalankan evaluasi GPU paralel yang berat di cluster Anda sendiri.

Dokumen referensi

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