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

Prima di iniziare

Completa i seguenti prerequisiti prima di creare un agente.

Abilita i servizi richiesti

Abilita 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 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.

  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 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 la pagina Introduzione a 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 saperne di più sull'installazione dell'estensione DB Context Enrichment, consulta la pagina 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

  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 autenticarti:

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.

  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 la pagina 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 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 saperne di più 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 saperne di più 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.

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.
      • 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 la pagina 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 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 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 saperne di più sul file di set di contesto, consulta la panoramica dei set di contesto.

Passaggi successivi