Google Cloud'da AlphaEvolve'u kullanmaya başlama

1. Giriş

Bu codelab'de, Google Cloud'da ilk iki AlphaEvolve denemenizi çalıştıracaksınız. AlphaEvolve, Google DeepMind'ın yapay zeka destekli evrimsel kodlama çerçevesidir. Tanımladığınız bir metriğe göre puanlanan kodu yazmak ve iyileştirmek için Gemini'ı kullanır. Önce, sonucu iyileşirken kelimenin tam anlamıyla izleyebileceğiniz küçük bir geometri problemi olan daire paketleme ile başlıyorsunuz. Ardından, kalıbın yerleşmesi için daha zor bir Gezgin Satıcı Problemi'nde tekrarlıyorsunuz.

Her iki denemede de yerel değerlendirme kullanılır. Aday kod kendi makinenizde çalıştırıldığından GPU ve yönetilecek küme yoktur. Tek bulut kullanımı, adaylar oluşturan AlphaEvolve API'dir.

Yapacaklarınız

• Google Cloud projenize karşı bir AlphaEvolve denemesi yapılandırın.
• Bir daire paketleme algoritmasını yerel olarak iyileştiren bir evrimsel arama çalıştırın.
• En iyi gelişmiş programın puanını, sıralamasını ve görselleştirmesini okuyun.
• Deseni genelleştirmek için Gezgin Satıcı Sorunu'ndaki döngüyü tekrarlayın.
• Arama bütçesini (adaylar, eşzamanlılık, model) ayarlama

İhtiyacınız olanlar

• Chrome gibi bir web tarayıcısı
• Faturalandırmanın etkin olduğu bir Google Cloud projesi
• Python 3.9 veya sonraki sürümler ve uv
• Python ve komut satırı hakkında temel düzeyde bilgi

Bu codelab, her seviyeden yapay zeka/makine öğrenimi mühendisleri ve geliştiricileri içindir. Evrimsel hesaplama konusunda bilgi sahibi olmanız gerekmez.

Tahmini tamamlama süresi: 45-60 dakika.

Maliyet: Bu codelab'de yerel değerlendirme (GPU yok, GKE yok) kullanılır. Tek ücret, aday oluşturmak için AlphaEvolve API kullanım ücretidir.

Test edildiği ortamlar: circle_packing ve tsp örneklerinde AlphaEvolve Cloud istemci kitaplığı v0.1.0, Python 3.9+.

2. Başlamadan önce

Projenizi seçin ve API'yi etkinleştirin

1. Google Cloud Console'da faturalandırmanın etkin olduğu bir proje seçin veya oluşturun, ardından terminalinizde ayarlayın:

gcloud config set project <YOUR_PROJECT_ID>

2. AlphaEvolve'a hizmet veren Discovery Engine API'yi etkinleştirin:

gcloud services enable discoveryengine.googleapis.com

Gemini Enterprise uygulama kimliğinizi bulma

AlphaEvolve, Gemini Enterprise aracılığıyla sunulur (temel REST yüzeyi, Discovery Engine API'dir). GE_APP_ID ayarı için uygulamanızın görünen adı değil, kimliği gerekir.

1. Projenizin Gemini Enterprise uygulamaları sayfasını açın.
2. Uygulamanızı tıklayın ve Kimlik alanını (örneğin, gemini-enterprise-1234567890_1234567890123) kopyalayın.

Bu kimliği elinizin altında bulundurun. Kısa süre içinde .env konsoluna yapıştıracaksınız. Özel bir asistan sağlamadıysanız ASSISTANT=default_assistant seçeneğini etkin bırakın.

Kimlik doğrulama, klonlama ve yükleme

1. Uygulama varsayılan kimlik bilgileri için kimlik doğrulama:

gcloud auth application-default login

2. Örnekler deposunu klonlayıp açın. Her komutu bu depo kökünden çalıştıracaksınız:

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

3. Sanal ortam oluşturun ve AlphaEvolve istemci kitaplığını bu ortama yükleyin:

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

uv venv, depoda .venv oluşturur; uv pip install -e ".[dev]", alpha_evolve paketini (düzenlenebilir) ve test araçlarını yükler. Bu ortamı otomatik olarak kullanan uv run ile denemeler başlatırsınız.

3. AlphaEvolve döngüsünü anlama

Herhangi bir işlem yapmadan önce AlphaEvolve'un ihtiyaç duyduğu üç parçayı anlayın. Bu, her deneme için yeniden kullanacağınız zihinsel modeldir.

Seed programı ve EVOLVE-BLOCK

AlphaEvolve yalnızca iki işaretçi arasındaki kodu yeniden yazar. Dosyadaki diğer her şey, dokunamayacağı sabit bir iskeledir. examples/circle_packing/src/program.py simgesini açın. Tohum, basit bir eşmerkezli halka paketidir:

# 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

EVOLVE-BLOCK-START / EVOLVE-BLOCK-END dışındaki her şey (evaluate() işlevi ve çakışma kontrolleri dahil) dondurulur. Buradaki püf nokta bu ayrışmadır: Gemini istediği paketleme algoritmasını önerebilir ancak adayların puanlanma şeklini değiştiremez.

Değerlendiren ve puan

examples/circle_packing/src/evaluate.py her adayı bir korumalı alanda çalıştırır ve bir puan döndürür. Daire paketleme için metrik sum_of_radii'dır ve yüksek değer daha iyidir:

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

Bir aday kuralı ihlal ederse (ör. daireler üst üste gelir veya kareyi terk ederse) değerlendirici, -inf sembolünü ve neyin yanlış gittiğini açıklayan bir analiz döndürür. Bu analizler Gemini'a geri bildirim olarak gönderilir. Böylece yeni nesil, aynı hatayı yapmaz.

Her AlphaEvolve sorunu şu şekildedir: EVOLVE-BLOCK'ta ifade edebileceğiniz kod, otomatikleştirilebilir değerlendirme ve maksimize edilecek tek bir skaler puan.

4. İlk denemenizi yapın

Denemeyi yapılandırma

Depo kökünden, daire paketleme şablonunu kullanarak .env dosyanızı oluşturun:

cp examples/circle_packing/example.env .env

.env dosyasını açın ve yalnızca proje ile uygulama kimliğinizi ayarlayın. Diğer tüm ayarlar, ilk çalıştırma için varsayılan olarak çalışır:

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

Varsayılanlar, Gemini modeli karışımıyla (MODEL_1=gemini-3.5-flash ağırlıkta 0.7, MODEL_2=gemini-3.1-pro-preview ağırlıkta 0.3) adaylar oluşturur ve aramayı MAX_PROGRAMS_EVALUATED=10 ile CONCURRENCY=4 olarak sınırlar. Bu, döngünün hızlı bir şekilde çalışmasını izlemek için yeterlidir.

Evrimi başlatma

Denemeyi depo kökünden çalıştırın:

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

Bu işlem, başlangıç programını yükler, aramayı başlatır ve 10 aday değerlendirilene kadar yerel kontrol döngüsünü çalıştırır. Modülü doğrudan çağırdığınız için (sarmalayıcı yok) tam olarak neyin çalıştığını görebilir ve deneme yapmak için dosyayı düzenleyebilirsiniz.

Şuna benzer bir çıkış alırsınız:

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

İlk adaylar genellikle 0,8-1,0 aralığında puan alır. Arama, bu noktadan itibaren iyileşir. Döngü tamamlandığında, sıralanmış programları yazdırır ve en iyi paketleri matplotlib ile oluşturur.

Not: Sorun giderme: PERMISSION_DENIED veya 403 genellikle Discovery Engine API'nin projede etkinleştirilmediği anlamına gelir. "Başlamadan önce" adımını tekrar kontrol edin. "Deneme oluşturulamadı" mesajıyla hemen sona eren bir çalıştırma, .env içindeki kimlik bilgilerinin veya GE_APP_ID değerinin yanlış olduğu anlamına gelir.

5. Sonuçları okuma

Çalıştırma, sum_of_radii'ya göre sıralanan en iyi programları yazdırır (daha yüksek değerler daha iyidir). Dikkat etmeniz gereken iki nokta:

• Puan arttı. En iyi gelişmiş sum_of_radii, başlangıç öğesinin eş merkezli halka düzenini geçmelidir. Gemini genellikle köşelere ve kenarlara yakın dairelerin büyüyebileceğini fark eder ve iç kısmı yeniden dengeler.
• Geçersiz adaylar atlanır. Çakışan veya sınırların dışında kalan daireler oluşturan tüm programlar -inf puan alır ve sıralamada atlanır. Bu, hata değil, kısıtlama geri bildiriminin çalışmasıdır.

Çalışmanın başında birkaç düşük puanlı veya atlanan aday görmek normal ve sağlıklıdır. Bu, Gemini'ın keşif yaptığı ve başarısızlıkların sağladığı analizlerin sonraki nesillere yol gösterdiği anlamına gelir.

Artık tüm döngüye sahipsiniz: başlangıç -> oluşturma -> değerlendirme -> puanlama -> tekrarlama. AlphaEvolve'daki diğer her şey, değerlendirmenin nerede çalıştırıldığıyla ilgili bir varyasyondur.

6. Gerçek bir aramayı geliştirme: TSP

Daire paketleme hızlı bir şekilde yakınsar. Aramanın daha zorlu bir problem üzerinde çalıştığını görmek için Gezgin Satıcı Problemi (Travelling Salesman Problem) sezgisini geliştirin. Yalnızca başlangıç ve metrik değişir, TSP örneği ise .env (proje, bütçe ve eşzamanlılık) değerinizi yeniden kullanır.

1. Daha uzun aramanın iyileşebilmesi için .env bütçesini artırın:

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

2. Depo kökünden çalıştırın:

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

Buradaki başlangıç noktası, 50 şehirde en yakın komşu turudur. Metrik ise neg_tour_length'dir (5 sabit örnekte ortalama tur uzunluğu negatif olduğundan daha yüksek değer daha iyidir). examples/tsp/src/program.py dosyasını açın ve EVOLVE-BLOCK içinde yalnızca construct_tour(distances, n) olduğunu unutmayın.

İki problem, farklı parçalara sahip aynı desendir:

Sorun	Dil	Değerlendirme	Metrik (yüksek değer daha iyidir)	Evrimleşen pokemon
circle_packing	Python	yerel exec()	sum_of_radii	construct_packing()
tsp	Python	yerel exec()	neg_tour_length	construct_tour()

Arama çalışırken Gemini, en yakın komşudan 2-opt / or-opt tarzı iyileştirmelere (sizin yazmadığınız stratejiler) doğru ilerledikçe neg_tour_length değerinin yükselmesini (sıfıra yaklaşmasını) izleyin.

7. Aramayı ayarlama

Her iki çalıştırma da çalıştığına göre .env bölümünde bütçeyi ayarlayın:

• MAX_PROGRAMS_EVALUATED: Kaç adayın puanlanacağı. Daha fazla aday = daha derin bir arama ve daha yüksek maliyet/süre.
• CONCURRENCY: Tek seferde kaç aday oluşturulur?
• MODEL_1 / MODEL_2 (MODEL_1_WEIGHT / MODEL_2_WEIGHT ile) — Daire paketleme çalıştırmasında adaylar oluşturan Gemini modellerinin ağırlıklı karışımı (TSP modülü bunun yerine tek bir MODEL okur). İzin verilen değerler gemini-3.5-flash ve gemini-3.1-pro-preview'dir. Daha az sayıda nesilde daha iyi programlar bulmak için ağırlığı daha güçlü modele doğru kaydırın.

Her değişiklikten sonra uv run python -m examples.circle_packing.src.run_evolution (veya tsp modülü) ile yeniden çalıştırın.

Not: MAX_PROGRAMS_EVALUATED değerini yükseltmek ve daha büyük bir modele geçmek maliyeti artırır. Bu codelab'de yerel değerlendirme kullanıldığından GPU ücreti alınmaz ancak oluşturulan aday başına AlphaEvolve API kullanımı için ödeme yapmaya devam edersiniz. Küçük adımlarla başlayın.

8. Temizleme

Bu codelab'de yerel değerlendirme kullanılır. Bu nedenle faturalandırılabilir hiçbir öğe çalışmaz (küme, GPU veya dağıtılmış hizmet yoktur). Ödeme işleminizi tamamen sıfırlamak için:

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

Not: git clean -xfd, .env (proje ayarlarınız dahil) ve .venv öğesini siler. Deneme yapmaya devam etmek istiyorsanız bu adımı atlayın.

Yalnızca bu codelab için bir proje oluşturduysanız tüm ücretlendirmeleri durdurmak için projeyi Console'da silin.

9. Tebrikler

Tebrikler! Google Cloud'da ilk AlphaEvolve denemelerinizi yaptınız ve yalnızca bir başlangıç programı, bir puanlama işlevi ve Gemini kullanarak iki algoritmayı (bir daire paketleme ve bir TSP sezgisel algoritması) geliştirdiniz.

Öğrendikleriniz

• AlphaEvolve'un döngüsünün işleyiş şekli: başlangıç -> oluşturma -> değerlendirme -> puanlama -> tekrarlama
• Arama motorunun, metriği manipüle etmeden bir tarifi optimize etmesine olanak tanıyan EVOLVE-BLOCK sözleşmesi
• Puanlar ve başarısızlık analizleri yeni nesli nasıl yönlendiriyor?
• Yerel değerlendirme denemesi yapılandırma, çalıştırma, okuma ve ayarlama

Diğer Codelab'ler

Bunlar bağımsızdır ve istediğiniz sırayla yapılabilir.

• Derlenmiş kodu uzaktan değerlendiriciyle geliştirme: Cloud Run'da container mimarisine alınmış bir değerlendirici tarafından puanlanan bir Rust/C++ algoritmasını geliştirin.
• GKE + Ray'de LLM ince ayarını geliştirme: Kendi kümenizde yoğun ve paralel GPU değerlendirmeleri yapın.

Referans belgeleri

• AlphaEvolve geliştirici kılavuzu
• AlphaEvolve örnekleri deposu
• Daire paketleme örneği
• TSP örneği