1. 소개
이 Codelab에서는 Google Cloud에서 처음 두 개의 AlphaEvolve 실험을 실행합니다. AlphaEvolve는 Google DeepMind의 AI 기반 진화적 코딩 프레임워크입니다. Gemini를 사용하여 사용자가 정의한 측정항목으로 점수가 매겨진 코드를 작성하고 개선합니다. 결과가 개선되는 것을 직접 확인할 수 있는 작은 기하학 문제인 원 패킹으로 시작한 다음 더 어려운 외판원 문제에서 반복하여 패턴을 고정합니다.
두 실험 모두 로컬 평가 를 사용합니다. 후보 코드가 자체 머신에서 실행되므로 관리할 GPU와 클러스터가 없습니다. 유일한 클라우드 사용은 후보를 생성하는 AlphaEvolve API입니다.
실습할 내용
- Google Cloud 프로젝트에 대해 AlphaEvolve 실험을 구성 합니다.
- 원 패킹 알고리즘을 로컬에서 개선하는 진화적 검색을 실행 합니다.
- 가장 진화된 프로그램의 점수, 순위, 시각화를 읽습니다.
- 외판원 문제에서 루프를 반복 하여 패턴을 일반화합니다.
- 검색 예산 (후보, 동시 실행, 모델)을 조정 합니다.
필요한 항목
이 Codelab은 모든 수준의 AI/ML 엔지니어와 개발자를 대상으로 합니다. 진화적 계산 배경은 필요하지 않습니다.
예상 소요 시간: 45~60분
비용: 이 Codelab은 로컬 평가 (GPU 없음, GKE 없음)를 사용합니다. 유일한 요금은 후보를 생성하기 위한 AlphaEvolve API 사용입니다.
circle_packing 및 tsp 예에서 AlphaEvolve Cloud 클라이언트 라이브러리 v0.1.0, Python 3.9+로 테스트되었습니다.
2. 시작하기 전에
프로젝트를 선택하고 API를 사용 설정합니다.
gcloud config set project <YOUR_PROJECT_ID>
- AlphaEvolve를 제공하는 Discovery Engine API를 사용 설정합니다.
gcloud services enable discoveryengine.googleapis.com
Gemini Enterprise 앱 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에 필요한 세 가지 요소를 이해합니다. 이는 모든 실험에 재사용할 정신 모델입니다.
시드 프로그램 및 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
evaluate() 함수 및 겹침 확인을 포함하여 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가 사용 설정되지 않았음을 의미합니다. '시작하기 전에' 단계를 다시 확인하세요. '실험을 만들지 못했습니다'로 즉시 종료되는 실행은 .env의 사용자 인증 정보 또는 GE_APP_ID가 잘못되었음을 의미합니다.
5. 결과 읽기
실행은 sum_of_radii로 순위가 매겨진 상위 프로그램을 출력합니다 (높을수록 좋음). 다음 두 가지를 확인하세요.
- 점수가 올라갔습니다. 가장 진화된
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 내부에 있음을 확인합니다.
두 문제는 서로 다른 조각으로 구성된 동일한 패턴입니다.
문제 | 언어 | 평가 | 측정항목 (높을수록 좋음) | 진화하는 항목 |
| Python | 로컬 |
|
|
| Python | 로컬 |
|
|
검색이 실행되는 동안 Gemini가 최근접 이웃에서 2-opt 또는 or-opt 스타일 개선(작성하지 않은 전략)으로 이동함에 따라 neg_tour_length가 상승(0에 가까워짐)하는 것을 확인합니다.
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는 프로젝트 설정과 .venv를 포함하여 .env를 삭제합니다. 실험을 계속하려면 건너뛰세요.
이 Codelab에만 프로젝트를 만든 경우 콘솔에서 삭제하여 모든 요금을 중지합니다.
9. 축하합니다
축하합니다. Google Cloud에서 첫 번째 AlphaEvolve 실험을 실행하고 시드 프로그램, 점수 함수, Gemini만 사용하여 원 패킹과 TSP 휴리스틱이라는 두 가지 알고리즘을 진화시켰습니다.
학습한 내용
- AlphaEvolve의 루프 작동 방식: 시드 -> 생성 -> 평가 -> 점수 -> 반복
- 검색에서 측정항목을 게임화하지 않고 레시피를 최적화할 수 있는 EVOLVE-BLOCK 계약
- 점수와 실패 통계가 다음 세대를 이끄는 방법
- 로컬 평가 실험을 구성, 실행, 읽기, 조정하는 방법
기타 Codelab
이러한 Codelab은 독립형이므로 원하는 순서대로 실행하세요.
- 원격 평가자로 컴파일된 코드 진화: Cloud Run에서 컨테이너화된 평가자로 점수가 매겨진 Rust/C++ 알고리즘을 진화시킵니다.
- GKE + Ray에서 LLM 미세 조정 진화: 자체 클러스터에서 대규모 병렬 GPU 평가를 실행합니다.