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 bien suivi les étapes de base concernant l'approvisionnement et l'infrastructure.

Projet et licencesGoogle Cloud

  • ProjetGoogle Cloud  : créez un projet Google Cloud dédié. Pour le provisionnement des projets, contactez l'équipe de gestion de votre 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, permettent d'accéder à AlphaEvolve.

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

Profils utilisateur et exigences IAM

Le cycle de vie d'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 unique 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 uniquement par l'emprunt d'identité d'un compte de service.
  • roles/iam.serviceAccountTokenCreator accordé sur la ressource de 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 s'interface directement avec le service d'API AlphaEvolve sur Cloud.
  • roles/discoveryengine.editor ou roles/discoveryengine.admin (à l'échelle du projet)

Environnement hôte administratif

Un hôte Linux d'administration (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 paquets :

    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 d'administration :

  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 ultérieures s'exécutent 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 de compte de service :

    Cette étape déclare une variable d'environnement pour l'identifiant lisible par l'humain 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 d'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 la ressource de manière unique.

    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 attribuer 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 fonctionnalités du rôle d'administrateur.

    • --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

Après avoir suivi les étapes de création, utilisez l'outil de ligne de commande gcloud pour accorder à un chercheur (SYSTEM_USER) la capacité explicite d'emprunter l'identité du compte de service nouvellement créé.

  1. Définissez le compte principal empruntant l'identité : déclarez la chaîne cible de la variable. Remplacez SYSTEM_USER_EMAIL par l'identité d'entreprise 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 capacité de création de jetons d'identification de courte durée à 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 que :

    • --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 créer 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 stratégie entrante.

Activer les API requises

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

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

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

Rôles requis pour activer les API

Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le 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. À ce stade, vous allez créer les composants logiques imbriqués requis par l'API sous-jacente pour gérer, acheminer et suivre vos tests de mutation de code.

Hiérarchie des ressources Discovery Engine

La hiérarchie des ressources Discovery Engine commence par un projetGoogle Cloud , et ses ressources sont hébergées dans un emplacement spécifique (les emplacements compatibles avec AlphaEvolve sont global, us et eu). 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'emplacement 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 en tant qu'objets session.

AlphaEvolveExperiment est imbriqué dans une session, représentant une seule exécution de l'agent de codage évolutif utilisé pour la découverte et l'optimisation d'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 cible Google Cloud, ce qui garantit que les commandes suivantes s'exécutent 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 de l'ID du moteur, qui est compatible avec les URL.

    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 de l'ID de l'assistant, qui est compatible avec les URL.

    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, effectuez ces dernières vérifications. Ce test de détection rapide vérifie votre autorisation et votre connexion de bout en bout avant d'exécuter des charges de travail d'optimisation actives.

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é la configuration. Vous pouvez maintenant exécuter l'API AlphaEvolve V1.