Installare e configurare AlphaEvolve

Questa pagina descrive 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 di base relativi ad approvvigionamento e infrastruttura.

Google Cloud progetto e licenze

  • Progetto Google Cloud:crea un progetto Google Cloud dedicato con collegamenti di fatturazione attivi. Google Cloud Per domande sul provisioning del progetto o sull'inserimento nella lista consentita, coordina l'operazione con il team dedicato al tuo account Google Cloud .

  • Licenze Gemini Enterprise:acquista le licenze Gemini Enterprise tramite il tuo Google Cloud rappresentante di vendita o Google Cloud Marketplace. Puoi aggiungere licenze a Google Workspace o provisionarle 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 l'impersonificazione del account di servizio account. Google Cloud I service account non utilizzano 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 obbligatorio:

Profilo Descrizione Ruoli e autorizzazioni richiesti
Amministratore cloud Gestisce la configurazione iniziale una tantum dell'ambiente, l'attivazione dell'API e l'assegnazione IAM.
  • roles/resourcemanager.projectCreator (livello di organizzazione/ cartella)
  • roles/billing.user (livello dell'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à delaccount di serviziot.
  • 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).
Account di servizio Identità automatizzata che interagisce direttamente con AlphaEvolve sul servizio API Cloud Private Preview.
  • roles/discoveryengine.admin (ambito del progetto)

Ambiente host amministrativo

Un host Linux amministrativo (ad esempio Google Cloud Shell o un bastion host sicuro) 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 gcloud se 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

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 progetto Google Cloud :

    Questo passaggio dichiara una variabile di ambiente per il progetto di destinazione, Google Cloud garantendo che i comandi successivi vengano eseguiti 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 delaccount di serviziot, che verrà utilizzato nel comando di creazione.

    SA_NAME="alpha-evolve-client"

  3. Crea l'account di servizio:

    Questo comando registra un nuovo account di servizio all'interno del progetto Google Cloud , 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 Private \
Preview API service" \
  --display-name="AlphaEvolve Client SA" \
  --project=$PROJECT_ID

  4. Estrai la stringa dell'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 all'account di servizio:

    Esegui questo comando gcloud per concedere il ruolo roles/discoveryengine.admin all'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 istanze Discovery Engine sottostanti, sessioni conversazionali e risorse secondarie AlphaEvolveExperiments.

    • ${SERVICE_ACCOUNT_EMAIL}: identifica la risorsa (il nuovo service account) che l'entità può impersonare.

Rappresentare 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 ilaccount di serviziont appena creato.

  1. Definisci l'entità che esegue l'impersonificazione: 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 al principal: esegui questo comando per mappare la funzionalità di generazione di token di credenziali di breve durata all'utente di 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 dell'autorizzazione garantisce che:

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

    • --role="roles/iam.serviceAccountTokenCreator": concede l'autorizzazione a creare token di accesso OAuth 2.0 di breve durata, che consente l'impersonificazione sicura dell'account di servizio.

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

Abilita l'API Discovery Engine

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

Creare risorse e sessioni di Discovery Engine

Il processo di configurazione passa dalle configurazioni dell'identità amministrativa al provisioning del data layer 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 Discovery Engine

La gerarchia delle risorse di Discovery Engine inizia con un progettoGoogle Cloud e le sue risorse sono ospitate in una località specifica (regione). All'interno di questa struttura di base, una raccolta funge da contenitore organizzativo di primo livello per le risorse correlate. Il motore viene provisionato all'interno di una raccolta per ospitare l'applicazione AI principale, in cui viene configurata anche una risorsa assistente 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 la scoperta 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 progetto Google Cloud :

    Questo passaggio dichiara una variabile di ambiente per il progetto di destinazione, Google Cloud garantendo 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 progetto Google Cloud , definendo 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 progetto Google Cloud , definendo il suo nome univoco, il nome visualizzato e una breve descrizione del suo 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

Dopo che l'amministratore cloud ha eseguito il provisioning delle identità richieste, configurato l'imitazione del account di servizio e verificato il layout del motore, l'utente del sistema di ricerca deve eseguire i seguenti passaggi di convalida. Questa sequenza funge da test preliminare per verificare il trasporto end-to-end e l'autorizzazione prima di avviare i carichi di lavoro di ottimizzazione attivi.

Generare un token di accesso utilizzando la rappresentazione

Esegui questo comando per verificare che la policy vincoli correttamente l'impersonificazione dell'account di servizio. Questo controllo garantisce che l'identità del ricercatore locale assuma in modo sicuro l'identità di esecuzione automatica.

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

Utilizzare il token di accesso

Il comando restituisce una stringa di credenziali OAuth 2.0 temporanea non elaborata. Per i flussi di lavoro di verifica in più passaggi, memorizza nella cache questo token in una variabile shell di breve durata o incorporalo direttamente nelle chiamate di trasporto per eseguire query sui metadati del progetto di 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}"

Visualizzare ed eliminare i motori

Utilizza il token di accesso corrente o il account di servizio rappresentato per verificare, elencare o eliminare i tuoi 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.