Configurer l'environnement et l'accès à l'API

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

  • Google Cloud project : créez un projet Google Cloud dédié. Pour le provisionnement de projet, coordonnez-vous avec votre équipe chargée du compte Google Cloud .

  • Licences Gemini Enterprise : achetez des licences Gemini Enterprise auprès de votre représentant commercial Google Cloud . 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'emprunt 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'attribution IAM et l'activation de l'API Discovery Engine et de l'API Gemini dans Vertex AI.
  • 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 on Cloud.
  • 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 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}"

  5. 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 les instances Discovery Engine sous-jacentes, les sessions conversationnelles et les 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 compte principal : exécutez la commande suivante pour mapper la fonctionnalité 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 les API requises

L'administrateur Cloud doit activer deux API dans le projet :

  • L'API Discovery Engine (discoveryengine.googleapis.com), qui dessert les points de terminaison de l'API AlphaEvolve on Cloud.

  • L'API Vertex AI (aiplatform.googleapis.com), qui sert l'API Gemini dans Vertex AI. AlphaEvolve génère chaque programme candidat avec un ensemble de modèles Gemini. Par conséquent, un utilisateur système ne peut pas exécuter d'expérience tant que cette API n'est pas activée.

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer les API

Vous pouvez également activer les deux API avec Google Cloud SDK sur l'hôte Linux :

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

Vérifiez que les deux API sont activées :

gcloud services list --enabled --project="${PROJECT_ID}" \
  --filter="config.name:(discoveryengine.googleapis.com OR aiplatform.googleapis.com)"

Créer des ressources et des sessions Discovery Engine

Le processus de configuration passe de la configuration de l'identité administrative au provisionnement de la couche de données de votre 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.

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 de l'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 votre administrateur cloud a terminé de provisionner les identités, de configurer l'emprunt d'identité d'un compte de service et de vérifier la mise en page du moteur, exécutez ces dernières vérifications. Ce test rapide vérifie votre autorisation et votre connexion de bout en bout avant que vous n'exécutiez des charges de travail d'optimisation active.

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.