Configuración del acceso al entorno y a la API

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

  • Google Cloud proyecto: Crea un Google Cloud proyecto dedicado. Para el aprovisionamiento del proyecto, coordina 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. 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 usuario del sistema que interactúe con la API a través de la identidad temporal como 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 asignación de IAM y la habilitación de la API de Discovery Engine y la API de Gemini en Vertex AI.
  • 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 identidad temporal como cuenta de servicio.
  • roles/iam.serviceAccountTokenCreator otorgado en el recurso de la cuenta de servicio
  • Opcional: roles/iam.serviceAccountUser si se adjunta la cuenta de servicio a los 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 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 los pasos que se indican a continuación 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 para mostrar y una breve descripción de su propósito.

    gcloud iam service-accounts create "${SA_NAME}" \
  --description="Service Account to call AlphaEvolve on Cloud 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 en función del nombre para mostrar y extrae la dirección de correo electrónico oficial como una variable de entorno (SERVICE_ACCOUNT_EMAIL) para identificar de forma única el recurso.

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

  5. Otorga el rol de Discovery Engine a la cuenta de servicio:

    Ejecuta el siguiente comando 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 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 cuenta de servicio recién creada.

  1. Define la principal que suplanta: 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 segura de la cuenta de servicio.

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

Habilite las API necesarias

El administrador de la nube debe habilitar dos APIs en el proyecto:

  • La API de Discovery Engine (discoveryengine.googleapis.com), que entrega los extremos de la API de AlphaEvolve en Cloud

  • La API de Vertex AI (aiplatform.googleapis.com), que entrega la API de Gemini en Vertex AI AlphaEvolve genera cada programa candidato con un conjunto de modelos de Gemini, por lo que un usuario del sistema no puede ejecutar un experimento hasta que se habilite esta API.

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

Habilitar las API

Como alternativa, habilita ambas APIs con el SDK de Google Cloud en el host de Linux:

gcloud services enable discoveryengine.googleapis.com \
  aiplatform.googleapis.com --project="${PROJECT_ID}"

Confirma que ambas APIs estén habilitadas:

gcloud services list --enabled --project="${PROJECT_ID}" \
  --filter="config.name:(discoveryengine.googleapis.com OR aiplatform.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, compilas 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 para mostrar 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 para mostrar 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

Una vez que el administrador de la nube termine de aprovisionar identidades, configurar la identidad temporal como cuenta de servicio y verificar el diseño del motor, ejecuta estas verificaciones finales. Esta prueba rápida de humo verifica tu autorización y conexión de extremo a extremo antes de ejecutar cargas de trabajo de optimización activas.

Visualiza 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.