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.

Un set di contesti è una raccolta di informazioni specifiche del database che consente a strumenti come QueryData di generare query con elevata precisione. Il set di contesti 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

Che cosa sono i set di contesti

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

Definisci il contesto nei file che contengono oggetti JSON per ogni tipo di contesto. Crea questi file di contesto con l'aiuto di Gemini CLI. Poi carica il file di contesto in un set di contesti che crei nella Google Cloud console. Questo processo consente a strumenti come 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"
    }
   ]
}

Formato del file del set di contesti

Il file del set di contesti è costituito da un insieme curato di modelli e sfaccettature in formato JSON che guidano strumenti come 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 contesti sia accurato e completo nella copertura delle query dell'applicazione previste.

I set di contesti 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 strumenti come 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 parametrizzata.

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 i filtri e le condizioni, consentendo ai modelli di query di eseguire ricerche sfaccettate.

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

Query di ricerca di valori

Le [query di ricerca di valori](/alloydb/docs/ai/build-context-gemini-cli#generate-value-searches) sono query definite dallo sviluppatore che utilizzano le 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 di ortografia.

L'API QueryData utilizza il collegamento dei valori per convertire con maggiore precisione il linguaggio naturale in SQL. 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.

Di seguito è riportato 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 parametrizzata che definisce la logica per la corrispondenza di una frase di valore con i valori memorizzati 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, gli strumenti come l'API QueryData a comprendere il ruolo della frase di valore nello schema. Consente inoltre di produrre un'istruzione SQL che targetizza il concetto per il valore, nonché la tabella e la colonna in cui viene visualizzata la frase di valore.
• description: una descrizione della logica di ricerca.

Limitazioni

I set di contesti presentano le seguenti limitazioni:

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

Passaggi successivi

• Scopri come creare o eliminare un set di contesti in AlloyDB Studio.