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 contesti, consulta la panoramica dei set di contesti.

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 Knowledge Catalog

Prepara un'istanza Cloud SQL

• Assicurati di avere accesso a un'istanza Cloud SQL esistente o creane una nuova. Per saperne di più, consulta Crea istanze per Cloud SQL.
• Assicurati di creare un database nell'istanza in cui creerai le tabelle. Per saperne di più, consulta Crea un database sull' istanza Cloud SQL.

Ruoli e autorizzazioni richiesti

• Aggiungi un utente IAM o un account di servizio a livello di istanza. Per saperne di più, consulta Aggiungi un binding dei criteri IAM a un utente, un account di servizio o un gruppo.
• Concedi i ruoli cloudsql.studioUser, cloudsql.instanceUser e geminidataanalytics.queryDataUser all'utente IAM o al account di servizio a livello di progetto. Per saperne di più, consulta Aggiungi un binding dei criteri IAM per un progetto.
• Devi avere un utente con privilegi che conceda i privilegi del database a l'utente IAM o al service account.
  
  GRANT SELECT PRIVILEGES ON * TO "IAM_USERNAME";.
  
  Per saperne di più, consulta Concedi i privilegi del database a un singolo utente IAM o service account.

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 il database per le ricerche di valori

Per utilizzare le ricerche di valori semantici e trigrammi, devi configurare l'istanza Cloud SQL per MySQL in modo che supporti i vector embedding e l'indicizzazione n-grammi.

Nota: il modello Semantic_SIMILARITY_MATCH è disponibile solo per MySQL 8.0.36 o versioni successive.

1. Per consentire all'istanza Cloud SQL per MySQL di eseguire ricerche di valori semantici, devi abilitare i seguenti flag.

   1. Abilita il flag cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on
      

   2. Abilita il flag enable-google-ml-integration per consentire all'istanza Cloud SQL per MySQL di integrarsi con Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration
      

   3. Crea una colonna vettoriale per archiviare gli embedding delle città

      ALTER TABLE `airports` 
      ADD COLUMN `city_embedding` VECTOR(768);
      

   4. Genera e archivia i vector embedding per i nomi delle città

      UPDATE `airports` 
      SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
      WHERE `city` IS NOT NULL;
      

2. Per consentire all'istanza Cloud SQL per MySQL di eseguire ricerche di valori trigrammi, segui questi passaggi.

   1. Abilita il flag ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3
      

   2. Crea un indice FULLTEXT per la corrispondenza trigrammi sul nome dell'aeroporto

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
      ON `airports`(`name`) 
      WITH PARSER ngram;
      

prepara l'ambiente

Puoi creare file di set di contesti 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 il contesto NL2SQL strutturato dagli schemi del database.

Per saperne di più 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 DB Context Enrichment:

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

   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, 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 il recupero degli schemi e l'esecuzione di 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 include 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, 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 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 contesti, puoi utilizzare il comando /generate_targeted_templates. Per saperne di più sui modelli, consulta la panoramica dei set di contesti.

Per aggiungere un modello di query al set di contesti:

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 contesti o aggiungerlo a un file di set di contesti esistente.

Il file di set di contesti 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 contesti e sul modello di query, consulta la panoramica dei set di contesti.

Genera sfaccettature mirate

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

Per aggiungere una sfaccettatura al file di set di contesti:

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 contesti o aggiungerla a un file di set di contesti esistente.

Il file di set di contesti 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 contesti e sulle sfaccettature, consulta la panoramica dei set di contesti.

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.

Assicurati di completare i passaggi descritti in Prepara il database per le ricerche di valori.

Per generare un indice di valori:

1. Esegui il comando /generate_targeted_value_searches:

   /generate_targeted_value_searches

1. Inserisci mysql per selezionare MySQL come motore del database. Seleziona default per selezionare MySQL 8.0.

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 trigrammi normalizzata. Ideale per le ricerche degli utenti e la correzione dei nomi. Per utilizzare TRIGRAM_STRING_MATCH, devi preparare il database in modo che supporti l'indicizzazione n-grammi.
     Nota: il modello Semantic_SIMILARITY_MATCH è disponibile per MySQL 8.0.36 o versioni successive.
     • 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 preparare il database in modo che supporti i vector embedding.

   • 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 indici di valori aggiuntivi, la generazione di SQL basata su modelli passa al passaggio successivo.

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

Il file di set di contesti 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 dei set di contesti.

(Facoltativo) Genera modelli collettivi

Se vuoi generare automaticamente il file di set di contesti 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 contesti 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 contesti 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 contesti, consulta la panoramica dei set di contesti.

Passaggi successivi

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