Creare set di contesto utilizzando Gemini CLI

MySQL   |  PostgreSQL   |  SQL Server

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.

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 dei 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 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 Cloud SQL

Assicurati di avere accesso a un'istanza Cloud SQL esistente o creane una nuova. Per ulteriori informazioni, consulta Crea istanze per Cloud SQL.

Questo tutorial richiede che tu abbia un database nell'istanza Cloud SQL. Per ulteriori informazioni, consulta Crea un database su l'istanza Cloud SQL

Ruoli e autorizzazioni richiesti

• Aggiungi un utente IAM o un account di servizio all'istanza. Per ulteriori informazioni, consulta Gestisci gli utenti con l'autenticazione IAM dei database per Cloud SQL.
• Concedi i ruoli cloudsql.studioUser, cloudsql.instanceUser e geminidataanalytics.queryDataUser all'utente IAM a livello di progetto. Per ulteriori informazioni, consulta Aggiungi un binding della policy IAM per un progetto.
• Devi anche concedere i privilegi di database di sola lettura a un utente IAM o a un account di servizio accedendo come utente con privilegi di superutente, ad esempio l'utente postgres.
  
  GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;
  
  Sostituisci USER_NAME con l'indirizzo email dell'utente. Devi utilizzare le virgolette intorno all'email perché contiene caratteri speciali (@ e .).
  
  Per ulteriori informazioni, consulta Concedi i privilegi di database a un singolo utente IAM o account di servizio.

Concedi l'autorizzazione executesql all'istanza Cloud SQL

Per concedere l'autorizzazione executesql all'istanza Cloud SQL e abilitare l'API dati Cloud SQL, esegui questo comando:

gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

Sostituisci quanto segue:

• PROJECT_ID: l'ID del tuo Google Cloud progetto.
• INSTANCE_ID: l'ID della tua istanza Cloud SQL.

Per eseguire i passaggi di questo tutorial, accedi a Google Cloud e poi autenticati al database utilizzando l'autenticazione IAM.

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, consulta 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 di database.

Per ulteriori informazioni sull'installazione dell'estensione DB Context Enrichment, consulta 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 ulteriori informazioni su come trovare la chiave API, consulta 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 recuperare gli schemi ed eseguire le 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 autenticare:

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 ulteriori informazioni sulla configurazione manuale del file tools.yaml, consulta 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 tuoi file locali per ridurre i costi generali, 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 ulteriori informazioni sui modelli, consulta la panoramica dei 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 pronti 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 ulteriori informazioni sul file di set di contesto e sul modello di query, consulta la panoramica dei 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 ulteriori informazioni sul file di set di contesto e sulle sfaccettature, consulta la panoramica dei 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 postgresql per selezionare AlloyDB come motore del database.

2. Inserisci la versione di PostgreSQL che vuoi utilizzare. Seleziona default per selezionare PostgreSQL 16.

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.
     • SEMANTIC_SIMILARITY_MATCH: per la ricerca semantica sui valori stringa. Ideale per le ricerche multilingue e di sinonimi. Per un elenco dei modelli supportati, consulta Modelli Google supportati. Per utilizzare SEMANTIC_SIMILARITY_MATCH, devi abilitare l'estensione vector e google_ml_integration.

   • 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 ulteriori informazioni sull'indice di valori, consulta la panoramica dei 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 ulteriori informazioni sul file di set di contesto, consulta la panoramica dei set di contesto.

Passaggi successivi

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