AlphaEvolve 설치 및 구성

이 페이지에서는 AlphaEvolve를 사용하기 위해 환경을 초기화하고, API를 프로비저닝하고, 사용자 설정을 구성하는 데 필요한 단계를 설명합니다.

  1. 기본 요건

  2. AlphaEvolve 설정

기본 요건

환경을 구성하기 전에 Google Cloud 조직에서 기본 조달 및 인프라 단계를 완료했는지 확인합니다.

Google Cloud 프로젝트 및 라이선스

  • Google Cloud 프로젝트: 활성 결제 링크가 있는 전용 Google Cloud (GCP) 프로젝트를 만듭니다. 프로젝트 프로비저닝 또는 허용 목록 관련 문의는 Google Cloud 할당된 계정팀과 협의하세요.

  • Gemini Enterprise 라이선스: Google Cloud 영업 담당자 또는 Google Cloud Marketplace를 통해 Gemini Enterprise 라이선스를 구매합니다. Google Workspace에 라이선스를 추가하거나 독립형 제품으로 프로비저닝할 수 있습니다. 무료 체험 라이선스를 포함한 모든 Gemini Enterprise 등급에서 AlphaEvolve에 액세스할 수 있습니다.

  • 라이선스 할당 참고사항: 서비스 계정 가장을 통해 API와 상호작용하는 시스템 사용자당 하나의 Gemini Enterprise 라이선스가 필요합니다. Google Cloud 서비스 계정은 Workspace 또는 Cloud ID 라이선스를 사용하지 않습니다.

사용자 프로필 및 IAM 요구사항

AlphaEvolve 수명 주기는 세 가지 고유한 ID를 활용합니다.

프로젝트가 다음 필수 액세스 제어 역할을 준수하는지 확인합니다.

프로필 설명 필수 역할 및 권한
클라우드 관리자 일회성 초기 환경 구성, API 사용 설정, IAM 할당을 관리합니다.
  • roles/resourcemanager.projectCreator (조직/폴더 수준)
  • roles/billing.user (결제 계정 수준)
  • roles/serviceusage.admin
  • Workspace 또는 Cloud ID 관리자 권한
시스템 사용자
(연구원 / 과학자)		 최적화 실험을 구성하고 실행합니다. 서비스 계정 가장을 통해서만 API와 상호작용합니다.
  • 서비스 계정 리소스에 부여된 roles/iam.serviceAccountTokenCreator
  • 선택사항: 서비스 계정을 컴퓨팅 리소스 (예: Vertex AI Workbench)에 연결하는 경우 roles/iam.serviceAccountUser
서비스 계정 Cloud 비공개 미리보기 API 서비스의 AlphaEvolve와 직접 인터페이스하는 자동화된 ID입니다.
  • roles/discoveryengine.admin (프로젝트 범위)

관리 호스트 환경

관리 Linux 호스트 (예: Google Cloud 셸 또는 보안 배스천 호스트)는 구성 스크립트와 테스트 페이로드를 실행합니다. 호스트에 다음 기본 유틸리티가 포함되어 있는지 확인합니다.

  • Google Cloud SDK: 프로젝트 관리 명령어를 실행하는 데 필요합니다. 호스트에 gcloud CLI가 없으면 설치합니다.

  • curl: 백엔드 API 엔드포인트에 대한 HTTP 전송 액세스를 검증합니다. Debian 또는 Ubuntu 배포의 경우 패키지 관리자를 통해 유틸리티를 설치합니다.

    sudo apt update && sudo apt install -y curl

AlphaEvolve 설정

AlphaEvolve를 설정하려면 클라우드 관리자와 시스템 사용자 간에 협력이 필요합니다. 다음 설치 작업을 완료해야 합니다.

서비스 계정 만들기

다음 단계에 따라 최적화 실험을 위한 서비스 계정을 프로비저닝합니다. 클라우드 관리자는 관리 호스트에서 다음 명령어를 실행해야 합니다.

  1. Google Cloud 프로젝트 ID를 설정합니다.

    이 단계에서는 타겟 Google Cloud 프로젝트의 환경 변수를 선언하여 후속 명령어가 올바른 컨텍스트에서 작동하도록 합니다.

    PROJECT_ID="my-gcp-project-id"

    또는 활성 CLI 프로젝트 ID를 동적으로 가져올 수 있습니다.

    PROJECT_ID=$(gcloud config get project)

  2. 서비스 계정 이름을 선택합니다.

    이 단계에서는 생성 명령어에 사용될 서비스 계정의 사람이 읽을 수 있는 식별자의 환경 변수를 선언합니다.

    SA_NAME="alpha-evolve-client"

  3. 서비스 계정을 만듭니다.

    이 명령어는 Google Cloud 프로젝트 내에 새 서비스 계정을 등록하여 고유한 이름, 표시 이름, 의도된 목적에 관한 간단한 설명을 정의합니다.

    gcloud iam service-accounts create "${SA_NAME}" \
  --description="Service Account to call AlphaEvolve on Cloud Private \
Preview API service" \
  --display-name="AlphaEvolve Client SA" \
  --project=$PROJECT_ID

  4. 서비스 계정 이메일 문자열을 추출합니다.

    이 명령어는 표시 이름을 기반으로 서비스 계정 목록을 쿼리하고 리소스를 고유하게 식별하기 위해 공식 이메일 주소를 환경 변수(SERVICE_ACCOUNT_EMAIL)로 추출합니다.

    SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts list \
  --filter="displayName:AlphaEvolve Client SA" \
  --format='value(email)' \
  --project=$PROJECT_ID)

echo "Newly created Service Account Email: ${SERVICE_ACCOUNT_EMAIL}"

  1. 서비스 계정에 Discovery Engine 역할을 부여합니다.

    다음 gcloud 명령어를 실행하여 프로젝트 수준에서 서비스 계정에 roles/discoveryengine.admin 역할을 부여합니다.

    gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
  --role="roles/discoveryengine.admin" \
  --project="${PROJECT_ID}"

    이 구성은 다음 기술 논리 매개변수를 적용합니다.

    • --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}": 관리 역할 기능을 수신하는 주 구성원을 지정합니다.

    • --role="roles/discoveryengine.admin": 기본 검색 엔진 인스턴스, 대화 세션, AlphaEvolveExperiments 하위 리소스를 만드는 데 필요한 권한을 부여합니다.

    • ${SERVICE_ACCOUNT_EMAIL}: 주 구성원이 가장할 수 있는 리소스 (새 서비스 계정)를 식별합니다.

서비스 계정 대리

만들기 단계를 완료한 후 gcloud 명령줄 도구를 사용하여 연구원 (SYSTEM_USER)에게 새로 만든 서비스 계정을 가장할 수 있는 명시적 권한을 부여합니다.

  1. 가장 주 구성원 정의: 타겟 문자열 변수를 선언합니다. SYSTEM_USER_EMAIL을 최적화 실행을 수행하는 연구원의 회사 ID 또는 이메일 주소로 바꿉니다.

    SYSTEM_USER="user:SYSTEM_USER_EMAIL"

  2. 주 구성원에 토큰 생성 역할 부여: 다음 명령어를 실행하여 수명이 짧은 사용자 인증 정보 토큰 생성 기능을 지정된 시스템 사용자에 매핑합니다.

    gcloud iam service-accounts add-iam-policy-binding \
  "${SERVICE_ACCOUNT_EMAIL}" \
  --member="${SYSTEM_USER}" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project="${PROJECT_ID}"

    이 승인 바인딩은 다음을 보장합니다.

    • --member="${SYSTEM_USER}": 사용자 인증 정보 생성 승인을 받는 실제 사용자를 지정합니다.

    • --role="roles/iam.serviceAccountTokenCreator": 안전한 서비스 계정 가장을 지원하는 단기 OAuth 2.0 액세스 토큰을 생성할 권한을 부여합니다.

    • "${SERVICE_ACCOUNT_EMAIL}": 수신 정책에 바인딩되는 타겟 서비스 계정 리소스를 식별합니다.

Discovery Engine API 사용 설정

클라우드 관리자는 클라우드 비공개 미리보기 API 엔드포인트에서 AlphaEvolve와 인터페이스할 수 있도록 discoveryengine.googleapis.com API를 사용 설정해야 합니다. 클라우드 관리자는 Google Cloud 콘솔에서 또는 Linux 호스트에서 Google Cloud SDK를 사용하여 이 작업을 실행할 수 있습니다. gcloud services enable discoveryengine.googleapis.com

Discovery Engine 리소스 및 세션 만들기

구성 프로세스는 관리 ID 설정에서 핵심 애플리케이션 데이터 레이어 프로비저닝으로 전환됩니다. 이 단계에서는 코드 변이 실험을 관리, 라우팅, 추적하기 위해 기본 API에 필요한 중첩된 논리 구성요소를 빌드합니다.

Discovery Engine 리소스 계층 구조

Discovery Engine 리소스의 계층 구조는Google Cloud 프로젝트로 시작하며, 리소스는 특정 위치(리전) 내에서 호스팅됩니다. 이 기본 구조 내에서 컬렉션은 관련 리소스의 최상위 조직 컨테이너 역할을 합니다. 엔진은 핵심 AI 애플리케이션을 호스팅하기 위해 컬렉션 내에 프로비저닝되며, 여기에서 어시스턴트 리소스가 애플리케이션의 생성형 AI 속성과 도구를 관리하도록 구성됩니다. 엔진은 세션 객체로 캡처된 개별 사용자 상호작용을 관리합니다.

AlphaEvolveExperiment는 세션 아래에 중첩되어 있으며, 특정 사용자 상호작용의 맥락 내에서 알고리즘 검색 및 최적화에 사용되는 진화적 코딩 에이전트의 단일 실행을 나타냅니다.

Discovery Engine 계층 구조

리소스 프로비저닝

  1. Google Cloud 프로젝트 ID를 설정합니다.

    이 단계에서는 타겟 Google Cloud프로젝트의 환경 변수를 선언하여 후속 명령어가 올바른 컨텍스트에서 작동하도록 합니다.

    PROJECT_ID="my-gcp-project-id"

    또는

    PROJECT_ID=$(gcloud config get project)

  2. 엔진 ID를 정의합니다.

    이 단계에서는 엔진 ID의 URL 친화적인 고유 식별자의 환경 변수를 선언합니다.

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. 엔진을 만듭니다.

    이 명령어는 Google Cloud 프로젝트 내에 새 엔진을 등록하여 고유한 이름, 표시 이름, SolutionType(SOLUTION_TYPE_GENERATIVE_CHAT)을 정의합니다.

    URL="https://discoveryengine.googleapis.com/v1alpha"
URL="${URL}/projects/${PROJECT_ID}/locations/global"
URL="${URL}/collections/default_collection/engines"
URL="${URL}?engineId=${ENGINE_ID}"
curl -X POST "${URL}" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
    "display_name": "'"${ENGINE_ID}"'",
    "data_store_ids": [],
    "solution_type": "SOLUTION_TYPE_GENERATIVE_CHAT"
  }'

  4. 어시스턴트 ID를 정의합니다.

    이 단계에서는 어시스턴트 ID의 URL 친화적인 고유 식별자의 환경 변수를 선언합니다.

    ASSISTANT_ID="default_assistant"

  5. 어시스턴트를 만듭니다.

    이 명령어는 Google Cloud 프로젝트 내에 새 어시스턴트를 등록하여 고유한 이름, 표시 이름, 의도된 목적에 관한 간단한 설명을 정의합니다.

    URL="https://discoveryengine.googleapis.com/v1alpha"
URL="${URL}/projects/${PROJECT_ID}/locations/global"
URL="${URL}/collections/default_collection/engines"
URL="${URL}/${ENGINE_ID}/assistants?assistantId=${ASSISTANT_ID}"
curl -X POST "${URL}" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
    "display_name": "'"${ASSISTANT_ID}"'",
    "description": null,
    "generation_config": null,
    "web_grounding_type": "WEB_GROUNDING_TYPE_UNSPECIFIED",
    "enabled_actions": null,
    "customer_policy": null
  }'

API 액세스 테스트

클라우드 관리자가 필수 ID를 프로비저닝하고, 서비스 계정 가장을 구성하고, 엔진 레이아웃을 확인한 후 연구 시스템 사용자는 다음 검증 단계를 실행해야 합니다. 이 시퀀스는 활성 최적화 워크로드를 시작하기 전에 엔드 투 엔드 전송 및 승인을 확인하는 사전 비행 스모크 테스트 역할을 합니다.

가장을 사용하여 액세스 토큰 생성

다음 명령어를 실행하여 정책이 서비스 계정 가장을 올바르게 바인딩하는지 확인합니다. 이 검사를 통해 로컬 연구원 ID가 자동 실행 ID를 안전하게 가정할 수 있습니다.

  gcloud auth print-access-token \
    --impersonate-service-account="${SERVICE_ACCOUNT_EMAIL}"

액세스 토큰 사용

명령어는 원시 임시 OAuth 2.0 사용자 인증 정보 문자열을 출력합니다. 다단계 인증 워크플로의 경우 이 토큰을 수명이 짧은 셸 변수에 캐시하거나 전송 호출 내에 직접 인라인하여 기본 프로젝트 메타데이터를 쿼리합니다.

  TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account="${SERVICE_ACCOUNT_EMAIL}")
  curl -X GET \
    -H "Authorization: Bearer ${TOKEN}" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/${PROJECT_ID}"

엔진 보기 및 삭제

현재 액세스 토큰 또는 가장된 서비스 계정을 사용하여 엔진을 확인, 나열 또는 삭제합니다.

  URL="https://discoveryengine.googleapis.com/v1alpha"
  URL="${URL}/projects/${PROJECT_ID}/locations/global"
  URL="${URL}/collections/default_collection/engines"
  curl -X GET "${URL}" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

  URL="https://discoveryengine.googleapis.com/v1alpha"
  URL="${URL}/projects/${PROJECT_ID}/locations/global"
  URL="${URL}/collections/default_collection/engines/${ENGINE_ID}"
  curl -X DELETE "${URL}" \
    -H "Content-Type: application/json" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

수고하셨습니다. 설정 단계를 완료했습니다. 이제 AlphaEvolve V1 API를 실행할 수 있습니다.