Panoramica dei set di contesti

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.

I set di contesto ti consentono di interagire con i dati nel database utilizzando il linguaggio conversazionale e vengono utilizzati da strumenti come QueryData per creare agenti di conversazione. Puoi creare set di contesto definendo il contesto per un insieme di tabelle nel database. Questo contesto consente a QueryData di tradurre le domande in linguaggio naturale in query accurate per i casi d'uso di destinazione.

Un set di contesto è una raccolta di informazioni specifiche del database che consente a QueryData di generare query con elevata precisione. Il set di contesto include modelli, sfaccettature e ricerche di valori che aiutano QueryData a comprendere lo schema del database e la logica di business delle applicazioni.

Sono supportati i seguenti database:

• AlloyDB per PostgreSQL
• Cloud SQL per MySQL
• Cloud SQL per PostgreSQL
• Spanner

Quando utilizzare i set di contesto

Puoi utilizzare i set di contesto per creare applicazioni di dati conversazionali ideali per casi d'uso come:

• Automazione del servizio clienti: gestisci le richieste di alto volume come "Dov'è il mio ordine?" o "Qual è il mio saldo attuale?".
• Assistenti per lo shopping e-commerce: aiuta gli utenti a navigare in cataloghi di prodotti di grandi dimensioni con query in linguaggio naturale come "Mostrami le scarpe da corsa sotto i 100 €".
• Strumenti per le operazioni sul campo: consente ai dipendenti in mobilità di eseguire query in tempo reale sui livelli di inventario , sulla disponibilità dei componenti o sui dettagli dei ticket di assistenza.

Come funzionano i set di contesto

Per creare applicazioni agentiche efficaci, QueryData deve comprendere l'organizzazione dei dati e la logica di business. Queste informazioni vengono fornite sotto forma di set di contesto.

Definisci il contesto nei file che contengono oggetti JSON per ogni tipo di contesto. Crea questi file di contesto con l'aiuto dell'interfaccia a riga di comando di Gemini. Poi carica il file di contesto in un set di contesto creato nella Google Cloud console. Questo processo consente a QueryData di apprendere lo schema specifico del database e la logica di business dell'applicazione.

Il file di contesto è simile al seguente:

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

Quando un utente finale pone una domanda in linguaggio naturale, QueryData assegna la priorità alla corrispondenza della domanda con i modelli e le sfaccettature sottoposti a revisione dallo sviluppatore che cura il contesto. Una volta identificata una corrispondenza, QueryData utilizza il modello di query e le sfaccettature selezionati per sintetizzare una query di database. La logica del set di contesto esegue quindi la query sul database per restituire risultati accurati.

Un passaggio consigliato è definire le ricerche di valori all'interno del contesto. Le ricerche di valori consentono all'agente di mappare le frasi di valori a valori specifici archiviati nelle colonne del database. In questo modo, il modello linguistico di grandi dimensioni si basa sui dati effettivi, il che aiuta a risolvere le ambiguità, ad esempio se un termine si riferisce a un nome di District o a una City.

Se l'agente non riesce a trovare un modello corrispondente, utilizza le ricerche di valori per mappare le frasi in linguaggio naturale a valori specifici archiviati nelle colonne del database. In questo modo, il modello linguistico di grandi dimensioni si basa sui dati effettivi, il che aiuta a risolvere le ambiguità, ad esempio se un termine si riferisce a un District, a un Name o a una City.

L'endpoint QueryData nell'API Analisi conversazionale è uno strumento agentico che consente l'integrazione programmatica con le applicazioni per abilitare la generazione di query SQL da domande in linguaggio naturale. In un'applicazione conversazionale, l'endpoint QueryData deve essere utilizzato all'interno del framework che gestisce la cronologia e il contesto della conversazione.Per applicare la risoluzione delle entità mantenendo una rigorosa sicurezza a livello di riga, puoi utilizzare le viste sicure con parametri (PSV). Per ulteriori informazioni, consulta Proteggere e controllare l'accesso ai dati delle applicazioni utilizzando le viste sicure con parametri

File del set di contesto

Il file del set di contesto è costituito da un insieme curato di modelli e sfaccettature in formato JSON che guidano QueryData nella traduzione di domande in linguaggio naturale in query per un database specifico. La definizione del contesto garantisce una generazione SQL di alta precisione per i pattern di query comuni.

Per massimizzare la precisione, assicurati che il set di contesto sia accurato e completo nella copertura delle query dell'applicazione previste.

I set di contesto possono essere creati nelle regioni us-central1, us-east1, europe-west4 e asia-southeast1.

Modelli di query

I modelli di query sono un insieme curato di domande rappresentative in linguaggio naturale con le query SQL corrispondenti. Includono anche spiegazioni per fornire una logica dichiarativa per la generazione da linguaggio naturale a SQL.

Un oggetto modello di query è simile al seguente:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ]
},
...

I componenti principali dell'oggetto JSON del modello di query sono i seguenti:

• nl_query: un esempio di query in linguaggio naturale gestita da QueryData.
• sql: la query SQL per la query in linguaggio naturale.
• intent: l'obiettivo o lo scopo della query in linguaggio naturale. Se non è impostato, questo valore viene impostato per impostazione predefinita sulla query in linguaggio naturale.
• manifest: una forma generalizzata e generata automaticamente dell'intenzione.
• parameterized_intent: una forma con modello e generata automaticamente dell'intenzione, con i valori delle entità sostituiti dai parametri.
• parameterized_sql: una forma con modello e generata automaticamente della query SQL che corrisponde all'intenzione con parametri.

Sfaccettature delle query

Le sfaccettature delle query sono un insieme curato di condizioni rappresentative in linguaggio naturale con i predicati SQL corrispondenti. Le sfaccettature gestiscono il filtraggio e le condizioni, il che consente ai modelli di query di eseguire ricerche con sfaccettature.

Un oggetto sfaccettatura di query è simile al seguente:

{
...
"facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

I componenti principali dell'oggetto JSON della sfaccettatura sono i seguenti:

• sql_snippet: uno snippet SQL.
• intent: una spiegazione del predicato SQL.
• manifest: una forma generalizzata e generata automaticamente dell'intenzione.
• parameterized_intent: una forma con modello e generata automaticamente dell'intenzione, con i valori delle entità sostituiti dai parametri.
• parameterized_sql_snippet: una forma con modello e generata automaticamente di sql_snippet che corrisponde all'intenzione con parametri.

Query di ricerca di valori

Le query di ricerca di valori sono query definite dallo sviluppatore che utilizzano le funzioni di corrispondenza per trovare i valori e il relativo contesto all'interno di un database. Il collegamento dei valori utilizza i risultati di queste query per identificare le tabelle e le colonne che contengono un valore corrispondente, comprendere il tipo di concetto del valore e correggere gli errori di ortografia.

L'API QueryData utilizza il collegamento dei valori per convertire il linguaggio naturale in SQL con maggiore precisione. Utilizzando le query di ricerca di valori, l'API può correggere gli errori di ortografia e risolvere i tipi di valori in base ai valori del database, migliorando così la precisione della conversione.

Il collegamento dei valori migliora la precisione della conversione da linguaggio naturale a SQL. Ad esempio, se un utente chiede "Ci sono voli in partenza da Heathrow?", il database potrebbe memorizzare il nome dell'aeroporto come "London Heathrow". Senza il collegamento dei valori, l'SQL generato potrebbe filtrare in base a WHERE name = 'Heathrow' e non restituire risultati. Le query di ricerca di valori guidano l'agente a mappare "Heathrow" al valore corretto del database "London Heathrow" e alla relativa posizione dello schema (airports.name), garantendo che l'SQL generato sia accurato.

Un esempio di query di ricerca di valori è:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

I componenti principali dell'oggetto JSON di ricerca di valori sono i seguenti:

• query: un'istruzione SQL con parametri che definisce la logica per la corrispondenza di una frase di valori con i valori archiviati in una colonna di una tabella in un database. Il set di risultati in genere proietta il valore corrispondente, la posizione dello schema, il tipo di concetto e una metrica di distanza normalizzata (tra 0 e 1).
• concept_type: un'etichetta semantica assegnata al valore, ad esempio district o loan_status. Questa etichetta aiuta il collegamento dei valori e, infine, l'API QueryData a comprendere il ruolo della frase di valori nello schema. Consente inoltre di produrre un'istruzione SQL che ha come target il concetto per il valore, nonché la tabella e la colonna in cui viene visualizzata la frase di valori.
• description: una descrizione della logica di ricerca.

Limitazioni

I set di contesto presentano le seguenti limitazioni:

• Cloud SQL per SQL Server non è supportato.
• I set di contesto per i database supportano solo modelli, sfaccettature e ricerche di valori.
• I set di contesto per i database vengono utilizzati solo dall'endpoint QueryData nell'API Analisi conversazionale.

Passaggi successivi

• Scopri come creare o eliminare un set di contesto in Cloud SQL Studio.