Creare set di contesto utilizzando Gemini CLI

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, vedi 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
  • Generare sfaccettature mirate
  • Generare ricerche di valori mirate
  • Facoltativo. Genera modelli collettivi

Prima di iniziare

Completa i seguenti prerequisiti prima di creare un agente.

Attivare i servizi richiesti

Attiva i seguenti servizi per il tuo progetto:

Prepara un'istanza Cloud SQL

Ruoli e autorizzazioni richiesti

Concedi l'autorizzazione executesql all'istanza Cloud SQL

Per concedere l'autorizzazione executesql all'istanza Cloud SQL e abilitare l'API Cloud SQL Data, 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 dell'istanza Cloud SQL.
Per eseguire i passaggi di questo tutorial, accedi a Google Cloud, quindi autenticati al database utilizzando l'autenticazione IAM.

Preparare 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 gli incorporamenti vettoriali e l'indicizzazione n-grammi.

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

    1. Attiva 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. Generare e archiviare 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. Attiva 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 di 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 contesto 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 per l'arricchimento del contesto del database

L'estensione DB Context Enrichment fornisce un workflow 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 per l'arricchimento del contesto DB:

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

  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 per 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 l'autenticazione:

gcloud auth application-default login

Configurare 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 del database e gli strumenti necessari per recuperare gli schemi o eseguire SQL. L'estensione è dotata di competenze dell'agente preinstallate per aiutarti a generare la configurazione.

  1. Avvia Gemini CLI:

    gemini

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

    /skills

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

  4. Esegui il seguente comando in Gemini CLI per applicare la configurazione tools.yaml al server MCP di 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.

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 Panoramica dei set di contesto.

Per aggiungere un modello di query al set di contesto, segui questi passaggi:

  1. Nella stessa directory, avvia Gemini CLI:

    gemini

  2. Completa la configurazione dell'autenticazione Gemini CLI.

  3. Verifica che la casella degli strumenti MCP e l'estensione per l'arricchimento del database siano pronte all'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 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 del set di contesti e sul modello di query, consulta Panoramica dei set di contesti.

Generare sfaccettature mirate

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

Per aggiungere una sfaccettatura al file del 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 contesti o aggiungerla a un file di set di contesti esistente.

Il file 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 e sulle sfaccettature del set di contesti, vedi Panoramica dei set di contesti.

Generare query di ricerca di valori

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

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

Per generare un indice di valori, segui questi passaggi:

  1. Esegui il comando /generate_targeted_value_searches:

    /generate_targeted_value_searches
  1. Inserisci mysql per selezionare MySQL come motore del database. Seleziona il valore predefinito per selezionare MySQL 8.0.

  1. Inserisci la configurazione di ricerca dei valori nel seguente modo:

    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 dei valori. Puoi utilizzare una delle seguenti funzioni:

      • EXACT_STRING_MATCH: per la corrispondenza esatta di due valori stringa. Ideale per ID univoci, codici e chiavi primarie.
      • TRIGRAM_STRING_MATCH: Per la corrispondenza fuzzy che calcola la distanza trigramma normalizzata. Ideale per le ricerche degli utenti e la correzione dei nomi. Per utilizzare TRIGRAM_STRING_MATCH, devi preparare il database per supportare l'indicizzazione di n-grammi.
      • SEMANTIC_SIMILARITY_MATCH: Per la ricerca semantica sui valori stringa. Ideale per ricerche multilingue e di sinonimi. Per un elenco dei modelli supportati, consulta Modelli Google supportati. Per utilizzare SEMANTIC_SIMILARITY_MATCH, devi preparare il database per supportare i vector embedding.

    • DESCRIPTION: (facoltativo) la descrizione della query di ricerca dei 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 contesto come file o aggiungerlo a un file esistente.

Il file 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 valore, consulta la Panoramica dei set di contesto.

(Facoltativo) Genera modelli collettivi

Se vuoi generare automaticamente il file del 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 modello o aggiungere le coppie di query a un file modello esistente. Il modello di query viene salvato come file JSON nella directory locale.

Il file 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 del set di contesti, vedi Panoramica dei set di contesti.

Passaggi successivi