1. はじめに
この Codelab では、Google Cloud で最初の 2 つの AlphaEvolve テストを実行します。AlphaEvolve は、Google DeepMind の AI ガイド付き進化型コーディング フレームワークです。Gemini を使用してコードを作成し、定義した指標でスコアを付けて改善します。まず、円のパッキング（結果が改善されるのを実際に確認できる小さな幾何学の問題）から始め、より難しい巡回セールスマン問題で繰り返してパターンを定着させます。
どちらのテストでもローカル評価 を使用します。候補コードは自分のマシンで実行されるため、GPU もクラスタも管理する必要はありません。クラウドの使用は、候補を生成する AlphaEvolve API のみです。
演習内容
- Google Cloud プロジェクトに対して AlphaEvolve テストを構成 する
- 円のパッキング アルゴリズムをローカルで改善する進化型検索を実行 する
- 最も進化したプログラムのスコア、ランキング、可視化を確認 する
- 巡回セールスマン問題でループを繰り返して パターンを一般化する
- 検索予算（候補、同時実行、モデル）を調整 する
必要なもの
この Codelab は、あらゆるレベルの AI/ML エンジニアとデベロッパーを対象としています。進化計算の知識は必要ありません。
所要時間: 45 ～ 60 分
費用: この Codelab ではローカル評価 を使用します（GPU なし、GKE なし）。料金は、候補を生成するための AlphaEvolve API の使用量のみです。
テスト済み: AlphaEvolve Cloud クライアント ライブラリ v0.1.0、Python 3.9 以降、circle_packing と tsp のサンプル。
2. 始める前に
プロジェクトを選択して API を有効にする
- Google Cloud Console で、課金が有効になっているプロジェクトを選択または作成し、ターミナルで設定します。
gcloud config set project <YOUR_PROJECT_ID>
- AlphaEvolve を提供する Discovery Engine API を有効にします。
gcloud services enable discoveryengine.googleapis.com
Gemini Enterprise app ID を確認する
AlphaEvolve は Gemini Enterprise を介して提供されます（基盤となる REST サーフェスは Discovery Engine API です）。GE_APP_ID 設定には、アプリの表示名ではなくID が必要です。
- プロジェクトの Gemini Enterprise アプリ のページを開きます。
- アプリをクリックして、[ID] フィールド（
gemini-enterprise-1234567890_1234567890123など）をコピーします。
認証、クローン、インストール
- アプリケーションのデフォルト認証情報を認証します。
gcloud auth application-default login
- サンプル リポジトリのクローンを作成して開きます。すべてのコマンドはこのリポジトリのルートから実行します。
git clone https://github.com/Google-Cloud-AI/alphaevolve-on-googlecloud.git
cd alphaevolve-on-googlecloud
- 仮想環境を作成し、AlphaEvolve クライアント ライブラリをインストールします。
uv venv
uv pip install -e ".[dev]"
uv venv はリポジトリに .venv を作成します。uv pip install -e ".[dev]" は alpha_evolve パッケージ（編集可能）とテストツールをインストールします。テストは uv run で起動します。この環境が自動的に使用されます。
3. AlphaEvolve ループを理解する
実行する前に、AlphaEvolve に必要な 3 つの要素を理解してください。これは、すべてのテストで再利用するメンタルモデルです。
シード プログラムと EVOLVE-BLOCK
AlphaEvolve は、2 つのマーカーの間 のコードのみを書き換えます。ファイル内の他のすべての要素は固定されたスキャフォールディングであり、変更できません。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 にフィードバックされ、次世代では同じ間違いを回避できます。
4. 最初のテストを実行する
テストを構成する
リポジトリのルートから、円のパッキング テンプレートを使用して .env を作成します。
cp examples/circle_packing/example.env .env
.env を開き、プロジェクトとアプリ ID のみ設定します。他のすべての要素には、最初の実行に適したデフォルト値が設定されています。
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）で候補が生成され、CONCURRENCY=4 で検索が MAX_PROGRAMS_EVALUATED=10 に制限されます。これにより、ループが迅速に動作するのを確認できます。
進化を開始する
リポジトリのルートからテストを実行します。
uv run python -m examples.circle_packing.src.run_evolution
これにより、シード プログラムがアップロードされ、検索が開始され、10 個の候補が評価されるまでローカル制御ループが実行されます。モジュールを直接呼び出しているため（ラッパーなし）、実行内容を正確に確認し、ファイルを編集してテストできます。
次のような出力が表示されます。
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).
初期の候補のスコアは通常 0.8 ～ 1.0 の範囲で、検索によって改善されます。ループが完了すると、ランク付けされたプログラムが出力され、上位のパッキングが matplotlib でレンダリングされます。
注: トラブルシューティング: PERMISSION_DENIED または 403 は通常、プロジェクトで Discovery Engine API が有効になっていないことを意味します。「始める前に」の手順をもう一度確認してください。「Failed to create experiment」で直ちに終了する場合は、.env の認証情報または GE_APP_ID が間違っています。
5. 結果を確認する
実行すると、sum_of_radii でランク付けされた上位のプログラムが出力されます（値が大きいほど優れています）。確認する点は次の 2 つです。
- スコアが上がった。最も進化した
sum_of_radiiは、シードの同心円状のレイアウトよりも優れているはずです。Gemini は通常、隅や端に近い円を大きくできることを発見し、内部のバランスを調整します。 - 無効な候補はスキップされる。円が重なっている、または範囲外の円を生成したプログラムは
-infと評価され、ランキングでスキップされます。これはエラーではなく、制約フィードバックが機能しているためです。
これで、シード -> 生成 -> 評価 -> スコア -> 反復の完全なループができました。AlphaEvolve の他のすべての要素は、評価の実行場所のバリエーションです。
6. 実際の検索を進化させる: TSP
円のパッキングはすぐに収束します。より難しい問題で検索を試すには、巡回セールスマン問題 のヒューリスティックを進化させます。パターンは同じです。シードと指標のみが変更され、TSP の例では .env（プロジェクト、予算、同時実行）が再利用されます。
.envの予算を増やして、検索を長くして改善の余地を残します。
# in .env — raise the generation cap and the evaluation target together
MAX_PROGRAMS_GENERATED=20
MAX_PROGRAMS_EVALUATED=20
- リポジトリのルートから実行します。
uv run python -m examples.tsp.src.run_evolution
ここでのシードは、50 都市を巡る最近傍 ツアーです。指標は neg_tour_length です（5 つの固定インスタンスの平均ツアー長の負の値。値が大きいほど優れています ）。examples/tsp/src/program.py を開き、construct_tour(distances, n) のみが EVOLVE-BLOCK 内にあることに注意してください。
2 つの問題は、異なる要素を持つ同じパターンです。
問題 | 言語 | 評価 | 指標（値が大きいほど優れています） | 進化するもの |
| Python | ローカル |
|
|
| Python | ローカル |
|
|
検索の実行中に、Gemini が最近傍から 2-opt / or-opt スタイルの改善（作成していない戦略）に移行するにつれて、neg_tour_length が増加（ゼロに近づく）するのを確認します。
7. 検索を調整する
両方の実行が機能するようになったので、.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 を増やしてより大きなモデルに切り替えると、費用が増加します。この Codelab ではローカル評価を使用するため、GPU の料金は発生しませんが、生成された候補ごとに AlphaEvolve API の使用料金が発生します。小規模で始める。
8. クリーンアップ
この Codelab ではローカル評価を使用するため、課金対象の実行中のリソースはありません 。クラスタ、GPU、デプロイされたサービスはありません。チェックアウトを完全にリセットするには:
git clean -xfd # removes .env, .venv, and generated outputs
注: git clean -xfd は、.env（プロジェクト設定を含む）と .venv を削除します。テストを続行する場合はスキップしてください。
この Codelab 専用のプロジェクトを作成した場合は、コンソールで削除してすべての料金を停止します。
9. 完了
おめでとうございます！Google Cloud で最初の AlphaEvolve テストを実行し、シード プログラム、スコアリング関数、Gemini のみを使用して、円のパッキングと TSP ヒューリスティックの 2 つのアルゴリズムを進化させました。
学習した内容
- AlphaEvolve のループの仕組み: シード -> 生成 -> 評価 -> スコア -> 反復
- 指標を操作せずに検索でレシピを最適化できる EVOLVE-BLOCK コントラクト
- スコアと失敗の分析情報が次世代の指針となる仕組み
- ローカル評価テストの構成、実行、読み取り、調整の方法
その他の Codelab
これらはスタンドアロンです。任意の順序で実行してください。
- リモート評価ツールでコンパイル済みコードを進化させる: Cloud Run のコンテナ化された評価ツールでスコア付けされた Rust/C++ アルゴリズムを進化させます。
- GKE + Ray で LLM ファイン チューニングを進化させる: 独自のクラスタで大規模な並列 GPU 評価を実行します。