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 establecer la configuración de usuario para comenzar a trabajar con AlphaEvolve.

  1. Requisitos previos

  2. Configura AlphaEvolve

Requisitos previos

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

Proyecto y licencias deGoogle Cloud

  • Proyecto deGoogle Cloud : Crea un proyecto de Google Cloud dedicado. Para el aprovisionamiento de proyectos, comunícate con el equipo de cuentas de Google Cloud que tengas asignado.

  • Licencias de Gemini Enterprise: Compra licencias de Gemini Enterprise a través de tu representante de ventas de Google Cloud . 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. Las cuentas de servicio de Google Cloud 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 de control de acceso obligatorios:

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 la 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 adjuntas la cuenta de servicio a los recursos de procesamiento (por ejemplo, Vertex AI Workbench).
Cuenta de servicio Es una identidad automatizada que interactúa directamente con el servicio de la API de AlphaEvolve en Cloud.
  • roles/discoveryengine.editor o roles/discoveryengine.admin (con alcance de proyecto)

Entorno de host administrativo

Un host administrativo de Linux (como Google Cloud Shell o un host de bastión 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 CLI de gcloud 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 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. Establece el ID del proyecto de Google Cloud :

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

    PROJECT_ID="my-gcp-project-id"

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

    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 cuenta de servicio nueva en el proyecto de Google Cloud , 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 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 inequívoca.

    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 de gcloud para otorgar el rol de 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 de administrador.

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

    • ${SERVICE_ACCOUNT_EMAIL}: Identifica el recurso (la cuenta de servicio nueva) que el principal puede usar para actuar en nombre de otro.

Usa 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 otorgarle a un investigador (SYSTEM_USER) la capacidad explícita de actuar en nombre de la cuenta de servicio recién creada.

  1. Define la principal que robará 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 creació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 creación de credenciales.

    • --role="roles/iam.serviceAccountTokenCreator": Otorga permiso para crear tokens de acceso de OAuth 2.0 de corta duración, lo que impulsa la identidad temporal como 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.

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 endpoints de la API de AlphaEvolve on 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 obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más 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 la identidad administrativa al aprovisionamiento de la capa de datos de la aplicación principal. En esta etapa, compilarás 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 los recursos de Discovery Engine comienza con un proyecto deGoogle Cloud , y sus recursos se alojan en una ubicación específica (las ubicaciones admitidas para AlphaEvolve son global, us y eu). Dentro de esta estructura fundamental, una colección actúa como un contenedor organizativo de nivel superior para los recursos relacionados. El motor se aprovisiona dentro de una colección para alojar la aplicación de IA principal, que también es donde se configura un recurso de asistente para administrar las propiedades y herramientas de IA generativa para la aplicación. El motor administra las interacciones individuales de los usuarios capturadas como objetos session.

El AlphaEvolveExperiment está anidado en una sesión y representa una sola ejecución del agente de programació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. Establece el ID del proyecto de Google Cloud :

    En este paso, se declara una variable de entorno para tu proyecto de Google Cloud destino, 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 de tu motor:

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

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. Crea el motor:

    Este comando registra un motor nuevo en el proyecto de Google Cloud , lo que define su nombre único, 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 de tu asistente:

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

    ASSISTANT_ID="default_assistant"

  5. Crea el asistente:

    Este comando registra un nuevo asistente dentro del proyecto de Google Cloud , definiendo 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
  }'

Acceso a la API de pruebas

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

Cómo ver y borrar motores

Usa tu token de acceso actual o la cuenta de servicio con identidad 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.