Creare set di contesto utilizzando Gemini CLI

Questo documento descrive come creare e ottimizzare il contesto che consente di migliorare l'accuratezza di QueryData per la creazione delle applicazioni dell'agente dati. Utilizzando l'estensione di arricchimento del contesto DB in Gemini CLI, si accede a una suite di strumenti per sviluppatori che automatizzano la creazione e l'ottimizzazione dei set di contesti.

Per scoprire di più sui set di contesti, vedi Panoramica dei set di contesti.

L'estensione automatizza la creazione e l'ottimizzazione dei set di contesto nella seguente sequenza:

  1. Comprendi le applicazioni: importa artefatti come schemi di database, codice dell'applicazione e requisiti aziendali per stabilire la logica di business di base per l'agente di dati.
  2. Crea set di dati: crea un set di dati di valutazione contenente domande rappresentative in linguaggio naturale e le relative risposte SQL previste. La creazione di questo set di dati di base è fondamentale per misurare il rendimento e monitorare i miglioramenti nel tempo.
  3. Genera contesto iniziale: genera automaticamente un insieme di contesto di base derivato direttamente dallo schema del database e dagli artefatti dell'applicazione facoltativi come punto di partenza rapido.
  4. Ottimizza il contesto in modo iterativo: valuta il tuo set di dati per identificare il motivo per cui query specifiche non vanno a buon fine. Gemini utilizza il ragionamento automatizzato per suggerire aggiornamenti mirati del contesto, ottenendo in modo iterativo una maggiore precisione.

Sebbene l'estensione offra un flusso di lavoro automatizzato efficace, è adattabile alle tue esigenze. Puoi ignorare l'automazione per creare e inserire il contesto a un livello più granulare. Utilizzando comandi di generazione specializzati, controlli la creazione di modelli, sfaccettature e query di ricerca di valori di alta qualità.

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, attiva 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, completa i seguenti 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, completa i seguenti 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 DB Context Enrichment

L'estensione per l'arricchimento del contesto del database fornisce un flusso di lavoro guidato e interattivo per generare set di contesto strutturati e iterare su di essi.

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

Per installare l'estensione DB Context Enrichment, completa questi passaggi:

  1. Installa l'estensione Gemini CLI per l'arricchimento del contesto del database:

    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.5.0 o successive. 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 una connessione al database per recuperare gli schemi e la possibilità di convalidare la sintassi del contesto SQL generato. Per consentire all'estensione di interagire con il tuo database, configura le credenziali di autenticazione e definisci la configurazione della connessione al database.

Configura le credenziali predefinite dell'applicazione

Configura 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 di connessione al database

L'estensione richiede una connessione al database per la generazione del contesto, che MCP Toolbox supporta e definisce all'interno di un file di configurazione.

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

  1. Avvia Gemini CLI:

    gemini

  2. Verifica che le skill siano attive digitando quanto segue nella CLI Gemini:

    /skills

  3. Digita un prompt, ad esempio help me set up the database connection. La skill ti guida nella creazione del file di configurazione nella directory di lavoro corrente come autoctx/tools.yaml.

  4. Esegui questo 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 di configurazione del database, consulta Configurazione di MCP Toolbox.

Genera il contesto con il workflow automatizzato

Il miglioramento della precisione tramite l'ingegneria del contesto è in genere un processo manuale basato su prove ed errori. Gli sviluppatori spesso indovinano il motivo per cui una query non è riuscita, scrivono una correzione e la testano manualmente. L'estensione DB Context Enrichment nella Gemini CLI automatizza questo processo di miglioramento. Utilizza set di dati di valutazione, ovvero insiemi di domande con le relative risposte SQL corrette, per misurare le prestazioni e identificare il motivo per cui alcune query non vanno a buon fine. Gemini suggerisce quindi automaticamente aggiornamenti contestuali specifici per ottenere una maggiore accuratezza. Completa questi passaggi per migliorare sistematicamente l'accuratezza del tuo agente dati.

Inizializzare un workspace

Il comando di inizializzazione configura lo spazio di lavoro locale, inclusi la configurazione della connessione al database e la directory dell'esperimento. Questo spazio di lavoro dedicato garantisce che tutte le configurazioni, gli esperimenti e i file generati siano organizzati in un unico posto, semplificando la gestione e il monitoraggio degli sforzi di ottimizzazione del contesto.

  1. Crea una nuova directory che funga da spazio di lavoro per il flusso di ottimizzazione iterativo e vai alla directory.

  2. Avvia Gemini CLI nella nuova directory:

    gemini

  3. Esegui il comando di inizializzazione:

    /autoctx:init

    L'agente ti guida nella creazione del file tools.yaml se non è stata configurata alcuna connessione al database e inizializza anche il file state.md locale e una directory experiments.

    Dopo l'inizializzazione, lo spazio di lavoro dovrebbe avere l'aspetto seguente:

    my-workspace/
└── autoctx/
    ├── tools.yaml          # Database connection and tools configuration
    ├── state.md            # Local file to track the experiment progress
    └── experiments/        # Dedicated directory for future experiment-specific files

Preparare ed espandere i set di dati

Per consentire a Gemini di eseguire sistematicamente le ottimizzazioni sul tuo set di contesto, prepara un set di dati di valutazione di domande rappresentative in linguaggio naturale e le relative risposte SQL previste ("goldens") per valutare il tuo set di contesto. Un set di dati di valutazione di alta qualità è fondamentale per misurare il rendimento, identificare gli errori delle query e monitorare i miglioramenti nel tempo. Il set di dati deve essere un file JSON contenente la domanda in linguaggio naturale (NLQ) e l'SQL di riferimento che copre i casi d'uso mirati nell'applicazione di dati.

Ecco un esempio del formato previsto:

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

L'estensione Gemini CLI include un comando fornito che crea e ridimensiona una piccola base di domande di riferimento a scopo di valutazione.

  1. Vai alla cartella dell'area di lavoro.

  2. Avvia Gemini CLI nella nuova directory:

    gemini

  3. Esegui il comando /autoctx:generate-dataset in Gemini CLI:

    /autoctx:generate-dataset

  4. Quando l'agente ti chiede di fornire un seme, ovvero un esempio iniziale o un piccolo insieme di esempi che guidano la generazione di un set di dati più grande. Un seme può essere uno dei seguenti:

    • Un piccolo file del set di dati di riferimento
    • Coppie d'oro specifiche per la conversione da linguaggio naturale a SQL (NL2SQL)

    Ad esempio, potresti fornire la seguente coppia d'oro NL2SQL come seme:

    Question: "What are the names of all airports in California?"
SQL: "SELECT name FROM airports WHERE state = 'CA';"

  5. L'agente richiede l'autorizzazione per verificare la sintassi e la validità dell'esecuzione utilizzando lo strumento execute_sql. Questo passaggio è facoltativo.

  6. L'agente chiede se espandere il set di dati con varianti dei dati iniziali (applicando filtri, sinonimi e così via diversi). Questo passaggio è facoltativo.

    L'agente utilizza lo strumento execute_sql per eseguire le query SQL appena generate sul database per verificare la sintassi e la validità dell'esecuzione prima di presentarle.

  7. Accetta, modifica o rifiuta selettivamente i suggerimenti. Le coppie approvate vengono salvate automaticamente in locale e sono pronte per la valutazione.

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json  # Generated dataset
    └── experiments/

Crea il set di contesti iniziale

La generazione di un insieme di contesto iniziale fornisce una base di riferimento per la valutazione e il miglioramento iterativo. Questo passaggio utilizza lo schema del database e gli artefatti dell'applicazione per creare un contesto di base che rifletta la logica di business.

L'estensione Gemini CLI include un comando predefinito per generare un insieme iniziale di modelli e sfaccettature in base allo schema del database e alle informazioni sull'applicazione dell'agente di dati, ad esempio il codice dell'applicazione o i file con informazioni sui requisiti aziendali. Per generare da zero un insieme di contesto di base:

  1. Vai alla cartella dell'area di lavoro.

  2. Avvia Gemini CLI nella nuova directory:

    gemini

  3. Esegui il comando /autoctx:bootstrap in Gemini CLI:

    /autoctx:bootstrap

    In genere, puoi aspettarti quanto segue dall'agente.

    • L'agente ti chiede di specificare un nome per l'esperimento. Un esperimento è una cartella di spazio di lavoro dedicata che racchiude l'intero ciclo di vita di una configurazione del contesto del database, monitorando il suo stato di base, i risultati dei test di valutazione e i successivi miglioramenti iterativi di hill climbing. Questo nome viene utilizzato per organizzare tutti i file generati nella cartella dell'esperimento nell'area di lavoro. Scegli un nome descrittivo e facile da ricordare.

    • L'agente recupera ed elenca gli schemi dal database di destinazione e ti chiede di fornire facoltativamente risorse o file aggiuntivi. Se lo schema è complesso, l'agente ti chiede anche di selezionare schemi o tabelle specifici per il set di contesto iniziale. Se non ne specifichi nessuno, vengono prese in considerazione tutte le tabelle disponibili negli schemi di database correnti.

  4. Rivedi e, se vuoi, perfeziona il set di contesti generato. Una volta perfezionato, l'agente produce un file di contesto JSON direttamente sul disco locale nella cartella dello spazio di lavoro:

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json  # The generated initial context set file

  5. Segui le istruzioni per caricare il contesto da Cloud SQL Studio.

Valutare l'efficacia del contesto

L'estensione Gemini CLI include un comando integrato per valutare il data agent utilizzando un golden dataset. L'estensione si integra con Evalbench per eseguire valutazioni eseguendo query sull'API QueryData dell'agente con le domande specificate nel set di riferimento e confrontando poi l'SQL generato e i relativi risultati di esecuzione con l'SQL di riferimento. La valutazione è fondamentale per comprendere l'efficacia del set di contesto attuale. Confrontando l'SQL generato con il set di dati di riferimento, puoi individuare query specifiche che non vanno a buon fine e identificare le aree in cui è necessario migliorare il contesto.

Per misurare l'efficacia del contesto attuale rispetto al set di dati di riferimento:

  1. Carica il contesto da Cloud SQL Studio nei set di contesti di destinazione per la valutazione. Questo passaggio è facoltativo se il contesto da valutare non viene caricato.
  2. Vai alla cartella dell'area di lavoro.

  3. Avvia Gemini CLI nella cartella:

    gemini

  4. Esegui il comando /autoctx:evaluate in Gemini CLI:

    /autoctx:evaluate

  5. Fornisci i percorsi per il set di dati di riferimento, l'ID del set di contesto per la generazione della configurazione di valutazione e l'esecuzione della valutazione, nonché una directory di output designata.

    Una volta completata, l'agente genera i risultati della valutazione come file nella cartella dell'esperimento e riepiloga il risultato della valutazione.

    Se vuoi, puoi esaminare manualmente la valutazione dal report dettagliato, che viene memorizzato come file CSV nella cartella dell'esperimento.

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
                └── <configs_for_eval_run>/
            └── eval_reports/
                └── <eval_id>/
                    └── eval_report/
                        ├── configs.csv
                        ├── evals.csv
                        ├── scores.csv
                        └── summary.csv

Eseguire l'analisi dei punti deboli e l'ottimizzazione del contesto

Come passaggio fondamentale per ottimizzare il set di contesto, l'estensione Gemini CLI include un comando integrato per eseguire l'analisi delle lacune nel set di contesto esistente e proporre modifiche per migliorarne la qualità. L'analisi delle lacune è fondamentale per capire perché determinate query non vanno a buon fine e dove è possibile migliorare il contesto. In base a questa analisi, Gemini utilizza il ragionamento automatizzato per suggerire aggiornamenti del contesto mirati, come nuovi modelli o sfaccettature, per risolvere questi errori e migliorare in modo iterativo l'accuratezza delle query.

  1. Vai alla cartella dell'area di lavoro.

  2. Avvia Gemini CLI nella cartella:

    gemini

  3. Esegui il comando /autoctx:hillclimb in Gemini CLI:

    /autoctx:hillclimb

    L'agente identifica automaticamente i risultati di valutazione e il contesto di base più adatti per la ricerca locale e chiede conferma se sono disponibili più opzioni.

    Se non è disponibile alcun risultato di valutazione, l'agente ti chiede di eseguire una valutazione con il set di dati e il contesto impostati.

    Una volta pronto, l'agente legge i risultati della valutazione e il contesto esistente, quindi genera un report di analisi delle lacune.

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
            └── eval_reports/
            └── hillclimb/
                └── gap_analysis_v1.md

    L'agente formula le correzioni proponendo nuovi modelli e sfaccettature prescrittivi, testando facoltativamente SQL sul database tramite execute_sql.

    Una volta pronto, viene generato localmente un nuovo file JSON di contesto migliorato, lasciando intatto il file JSON di contesto di base.

    my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
            └── eval_reports/
            └── hillclimb/
                ├── gap_analysis_v1.md
                └── improved_context_v1.md

  4. Segui le istruzioni per caricare il contesto nel set di contesti di destinazione da Cloud SQL Studio, pronto per il successivo ciclo di iterazione a partire dalla valutazione.

Limitazioni

Il flusso di lavoro automatizzato supporta solo la generazione e l'ottimizzazione di modelli e sfaccettature. Se vuoi configurare la ricerca di valori per il tuo agente dati, vedi Generare query di ricerca di valori.

Genera un contesto mirato

Se preferisci un approccio più personalizzato alla creazione del contesto, puoi utilizzare l'estensione DB Context Enrichment per generare manualmente elementi di contesto specifici. I seguenti comandi ti guidano nella creazione del contesto come file JSON, offrendoti un controllo granulare sulla generazione di query di ricerca di modelli, sfaccettature e valori.

Genera modelli mirati

Per aggiungere una coppia query-SQL specifica come modello di query al set di contesto, utilizza il comando /generate_targeted_templates.

Per saperne di più sul file del set di contesti e sul modello di query, consulta Panoramica dei set di contesti.

Per aggiungere un modello di query al set di contesto, completa i seguenti passaggi:

  1. Esegui il comando /generate_targeted_templates in Gemini CLI:

    /generate_targeted_templates

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

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

  4. 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 del set di contesto, ad esempio my-cluster-psc-primary_postgres_context_set_20251104111122.json, viene salvato nella directory in cui hai eseguito i comandi.

Generare sfaccettature mirate

Per aggiungere una query specifica alla condizione SQL come sfaccettatura al file del set di contesto, utilizza il comando /generate_targeted_facets.

Per saperne di più sul file e sulle sfaccettature del set di contesti, vedi Panoramica dei set di contesti.

Per aggiungere un aspetto al file del set di contesto, completa i seguenti passaggi:

  1. Esegui il comando /generate_targeted_facets in Gemini CLI:

    /generate_targeted_facets

  2. Inserisci l'intent in linguaggio naturale da aggiungere alla sfaccettatura.

  3. Inserisci lo snippet SQL corrispondente nella sfaccettatura.

  4. Rivedi 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 del set di contesto, ad esempio my-cluster-psc-primary_postgres_context_set_20251104111122.json, viene salvato nella directory in cui hai eseguito i comandi.

Generare query di ricerca di valori

Per generare ricerche di valori che specificano in che modo il sistema cerca e trova corrispondenze per valori specifici all'interno di un tipo di concetto, utilizza il comando /generate_targeted_value_searches.

Per saperne di più sull'indice di valore, consulta la Panoramica dei set di contesto.

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

Per generare un indice di valori, completa i seguenti passaggi:

  1. Esegui il comando /generate_targeted_value_searches:

    /generate_targeted_value_searches

  2. Inserisci mysql per selezionare MySQL come motore del database. Seleziona il valore predefinito per selezionare MySQL 8.0.

  3. 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 da 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, prepara il tuo database in modo che supporti 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, prepara il tuo database per supportare i vector embedding.

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

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

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

Il file del set di contesto, ad esempio my-cluster-psc-primary_postgres_context_set_20251104111122.json, viene salvato nella directory in cui hai eseguito i comandi.

Passaggi successivi