Creare set di contesto utilizzando Gemini CLI

Anteprima

Queste funzionalità sono ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini di servizio specifici e ai Termini aggiuntivi per i prodotti in anteprima dell'AI generativa. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota sull'interfaccia PostgreSQL: gli esempi in questo argomento sono destinati ai database con dialetto GoogleSQL. Questa funzionalità non supporta l'interfaccia PostgreSQL.

Questo documento descrive come utilizzare Gemini CLI e MCP Toolbox per creare file di contesto dell'agente. Questi file contengono modelli, sfaccettature e ricerche di valori che forniscono il contesto per la generazione di query SQL dal linguaggio naturale. Utilizzerai anche l'estensione DB Context Enrichment.

Per scoprire di più sui set di contesto, consulta la panoramica sui set di contesto.

Per creare un file di contesto dell'agente, segui questi passaggi di alto livello:

• prepara l'ambiente
• genera modelli mirati
• genera sfaccettature mirate
• genera ricerche di valori mirate
• (Facoltativo) genera modelli collettivi

Prima di iniziare

Completa i seguenti prerequisiti prima di creare un agente.

Abilita i servizi richiesti

Abilita i seguenti servizi per il tuo progetto:

• API Data Analytics con Gemini
• API Gemini for Google Cloud
• API Dataplex Universal Catalog

Prepara un'istanza di Spanner

• Assicurati che sia disponibile un'istanza di Spanner. Per saperne di più, consulta Crea un'istanza.
• Assicurati di creare un database nell'istanza in cui creerai le tabelle. Per saperne di più, consulta Crea un database nell' istanza di Spanner.

Questo tutorial richiede che tu abbia un database nella tua istanza di Spanner. Per saperne di più, consulta Crea un database.

Ruoli e autorizzazioni richiesti

• Aggiungi un utente IAM o account di servizio al cluster. Per saperne di più, consulta Applica i ruoli IAM.
• Concedi i ruoli spanner.databaseReader e geminidataanalytics.queryDataUser all'utente IAM a livello di progetto. Per saperne di più, consulta Aggiungi un binding della policy IAM per un progetto.
• Concedi ruoli e autorizzazioni all'utente IAM a livello di progetto per i database richiesti.

Prepara l'ambiente

Puoi creare file di contesto dell'agente da qualsiasi ambiente di sviluppo locale o IDE. Per preparare l'ambiente, segui questi passaggi:

• Installa Gemini CLI
• Installa l'estensione DB Context Enrichment
• Configura la connessione al database

Installa Gemini CLI

Per installare Gemini CLI, vedi Inizia a utilizzare Gemini CLI.

Installa l'estensione MCP DB Context Enrichment

L'estensione DB Context Enrichment fornisce un flusso di lavoro guidato e interattivo per generare un contesto NL2SQL strutturato dagli schemi del database.

Per saperne di più sull'installazione dell'estensione DB Context Enrichment, vedi Estensione DB Context Enrichment.

Per installare l'estensione DB Context Enrichment:

1. Installa l'estensione Gemini CLI di MCP Toolbox:

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

   Nota: l'estensione richiede una chiave API Gemini durante l'installazione per l'autenticazione con l'API Gemini e per abilitare la generazione del contesto. Per saperne di più su come trovare la chiave API, vedi Utilizzare le chiavi API Gemini.

2. (Facoltativo) Aggiorna l'estensione DB Context Enrichment.

   Per verificare la versione installata dell'estensione, esegui questo comando:

   gemini extensions list

   Assicurati che la versione sia 0.4.2 o successiva. Per aggiornare l'estensione DB Context Enrichment, esegui questo comando:

     gemini extensions update mcp-db-context-enrichment

   Per aggiornare l'estensione DB Context Enrichment o sostituire GEMINI_API_KEY, esegui questo comando:

   gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

   Sostituisci GEMINI_API_KEY con la tua chiave API Gemini.

Configura la connessione al database

L'estensione richiede la connessione al database per la generazione del contesto per il recupero degli schemi e l'esecuzione delle istruzioni SQL. Per consentire all'estensione di interagire con il database, devi configurare le credenziali di autenticazione e definire le origini e gli strumenti del database.

Configura le Credenziali predefinite dell'applicazione

Devi configurare le Credenziali predefinite dell'applicazione (ADC) per fornire le credenziali utente per due componenti principali:

• Server MCP Toolbox: utilizza le credenziali per connettersi al database, recuperare gli schemi ed eseguire SQL per la convalida.
• Estensione DB Context Enrichment: utilizza le credenziali per autenticare e chiamare l'API Gemini.

Esegui questi comandi nel terminale per l'autenticazione:

gcloud auth application-default login

Configura il file tools.yaml

L'estensione richiede una connessione al database per la generazione del contesto, supportata da MCP Toolbox e definita nel file di configurazione tools.yaml.

Il file tools.yaml specifica l'origine e gli strumenti del database necessari per recuperare gli schemi o eseguire SQL. L'estensione viene fornita con le competenze dell'agente preinstallate per aiutarti a generare la configurazione.

Nota: se questa connessione non viene stabilita, l'estensione restituirà messaggi di errore, ad esempio "Error Discovering tools from mcp_toolbox" e la generazione del contesto non funzionerà.

1. Avvia Gemini CLI:

   gemini

2. Verifica che le competenze siano attive digitando in Gemini CLI:

   /skills

3. Digita un prompt come help me setup the database connection. La competenza ti guida nella creazione del file tools.yaml nella directory di lavoro corrente.

4. Esegui questo comando in Gemini CLI per applicare la configurazione tools.yaml al server MCP Toolbox.

   /mcp reload

Per saperne di più sulla configurazione manuale del file tools.yaml, vedi Configurazione di MCP Toolbox.

Genera contesto

Le estensioni installate in precedenza consentono a Gemini CLI di aiutarti a creare il contesto sotto forma di file JSON.

Nota: Gemini CLI può accedere ai file locali per ridurre i sovraccarichi, ad esempio specificando le posizioni esatte dei file nelle directory locali. Ad esempio, se un passaggio del flusso di lavoro di Gemini CLI ti chiede informazioni che puoi trovare nel file tools.yaml, puoi chiedere a Gemini CLI di use tools.yaml o rispondere con un prompt come look it up.

Genera modelli mirati

Se vuoi aggiungere una coppia di query specifica come modello di query al set di contesto, puoi utilizzare il comando /generate_targeted_templates. Per saperne di più sui modelli, consulta la panoramica sui set di contesto.

Per aggiungere un modello di query al set di contesto:

1. Nella stessa directory, avvia Gemini CLI:

   gemini

2. Completa la configurazione dell'autenticazione di Gemini CLI.

3. Verifica che MCP Toolbox e l'estensione di arricchimento del database siano pronte per l'uso:

   /mcp reload

4. Esegui il comando /generate_targeted_templates:

   /generate_targeted_templates

5. Inserisci la query in linguaggio naturale che vuoi aggiungere al modello di query.

6. Inserisci la query SQL corrispondente nel modello di query.

7. Esamina il modello di query generato. Puoi salvare il modello di query come file di set di contesto o aggiungerlo a un file di set di contesto esistente.

Il file di set di contesto simile a my-cluster-psc-primary_postgres_templates_20251104111122.json viene salvato nella directory in cui hai eseguito i comandi.

Per saperne di più sul file di set di contesto e sul modello di query, consulta la panoramica sui set di contesto.

Genera sfaccettature mirate

Se vuoi aggiungere una coppia di query specifica come sfaccettatura al file di set di contesto, puoi utilizzare il comando /generate_targeted_facets.

Per aggiungere una sfaccettatura al file di set di contesto:

1. Esegui il comando /generate_targeted_facets:

   /generate_targeted_facets

2. Inserisci la query in linguaggio naturale che vuoi aggiungere al modello di query.

3. Inserisci la query SQL corrispondente nel modello di query.

4. Esamina la sfaccettatura generata. Puoi salvare la sfaccettatura in un file di set di contesto o aggiungerla a un file di set di contesto esistente.

Il file di set di contesto simile a my-cluster-psc-primary_postgres_templates_20251104111122.json viene salvato nella directory in cui hai eseguito i comandi.

Per saperne di più sul file di set di contesto e sulle sfaccettature, consulta la panoramica sui set di contesto.

Genera query di ricerca di valori

Se vuoi generare ricerche di valori che specificano in che modo il sistema deve cercare e trovare valori specifici all'interno di un tipo di concetto, puoi utilizzare il comando /generate_targeted_value_searches.

Per generare un indice di valori:

1. Esegui il comando /generate_targeted_value_searches:

   /generate_targeted_value_searches

1. Inserisci spanner per selezionare Spanner come motore del database.

1. Inserisci la configurazione della ricerca di valori come segue:

   Table name: TABLE_NAME
   Column name: COLUMN_NAME
   Concept type: CONCEPT_TYPE
   Match function: MATCH_FUNCTION
   Description: DESCRIPTION
   

   Sostituisci quanto segue:

   • TABLE_NAME: la tabella in cui esiste la colonna associata al tipo di concetto.
   • COLUMN_NAME: il nome della colonna associata al tipo di concetto.
   • CONCEPT_TYPE: il tipo di concetto che vuoi definire, ad esempio City name.

   • MATCH_FUNCTION: la funzione di corrispondenza da utilizzare per la ricerca di valori. Puoi utilizzare una delle seguenti funzioni:

     • EXACT_STRING_MATCH: per la corrispondenza esatta di due valori stringa. Ideale per ID, codici e chiavi primarie univoci.
     • TRIGRAM_STRING_MATCH: per la corrispondenza approssimativa che calcola la distanza trigramma normalizzata. Ideale per le ricerche degli utenti e la correzione dei nomi.

   • DESCRIPTION: (facoltativo) la descrizione della query di ricerca di valori.

2. Aggiungi altre ricerche di valori in base alle esigenze. Se salti l'aggiunta di altri indici di valori, la generazione di SQL basata su modelli passa al passaggio successivo.

3. Esamina le ricerche di valori generate. Puoi salvare il set di contesto come file di set di contesto o aggiungerlo a un file di set di contesto esistente.

Il file di set di contesto simile a my-cluster-psc-primary_postgres_templates_20251104111122.json viene salvato nella directory in cui hai eseguito i comandi.

Per saperne di più sull'indice di valori, consulta la panoramica sui set di contesto.

(Facoltativo) Genera modelli collettivi

Se vuoi generare automaticamente il file di set di contesto in base allo schema e ai dati del database, puoi utilizzare il comando /generate_bulk_templates.

Per generare automaticamente modelli collettivi:

1. Esegui il comando /generate_bulk_templates:

   /generate_bulk_templates

2. In base allo schema del database, la generazione di SQL basata su modelli ti guida attraverso una serie di domande relative alla verifica delle informazioni del database e alla concessione delle autorizzazioni per accedere allo schema del database.

3. Esamina il modello di query generato. Puoi approvare il modello o aggiornare una coppia di query che vuoi rivedere.

4. Inserisci la query in linguaggio naturale che vuoi aggiungere al modello di query.

5. Inserisci la query SQL corrispondente nel modello di query.

6. Esamina il modello di query generato. Puoi salvare il modello di query come file di set di contesto o aggiungerlo a un file di contesto esistente.

7. Dopo aver approvato il modello di query, puoi creare un nuovo file di modello o aggiungere le coppie di query a un file di modello esistente. Il modello di query viene salvato come file JSON nella directory locale.

Il file di set di contesto simile a my-cluster-psc-primary_postgres_templates_20251104111122.json viene salvato nella directory in cui hai eseguito i comandi.

Per saperne di più sul file di set di contesto, consulta la panoramica sui set di contesto.

Passaggi successivi

• Scopri di più sui set di contesto.
• Scopri come creare o eliminare un set di contesto in Spanner Studio.
• Scopri come testare un set di contesto.