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 lavorare con AlphaEvolve.

  1. Prerequisiti

  2. Configurazione di AlphaEvolve

Prerequisiti

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

Progetto e licenzeGoogle Cloud

  • ProgettoGoogle Cloud : crea un progetto Google Cloud dedicato. Per il provisioning dei progetti, collabora con il team dedicato all'account Google Cloud assegnato.

  • Licenze Gemini Enterprise: acquista le licenze Gemini Enterprise tramite il tuo rappresentante di vendita Google Cloud . Qualsiasi livello di Gemini Enterprise, inclusa una licenza di prova, concede l'accesso ad AlphaEvolve.

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

Profili utente e requisiti IAM

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

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

Profilo Descrizione Ruoli e autorizzazioni richiesti
Cloud Administrator Gestisce la configurazione iniziale una tantum dell'ambiente, l'assegnazione IAM e l'abilitazione dell'API Discovery Engine e dell'API Gemini in Vertex AI.
  • roles/resourcemanager.projectCreator (livello di organizzazione/cartella)
  • roles/billing.user (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 sulla 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 il servizio API Cloud AlphaEvolve.
  • roles/discoveryengine.editor o roles/discoveryengine.admin (con ambito a livello di progetto)

Ambiente host amministrativo

Un host Linux amministrativo (come 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

Configura 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 i tuoi 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 Google Cloud di destinazione, 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 dall'uomo del account di servizio, 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 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}"

  5. Concedi il ruolo Discovery Engine al account di servizio:

    Esegui questo 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 istanze Discovery Engine, sessioni di conversazione e risorse secondarie AlphaEvolveExperiments sottostanti.

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

Simula l'identità del 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 impersonare il account di servizio appena creato.

  1. Definisci l'entità di impersonificazione: dichiara la stringa target 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 dei token all'entità: esegui questo comando per mappare la funzionalità di generazione dei token delle 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}"

    Questa associazione di 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 per generare token di accesso OAuth 2.0 di breve durata, che consentono la simulazione dell'identità dei service account in modo sicuro.

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

Abilita le API richieste

L'amministratore cloud deve abilitare due API nel progetto:

  • L'API Discovery Engine (discoveryengine.googleapis.com), che gestisce gli endpoint API AlphaEvolve su Cloud.

  • L'API Vertex AI (aiplatform.googleapis.com), che gestisce l'API Gemini in Vertex AI. AlphaEvolve genera ogni programma candidato con un insieme di modelli Gemini, pertanto un utente del sistema non può eseguire un esperimento finché questa API non viene abilitata.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

In alternativa, abilita entrambe le API con Google Cloud SDK sull'host Linux:

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

Verifica che entrambe le API siano abilitate:

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

Crea risorse e sessioni di Discovery Engine

Il processo di configurazione passa dalle configurazioni delle identità amministrative al provisioning del livello 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 progettoGoogle Cloud e le sue risorse sono ospitate in una località specifica (le località supportate per AlphaEvolve sono global, use eu). All'interno di questa struttura di base, una raccolta funge da container organizzativo di primo livello per le risorse correlate. Il motore viene eseguito il provisioning all'interno di una raccolta per ospitare l'applicazione AI principale, che è anche il luogo in cui viene configurata una risorsa assistente per gestire le proprietà e gli strumenti di AI generativa per l'applicazione. Il motore gestisce le singole interazioni degli utenti acquisite come oggetti sessione.

AlphaEvolveExperiment è nidificato in una sessione e rappresenta una singola esecuzione dell'agente di programmazione evolutiva utilizzato per l'individuazione e l'ottimizzazione degli algoritmi nel contesto di quella specifica interazione dell'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 Google Clouddi destinazione, 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 compatibile con l'URL dell'ID motore.

    ENGINE_ID="alpha-evolve-experiment-engine"

  3. Crea il motore:

    Questo comando registra un nuovo motore all'interno del progetto Google Cloud , definendone il nome univoco, il nome visualizzato e il tipo di soluzione (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 compatibile con l'URL dell'ID dell'assistente.

    ASSISTANT_ID="default_assistant"

  5. Crea l'assistente:

    Questo comando registra un nuovo assistente all'interno del progetto Google Cloud , 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 API

Una volta che l'amministratore cloud ha completato 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 workload di ottimizzazione attiva.

Visualizza ed elimina i motori

Utilizza il tuo token di accesso attuale o il account di servizio di cui hai assunto l'identità 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.