Panoramica dei set di contesti

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.

Nota sull'interfaccia PostgreSQL: Gli esempi in questo argomento sono destinati ai database di dialetto GoogleSQL. Questa funzionalità non supporta l'interfaccia PostgreSQL.

I set di contesto ti consentono di interagire con i dati nel database utilizzando un linguaggio conversazionale e vengono utilizzati da strumenti come QueryData per creare agenti conversazionali. 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 tuoi casi d'uso target.

Un insieme 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 tue 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 richieste ad alto volume come "Dov'è il mio ordine?" o "Qual è il mio saldo attuale?".
• Assistenti per lo shopping e-commerce: aiutano gli utenti a navigare in cataloghi di prodotti di grandi dimensioni con query in linguaggio naturale come "Mostrami scarpe da corsa sotto i 100 $".
• Strumenti per le operazioni sul campo: consentono ai dipendenti mobili di eseguire query in tempo reale sui livelli di inventario, sulla disponibilità dei pezzi 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. Fornisci queste informazioni sotto forma di insieme di contesto.

Definisci il contesto in file che contengono oggetti JSON per ogni tipo di contesto. Questi file di contesto vengono creati con l'aiuto di Gemini CLI. Quindi, carica il file di contesto in un insieme di contesti che crei nella console Google Cloud. 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 controllati dallo sviluppatore che cura il contesto. Una volta identificata una corrispondenza, QueryData utilizza il modello di query e i facet selezionati per sintetizzare una query del database. La logica del 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 LLM si basa sui tuoi dati effettivi, il che lo aiuta a risolvere le ambiguità, ad esempio se un termine si riferisce a un nome di District o a un 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 memorizzati nelle colonne del database. In questo modo, l'LLM si basa sui tuoi dati effettivi, il che lo aiuta a risolvere le ambiguità, ad esempio se un termine si riferisce a un District, a un Name o a un City.

L'endpoint QueryData nell'API Analisi conversazionale è uno strumento agentico che consente l'integrazione programmatica con le tue applicazioni per consentire 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.

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.

Assicurati che il contesto impostato sia accurato e completo nella copertura delle query dell'applicazione previste per massimizzare l'accuratezza.

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 selezionato 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: Lo scopo o la finalità della query in linguaggio naturale. Se non viene impostato, questo valore corrisponde per impostazione predefinita alla query in linguaggio naturale.
• manifest: una forma generalizzata e generata automaticamente dell'intent.
• parameterized_intent: una forma predefinita e generata automaticamente dell'intent, con i valori delle entità sostituiti dai parametri.
• parameterized_sql: una forma con modello e generata automaticamente della query SQL che corrisponde all'intent con parametri.

Facet di query

I facet di query sono un insieme curato di condizioni rappresentative in linguaggio naturale con predicati SQL corrispondenti. I facet gestiscono i filtri e le condizioni, il che consente ai modelli di query di eseguire ricerche per facet.

Un oggetto sfaccettatura della 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 sfaccettatura sono i seguenti:

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

Query di ricerca dei valori

Le query di ricerca di valori sono query definite dagli sviluppatori che utilizzano funzioni di corrispondenza per trovare 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 ortografici.

L'API QueryData utilizza il collegamento dei valori per convertire in modo più accurato il linguaggio naturale in SQL. Utilizzando le query di ricerca dei valori, l'API può correggere gli errori ortografici e risolvere i tipi di valori in base ai valori del database, migliorando così l'accuratezza delle conversioni.

Il collegamento dei valori migliora l'accuratezza 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 "Londra 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 dei valori guidano l'agente a mappare "Heathrow" al valore corretto del database "London Heathrow" e alla sua posizione dello schema (airports.name), garantendo che l'SQL generato sia accurato.

Una query di ricerca di valori di esempio è:

{
  ...
  "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"
    }
  ]
}

I componenti principali dell'oggetto JSON di ricerca dei 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 di 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 (compresa 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, in definitiva, l'API QueryData a comprendere il ruolo della frase di valore nello schema. Inoltre, aiuta a 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 del valore.
• description: una descrizione della logica di ricerca.

Limitazioni

I set di contesto presentano le seguenti limitazioni:

• I set di contesto per i database supportano solo modelli, facet e ricerche di valori.
• I set di contesto per i database vengono utilizzati solo dall'endpoint QueryData nell'API Analisi conversazionale.

Avviso: tutti i contesti degli agenti associati a un database sono visibili a tutti gli utenti con accesso in lettura al database. Nei casi in cui gli utenti hanno un accesso più limitato al database, ad esempio controllo dell'accesso granulare di Spanner, possono potenzialmente scoprire altri campi e tabelle dal contesto dell'agente.

Passaggi successivi

• Scopri come creare o eliminare un insieme di contesto in Spanner Studio.