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, 최대: 100,000 총 실행 예산 (생성 및 평가할 프로그램) 1보다 커야 합니다.
concurrency int32 1 최소: 1, 최대: 30 대기열에서 활성 상태인 병렬 프로그램 변이 수입니다. 30보다 큰 값은 허용되지 않습니다.
maxDuration 문자열 24시간 (86400초) ISO 8601 dayTimeDuration 문자열
최소: >0, 최대: 7일		 실험이 중지되기 전에 허용되는 총 실제 시간입니다.
idleTimeout 문자열 5시간 (미국/EU)
2시간 (전 세계)		 ISO 8601 dayTimeDuration 문자열
최소: >0
최대: 위치의 기본값		 PAUSED로 자동 전환되기 전 비활성 기간입니다. 기본값은 global의 경우 2시간, 지역 위치 (us, eu)의 경우 5시간입니다. 기간은 위치의 기본값에 의해 제한되므로 위치 기본값 (예: global의 경우 12시간)보다 큰 값을 지정하면 무시되고 값은 2시간이 됩니다 (오류 없음).

생성 설정

GenerationSettings 스키마는 프롬프트 어셈블리, 컨텍스트 윈도우, 변형 모델 구성을 제어합니다.

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

  • includeFullProgramInPrompt (bool): 기본 false입니다.

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

    • false: 변경 가능한 블록만 표시되어 토큰 컨텍스트가 저장됩니다.

  • models (객체 배열): 선택사항입니다. 각 항목은 모델의 이름을 지정하고 선택적 weight를 제공합니다. 이는 다른 항목에 대한 해당 모델의 생성 호출 점유율입니다. models를 생략하면 AlphaEvolve가 실험을 만들 때 기본값을 선택합니다. 기본값은 Google에서 AlphaEvolve를 사용한 코드 생성에 권장하는 Gemini 모델입니다. 이 권장사항은 새 모델이 출시됨에 따라 변경됩니다. 2026년 9월 29일부터 기본값은 gemini-3.8-flash입니다. 다른 모델을 사용하려면 models에서 원하는 모델을 지정하세요. 실행할 때마다 동일한 모델을 고정하려면 models을 직접 설정하세요.

    AlphaEvolve는 실험을 만들 때 기본값을 확인하므로 기본 모델이 변경되기 전에 생성된 실험은 구성에 기록된 모델을 유지합니다. 기존 실험을 Gemini 3.8 Flash로 이동하려면 models에서 지정하거나 새 실험을 만드세요.

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

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

지원되는 모델

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

모델 이름 서비스 지역
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을 반환합니다.

진화 설정

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

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (float): 표준 적합도 기반 선택을 사용하는 대신 활성 파레토 프런티어에서 직접 상위 프로그램을 샘플링할 확률 (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줄의 코드로 유지하는 것이 좋습니다. 이는 모델 어텐션 및 변이 생성 성능에 최적입니다.

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

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

AlphaEvolveProgramEvaluation

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

  • scores (AlphaEvolveScores): 표준화된 객관적인 숫자 측정항목 값입니다. 권장사항에 따라 이를 3~5개의 고유한 부동 소수점 측정항목으로 제한해야 합니다. 타겟 차원이 너무 많으면 다중 목표 파레토 비교기 성능이 저하됩니다.

  • insights (AlphaEvolveEvaluationInsight 배열): LLM의 후속 변경사항 생성 시도를 지원하기 위해 다시 전달되는 진단 시맨틱스 라벨과 자연어 실행 트레이스입니다 (최대 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을 실험 이름으로 바꿉니다.

핵심 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의 일부가 아닌 필드(예: API의 미리보기 버전에 있던 notes)를 삭제합니다. 평가를 한 번에 하나씩 개별적으로 제출합니다.
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

참고: AlphaEvolve 구성에서는 Model Armor가 지원되지 않습니다.
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 마커가 표시됩니다. 중첩된 시작 마커를 삭제합니다. 중첩된 진화 블록은 지원되지 않습니다.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. EVOLVE-BLOCK-START이 앞에 나오지 않고 EVOLVE-BLOCK-END 마커가 표시됩니다. 모든 종료 마커 앞에 일치하는 시작 마커가 있는지 확인합니다.
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 페이로드에서 원시 예외 추적 또는 터미널 stderr 로그를 파싱하고 자르면 다운스트림 필터를 트리거하는 안전하지 않은 시스템 콘텐츠가 에코되지 않습니다.

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

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

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

소스 형식이 최적이 아니면 최적화 품질이 저하됩니다('스파게티 코드 == 노이즈가 많은 검색 공간'). EVOLVE-BLOCK 마커를 배치하기 전에 다음을 확인하세요.

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

  • 각 함수나 변수가 무엇을 하는지, 왜 하는지를 설명하는 간결한 설명 문자열을 추가합니다. 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)가 감지되면 즉시 실행을 중단하고 심각한 실패 페널티를 적용합니다.

추가 자료

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