Connetti Google Vertex AI

Pensa a Google Vertex AI come alla “sala business class” dei modelli Gemini di Google: stessi ottimi modelli, ma con vantaggi da impresa come tariffe stabili, fatturazione tramite il tuo account Google Cloud e niente sorprese con limiti di richieste casuali.

Perché Non Usare Semplicemente una Chiave API Normale?

Se hai usato altri provider di IA, sei abituato a copiare una chiave API statica in un file di configurazione. Vertex non funziona così. Invece di una chiave che non cambia mai, Vertex usa token OAuth2 a breve scadenza—come una carta d’imbarco che scade dopo circa un’ora.

La buona notizia? Hermes Agent gestisce automaticamente la creazione e il rinnovo dei token. Non tocchi mai un token. Questo è anche il motivo per cui non puoi semplicemente incollare un token temporaneo nel campo api_key di un provider personalizzato—scadrebbe a metà conversazione e romperebbe la tua sessione.

Cosa Ti Serve (Prerequisiti)

• Un progetto Google Cloud con API Vertex AI abilitata e fatturazione attiva
• Uno di questi tipi di credenziali:
  • Un file JSON di chiave dell’account di servizio (consigliato per i server)
  • Credenziali predefinite dell’applicazione (ADC) tramite gcloud auth application-default login (ottimo per lo sviluppo locale)

Tutto qui. Hermes installerà automaticamente google-auth la prima volta che selezioni Vertex.

Avvio Rapido: Due Opzioni

Opzione A — JSON dell’account di servizio (per server/gateway)

Aggiungi solo una riga al tuo file ~/.hermes/.env:

echo "VERTEX_CREDENTIALS_PATH=/percorso/al/account-di-servizio.json" >> ~/.hermes/.env

Opzione B — Credenziali predefinite dell’applicazione (per sviluppo locale)

Esegui questo nel tuo terminale:

gcloud auth application-default login

Poi seleziona Vertex come provider:

hermes model

Scegli “More providers…” → “Google Vertex AI” → inserisci il tuo ID progetto GCP (o lascia vuoto per usare quello nelle tue credenziali) → seleziona una regione (predefinita: global) → scegli un modello Gemini.

Infine, inizia a chattare:

hermes chat

Dove Vivono le Impostazioni (Spiegazione Semplice)

Hermes divide le impostazioni di Vertex in due file in base alla sensibilità:

~/.hermes/.env — contiene il puntatore segreto (il percorso delle tue credenziali):

# Usa uno di questi (controllati in quest'ordine); ometti entrambi per usare ADC:
VERTEX_CREDENTIALS_PATH=/percorso/al/account-di-servizio.json
GOOGLE_APPLICATION_CREDENTIALS=/percorso/al/account-di-servizio.json

~/.hermes/config.yaml — contiene le impostazioni di routing non segrete (ID progetto e regione):

model:
  default: google/gemini-...

Riepilogo e Consiglio Pratico

Vertex AI ti offre affidabilità di livello enterprise con i modelli Gemini, e Hermes gestisce automaticamente il complicato rinnovo dei token OAuth2. Devi solo indicare a Hermes le tue credenziali una volta, e sei a posto.

Consiglio da pro: Se stai eseguendo Hermes su un server o gateway, usa sempre il metodo del JSON dell’account di servizio (Opzione A)—è più sicuro e prevedibile di ADC. E se ti blocchi, esegui hermes setup per riparare un’installazione gestita se l’installazione automatica di google-auth fallisce. Buon lavoro!