AlphaEvolve API 참조

이 문서는 Google Cloud검색 엔진 대화 레이어에서 AlphaEvolve Cloud API의 신뢰할 수 있는 프로덕션 등급 API 참조 및 시스템 사양 역할을 합니다. 완전히 자동화된 클라이언트 측 컨트롤러 및 평가 루프를 엔지니어링하는 데 필요한 정확한 중첩 리소스 계층 구조, REST 및 gRPC 엔드포인트, 필드 수준 제약 조건, 수명 주기 상태 머신, 오류 진단 매트릭스, 보안 샌드박스 규칙, 통합 워크플로를 정의합니다.

통합 수명 주기 상태 머신

AlphaEvolve 에이전트는 두 개의 독립적인 상태 머신을 조정하여 실험 캠페인 진행 상황을 모니터링하고 개별 프로그램 변형의 전달 및 실행을 관리합니다.

실험 수명 주기 상태

실험은 전체 최적화 캠페인을 나타냅니다. 영구 서버 측 리소스로 처리되며 다음 상태를 거칩니다.

  • CREATED: 초기화 상태입니다. 리소스가 선언되고 구성되었지만 아직 초기 생성을 채우거나 API 호출을 전달하지 않았습니다.

  • RUNNING: 활성 평가 상태입니다. 엔진은 상위 후보를 동시에 샘플링하고, LLM 혼합을 통해 코드 변형을 생성하고, 평가자에게 작업을 스트리밍합니다.

  • PAUSED: 수동으로 또는 자동 보호 idle_timeout를 통해 트리거되는 임시 보류 상태입니다. 코드 생성이 중지되고 기존 작업자가 측정항목 전송을 일시중지합니다.

  • COMPLETED: 검색이 max_programs 타겟 할당을 성공적으로 충족했거나 구조적 생성 한도에 도달했음을 나타내는 터미널 상태입니다.

  • FAILED: 포착되지 않은 API 사용자 인증 정보 예외, 데이터 스토어 손상, 연속 실행기 패닉과 같은 시스템 환경 문제로 인해 처리 실행이 중단되었음을 나타내는 터미널 오류 상태입니다.

프로그램 상태

런타임 검증 시퀀스는 개별 후보 변이에 적용됩니다.

생성된 모든 코드 변형은 모집단 데이터베이스 내에서 일련의 세분화된 운영 상태를 통해 전환되는 격리된 프로그램 항목으로 작동합니다.

  1. INITIALIZED: 프로그램 항목이 데이터베이스에 생성되어 상위 계통 및 상위 프로그램 연결을 추적합니다.

  2. GENERATING: 특정 기능 코드 블록의 초안을 작성하거나 변경하기 위해 언어 모델 혼합 백엔드에 작업이 적극적으로 전달됩니다.

  3. EVALUATING: 코드 페이로드는 평가 작업자 프로세스에 의해 잠기고 격리된 테스트 하네스 환경 내에서 실행됩니다.

  4. COMPLETED: 실행 점수와 설명적인 구조적 통계가 진화 데이터베이스에 안전하게 커밋되고 프로그램이 선택 풀에 추가됩니다.

동시 실행 및 잠금 메커니즘

프로그램은 분산 토폴로지에서 경합 상태 또는 중복 점수 산정 오버헤드를 방지하기 위해 원자적 잠금 토큰 메커니즘을 사용하여 작업자 루프에 의해 획득됩니다. 평가자는 결과를 데이터베이스에 다시 커밋하려면 정확히 일치하는 잠금 토큰과 함께 최종 점수 스키마를 제출해야 합니다.

구성 및 설정 스키마

AlphaEvolve 엔진 런타임에서 활용하는 핵심 스키마 구성, 매개변수, 기본값의 개요입니다.

AlphaEvolveExperimentConfig

진화 실험 실행의 핵심 구조 매개변수와 프로그래매틱 제약 조건을 정의합니다.

필드 이름 유형 기본값 제약 조건 / 값 경계 기술적 설명
title 문자열 필수 최대 256자(영문 기준) 실험의 고유한 표시 이름입니다.
problemDescription 문자열 필수 최대 5,000자(영문 기준) 문제의 공식 사양입니다. 규칙을 설정하기 위해 프롬프트 컨텍스트에 직접 삽입됩니다.
programLanguage 문자열 필수 자유 형식 값 진화된 코드베이스의 대상 언어 (예: "python", "cpp", "verilog", "cuda", "julia", "java")입니다.
runSettings 객체 필수 RunSettings 스키마에 매핑됩니다. 게재 간격 및 제한 시간 매개변수
generationSettings 객체 선택사항 GenerationSettings 스키마에 매핑됩니다. 모델 선택 및 컨텍스트 파라미터
evolutionSettings 객체 선택사항 EvolutionSettings 스키마에 매핑됩니다. 상위 선택 및 다양성 매개변수

RunSettings

처리량 속도, 동시 로드 한도, 자동 시스템 제한 시간을 제어합니다.

필드 이름 유형 기본값 제약 조건 / 값 경계 기술적 설명
maxPrograms int32 100 최소: 2, 최대: 100000 총 실행 예산 (생성 및 평가할 프로그램)입니다. 1보다 커야 합니다.
concurrency int32 1 최소: 1, 최대: 30 큐에서 활성 상태인 동시 프로그램 변형 수입니다. 30을 초과하는 값은 허용되지 않습니다.
maxDuration 문자열 24시간 (86400초) ISO 8601 dayTimeDuration 문자열
최소: >0, 최대: 7일		 실험이 중지되기 전에 허용되는 총 실제 시간입니다.
idleTimeout 문자열 5시간 (미국/유럽)
2시간 (전 세계)		 ISO 8601 dayTimeDuration 문자열
최소: >0
최대: 위치의 기본값		 PAUSED로 자동 전환되기 전의 비활성 기간입니다. 기본값은 global에서 2시간, 리전 위치 (us, eu)에서 5시간입니다. 기간은 위치의 기본값으로 제한되므로 위치 기본값보다 큰 값 (예: global에서 12시간)을 지정하면 무시되고 값은 2시간입니다 (오류 없음).

생성 설정

GenerationSettings 스키마는 변형에 대한 프롬프트 조합, 컨텍스트 윈도우, 모델 구성을 제어합니다.

  • context (문자열): 사용자가 제공하는 선택적 참고 문서, 보조 API 또는 규칙입니다. 토큰을 200,000개 미만으로 유지하는 것이 좋습니다. 컨텍스트 크기가 200,000개 토큰을 초과하면 모델의 주의가 분산되고 변형 품질이 저하됩니다.

  • includeFullProgramInPrompt (불리언): 기본값은 false입니다.

    • true: 변형 프롬프트에는 변경 가능한 EVOLVE-BLOCK와 주변의 변경 불가능한 상용구 (복잡한 구조적 추론에 적극 권장됨)가 포함됩니다.

    • false: 변경 가능한 블록만 표시되어 토큰 컨텍스트를 절약합니다.

  • models (객체 배열): 선택사항입니다. 각 항목은 모델의 이름을 지정하고 선택적 weight를 제공합니다. 이는 다른 항목에 대한 해당 모델의 생성 호출 공유입니다. models을 생략하면 AlphaEvolve는 실험을 만들 때 이를 기본 모델로 설정합니다. 기본값은 최신 Gemini 모델이 출시됨에 따라 변경됩니다. 기본 모델에는 어떤 모델이 어떤 날짜에 적용되는지 나열됩니다. 모델을 직접 선택하거나 실행할 때마다 동일한 모델을 유지하려면 models를 설정합니다.

    다음 예시에서는 생성 호출의 약 90%를 첫 번째 모델로 보내고 나머지를 두 번째 모델로 보냅니다. 가중치는 비율이므로 합계가 1일 필요는 없습니다.

    "models": [
  {
    "name": "gemini-3.8-flash",
    "weight": 0.9
  },
  {
    "name": "gemini-3.1-pro-preview",
    "weight": 0.1
  }
]

지원되는 모델

models[].name를 다음 값 중 하나로 설정합니다. 단일 실험에서 최대 2개의 모델을 결합할 수 있습니다.

모델 이름 서비스 리전
gemini-4-argon global, us, eu
gemini-3.8-flash global, us, eu
gemini-3.7-flash global, us, eu
gemini-3.5-flash global, us, eu
gemini-3.1-pro-preview global

AlphaEvolve는 실험을 만들 때 models를 검증하고 이 표에 없거나 요청한 리전에서 사용할 수 없는 모델 이름에 대해 INVALID_ARGUMENT를 반환합니다.

기본 모델

다음 표에는 models를 생략할 때 AlphaEvolve에서 사용하는 모델이 실험 생성 날짜별로 나와 있습니다.

실험이 생성됨 기본 모델
2026년 10월 24일 이후 gemini-4-argon
2026년 9월 29일~2026년 10월 23일 gemini-3.8-flash
2026년 6월 30일~2026년 9월 28일 gemini-3.5-flash
2026년 6월 30일 이전 gemini-2.5-flash

실험에 할당된 모델을 식별하려면 실험 구성 또는 생성 응답에서 generationSettings.models를 확인합니다. 전환일 내내 변경사항이 적용되므로 해당 날짜에 생성된 실험에는 이전 또는 새로운 기본 모델이 적용될 수 있습니다. 2026년 6월 30일 이전에 models 없이 생성된 실험에는 이 필드의 값이 포함되지 않습니다.

모델은 각 실험에 저장되므로 기본값을 변경해도 이미 존재하는 실험에는 영향을 미치지 않습니다. 최신 기본 모델을 사용하려면 새 실험을 만드세요.

진화 설정

EvolutionSettings 스키마는 아일랜드 모델 재시드 및 상위 샘플링 확률을 제어합니다.

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (부동 소수점 수): 표준 적합도 기반 선택을 사용하는 대신 활성 파레토 프런티어에서 직접 상위 프로그램을 샘플링할 확률 (0.0~1.0)입니다. 최적화된 측정항목이 단일 스칼라 측정항목만 반환하는 경우 이 매개변수를 0.0 (사용 중지됨)로 설정해야 합니다.

후보 프로그램 데이터 모델

이 섹션에서는 모집단 데이터베이스 내에서 후보 코드 구조를 정의하고 구성하는 데 사용되는 데이터 스키마와 표현을 간략하게 설명합니다.

AlphaEvolveProgramContent

후보 프로그램의 파일과 구조적 구성을 정의합니다.

  • files (AlphaEvolveSourceFile 배열): 후보 코드베이스를 구성하는 모든 파일의 목록입니다. 페이로드에는 소스 파일이 하나 이상 포함되어야 합니다. Google에서는 후보 프로그램당 총 파일 수를 50개로 유지하는 것이 좋습니다. 이렇게 하면 최적의 모델 주의 및 컨텍스트 윈도우 효율성이 제공됩니다.

  • description (문자열): 생성 모델에서 제안하는 프로그래매틱 변경사항을 간략하게 설명하는 자동 생성 요약입니다 (최대 1,000자).

AlphaEvolveSourceFile

코드베이스의 개별 소스 코드 파일을 나타냅니다.

  • path (문자열): 작업공간 상대 경로 대상입니다 (필수, 최대 256자). 각 소스 파일 항목은 비어 있지 않은 경로를 지정해야 합니다. Python 작업공간을 구성하는 경우 기본 실행 파일 진입점의 이름은 정확히 "initial_program.py"이어야 합니다.

  • content (문자열): 함수 구현 블록으로 구성된 원시 소스 코드 문자열입니다. Google은 모든 파일의 누적 코드베이스 크기를 4,000~5,000줄의 코드 (LOC) 미만으로 유지하는 것을 권장합니다. 이는 모델 어텐션 및 변형 생성 성능에 최적입니다.

  • programLanguage (문자열): 언어 파서 매핑 태그입니다. 이 문자열은 상위 실험 구성 내에 지정된 언어와 명시적으로 일치해야 합니다.

  • description (문자열): 파일의 개별 아키텍처 또는 목적을 간략하게 설명하는 선택적 요약으로, 변형 패스 중에 LLM에 노출됩니다 (최대 500자).

AlphaEvolveProgramEvaluation

런타임 실행 후 클라이언트 실행기 인스턴스에서 진화 데이터베이스로 다시 제출하는 구조화된 페이로드입니다.

  • scores (AlphaEvolveScores): 표준화된 객관적인 수치 측정항목 값입니다. 이를 3~5개의 고유한 부동 소수점 측정항목으로 제한하는 것이 좋습니다. 타겟 측정기준이 과도하면 다중 목표 파레토 비교기 성능이 저하됩니다.

  • insights (AlphaEvolveEvaluationInsight 배열): LLM의 후속 변형 생성 시도를 지원하기 위해 다시 전달되는 진단 시맨틱 라벨 및 자연어 실행 trace입니다 (최대 10개 항목 권장).

점수 공식 및 수집 형식

최대화 규칙

AlphaEvolve는 기본적으로 단조 언덕 오르기 알고리즘으로 작동하며 모든 수치 측정항목을 엄격하게 극대화합니다. 평가 파이프라인이 최소화 타겟(예: 애플리케이션 지연 시간 최소화(밀리초) 또는 메모리 사용량 감소)을 추적하는 경우 데이터베이스에 다시 제출하기 전에 값을 무효화해야 합니다(submitted_score = -latency_ms).

점수는 연속적이어야 합니다. 불리언 또는 고도로 이산적인 측정항목은 효과적인 언덕 오르기 탐색에 충분한 경사 신호를 제공하지 않습니다.

단일 목표 수집 스키마

평가 도구가 단일 스칼라 목적 함수에 대해 최적화하는 경우 다음 JSON을 사용합니다.

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "validation",
        "text": "Passed syntax and basic compilation."
      }
    ]
  }
}

다중 목표 수집 스키마

독립적인 다중 목표 추적 매개변수를 전달하여 서버 측 파레토 프런티어 최적화 루틴을 활성화할 때 다음 JSON을 사용합니다.

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      },
      {
        "metric": "latency",
        "score": -42.5
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "verification",
        "text": "Passed 5 out of 5 unit tests."
      },
      {
        "label": "latency_warning",
        "text": "Latency regression of 3% observed on large dataset."
      }
    ]
  }
}

프로그램 데이터 가져오기 및 쿼리

AlphaEvolve 시스템은 생성된 모든 변형의 원격 분석, 실행 측정항목, 전체 소스 코드를 시스템 로그에 기록하므로 개발자는 API 또는 CLI를 사용하여 이 이전 데이터 스토어를 쿼리하여 최적화 진행 상황을 추적하고 가장 성능이 우수한 코드 후보를 추출할 수 있습니다.

REST API를 사용한 프로그램 검색

평가된 프로그램 리소스는 필터링 및 정렬 쿼리 매개변수와 함께 표준 ListAlphaEvolvePrograms 엔드포인트를 사용하여 데이터베이스에서 쿼리할 수 있습니다.

  • 상태 필터링: 특정 수명 주기 상태와 일치하는 프로그램을 쿼리합니다.

    GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED

  • 측정항목 기반 정렬: 최적화된 측정항목을 기준으로 정렬된 후보를 검색합니다.

    GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5

CLI를 사용한 프로그램 검색

터미널에서 직접 완료된 상위 후보를 가져오려면 다음 명령어를 실행합니다.

ae results best <experiment-nickname> --top 5

전체 CLI 사용 예시

AlphaEvolve CLI는 개발자에게 셸에서 직접 캠페인을 빠르게 관리하고 모니터링할 수 있는 기능을 제공합니다.

  • 대화 세션의 모든 실험을 나열합니다.

    ae experiment list

  • 특정 실험의 모든 변형된 후보 프로그램을 나열합니다.

    ae program list EXPERIMENT_NICKNAME \
  --state=COMPLETED \
  --order_by="accuracy desc"

    EXPERIMENT_NICKNAME을 실험 이름으로 바꿉니다.

  • 실적이 가장 우수한 완성된 코드 후보를 가져옵니다.

    ae results best EXPERIMENT_NICKNAME --top 5

    EXPERIMENT_NICKNAME을 실험 이름으로 바꿉니다.

  • 일시중지된 캠페인 재개:

    ae experiment resume EXPERIMENT_NICKNAME

    EXPERIMENT_NICKNAME을 실험 이름으로 바꿉니다.

Core REST API 엔드포인트 디렉터리

모든 엔드포인트는 Google Cloud Discovery Engine API의 v1alpha에서 버전이 지정됩니다.

상위 리소스 경로 패턴

실제 중첩된 상위 리소스 URI는 projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}와 같이 구성됩니다.

  • AlphaEvolve는 global, us, eu에서 사용할 수 있습니다. 다른 위치에서 실험을 만들면 FAILED_PRECONDITION가 반환됩니다.
  • Assured Workloads 프로젝트는 지원되지 않습니다.
  • 프로젝트는 위치당 동시에 활성 상태인 (STARTED 또는 RUNNING) AlphaEvolve 실험이 30개로 제한됩니다. 이 한도를 초과하는 실험을 시작하거나 재개하면 RESOURCE_EXHAUSTED가 반환됩니다.

실험 만들기 (POST)

  • 경로:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*}/alphaEvolveExperiments

  • 요청 본문: AlphaEvolveExperimentConfig (섹션 2.1 참고)

  • 응답: 초기화된 캠페인이 포함된 AlphaEvolveExperiment 리소스입니다.

  • HTTP 상태: 200 OK

API 페이로드 예시

  1. 요청 본문 예시 (POST /alphaEvolveExperiments)

    {
  "config": {
    "title": "Sorting Optimization Campaign",
    "problemDescription": "Optimize the custom_heuristic function.",
    "programLanguage": "python",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.8-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

  2. 응답 본문 예시 (200 OK)

    {
  "name": "projects/.../sort-opt-01",
  "state": "CREATED",
  "createTime": "2026-06-23T13:30:00Z",
  "config": {
    "title": "Sorting Optimization Campaign",
    "problemDescription": "Optimize the custom_heuristic function.",
    "programLanguage": "python",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.8-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

실험 시작 (POST)

  • 경로:

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:start

  • 요청 본문: StartExperimentRequest

  • 지원 중단 경고: 본문 필드 initialProgram는 지원 중단되었으며 무시됩니다.

  • 응답: GoogleLongrunningOperation (LRO)

  • HTTP 상태: 200 OK (상태가 CREATED에서 RUNNING로 전환됨)

API 페이로드 예시

  1. 요청 본문 예시

    {
  "desiredProgramsCount": 1
}

  2. 응답 본문 예시 (200 OK - 장기 실행 작업)

    {
  "name": "projects/.../operations/start-op-7788",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveStartExperimentMetadata",
    "createTime": "2026-06-23T13:31:00Z"
  },
  "done": false
}

포인트 멤버십 획득 (POST)

  • 경로:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:acquirePrograms

  • 요청 본문: AcquireProgramsRequest

    • desiredProgramsCount (int32): 검색할 변형된 프로그램의 선택적 배치 수입니다 (설정하지 않은 경우 기본값은 1).

  • 응답 상태:

    • 200 OK: 잠긴 AlphaEvolveProgram 리소스가 포함된 응답을 반환합니다.

    • 204 No Content: 대기열이 비어 있거나 캠페인이 일시중지되었습니다. 실행기는 절전 모드로 전환 (예: 15초)하고 다시 시도해야 합니다.

API 페이로드 예시

  1. 요청 본문 예시

    {
  "desiredProgramsCount": 1
}

  2. 응답 본문 예시 (200 OK)

    {
  "programs": [
    {
      "name": "projects/.../alphaEvolvePrograms/prog-102",
      "lockToken": "token_uuid_8877_x99",
      "state": "EVALUATING",
      "createTime": "2026-06-23T13:32:00Z",
      "content": {
        "description": "Mutated candidate program.",
        "files": [
          {
            "path": "initial_program.py",
            "programLanguage": "python",
            "description": "Primary sorting executable.",
            "content": "def custom_heuristic(arr, _):\n    ..."
          }
        ]
      }
    }
  ]
}

  3. 응답 본문 예시 (204 콘텐츠 없음)

HTTP 상태 204가 빈 페이로드 컨텍스트와 함께 반환되었습니다.

프로그램 평가 제출 (POST)

  • 경로:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:submitProgramsEvaluations

  • 요청 본문: SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (배열): 일치하는 lockToken, 정규화된 프로그램 리소스 경로, 평가 페이로드 (점수 및 통계)가 포함됩니다. API는 호출당 정확히 하나의 평가 제출을 허용합니다. 여러 평가를 단일 요청으로 일괄 처리하면 INVALID_ARGUMENT로 거부됩니다. 여러 후보를 평가할 때는 각 프로그램을 개별적으로 제출합니다.

  • 응답: SubmitProgramsEvaluationsResponse (비어 있음)

  • HTTP 상태: 200 OK (점수 저장, 활성 잠금 해제, 통계 등록)

API 페이로드 예시

  1. 요청 본문 예시

    {
  "evaluationSubmissions": [
    {
      "lockToken": "token_uuid_8877_x99",
      "program": "projects/.../alphaEvolvePrograms/prog-102",
      "evaluation": {
        "scores": {
          "scores": [
            {
              "metric": "latency_performance",
              "score": evaluation_payload["score"]
            }
          ]
        },
        "insights": {
          "insights": [
            {
              "label": "benchmark",
              "text": "Completed test case in 12.45ms."
            }
          ]
        }
      }
    }
  ]
}

  2. 응답 본문 예시 (200 OK)

    {}

실험 재개 (POST)

  • 경로:

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:resume

  • 요청 본문: ResumeExperimentRequest

  • 응답: GoogleLongrunningOperation (LRO)

  • HTTP 상태: 200 OK (상태가 PAUSED에서 RUNNING로 다시 전환됨)

API 페이로드 예시

  1. 요청 본문 예시

    {}

  2. 응답 본문 예시 (200 OK - 장기 실행 작업)

    {
  "name": "projects/.../operations/resume-op-9900",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveResumeExperimentMetadata",
    "createTime": "2026-06-23T13:45:00Z"
  },
  "done": false
}

프로그램 나열 (GET)

  • 경로:

    GET v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}/alphaEvolvePrograms

  • 쿼리 매개변수:

    • stateFilter (문자열): 선택사항입니다. 표준 목록 필터(예: stateFilter = 'COMPLETED')입니다.

    • orderBy (문자열): 선택사항입니다. 측정항목 기반 정렬(예: accuracy desc)

  • 대답: ListAlphaEvolveProgramsResponse.

  • HTTP 상태: 200 OK

API 페이로드 예시

  1. 요청 쿼리 URL 예시

    GET v1alpha/projects/.../alphaEvolveExperiments/sort-opt-01/
  alphaEvolvePrograms?stateFilter=COMPLETED&orderBy=latency_performance%20desc
  &pageSize=1

  2. 응답 본문 예시 (200 OK)

    {
  "alphaEvolvePrograms": [
    {
      "name": "projects/.../alphaEvolvePrograms/prog-102",
      "state": "COMPLETED",
      "createTime": "2026-06-23T13:32:00Z",
      "evaluation": {
        "scores": {
          "scores": [
            {
              "metric": "latency_performance",
              "score": -12.45
            }
          ]
        },
        "insights": {
          "insights": [
            {
              "label": "benchmark",
              "text": "Completed test case in 12.45ms."
            }
          ]
        }
      }
    }
  ],
  "nextPageToken": "token_page_1_next"
}

진단 코드 및 문제 해결 참조

API 진단 코드 매트릭스

HTTP 상태 오류 유형 시스템 원인 해결 방법 또는 완화 조치
400 INVALID_ARGUMENT
  • 잘못된 형식의 EVOLVE-BLOCK-START / EVOLVE-BLOCK-END 마커 (예: 마커의 줄을 공유하는 콘텐츠, 중첩된 블록 또는 누락된 종료 마커)
  • 수정 가능한 코드 없이 주석 또는 공백만 포함된 빈 evolve 블록입니다.
  • maxPrograms이(가) 2 미만으로 설정되었습니다.
  • 인식할 수 없는 구성 필드입니다.
  • 모델 구성이 잘못되었습니다 (모델이 2개 이상, 중복 항목, 양수가 아닌 가중치 또는 [0.0, 2.0] 범위를 벗어난 온도).
  • 단일 submitProgramsEvaluations 호출에서 여러 평가를 제출합니다.
  • 프로젝트가 Assured Workloads 프로젝트입니다.
 마커가 한 줄에 하나만 있고 주석이 아닌 코드 줄을 하나 이상 포함하는지 확인합니다. maxPrograms을 2 이상으로 설정합니다. API의 프리뷰 버전에 있던 notes와 같이 API에 포함되지 않은 필드를 삭제합니다. 평가는 한 번에 하나씩 개별적으로 제출합니다.
403 PERMISSION_DENIED
  • 호출자에게 검색 엔진 편집자 역할 (roles/discoveryengine.editor) 또는 관리자 역할 (roles/discoveryengine.admin)이 없습니다. 참고: roles/discoveryengine.user은 AlphaEvolve 권한을 부여하지 않으며 roles/discoveryengine.viewer은 실험을 가져올 수 없습니다.
  • 호출자에게 상위 세션 리소스에 대한 권한이 없습니다.
  • 활성 Gemini Enterprise 라이선스가 할당되지 않았습니다.
 프로젝트 수준에서 roles/discoveryengine.editor 또는 roles/discoveryengine.admin을 부여하고 상위 세션에 대한 액세스 권한을 확인합니다. 활성 Gemini Enterprise 라이선스를 확인합니다. 애플리케이션 기본 사용자 인증 정보를 구성합니다.

gcloud auth application-default login --project=PROJECT_ID

참고: Model Armor는 AlphaEvolve 구성에서 지원되지 않습니다.
400 FAILED_PRECONDITION
  • 오래되었거나 만료된 잠금 토큰 또는 프로그램 상태 불일치 (예: 임대가 만료된 후 후보가 다시 획득되거나 완료됨)
  • 지원되지 않는 위치 (global, us 또는 eu 외부)에서 실험이 생성되었습니다.
  • 프로젝트에서 Vertex AI API (aiplatform.googleapis.com)가 사용 설정되지 않았습니다.
 :acquirePrograms에서 반환된 정확한 lockToken를 에코합니다. 클라이언트 측 제한 시간 (권장 30분)을 적용하고 제한 시간 초과 시 실패 페널티 점수를 제출합니다. 지원되는 위치에서 실험을 다시 만듭니다. Vertex AI API를 사용 설정합니다. gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID
429 RESOURCE_EXHAUSTED
  • 프로젝트가 위치당 동시에 활성화된 실험 (STARTED / RUNNING) 한도인 30개에 도달했습니다.
  • 백엔드 모델 생성 토큰 할당량이 소진되었습니다.
 진행 중인 실험 한도: 새 실험을 시작하기 전에 진행 중인 실험을 완료하거나 중지합니다 (runSettings에서 concurrency를 낮춰도 이 한도에 영향을 미치지 않음). 모델 토큰 할당량: runSettings에서 concurrency를 낮추고 지수 백오프를 구현합니다.
503 SERVICE_UNAVAILABLE 입력 안전 분류기를 사용할 수 없거나 백엔드 서비스에 일시적으로 과부하가 발생했습니다. 클라이언트 측에서 무작위 지수 백오프를 사용하여 재시도 루프를 구현합니다.

일반적인 오류 메시지 및 해결 방법

다음 참조에는 API에서 반환하는 일반적인 오류 메시지, 근본 원인, 해결 단계가 나와 있습니다.

초기 프로그램 및 EVOLVE-BLOCK 파싱 오류

오류 메시지 시스템 원인 해결 방법 또는 완화 조치
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. EVOLVE-BLOCK-START 및 EVOLVE-BLOCK-END 마커가 모두 같은 줄에 표시됩니다. 시작 및 종료 마커를 별도의 줄에 배치합니다.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. 코드, 텍스트 또는 후행 문자가 EVOLVE-BLOCK-START 또는 EVOLVE-BLOCK-END 마커와 같은 줄에 있습니다. 마커가 줄에 단독으로 있는지 확인합니다 (# EVOLVE-BLOCK-START와 같은 주석 프리픽스만 앞에 옴).
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. 이미 열려 있는 evolve 블록 내에 EVOLVE-BLOCK-START 마커가 표시됩니다. 중첩된 시작 마커를 삭제하세요. 중첩된 evolve 블록은 지원되지 않습니다.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. EVOLVE-BLOCK-END 마커가 앞에 EVOLVE-BLOCK-START 없이 표시됩니다. 모든 종료 마커 앞에 일치하는 시작 마커가 있는지 확인합니다.
Parsing error: Evolve block started but not ended. 일치하는 닫는 EVOLVE-BLOCK-END 마커가 없는 EVOLVE-BLOCK-START 마커가 발견되었습니다. 닫는 EVOLVE-BLOCK-END 마커를 추가합니다.

프로그램 콘텐츠 및 구조 오류

오류 메시지 시스템 원인 해결 방법 또는 완화 조치
Program content must contain at least one source file. program_content.source_files가 비어 있습니다. 소스 파일을 하나 이상 제공하세요.
source_files entries must have a non-empty path. 소스 파일 항목에 빈 path 문자열이 있습니다. 모든 소스 파일에 유효한 상대 경로를 지정합니다.
source_files entry has empty content; path: <path> 소스 파일 항목에 빈 문자열 콘텐츠가 포함되어 있습니다. 파일 콘텐츠를 채웁니다.
Program content must contain at least one EVOLVE-BLOCK-START / EVOLVE-BLOCK-END region with editable code between the markers (whitespace and comment-only regions don't count -- AlphaEvolve has nothing to mutate). Evolve 블록에는 주석, docstring 또는 공백만 포함되며 수정 가능한 코드는 없습니다. 블록 내에 수정 가능한 코드 (예: 함수 정의 또는 알고리즘 로직)를 한 줄 이상 포함합니다.

구성 및 모델 검증 오류

오류 메시지 시스템 원인 해결 방법 또는 완화 조치
unsupported model: <model_name> 요청한 모델이 지원되지 않거나 프로젝트에 사용 설정되지 않았습니다. 지원되는 모델을 사용합니다. 생성 설정을 참고하세요.
model '<model_name>' is not served from domain shard '<location>'. 지정된 리전 위치에서 모델을 사용할 수 없습니다. 지원되는 모델 및 위치는 생성 설정을 참고하세요.
generation_settings.models must contain at most 2 distinct models; got <count>. generation_settings.models에 모델 구성이 3개 이상 지정되었습니다. 혼합에서 모델을 최대 2개 지정합니다.
generation_settings.models contains duplicate entry: <model_name> generation_settings.models에 동일한 모델 이름이 두 번 이상 표시됩니다. 중복된 모델 항목을 삭제합니다.
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. 모델 샘플링 가중치가 음수, 0 또는 유한하지 않습니다. 양수 가중치를 설정하거나 항목을 삭제하세요.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. 모델 온도가 유효 범위 [0.0, 2.0]를 벗어납니다. 온도를 0.0~2.0 사이의 값으로 조정하세요.
RunSettings.max_programs is required and must be greater than 1. max_programs가 생략되었거나 1 이하로 설정되었습니다. max_programs를 2 이상으로 설정합니다 (진화된 후보를 허용하려면 최소 2가 필요함).
RunSettings.concurrency is required and must be positive. concurrency가 생략되었거나 0 이하로 설정되었습니다. concurrency를 양의 정수 (일반적으로 1~30)로 설정합니다.
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. pareto_sampling_probability이(가) [0.0, 1.0] 외부에 있습니다. 0.0~1.0 사이의 확률을 설정합니다.

프로젝트 기본 요건 및 실험 수명 주기 오류

오류 메시지 시스템 원인 해결 방법 또는 완화 조치
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> Google Cloud 프로젝트에서 Vertex AI API (aiplatform.googleapis.com)가 사용 설정되지 않았습니다. gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID를 실행합니다.
Project has reached the limit of 30 concurrently active AlphaEvolve experiments in location <location>. Stop or wait for a running experiment to finish before starting or resuming another. 프로젝트가 해당 위치에서 동시에 활성화된 실험 (STARTED 또는 RUNNING)의 할당량인 30개에 도달했습니다. 새 실험을 시작하거나 재개하기 전에 기존 실험을 중지하거나 완료하세요.
Cannot <action> experiment from state <current_state> 잘못된 상태 전환을 시도했습니다 (예: 이미 실행 중인 실험을 시작하거나 새로 만든 실험을 재개). 실험이 표준 수명 주기 전환(CREATED → START, PAUSED/COMPLETED → RESUME, STARTED/RUNNING → STOP)을 따르는지 확인합니다.
Cannot resume experiment: a start or watchdog message is already pending. Stop the experiment first to drain it, or wait for the pending delivery to complete. 이전 시작 또는 재개 작업이 아직 진행 중입니다. 대기 중인 전송이 완료될 때까지 기다리거나 STOP를 호출하여 대기 중인 메시지를 드레이닝하세요.
AlphaEvolve is not available for this project. 프로젝트가 차단되었거나 지원되지 않는 규정 준수 프로필입니다. 규정 준수 및 보안 프로필을 참고하세요.

프로그램 획득 및 평가 오류

오류 메시지 시스템 원인 해결 방법 또는 완화 조치
Exactly one evaluation submission is required. 여러 평가 제출이 단일 submitProgramsEvaluations 요청으로 일괄 처리되었습니다. 평가를 API 호출당 하나씩 개별적으로 제출합니다.
Program is required for each evaluation submission./submission.program is required. 평가 제출에 program 리소스 경로가 제공되지 않았습니다. 전체 프로그램 리소스 경로를 전달합니다.
Lock token is required for each evaluation submission./submission.lock_token is required. acquirePrograms 중에 반환된 lock_token이 생략되었습니다. 프로그램을 획득할 때 반환된 정확한 lock_token 문자열을 전달합니다.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' 제출 시 전송된 잠금 토큰이 활성 서버 임대와 일치하지 않습니다 (예: 임대가 만료되어 다른 작업자가 임대를 획득했거나 잘못된 토큰이 제공됨). acquirePrograms의 정확한 lockToken를 에코하고 클라이언트 제한 시간 전에 결과를 제출합니다.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> 프로그램이 이미 평가되었거나, 취소되었거나, EVALUATION_IN_PROGRESS에서 전환되었습니다. 오래된 평가를 삭제하거나 가능한 경우 후보를 다시 획득합니다.
The request was rejected by a safety policy. 입력 문제 설명, 초기 코드 또는 평가 측정항목이 안전 분류 정책을 트리거했습니다. 프롬프트 텍스트와 문제 설명을 정제하여 민감한 키워드나 흔적을 삭제합니다.
The input safety classifier is currently unavailable. 안전성 분류 서비스에 일시적으로 연결할 수 없거나 과부하가 발생했습니다 (실패 시 종료). 지수 백오프 재시도 로직을 구현합니다.

'자동 삭제' 해결

안전 필터 가로채기 (자동 삭제)는 민감한 문구 또는 안전 규칙 트리거로 인해 서버 측 언어 모델이 변형된 후보 프롬프트에 플래그를 지정하고 삭제할 때 발생합니다. 서버가 출력을 무음으로 처리하여 큐가 빈 응답을 반환하고 클라이언트 실행기가 무기한 대기할 수 있습니다.

해결 방법:

  • 컨텍스트 정제: problemDescription에서 감정적으로 격앙되거나 보안에 민감한 문구를 삭제합니다.

  • 인사이트 필터링: insights 페이로드에서 원시 예외 trace 또는 터미널 stderr 로그를 파싱하고 잘라내어 다운스트림 필터를 트리거하는 안전하지 않은 시스템 콘텐츠가 에코되지 않도록 합니다.

  • 데이터 세트 현지화: 프롬프트 내에 학습 레코드나 대규모 텍스트 코퍼스를 배치하지 마세요. 평가 루프 실행 중에 클라이언트 환경에서 로컬로 로드하세요.

클라이언트 측 평가 권장사항

'스파게티 코드' 병목 현상

최적화되지 않은 소스 형식은 최적화 품질을 저하시킵니다. '스파게티 코드 == 노이즈가 많은 검색 공간' EVOLVE-BLOCK 마커를 배치하기 전에 다음을 수행합니다.

  • 변수와 함수 서명이 명확하게 이름이 지정되도록 코드 블록을 리팩터링합니다.

  • 각 함수 또는 변수의 역할과 이유를 설명하는 설명적이고 간결한 docstring을 추가합니다. docstring이 실제 기능 코드와 함께 있는지 확인합니다. EVOLVE-BLOCK 내에 docstring 또는 주석만 배치하면 빈 블록으로 거부됩니다.

  • EVOLVE-BLOCK-START 및 EVOLVE-BLOCK-END 주석 마커는 선행 공백과 주석 접두사 (예: # 또는 //)를 제외하고 각 줄에 단독으로 배치해야 합니다.

  • 외부의 변경할 수 없는 종속 항목 (예: 도우미 모듈 가져오기 또는 정적 데이터 로드)이 EVOLVE-BLOCK 외부에 있는지 확인합니다.

컨텍스트 윈도우 할당

변형 창의성을 극대화하려면 API로 전송되는 코드 페이로드를 제한하세요. 전체 프로그램 컨텍스트는 150,000~200,000개 토큰 미만이어야 합니다. 정적이고 변경 불가능한 상용구의 큰 블록은 모델의 주의를 분산시키고 성능을 저하시킵니다. 유틸리티 스크립트, 데이터 수집 파이프라인, 무거운 검증 라이브러리를 클라이언트 측 평가자로 완전히 이동합니다.

초기 프로그램 먼저 준비

AlphaEvolve를 실행하기 전에 표준 코딩 에이전트를 사용하여 시드 코드베이스와 평가자를 모두 디버그합니다.

  • 시드 준비: 명백한 문법 버그, 컴파일 문제, 극단적 사례를 수정합니다.

  • 시작 점수 확인: 기준 점수가 합리적이고 평가자가 완전히 결정론적인지 확인합니다 (동일한 코드 + 동일한 입력 = 동일한 점수).

  • 잘못된 입력으로 테스트: 의도적으로 손상된 함수를 사용하여 평가자를 실행하여 컴파일러 문제를 포착하고, 무한 루프를 원활하게 처리하고, 높은 음수 페널티 점수를 반환하는지 확인합니다.

과도하게 최적화된 기준선 피하기

이미 고도로 최적화된 기준 프로그램을 시드로 전달하지 마세요. 초기 프로그램이 이미 최적에 가까운 경우 개선할 여지가 거의 없으므로 AlphaEvolve가 힐 클라이밍을 수행하기 어렵습니다. 합리적이지만 최대로 최적화되지 않은 기준선으로 시작합니다. 이를 통해 AlphaEvolve는 탐색과 힐 클라이밍을 수행할 수 있습니다

클라이언트 측 실행기 보호 장치

클라이언트 측 평가자는 악의적이거나 리소스 집약적이거나 응답하지 않는 후보가 병렬 작업자를 중단하지 않도록 엄격한 보호 장치를 시행해야 합니다.

  • 엄격한 제한 시간: 엄격한 실행 제한 시간인 30분 (또는 검색 공간 구조에 따라 더 짧은 시간)을 적용합니다.

  • 제한 시간 페널티 제출: 후보 프로그램 변형이 제한 시간 한도를 초과하면 실행 스레드를 즉시 종료합니다. 후보 프로세스가 실패하지 않도록 합니다. 대신 심각한 실패 페널티 점수 (예: -100000.0)를 설명 디버그 통계와 함께 즉시 컴파일하고 서버에 제출하여 프로그램의 큐 잠금을 해제합니다.

  • AST 보안 필터: 컴파일 전에 수신 소스 코드 페이로드에 대해 항상 추상 구문 트리 (AST) 검사 확인을 실행합니다. 제한된 리플렉션 또는 실행 프리미티브 (예: eval, exec, getattr, setattr)가 감지되면 즉시 실행을 중단하고 심각한 실패 페널티를 적용합니다.

추가 자료

자세한 내용은 다음 리소스를 참조하세요.