Installer et configurer AlphaEvolve

Cette page décrit les étapes nécessaires pour initialiser votre environnement, provisionner l'API et configurer vos paramètres utilisateur afin de commencer à utiliser AlphaEvolve.

  1. Prérequis

  2. Configurer AlphaEvolve

Prérequis

Avant de configurer votre environnement, vérifiez que votre organisation Google Clouda effectué les étapes de base concernant l'approvisionnement et l'infrastructure.

Projet et licenceGoogle Cloud

  • Projet Google Cloud : créez un projet Google Cloud (GCP) dédié avec des liens de facturation actifs. Pour toute question concernant le provisionnement de projets ou la liste d'autorisation, contactez l'équipe chargée de votre compte Google Cloud .

  • Licences Gemini Enterprise : achetez des licences Gemini Enterprise auprès de votre conseiller commercial Google Cloud ou sur Google Cloud Marketplace. Vous pouvez ajouter des licences à Google Workspace ou les provisionner en tant qu'offres autonomes. Tous les niveaux Gemini Enterprise, y compris une licence d'essai, donnent accès à AlphaEvolve.

  • Remarque sur l'attribution des licences : Le système nécessite une licence Gemini Enterprise par utilisateur du système qui interagit avec l'API par le biais de l'usurpation d'identité d'un compte de service.Les comptes de service Google Cloud ne consomment pas de licences Workspace ni Cloud Identity.

Profils utilisateur et exigences IAM

Le cycle de vie AlphaEvolve utilise les trois identités distinctes.

Assurez-vous que votre projet respecte les rôles de contrôle des accès obligatoires suivants :

Profil Description Rôles et autorisations nécessaires
Administrateur Cloud Gère la configuration initiale de l'environnement, l'activation des API et l'attribution des rôles IAM.
  • roles/resourcemanager.projectCreator (au niveau de l'organisation ou du dossier)
  • roles/billing.user (au niveau du compte de facturation)
  • roles/serviceusage.admin
  • Droits d'administrateur Workspace ou Cloud Identity
Utilisateur du système
(chercheur / scientifique)		 Configure et exécute des tests d'optimisation. Interagit avec l'API strictement par le biais de l'emprunt d'identité d'un compte de service.
  • roles/iam.serviceAccountTokenCreator accordé sur la ressource "Compte de service".
  • Facultatif : roles/iam.serviceAccountUser si vous associez le compte de service à des ressources de calcul (par exemple, Vertex AI Workbench).
Compte de service Identité automatisée qui interagit directement avec le service d'API AlphaEvolve sur Cloud Private Preview.
  • roles/discoveryengine.admin (portée du projet)

Environnement hôte administratif

Un hôte Linux administratif (tel que Google Cloud Shell ou un hôte bastion sécurisé) exécute les scripts de configuration et les charges utiles de test. Vérifiez que votre hôte contient les utilitaires de base suivants :

  • Google Cloud SDK : requis pour exécuter les commandes de gestion de projet. Installez la CLI gcloud si elle n'est pas présente sur l'hôte.

  • curl : valide l'accès au transport HTTP au point de terminaison de l'API de backend. Pour les distributions Debian ou Ubuntu, installez l'utilitaire via le gestionnaire de packages :

    sudo apt update && sudo apt install -y curl

Configurer AlphaEvolve

La configuration d'AlphaEvolve nécessite une coordination entre l'administrateur cloud et l'utilisateur du système. Vous devez effectuer les tâches d'installation suivantes :

Créer un compte de service

Suivez les étapes ci-dessous pour provisionner un compte de service pour vos tests d'optimisation. L'administrateur cloud doit exécuter les commandes suivantes à partir d'un hôte administratif :

  1. Définissez l'ID de votre projet Google Cloud  :

    Cette étape déclare une variable d'environnement pour votre projet Google Cloudcible, ce qui garantit que les commandes suivantes fonctionnent dans le bon contexte.

    PROJECT_ID="my-gcp-project-id"

    Vous pouvez également récupérer de manière dynamique l'ID de votre projet CLI actif :

    PROJECT_ID=$(gcloud config get project)

  2. Choisissez un nom pour votre compte de service :

    Cette étape déclare une variable d'environnement pour l'identifiant lisible du compte de service, qui sera utilisé dans la commande de création.

    SA_NAME="alpha-evolve-client"

  3. Créez le compte de service :

    Cette commande enregistre un nouveau compte de service dans le projet Google Cloud , en définissant son nom unique, son nom à afficher et une brève description de son objectif.

    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. Extrayez la chaîne de l'adresse e-mail du compte de service :

    Cette commande interroge la liste des comptes de service en fonction du nom à afficher et extrait l'adresse e-mail officielle en tant que variable d'environnement (SERVICE_ACCOUNT_EMAIL) pour identifier de manière unique la ressource.

    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. Attribuez le rôle Discovery Engine au compte de service :

    Exécutez la commande gcloud suivante pour accorder le rôle roles/discoveryengine.admin au compte de service au niveau du projet :

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

    Cette configuration applique les paramètres de logique technique suivants :

    • --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" : spécifie le compte principal qui reçoit les droits du rôle administratif.

    • --role="roles/discoveryengine.admin" : accorde les autorisations nécessaires pour créer des instances Discovery Engine sous-jacentes, des sessions de conversation et des ressources enfants AlphaEvolveExperiments.

    • ${SERVICE_ACCOUNT_EMAIL} : identifie la ressource (le nouveau compte de service) dont le compte principal est autorisé à emprunter l'identité.

Emprunter l'identité du compte de service

Une fois les étapes de création effectuées, utilisez l'outil de ligne de commande gcloud pour accorder à un chercheur (SYSTEM_USER) l'autorisation explicite d'usurper l'identité du compte de service nouvellement créé.

  1. Définissez le compte principal effectuant l'emprunt d'identité : déclarez la chaîne cible de la variable. Remplacez SYSTEM_USER_EMAIL par l'identité professionnelle ou l'adresse e-mail du chercheur qui effectue les exécutions d'optimisation.

    SYSTEM_USER="user:SYSTEM_USER_EMAIL"

  2. Attribuez le rôle de création de jetons au principal : exécutez la commande suivante pour mapper la capacité de création de jetons d'identifiants à courte durée de vie à l'utilisateur système spécifié :

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

    Cette liaison d'autorisation garantit les points suivants :

    • --member="${SYSTEM_USER}" : spécifie l'utilisateur humain qui reçoit l'autorisation de création d'identifiants.

    • --role="roles/iam.serviceAccountTokenCreator" : accorde l'autorisation de générer des jetons d'accès OAuth 2.0 de courte durée, ce qui permet d'emprunter l'identité d'un compte de service de manière sécurisée.

    • "${SERVICE_ACCOUNT_EMAIL}" : identifie la ressource de compte de service cible associée à la règle entrante.

Activer l'API Discovery Engine

L'administrateur cloud doit activer l'API discoveryengine.googleapis.com pour pouvoir interagir avec les points de terminaison de l'API AlphaEvolve sur le cloud en version Preview privée. L'administrateur cloud peut le faire depuis la console Google Cloud ou à l'aide de Google Cloud SDK sur l'hôte Linux : gcloud services enable discoveryengine.googleapis.com

Créer des ressources et des sessions Discovery Engine

Le processus de configuration passe de la configuration des identités administratives au provisionnement de votre couche de données d'application principale. À cette étape, vous allez créer les composants logiques imbriqués requis par l'API sous-jacente pour gérer, router et suivre vos expériences de mutation de code.

Hiérarchie des ressources Discovery Engine

La hiérarchie des ressources Discovery Engine commence par un projetGoogle Cloud . Ses ressources sont hébergées dans un emplacement (région) spécifique. Dans cette structure de base, une collection sert de conteneur organisationnel de premier niveau pour les ressources associées. Le moteur est provisionné dans une collection pour héberger l'application d'IA principale, qui est également l'endroit où une ressource d'assistant est configurée pour gérer les propriétés et les outils d'IA générative de l'application. Le moteur gère les interactions utilisateur individuelles capturées sous forme d'objets session.

Le AlphaEvolveExperiment est imbriqué dans une session et représente une seule exécution de l'agent de codage évolutif utilisé pour la découverte et l'optimisation des algorithmes dans le contexte de cette interaction utilisateur spécifique.

Hiérarchie Discovery Engine

Provisionner les ressources

  1. Définissez l'ID de votre projet Google Cloud  :

    Cette étape déclare une variable d'environnement pour votre projet Google Cloudcible, ce qui garantit que les commandes suivantes fonctionnent dans le bon contexte :

    PROJECT_ID="my-gcp-project-id"

    ou

    PROJECT_ID=$(gcloud config get project)

  2. Définissez l'ID de votre moteur :

    Cette étape déclare une variable d'environnement pour l'identifiant unique compatible avec les URL de l'ID du moteur.

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. Créez le moteur :

    Cette commande enregistre un nouveau moteur dans le projet Google Cloud , en définissant son nom unique, son nom à afficher et son 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. Définissez l'ID de votre assistant :

    Cette étape déclare une variable d'environnement pour l'identifiant unique compatible avec les URL de l'ID de l'assistant.

    ASSISTANT_ID="default_assistant"

  5. Créez l'assistant :

    Cette commande enregistre un nouvel Assistant dans le projet Google Cloud , en définissant son nom unique, son nom à afficher et une brève description de son objectif.

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

Tester l'accès à l'API

Une fois que l'administrateur Cloud a provisionné les identités requises, configuré l'emprunt d'identité du compte de service et vérifié la mise en page du moteur, l'utilisateur du système de recherche doit exécuter les étapes de validation suivantes. Cette séquence sert de test de fumée avant vol pour confirmer le transport et l'autorisation de bout en bout avant de lancer des charges de travail d'optimisation actives.

Générer un jeton d'accès à l'aide de l'usurpation d'identité

Exécutez la commande suivante pour vérifier que la stratégie lie correctement l'usurpation d'identité du compte de service. Cette vérification garantit que votre identité de chercheur local assume de manière sécurisée l'identité d'exécution automatisée.

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

Utiliser le jeton d'accès

La commande génère une chaîne d'identifiants OAuth 2.0 bruts et temporaires. Pour les workflows de validation en plusieurs étapes, mettez en cache ce jeton dans une variable shell à courte durée de vie ou insérez-le directement dans vos appels de transport pour interroger les métadonnées de votre projet de base :

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

Afficher et supprimer des moteurs

Utilisez votre jeton d'accès actuel ou le compte de service emprunté pour vérifier, lister ou supprimer vos moteurs :

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

Félicitations, vous avez terminé les étapes de configuration ! Vous pouvez maintenant exécuter l'API AlphaEvolve V1.