Instala y configura AlphaEvolve

En esta página, se describen los pasos necesarios para inicializar tu entorno, aprovisionar la API y configurar los parámetros de configuración del usuario para comenzar a trabajar con AlphaEvolve.

  1. Requisitos previos

  2. Configura AlphaEvolve

Requisitos previos

Antes de configurar tu entorno, verifica que tu Google Cloud organización complete los pasos básicos de adquisición y de infraestructura.

Google Cloud proyecto y licencias

  • Proyecto de Google Cloud: Crea un proyecto de GCP dedicado con Google Cloud vínculos de facturación activos. Para consultas sobre el aprovisionamiento de proyectos o la lista de entidades permitidas, comunícate con tu equipo de cuentas asignado Google Cloud .

  • Licencias de Gemini Enterprise: Compra licencias de Gemini Enterprise a través de tu Google Cloud representante de ventas o de Google Cloud Marketplace. Puedes agregar licencias a Google Workspace o aprovisionarlas como ofertas independientes. Cualquier nivel de Gemini Enterprise, incluida una licencia de prueba, otorga acceso a AlphaEvolve.

  • Nota sobre la asignación de licencias: El sistema requiere una licencia de Gemini Enterprise por cada usuario del sistema que interactúe con la API a través de la suplantación de la identidad de la cuenta de servicio. Google Cloud Las cuentas de servicio no consumen licencias de Workspace ni de Cloud Identity.

Perfiles de usuario y requisitos de IAM

El ciclo de vida de AlphaEvolve utiliza las tres identidades distintas.

Asegúrate de que tu proyecto cumpla con los siguientes roles obligatorios de control de acceso:

Perfil Descripción Roles y permisos requeridos
Administrador de la nube Administra la configuración inicial única del entorno, la habilitación de la API, y la asignación de IAM.
  • roles/resourcemanager.projectCreator (nivel de organización o carpeta)
  • roles/billing.user (nivel de cuenta de facturación)
  • roles/serviceusage.admin
  • Privilegios de administrador de Workspace o Cloud Identity
Usuario del sistema
(investigador o científico)		 Configura y ejecuta experimentos de optimización. Interactúa con la API estrictamente a través de la suplantación de la identidad de la cuenta de servicio.
  • roles/iam.serviceAccountTokenCreator otorgado en el recurso de la cuenta de servicio
  • Opcional: roles/iam.serviceAccountUser si adjuntas la cuenta de servicio a recursos de procesamiento (por ejemplo, Vertex AI Workbench).
Cuenta de servicio Identidad automatizada que interactúa directamente con el servicio de la API de AlphaEvolve en la versión preliminar privada de Cloud.
  • roles/discoveryengine.admin (con alcance del proyecto)

Entorno host administrativo

Un host administrativo de Linux (como Google Cloud Shell o un host bastion seguro ) ejecuta las secuencias de comandos de configuración y las cargas útiles de prueba. Verifica que tu host contenga las siguientes utilidades básicas:

  • SDK de Google Cloud: Es necesario para ejecutar comandos de administración de proyectos. Instala la gcloud CLI si no está presente en el host.

  • curl: Valida el acceso de transporte HTTP al extremo de API de backend. Para las distribuciones de Debian o Ubuntu, instala la utilidad a través del administrador de paquetes:

    sudo apt update && sudo apt install -y curl

Configura AlphaEvolve

La configuración de AlphaEvolve requiere la coordinación entre el administrador de la nube y el usuario del sistema. Debes completar las siguientes tareas de instalación:

Crea una cuenta de servicio

Sigue estos pasos para aprovisionar una cuenta de servicio para tus experimentos de optimización. El administrador de la nube debe ejecutar los siguientes comandos desde un host administrativo:

  1. Determina tu Google Cloud ID del proyecto:

    En este paso, se declara una variable de entorno para tu proyecto de destino Google Cloud , lo que garantiza que los comandos posteriores operen en el contexto correcto.

    PROJECT_ID="my-gcp-project-id"

    Como alternativa, puedes recuperar de forma dinámica el ID de tu proyecto de la CLI activa:

    PROJECT_ID=$(gcloud config get project)

  2. Elige un nombre para la cuenta de servicio:

    En este paso, se declara una variable de entorno para el identificador legible por humanos de la cuenta de servicio, que se usará en el comando de creación.

    SA_NAME="alpha-evolve-client"

  3. Crea la cuenta de servicio:

    Este comando registra una nueva cuenta de servicio dentro del Google Cloud proyecto, define su nombre único, su nombre visible y una breve descripción de su propósito.

    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. Extrae la cadena de correo electrónico de la cuenta de servicio:

    Este comando consulta la lista de cuentas de servicio según el nombre visible y extrae la dirección de correo electrónico oficial como una variable de entorno (SERVICE_ACCOUNT_EMAIL) para identificar el recurso de forma única.

    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. Otorga el rol de Discovery Engine a la cuenta de servicio:

    Ejecuta el siguiente comando de gcloud para otorgar el rol roles/discoveryengine.admin a la cuenta de servicio a nivel del proyecto:

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

    Esta configuración aplica los siguientes parámetros de lógica técnica:

    • --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}": Especifica la principal que recibe las capacidades del rol administrativo.

    • --role="roles/discoveryengine.admin": Otorga los permisos necesarios para crear instancias subyacentes de Discovery Engine, sesiones conversacionales y AlphaEvolveExperiments recursos secundarios.

    • ${SERVICE_ACCOUNT_EMAIL}: Identifica el recurso (la nueva cuenta de servicio) que la principal puede suplantar.

Suplanta la identidad de la cuenta de servicio

Después de completar los pasos de creación, usa la herramienta de línea de comandos de gcloud para otorgar a un investigador (SYSTEM_USER) la capacidad explícita de suplantar la identidad de la cuenta de servicio recién creada.

  1. Define la principal que suplanta la identidad: Declara la cadena de destino de la variable. Reemplaza SYSTEM_USER_EMAIL por la identidad corporativa o la dirección de correo electrónico del investigador que realiza las ejecuciones de optimización.

    SYSTEM_USER="user:SYSTEM_USER_EMAIL"

  2. Otorga el rol de creación de tokens a la principal: Ejecuta el siguiente comando para asignar la capacidad de acuñación de tokens de credenciales de corta duración al usuario del sistema especificado:

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

    Esta vinculación de autorización garantiza lo siguiente:

    • --member="${SYSTEM_USER}": Especifica el usuario humano que recibe la autorización de acuñación de credenciales.

    • --role="roles/iam.serviceAccountTokenCreator": Otorga permiso para acuñar tokens de acceso de OAuth 2.0 de corta duración, lo que impulsa la suplantación de la identidad de la cuenta de servicio segura.

    • "${SERVICE_ACCOUNT_EMAIL}": Identifica el recurso de la cuenta de servicio de destino que se vincula a la política entrante.

Habilita la API de Discovery Engine

El administrador de la nube debe habilitar la API de discoveryengine.googleapis.com para poder interactuar con los extremos de la API de AlphaEvolve en la versión preliminar privada de Cloud. El administrador de la nube puede hacerlo desde la Google Cloud consola o con el SDK de Google Cloud en el host de Linux: gcloud services enable discoveryengine.googleapis.com

Crea recursos y sesiones de Discovery Engine

El proceso de configuración pasa de la configuración de identidades administrativas al aprovisionamiento de tu capa de datos de aplicación principal. En esta etapa, debes crear los componentes lógicos anidados que requiere la API subyacente para administrar, enrutar y hacer un seguimiento de tus experimentos de mutación de código.

Jerarquía de recursos de Discovery Engine

La jerarquía de recursos de Discovery Engine comienza con un Google Cloud proyecto, y sus recursos se alojan en una ubicación específica (región). Dentro de esta estructura básica, una colección actúa como un contenedor organizacional de nivel superior para los recursos relacionados. El motor se aprovisiona dentro de una colección para alojar la aplicación principal de IA, que también es donde se configura un recurso de asistente para administrar las propiedades y herramientas de IA generativa de la aplicación. El motor administra las interacciones individuales del usuario capturadas como objetos de sesión.

AlphaEvolveExperiment está anidado en una sesión y representa una sola ejecución del agente de codificación evolutiva que se usa para el descubrimiento y la optimización de algoritmos en el contexto de esa interacción específica del usuario.

Jerarquía de Discovery Engine

Aprovisiona los recursos

  1. Determina tu Google Cloud ID del proyecto:

    En este paso, se declara una variable de entorno para tu proyecto de destino Google Cloud , lo que garantiza que los comandos posteriores operen en el contexto correcto:

    PROJECT_ID="my-gcp-project-id"

    o

    PROJECT_ID=$(gcloud config get project)

  2. Define el ID del motor:

    En este paso, se declara una variable de entorno para el identificador único compatible con URL del ID del motor.

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. Crea el motor:

    Este comando registra un nuevo motor dentro del Google Cloud proyecto, define su nombre único, su nombre visible y 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. Define el ID del asistente:

    En este paso, se declara una variable de entorno para el identificador único compatible con URL del ID del asistente.

    ASSISTANT_ID="default_assistant"

  5. Crea el asistente:

    Este comando registra un nuevo asistente dentro del Google Cloud proyecto, define su nombre único, su nombre visible y una breve descripción de su propósito.

    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
  }'

Prueba el acceso a la API

Después de que el administrador de la nube aprovisione las identidades requeridas, configure la suplantación de la identidad de la cuenta de servicio y verifique el diseño del motor, el usuario del sistema de investigación debe ejecutar los siguientes pasos de validación. Esta secuencia sirve como una prueba de humo previa al vuelo para confirmar el transporte y la autorización de extremo a extremo antes de iniciar cargas de trabajo de optimización activas.

Genera un token de acceso con la suplantación de identidad

Ejecuta el siguiente comando para validar que la política vincule correctamente la suplantación de la identidad de la cuenta de servicio. Esta verificación garantiza que la identidad de tu investigador local asuma de forma segura la identidad de ejecución automatizada.

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

Usa el token de acceso

El comando genera una cadena de credenciales de OAuth 2.0 sin procesar y temporal. Para los flujos de trabajo de verificación de varios pasos, almacena en caché este token en una variable de shell de corta duración o incorpóralo directamente en tus llamadas de transporte para consultar los metadatos básicos del proyecto:

  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}"

Consulta y borra motores

Usa tu token de acceso actual o la cuenta de servicio suplantada para verificar, enumerar o borrar tus motores:

  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)"

Felicitaciones. Completaste los pasos de configuración. Ahora puedes ejecutar la API de AlphaEvolve V1.