Configurazione dell'ambiente e dell'accesso API

Questa pagina illustra i passaggi necessari per inizializzare l'ambiente, eseguire il provisioning dell'API e configurare le impostazioni utente per iniziare a utilizzare AlphaEvolve.

  1. Prerequisiti

  2. Configurazione di AlphaEvolve

Prerequisiti

Prima di configurare l'ambiente, verifica che la tua Google Cloud organizzazione completi i passaggi fondamentali di approvvigionamento e infrastruttura.

Google Cloud Progetto e licenze

  • Progetto Google Cloud: crea unprogetto dedicato con Google Cloud link di fatturazione attivi. Per richieste di provisioning del progetto o di inserimento nella lista consentita, coordina l'operazione con il team dedicato al tuo Google Cloud account.

  • Licenze Gemini Enterprise: acquista le licenze Gemini Enterprise tramite il tuo Google Cloud rappresentante di vendita o il Google Cloud Marketplace. Puoi aggiungere licenze a Google Workspace o eseguirne il provisioning come offerte autonome. Qualsiasi livello di Gemini Enterprise, inclusa una licenza di prova, concede l'accesso ad AlphaEvolve.

  • Nota sull'allocazione delle licenze: il sistema richiede una licenza Gemini Enterprise per ogni utente del sistema che interagisce con l'API tramite la simulazione dell'identità dei account di servizio account. Google Cloud I service account non utilizzano le licenze Workspace o Cloud Identity.

Profili utente e requisiti IAM

Il ciclo di vita di AlphaEvolve utilizza le tre identità distinte.

Assicurati che il tuo progetto sia conforme ai seguenti ruoli di controllo dell'accesso obbligatori:

Profilo Descrizione Ruoli e autorizzazioni richiesti
Amministratore cloud Gestisce la configurazione iniziale una tantum dell'ambiente, l'abilitazione dell'API, e l'assegnazione IAM.
  • roles/resourcemanager.projectCreator (a livello di organizzazione/ cartella)
  • roles/billing.user (a livello di account di fatturazione)
  • roles/serviceusage.admin
  • Privilegi di amministratore di Workspace o Cloud Identity
Utente del sistema
(ricercatore / scienziato)		 Configura ed esegue esperimenti di ottimizzazione. Interagisce con l' API esclusivamente tramite la simulazione dell'identità dei account di servizio.
  • roles/iam.serviceAccountTokenCreator concesso alla risorsa Service Account.
  • Facoltativo: roles/iam.serviceAccountUser se colleghi il account di servizio alle risorse di computing (ad esempio, Vertex AI Workbench).
Service Account Identità automatizzata che interagisce direttamente con il servizio API AlphaEvolve on Cloud.
  • roles/discoveryengine.admin (con ambito progetto)

Ambiente host amministrativo

Un host Linux amministrativo (ad esempio Google Cloud Shell o un host bastion sicuro host) esegue gli script di configurazione e i payload di test. Verifica che l'host contenga le seguenti utilità di base:

  • Google Cloud SDK: necessario per eseguire i comandi di gestione dei progetti. Installa l'interfaccia a riga di comando gcloudse non è presente sull'host.

  • curl: convalida l'accesso al trasporto HTTP all'endpoint API di backend. Per le distribuzioni Debian o Ubuntu, installa l'utilità tramite il gestore di pacchetti:

    sudo apt update && sudo apt install -y curl

Configurazione di AlphaEvolve

La configurazione di AlphaEvolve richiede il coordinamento tra l'amministratore cloud e l'utente del sistema. Devi completare le seguenti attività di installazione:

Crea un account di servizio

Segui questi passaggi per eseguire il provisioning di un account di servizio per gli esperimenti di ottimizzazione. L'amministratore cloud deve eseguire i seguenti comandi da un host amministrativo:

  1. Imposta l'ID del progetto: Google Cloud

    Questo passaggio dichiara una variabile di ambiente per il progetto di destinazione Google Cloud, assicurando che i comandi successivi operino nel contesto corretto.

    PROJECT_ID="my-gcp-project-id"

    In alternativa, puoi recuperare dinamicamente l'ID progetto CLI attivo:

    PROJECT_ID=$(gcloud config get project)

  2. Scegli un nome per account di servizio:

    Questo passaggio dichiara una variabile di ambiente per l'identificatore leggibile del account di servizio, che verrà utilizzato nel comando di creazione.

    SA_NAME="alpha-evolve-client"

  3. Crea il account di servizio:

    Questo comando registra un nuovo account di servizio all'interno del Google Cloud progetto, definendone il nome univoco, il nome visualizzato e una breve descrizione dello scopo previsto.

    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. Estrai la stringa dell'indirizzo email del account di servizio:

    Questo comando esegue una query sull'elenco dei service account in base al nome visualizzato ed estrae l'indirizzo email ufficiale come variabile di ambiente (SERVICE_ACCOUNT_EMAIL) per identificare in modo univoco la risorsa.

    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. Concedi il ruolo Discovery Engine al account di servizio:

    Esegui il seguente comando gcloud per concedere il ruolo roles/discoveryengine.admin al account di servizio a livello di progetto:

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

    Questa configurazione applica i seguenti parametri di logica tecnica:

    • --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}": specifica l' entità che riceve le funzionalità del ruolo amministrativo.

    • --role="roles/discoveryengine.admin": concede le autorizzazioni necessarie per creare le istanze di Discovery Engine sottostanti, le sessioni di conversazione e le risorse secondarie AlphaEvolveExperiments.

    • ${SERVICE_ACCOUNT_EMAIL}: identifica la risorsa (il nuovo service account) che l'entità è autorizzata a rappresentare.

Rappresenta il account di servizio

Dopo aver completato i passaggi di creazione, utilizza lo strumento a riga di comando gcloud per concedere a un ricercatore (SYSTEM_USER) la possibilità esplicita di rappresentare il account di servizio appena creato.

  1. Definisci l'entità rappresentante: dichiara la stringa di destinazione della variabile. Sostituisci SYSTEM_USER_EMAIL con l'identità aziendale o l'indirizzo email del ricercatore che esegue le esecuzioni di ottimizzazione.

    SYSTEM_USER="user:SYSTEM_USER_EMAIL"

  2. Concedi il ruolo di creazione del token all'entità: esegui il seguente comando per mappare la funzionalità di creazione di token di credenziali di breve durata all'utente del sistema specificato:

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

    Questo binding di autorizzazione garantisce che:

    • --member="${SYSTEM_USER}": specifica l'utente che riceve l'autorizzazione per la creazione delle credenziali.

    • --role="roles/iam.serviceAccountTokenCreator": concede l'autorizzazione per creare token di accesso OAuth 2.0 di breve durata, che consente la rappresentazione sicura del service account.

    • "${SERVICE_ACCOUNT_EMAIL}": identifica la risorsa del account di servizio di destinazione a cui è associata la policy in entrata.

Attiva l'API Discovery Engine

L'amministratore cloud deve abilitare l'API discoveryengine.googleapis.com per poter interagire con gli endpoint API AlphaEvolve on Cloud. L'amministratore cloud può farlo dalla Google Cloud console o utilizzando Google Cloud SDK sull'host Linux: gcloud services enable discoveryengine.googleapis.com

Crea risorse e sessioni di Discovery Engine

La procedura di configurazione passa dalle configurazioni delle identità amministrative al provisioning del livello di dati dell'applicazione principale. In questa fase, crei i componenti logici nidificati richiesti dall'API sottostante per gestire, instradare e monitorare gli esperimenti di mutazione del codice.

Gerarchia delle risorse di Discovery Engine

La gerarchia delle risorse di Discovery Engine inizia con un Google Cloud progetto e le relative risorse sono ospitate in una località (regione) specifica. All'interno di questa struttura di base, una raccolta funge da container organizzativo di primo livello per le risorse correlate. Il motore viene sottoposto a provisioning all'interno di una raccolta per ospitare l'applicazione AI principale, in cui viene configurata anche una risorsa di assistenza per gestire le proprietà e gli strumenti di AI generativa per l'applicazione. Il motore gestisce le singole interazioni utente acquisite come oggetti sessione.

AlphaEvolveExperiment è nidificato in una sessione e rappresenta una singola esecuzione dell'agente di codifica evolutiva utilizzato per l'individuazione e l'ottimizzazione degli algoritmi nel contesto di quella specifica interazione utente.

Gerarchia di Discovery Engine

Esegui il provisioning delle risorse

  1. Imposta l'ID del progetto: Google Cloud

    Questo passaggio dichiara una variabile di ambiente per il progetto di destinazione Google Cloud, assicurando che i comandi successivi operino nel contesto corretto:

    PROJECT_ID="my-gcp-project-id"

    o

    PROJECT_ID=$(gcloud config get project)

  2. Definisci l'ID motore:

    Questo passaggio dichiara una variabile di ambiente per l'identificatore univoco dell'ID motore compatibile con gli URL.

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. Crea il motore:

    Questo comando registra un nuovo motore all'interno del Google Cloud progetto, definendone il nome univoco, il nome visualizzato e 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. Definisci l'ID assistente:

    Questo passaggio dichiara una variabile di ambiente per l'identificatore univoco dell'ID assistente compatibile con gli URL.

    ASSISTANT_ID="default_assistant"

  5. Crea l'assistente:

    Questo comando registra un nuovo assistente all'interno del Google Cloud progetto, definendone il nome univoco, il nome visualizzato e una breve descrizione dello scopo previsto.

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

Test dell'accesso all'API

Una volta che l'amministratore cloud ha terminato il provisioning delle identità, la configurazione della simulazione dell'identità dei account di servizio e la verifica del layout del motore, esegui questi controlli finali. Questo rapido smoke test verifica l'autorizzazione e la connessione end-to-end prima di eseguire i carichi di lavoro di ottimizzazione attivi.

Visualizza ed elimina i motori

Utilizza il token di accesso corrente o il account di servizio rappresentato per verificare, elencare o eliminare i motori:

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

Congratulazioni, hai completato i passaggi di configurazione. Ora puoi eseguire l'API AlphaEvolve V1.