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 Google Cloud organisation a effectué les étapes de base concernant l'acquisition et l'infrastructure.

Google Cloud Projet et licences

  • Projet Google Cloud : créez un projet dédié Google Cloud avec des liens de facturation actifs. Pour toute question concernant le provisionnement de projets ou les listes d'autorisation, contactez l'équipe chargée du compte qui vous a été attribuée. Google Cloud

  • Licences Gemini Enterprise : achetez des licences Gemini Enterprise auprès de votre Google Cloud représentant commercial ou sur le 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 en empruntant l'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 AlphaEvolve utilise trois identités distinctes.

Assurez-vous que votre projet est conforme aux rôles de contrôle des accès obligatoire suivants :

Profil Description Rôles et autorisations requis
Administrateur cloud Gère la configuration initiale unique de l'environnement, l'activation de l'API, et l'attribution IAM.
  • roles/resourcemanager.projectCreator (niveau Organisation/ Dossier)
  • roles/billing.user (niveau Compte de facturation)
  • roles/serviceusage.admin
  • Droits d'administrateur Workspace ou Cloud Identity
Utilisateur du système
(chercheur / scientifique)		 Configure et exécute des expériences d'optimisation. Interagit avec l'API uniquement en empruntant l'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 : obligatoire pour exécuter les commandes de gestion de projet. Installez l'interface de ligne de commande 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 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 expériences d'optimisation. L'administrateur cloud doit exécuter les commandes suivantes à partir d'un hôte administratif :

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

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

    PROJECT_ID="my-gcp-project-id"

    Vous pouvez également récupérer dynamiquement 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 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 Google Cloud projet, 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 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 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

Une fois les étapes de création terminées, utilisez l'outil de ligne de commande gcloud pour accorder explicitement à un chercheur (SYSTEM_USER) la possibilité 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 fonctionnalité de création de jetons d'identifiants éphémères à l'utilisateur du 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 éphémères, 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 lié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 on Cloud. L'administrateur cloud peut le faire à partir de la Google Cloud console ou à l'aide du 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 des configurations d'identité administrative au provisionnement de votre couche de données d'application principale. À cette étape, vous créez les composants logiques imbriqués requis par l'API sous-jacente pour gérer, acheminer 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 Google Cloud projet, et ses ressources sont hébergées dans un emplacement spécifique (région). 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, où une ressource d'assistant est également 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 individuelles des utilisateurs capturées en tant qu' objets de 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 de l'utilisateur spécifique.

Hiérarchie Discovery Engine

Provisionner les ressources

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

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

    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 Google Cloud projet, 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 Google Cloud projet, 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é du 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 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é les étapes de configuration. Vous pouvez maintenant exécuter l'API AlphaEvolve V1.