شروع به کار با AlphaEvolve در Google Cloud کنید

۱. مقدمه

در این آزمایشگاه کد، شما دو آزمایش اول AlphaEvolve خود را روی Google Cloud اجرا می‌کنید. AlphaEvolve چارچوب کدنویسی تکاملی هدایت‌شده توسط هوش مصنوعی Google DeepMind است: این چارچوب از Gemini برای نوشتن و بهبود کد استفاده می‌کند و بر اساس معیاری که شما تعریف می‌کنید، امتیازدهی می‌شود. شما با بسته‌بندی دایره‌ای شروع می‌کنید - یک مسئله هندسی کوچک که در آن می‌توانید به معنای واقعی کلمه شاهد بهبود نتیجه باشید - سپس این کار را روی یک مسئله فروشنده دوره‌گرد دشوارتر تکرار می‌کنید تا الگو به دست آید.

هر دو آزمایش از ارزیابی محلی استفاده می‌کنند - کد کاندید روی دستگاه خودتان اجرا می‌شود، بنابراین هیچ پردازنده گرافیکی (GPU) و هیچ کلاستری برای مدیریت وجود ندارد. تنها کاربرد ابری، API آلفاایولو (AlphaEvolve) است که کاندیدها را تولید می‌کند.

کاری که انجام خواهید داد

• یک آزمایش AlphaEvolve را در برابر پروژه Google Cloud خود پیکربندی کنید
• یک جستجوی تکاملی اجرا کنید که الگوریتم بسته‌بندی دایره‌ای را به صورت محلی بهبود بخشد
• امتیاز، رتبه‌بندی و تجسم بهترین برنامه تکامل‌یافته را بخوانید
• برای تعمیم الگو، حلقه را روی مسئله فروشنده دوره‌گرد تکرار کنید.
• تنظیم بودجه جستجو (کاندیداها، همزمانی، مدل)

آنچه نیاز دارید

• یک مرورگر وب مانند کروم
• یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
• پایتون ۳.۹ یا بالاتر و uv
• آشنایی اولیه با پایتون و خط فرمان

این آزمایشگاه کد برای مهندسان و توسعه‌دهندگان هوش مصنوعی/یادگیری ماشین در تمام سطوح است. هیچ پیش‌زمینه‌ای در محاسبات تکاملی لازم نیست.

زمان تخمینی برای تکمیل: ۴۵ تا ۶۰ دقیقه

هزینه: این آزمایشگاه کد از ارزیابی محلی استفاده می‌کند (بدون GPU، بدون GKE). تنها هزینه، استفاده از API AlphaEvolve برای تولید کاندیداها است.

تست شده با: کتابخانه کلاینت AlphaEvolve Cloud نسخه ۰.۱.۰، پایتون ۳.۹+، روی مثال‌های circle_packing و tsp .

۲. قبل از شروع

پروژه خود را انتخاب کنید و API را فعال کنید

1. در کنسول گوگل کلود ، یک پروژه با قابلیت پرداخت فعال انتخاب یا ایجاد کنید، سپس آن را در ترمینال خود تنظیم کنید:

gcloud config set project <YOUR_PROJECT_ID>

2. فعال کردن API موتور اکتشاف (Discovery Engine API) که به AlphaEvolve سرویس می‌دهد:

gcloud services enable discoveryengine.googleapis.com

شناسه برنامه Gemini Enterprise خود را پیدا کنید

AlphaEvolve از طریق Gemini Enterprise ارائه می‌شود (سطح REST زیرین، API موتور اکتشاف (Discovery Engine) است). برای تنظیم GE_APP_ID به شناسه برنامه خود - نه نام نمایشی آن - نیاز دارید.

1. صفحه برنامه‌های Gemini Enterprise را برای پروژه خود باز کنید.
2. روی برنامه خود کلیک کنید و فیلد شناسه (ID ) را کپی کنید (برای مثال، gemini-enterprise-1234567890_1234567890123 ).

این شناسه را دم دست نگه دارید - به زودی آن را در .env قرار خواهید داد. ASSISTANT=default_assistant را رها کنید، مگر اینکه یک دستیار سفارشی ایجاد کرده باشید.

تأیید اعتبار، کلون کردن و نصب

1. احراز هویت برای اعتبارنامه‌های پیش‌فرض برنامه:

gcloud auth application-default login

2. مخزن نمونه‌ها را کلون کرده و آن را باز کنید. شما هر دستوری را از ریشه این مخزن اجرا خواهید کرد:

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

3. یک محیط مجازی ایجاد کنید و کتابخانه کلاینت AlphaEvolve را در آن نصب کنید:

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

uv venv یک .venv ‎ در مخزن ایجاد می‌کند؛ uv pip install -e ".[dev]" بسته alpha_evolve (قابل ویرایش) به همراه ابزارهای تست را نصب می‌کند. شما آزمایش‌ها را با uv run اجرا خواهید کرد که به طور خودکار از این محیط استفاده می‌کند.

۳. حلقه AlphaEvolve را درک کنید

قبل از اجرای هر چیزی، سه بخش مورد نیاز AlphaEvolve را درک کنید. این مدل ذهنی است که برای هر آزمایش از آن استفاده خواهید کرد.

برنامه‌ی سید و بلوک تکامل (EVOLVE-BLOCK)

AlphaEvolve فقط کد بین دو نشانگر را بازنویسی می‌کند. هر چیز دیگری در فایل به صورت ثابت و بدون دستکاری باقی می‌ماند. examples/circle_packing/src/program.py را باز کنید - سید یک بسته‌بندی حلقه‌ای متحدالمرکز ساده است:

# 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 - از جمله تابع evaluate() و بررسی‌های همپوشانی - ثابت می‌ماند. این جداسازی کل ترفند است: Gemini می‌تواند هر الگوریتم بسته‌بندی که دوست دارد را پیشنهاد دهد، اما نمی‌تواند نحوه امتیازدهی به یک نامزد را تغییر دهد.

ارزیاب و امتیاز

examples/circle_packing/src/evaluate.py هر کاندید را در یک جعبه شنی اجرا می‌کند و یک امتیاز برمی‌گرداند. برای بسته‌بندی دایره‌ای، معیار sum_of_radii است و هرچه بالاتر باشد بهتر است :

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

اگر یک کاندیدا از یک قانون تخطی کند - دایره‌ها روی هم قرار بگیرند یا از مربع خارج شوند - ارزیاب -inf را به همراه بینشی که توضیح می‌دهد چه اشتباهی رخ داده است، برمی‌گرداند. این بینش‌ها به Gemini بازخورد می‌دهند تا نسل بعدی از همان اشتباه جلوگیری کند.

این شکلی است که هر مسئله AlphaEvolve به خود می‌گیرد: کدی که می‌توانید در یک EVOLVE-BLOCK بیان کنید ، یک ارزیابی خودکار و یک امتیاز اسکالر واحد برای به حداکثر رساندن آن.

۴. اولین آزمایش خود را اجرا کنید

آزمایش را پیکربندی کنید

از ریشه مخزن، .env خود را از الگوی circle-packing ایجاد کنید:

cp examples/circle_packing/example.env .env

فایل .env را باز کنید و فقط شناسه پروژه و برنامه خود را تنظیم کنید - همه موارد دیگر برای اولین اجرا پیش‌فرض‌های کار می‌کنند:

PROJECT_ID=<YOUR_PROJECT_ID>
GE_APP_ID=<YOUR_GEMINI_ENTERPRISE_APP_ID>

پیش‌فرض‌ها، کاندیدهایی با ترکیبی از مدل Gemini ( MODEL_1=gemini-3.5-flash با وزن 0.7 ، MODEL_2=gemini-3.1-pro-preview با 0.3 ) تولید می‌کنند و جستجو را در MAX_PROGRAMS_EVALUATED=10 با CONCURRENCY=4 محدود می‌کنند - به اندازه‌ای که بتوان عملکرد سریع حلقه را مشاهده کرد.

تکامل را شروع کنید

آزمایش را از ریشه مخزن اجرا کنید:

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

این برنامه‌ی اولیه را آپلود می‌کند، جستجو را شروع می‌کند و حلقه‌ی کنترل محلی را تا زمانی که ۱۰ کاندید ارزیابی شوند، اجرا می‌کند. از آنجایی که شما ماژول را مستقیماً فراخوانی می‌کنید (بدون پوشش)، می‌توانید دقیقاً ببینید چه چیزی اجرا می‌شود - و فایل را برای آزمایش ویرایش کنید.

شما باید خروجی مشابه زیر را ببینید:

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

کاندیداهای اولیه معمولاً در محدوده ۰.۸ تا ۱.۰ امتیاز می‌گیرند؛ جستجو از آنجا بهبود می‌یابد. وقتی حلقه تمام می‌شود، برنامه‌های رتبه‌بندی شده را چاپ می‌کند و بسته‌بندی‌های برتر را با matplotlib رندر می‌کند.

نکته: عیب‌یابی: PERMISSION_DENIED یا 403 معمولاً به این معنی است که رابط برنامه‌نویسی کاربردی موتور اکتشاف (Discovery Engine API) در پروژه فعال نیست. مرحله «قبل از شروع» را دوباره بررسی کنید. اجرایی که بلافاصله با «ایجاد آزمایش ناموفق بود» به پایان می‌رسد، به این معنی است که اعتبارنامه‌ها یا GE_APP_ID در .env اشتباه هستند.

۵. نتایج را بخوانید

این اجرا، برنامه‌های برتر رتبه‌بندی شده بر اساس sum_of_radii را چاپ می‌کند (هرچه عدد بالاتر باشد، بهتر است). دو نکته را باید در نظر بگیرید:

• امتیاز بالا رفت. بهترین sum_of_radii تکامل‌یافته باید از طرح حلقه‌های متحدالمرکز دانه پیشی بگیرد. جوزا معمولاً کشف می‌کند که دایره‌های نزدیک گوشه‌ها و لبه‌ها می‌توانند بزرگتر شوند و فضای داخلی را دوباره متعادل کنند.
• کاندیداهای نامعتبر رد می‌شوند. هر برنامه‌ای که دایره‌های همپوشانی یا خارج از محدوده تولید کند، امتیاز -inf می‌گیرد و در رتبه‌بندی رد می‌شود - این بازخورد محدودیت است که کار می‌کند، نه یک خطا.

دیدن چند کاندیدای با امتیاز پایین یا رد شده در اوایل دوره، طبیعی و سالم است - به این معنی است که Gemini در حال کاوش است و بینش‌های حاصل از شکست‌ها، نسل‌های بعدی را هدایت می‌کند.

حالا شما حلقه کامل را دارید: seed -> generate -> evaluation -> score -> repeat. هر چیز دیگری در AlphaEvolve، نوعی تغییر در محل اجرای ارزیابی است.

۶. یک جستجوی واقعی را تکامل دهید: TSP

بسته‌بندی دایره‌ای به سرعت همگرا می‌شود. برای اینکه حس کنید جستجو روی یک مسئله‌ی پیچیده‌تر کار می‌کند، یک الگوریتم ابتکاری برای مسئله‌ی فروشنده‌ی دوره‌گرد ایجاد کنید. الگو یکسان است - فقط دانه و متریک تغییر می‌کنند و مثال TSP از .env شما (پروژه، بودجه و همزمانی) دوباره استفاده می‌کند.

1. بودجه را در .env افزایش دهید تا جستجوی طولانی‌تر جای بهبود داشته باشد:

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

2. آن را از ریشه مخزن اجرا کنید:

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

در اینجا، سید (seed) یک تور نزدیکترین همسایه روی ۵۰ شهر است؛ معیار آن neg_tour_length است (میانگین طول تور در ۵ نمونه ثابت منفی است، بنابراین هرچه بیشتر باشد بهتر است ). examples/tsp/src/program.py را باز کنید و توجه داشته باشید که فقط construct_tour(distances, n) درون بلوک EVOLVE قرار دارد.

دو مسئله، الگوی یکسانی با قطعات متفاوت دارند:

مشکل	زبان	ارزیابی	متریک (هرچه بالاتر بهتر)	چه چیزی تکامل می‌یابد؟
circle_packing	پایتون	exec()	sum_of_radii	construct_packing()
tsp	پایتون	exec()	neg_tour_length	construct_tour()

همچنان که جستجو ادامه می‌یابد، مشاهده کنید که neg_tour_length با حرکت Gemini از نزدیکترین همسایه به سمت بهبودهای سبک 2-opt / or-opt - استراتژی‌هایی که شما ننوشته‌اید - بالا می‌رود (به صفر نزدیک‌تر می‌شود).

۷. جستجو را تنظیم کنید

حالا که هر دو اجرا می‌شوند، بودجه را در .env تنظیم کنید:

• MAX_PROGRAMS_EVALUATED — تعداد کاندیداهایی که باید امتیازدهی شوند. کاندیداهای بیشتر = جستجوی عمیق‌تر و هزینه/زمان بالاتر.
• CONCURRENCY — چند کاندید به طور همزمان در حال پرواز تولید می‌شوند.
• MODEL_1 / MODEL_2 (همراه با MODEL_1_WEIGHT / MODEL_2_WEIGHT ) — مخلوط وزن‌دار مدل‌های Gemini که در اجرای بسته‌بندی دایره‌ای، کاندیداها را تولید می‌کنند (ماژول TSP به جای آن یک MODEL واحد را می‌خواند). مقادیر مجاز عبارتند از gemini-3.5-flash و gemini-3.1-pro-preview . وزن را به سمت مدل قوی‌تر تغییر دهید تا برنامه‌های بهتری در نسل‌های کمتری پیدا کنید.

بعد از هر تغییر، با uv run python -m examples.circle_packing.src.run_evolution (یا ماژول tsp ) دوباره اجرا کنید.

توجه: افزایش MAX_PROGRAMS_EVALUATED و تغییر به یک مدل بزرگتر، هر دو هزینه را افزایش می‌دهند. از آنجا که این آزمایشگاه کد از ارزیابی محلی استفاده می‌کند، هیچ هزینه‌ای برای GPU وجود ندارد، اما شما همچنان برای استفاده از API AlphaEvolve به ازای هر کاندیدای تولید شده هزینه پرداخت می‌کنید. با مقادیر کوچک شروع کنید.

۸. تمیز کردن

این آزمایشگاه کد از ارزیابی محلی استفاده می‌کند، بنابراین هیچ چیز قابل پرداختی در حال اجرا باقی نمی‌ماند - نه کلاستر، نه پردازنده گرافیکی و نه سرویس‌های مستقر. برای تنظیم مجدد کامل پرداخت خود:

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

نکته: git clean -xfd .env (شامل تنظیمات پروژه) و فایل .venv شما را حذف می‌کند. اگر می‌خواهید به آزمایش ادامه دهید، از این مرحله صرف نظر کنید.

اگر فقط برای این codelab پروژه‌ای ایجاد کرده‌اید، آن را در کنسول حذف کنید تا تمام هزینه‌ها متوقف شود.

۹. تبریک

تبریک! شما اولین آزمایش‌های AlphaEvolve خود را روی Google Cloud اجرا کردید و دو الگوریتم - یک بسته‌بندی دایره‌ای و یک الگوریتم اکتشافی TSP - را با استفاده از یک برنامه‌ی اولیه، یک تابع امتیازدهی و Gemini توسعه دادید.

آنچه آموخته‌اید

• نحوه‌ی عملکرد حلقه‌ی AlphaEvolve: دانه‌بندی -> تولید -> ارزیابی -> امتیاز -> تکرار
• قرارداد EVOLVE-BLOCK که به جستجو اجازه می‌دهد بدون دستکاری معیار، یک دستور غذا را بهینه کند.
• چگونه نمرات و بینش‌های مربوط به شکست، نسل بعدی را هدایت می‌کنند
• نحوه پیکربندی، اجرا، خواندن و تنظیم یک آزمایش ارزیابی محلی

سایر آزمایشگاه‌های کد

اینها مستقل هستند - آنها را به هر ترتیبی انجام دهید.

• تکامل کد کامپایل شده با یک ارزیاب از راه دور : تکامل یک الگوریتم Rust/C++ که توسط یک ارزیاب کانتینر شده در Cloud Run امتیازدهی شده است.
• تنظیم دقیق Evolve LLM روی GKE + Ray : ارزیابی‌های سنگین و موازی GPU را روی کلاستر خودتان اجرا کنید.

اسناد مرجع

• راهنمای توسعه‌دهندگان AlphaEvolve
• مخزن نمونه‌های AlphaEvolve
• مثال بسته‌بندی دایره‌ای
• مثال TSP