Generare query SQL utilizzando domande in linguaggio naturale

Questa pagina descrive come configurare e generare istruzioni SQL utilizzando il linguaggio naturale di AlloyDB AI. Il linguaggio naturale ti consente di creare applicazioni di AI generativa rivolte agli utenti utilizzando il linguaggio naturale per eseguire query sui database.

Per abilitare l'estensione alloydb_ai_nl, che è l'API di supporto del linguaggio naturale di AlloyDB per PostgreSQL, segui i seguenti passaggi di alto livello:

  1. Installa l'estensione alloydb_ai_nl.
  2. Definisci una configurazione in linguaggio naturale per la tua applicazione.
  3. Registra uno schema.
  4. Aggiungi contesto.
  5. Aggiungi modelli di query.
  6. Definisci i tipi di concetti e crea un indice dei valori.
  7. Genera istruzioni SQL utilizzando un'interfaccia basata su linguaggio naturale.

Prima di iniziare

Crea un cluster e abilita l'integrazione di Vertex AI

  1. Crea un cluster e un'istanza AlloyDB. Utilizzi l'istanza AlloyDB per creare il database dell'applicazione e lo schema.
  2. Attiva l'integrazione di Vertex AI. Per ulteriori informazioni, consulta Integrazione con Vertex AI.

Ruoli obbligatori

Per installare l'estensione alloydb_ai_nl e concedere l'accesso ad altri utenti, devi disporre del seguente ruolo IAM (Identity and Access Management) nel progetto Google Cloud che stai utilizzando:

Per maggiori informazioni, vedi Gestire gli utenti PostgreSQL con l'autenticazione integrata.

prepara l'ambiente

Per prepararti a generare query in linguaggio naturale, devi installare l'estensione richiesta, creare una configurazione e registrare uno schema.

Installa l'estensione alloydb_nl_ai

L'estensione alloydb_ai_nl utilizza l'estensione google_ml_integration, che interagisce con modelli linguistici di grandi dimensioni (LLM), inclusi i modelli Gemini su Vertex AI.

Per installare l'estensione alloydb_ai_nl, connettiti al database ed esegui il seguente comando:

CREATE EXTENSION alloydb_ai_nl cascade;

Crea una configurazione in linguaggio naturale e registra uno schema

Il linguaggio naturale di AlloyDB AI utilizza nl_config per associare le applicazioni a determinati schemi, modelli di query ed endpoint del modello. nl_config è una configurazione che associa un'applicazione a schemi, modelli e altri contesti. Un'applicazione di grandi dimensioni può anche utilizzare configurazioni diverse per le diverse parti dell'applicazione, a condizione che tu specifichi la configurazione corretta quando viene inviata una domanda da quella parte dell'applicazione. Puoi registrare un intero schema oppure oggetti di schema specifici, come tabelle, viste e colonne.

  1. Per creare una configurazione in linguaggio naturale, utilizza il seguente esempio:

    SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );

    gemini-2.0-flash:generateContent è l'endpoint del modello.

  2. Per registrare uno schema per una configurazione specificata, utilizza il seguente esempio:

    SELECT
  alloydb_ai_nl.g_manage_configuration(
    operation => 'register_schema',
    configuration_id_in => 'my_app_config',
    schema_names_in => '{my_schema}'
  );

Aggiungi contesto

Il contesto include qualsiasi tipo di informazione che puoi utilizzare per rispondere a una domanda dell'utente finale. Il contesto include la struttura e le relazioni dello schema, i riepiloghi e le descrizioni di colonne, valori delle colonne e relativa semantica, nonché regole o istruzioni della logica di business specifiche per l'applicazione o il dominio.

Aggiungere un contesto generale per le regole specifiche per l'applicazione

Gli elementi di contesto generali includono regole specifiche dell'applicazione, istruzioni di logica aziendale o qualsiasi terminologia specifica dell'applicazione e del dominio che non è collegata a un oggetto schema specifico.

Per aggiungere un contesto generale per le regole specifiche dell'applicazione e la terminologia specifica dell'applicazione o del dominio, segui questi passaggi:

  1. Per aggiungere un elemento di contesto generale per la configurazione specificata, utilizza il seguente esempio:

    SELECT
  alloydb_ai_nl.g_manage_configuration(
    'add_general_context',
    'my_app_config',
    general_context_in => '{"If the user asks for a good seat, assume that means a window or aisle seat."}'
  );

    La precedente istruzione aiuta l'AI di AlloyDB in linguaggio naturale a fornire risposte di qualità superiore alle domande in linguaggio naturale degli utenti.

  2. Per visualizzare i contesti generali per la configurazione specificata, esegui la seguente istruzione:

    SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);

Generare e rivedere il contesto dello schema

Il contesto dello schema descrive gli oggetti dello schema, tra cui tabelle, viste, viste materializzate e colonne. Questo contesto viene memorizzato come COMMENT di ogni oggetto schema.

  1. Per generare contesti per gli oggetti schema, chiama le seguenti API. Per ottenere risultati ottimali, assicurati che le tabelle del database contengano dati rappresentativi.

    -- For all schema objects (tables, views, materialized views and columns)
-- within the scope of a provided nl_config.
SELECT
  alloydb_ai_nl.generate_schema_context(
    'my_app_config' -- nl_config
  );

  2. Esamina i contesti dello schema generati eseguendo la seguente istruzione:

    SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;

    I contesti dello schema generato vengono memorizzati nella visualizzazione precedente.

  3. (Facoltativo) Per aggiornare i contesti dello schema generati, esegui la seguente istruzione:

    SELECT
  alloydb_ai_nl.update_generated_relation_context(
    'my_schema.my_table',
    'This table contains archival records, if you need latest records use records_new table.'
  );

SELECT
  alloydb_ai_nl.update_generated_column_context(
    'my_schema.my_table.column1',
    'The seat_class column takes single letters like "E" for economy, "P" for premium economy, "B" for business and "F" for First.'
  );

  4. Applica il contesto. Quando applichi il contesto, questo ha effetto immediatamente e viene eliminato da generated_schema_context_view. Esegui questo comando:

    -- For all schema objects (tables, views, materialized views and columns)
-- within the scope of nl_config.
SELECT
  alloydb_ai_nl.apply_generated_schema_context(
    'my_app_config' --nl_config
  );

  5. (Facoltativo) Verifica il contesto generato. La seguente API ti consente di controllare i contesti dello schema, che vengono utilizzati quando generi istruzioni SQL:

    -- For table, view or materialized view.
SELECT
  alloydb_ai_nl.get_relation_context(
    'my_schema.my_table'
  );

-- For column.
SELECT
  alloydb_ai_nl.get_column_context(
    'my_schema.my_table.column1'
  );

  6. (Facoltativo) Per impostare manualmente il contesto dello schema, esegui la seguente istruzione:

    -- For table, view or materialized view.
SELECT
  alloydb_ai_nl.set_relation_context(
    'my_schema.my_table',
    'One-to-many mapping from product to categories'
  );

-- For column.
SELECT
  alloydb_ai_nl.set_column_context(
    'my_schema.my_table.column1',
    'This column provides additional tagged info for the product in  Json format, e.g., additional color or size information of the product - tags: { "color": "red", "size": "XL"}'
  );

Creare modelli di query

Per migliorare la qualità delle applicazioni di AI generativa create con gli LLM, puoi aggiungere modelli. Un modello di query è un insieme curato di domande in linguaggio naturale rappresentative o comuni, con le query SQL corrispondenti, nonché spiegazioni per fornire una motivazione dichiarativa per la generazione da linguaggio naturale a SQL (NL2SQL). I modelli sono pensati principalmente per essere specificati dall'applicazione, ma possono anche essere generati automaticamente dall'estensione alloydb_ai_nl in base alle query SQL utilizzate di frequente. Ogni modello deve essere associato a un nl_config.

L'estensione alloydb_ai_nl utilizza un template_store per incorporare dinamicamente modelli SQL pertinenti nel processo di generazione di un'istruzione SQL per rispondere alla domanda dell'utente. template_store identifica i modelli con intenzioni simili alla domanda in linguaggio naturale posta, identifica l'istruzione SQL con parametri corrispondente e sintetizza un'istruzione SQL istanziando i parametri con i valori della domanda in linguaggio naturale. Tuttavia, se non esiste un template con lo stesso intento della domanda posta dall'utente, alloydb_ai_nl utilizza ogni template e contesto pertinente per comporre un'istruzione SQL.

Per aggiungere modelli, specifica la domanda utilizzando un parametro denominato intent e la query SQL.

Per aggiungere un modello al negozio di modelli, esegui la seguente istruzione:

SELECT
  alloydb_ai_nl.add_template(
    nl_config => 'my_app_config',
    intent => 'How many accounts associated with loans are located in the Prague region?',
    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''',
    check_intent => TRUE
  );

Quando check_intent è TRUE, alloydb_ai_nl esegue un controllo semantico per verificare che l'intent fornito corrisponda all'istruzione SQL trasmessa. Se l'intent non corrisponde all'istruzione SQL, il modello non viene aggiunto.

Generare automaticamente i modelli

Una volta che le tabelle contengono un set di dati rappresentativo, ti consigliamo di eseguire query SQL che corrispondono alle domande comuni che gli utenti finali probabilmente porranno. È importante assicurarsi che le query abbiano buoni piani di query e che funzionino bene.

Dopo aver eseguito le query, il linguaggio naturale di AlloyDB AI può generare automaticamente modelli in base alla cronologia delle query. Puoi chiamare le seguenti API per generare modelli. Devi esaminare e applicare i modelli generati prima che abbiano effetto.

La generazione automatica dei modelli si basa sulle query più utilizzate nel log delle query, google_db_advisor_workload_statements. Le query vengono filtrate in base ai seguenti criteri:

  • SELECT istruzioni
  • Eseguibili: il comando EXPLAIN elabora correttamente la query.
  • Nessuna duplicazione: la query non è stata utilizzata in precedenza per generare modelli.
  • Tutte le tabelle e le viste a cui viene fatto riferimento rientrano nell'ambito di nl_config.

Per generare, rivedere e applicare automaticamente i modelli:

  1. Richiedi ad AlloyDB di generare modelli in base alla cronologia delle query:

    SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);

    Utilizza la visualizzazione fornita, alloydb_ai_nl.generated_templates_view, per esaminare generated_templates.

    L'output seguente mostra il numero di modelli generati:

    -[ RECORD 1 ]------+--
generate_templates | 1

  2. Rivedi i modelli generati utilizzando la visualizzazione generated_templates_view.

    SELECT *
FROM alloydb_ai_nl.generated_templates_view;

    Di seguito è riportato un esempio di output restituito:

    -[ RECORD 1 ]----------------------------------------------------------------
id          | 1
config      | my_app_config
type        | Template
manifest    | How many clients have a birth year of a given number?
nl          | How many clients have a birth year of 1997?
sql         | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = '1997';
intent      | How many clients have a birth year of 1997?
psql        | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = $1;
pintent     | How many clients have a birth year of $1?
comment     |
explanation |
weight      | 1

    manifest nell'output restituito è un modello generale o una descrizione generica del tipo di domanda o dell'operazione che può essere eseguita. pintent è una versione parametrizzata di intent e generalizza intent sostituendo il valore specifico (1997) con un segnaposto ($1).

  3. Per aggiornare un modello generato, esegui la seguente istruzione di esempio:

    SELECT alloydb_ai_nl.update_generated_template(
  id => 1,
  manifest => 'How many clients are born in a given year?',
  nl => 'How many clients are born in 1997?',
  intent => 'How many clients are born in 1997?',
  pintent => 'How many clients are born in $1?'

);

  4. Applica i modelli. I modelli che applichi vengono aggiunti immediatamente allo store dei modelli ed eliminati dalla visualizzazione della revisione.

    -- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');

Configurare la sicurezza per il linguaggio naturale

Per configurare la sicurezza per il linguaggio naturale di AlloyDB AI, vedi Gestire la sicurezza delle applicazioni di dati utilizzando viste sicure parametrizzate.

Definisci i tipi di concetti e l'indice dei valori

Definisci i tipi di concetti e gli indici di valore per comprendere meglio le domande poste. Un tipo di concetto è una categoria o una classe di entità che identifica il significato semantico di parole e frasi anziché solo la loro forma letterale.

Ad esempio, due nomi di paesi potrebbero essere uguali anche se uno è in maiuscolo, ad esempio USA, e l'altro è in minuscolo, ad esempio usa. In questo caso, il nome del paese è il tipo di concetto. Altri esempi di tipi di concetti includono nome della persona, nome della città e data.

Un indice di valori è un indice basato sui valori delle colonne che fanno parte della configurazione del linguaggio naturale nl_config, in base ai tipi di concetti associati a ciascuna colonna. Un indice dei valori consente di trovare in modo efficiente le frasi di valore per la domanda posta e i valori nel database.

Per definire i tipi di concetti e un indice dei valori, segui questi passaggi utilizzando gli esempi forniti. Gli esempi associano una colonna a un tipo di concetto, creano e aggiornano un indice dei valori e utilizzano un insieme di sinonimi per eseguire una ricerca di valori.

  1. Per associare una colonna a un tipo di concetto, esegui questa query:

    SELECT
  alloydb_ai_nl.associate_concept_type(
    column_names_in => 'my_schema.country.country_name',
    concept_type_in => 'country_name',
    nl_config_id_in => 'my_app_config'
  );

  2. Per creare un indice di valori basato su tutte le colonne che fanno parte di una configurazione in linguaggio naturale e sono associate a un tipo di concetto, esegui la seguente istruzione:

    SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );

  3. Quando associ i tipi di concetti a nuove colonne, aggiorna l'indice dei valori per riflettere le modifiche. Utilizza la seguente istruzione:

    SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );

  4. Per consentire al linguaggio naturale di AlloyDB AI di trovare i sinonimi di un valore, esegui la seguente istruzione di esempio:

    SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );

    Anche se i dati nelle tabelle potrebbero utilizzare un valore specifico, ad esempio se United States viene utilizzato per identificare un paese, puoi definire un insieme di sinonimi che contenga tutti i sinonimi di United States. Se uno dei sinonimi viene visualizzato nella domanda in linguaggio naturale, l'AI di AlloyDB in linguaggio naturale associa i sinonimi ai valori nelle tabelle.

  5. Esegui una ricerca di valori per trovare i valori di database corretti, dato un array di frasi di valori, utilizzando la seguente istruzione:

    SELECT
  alloydb_ai_nl.get_concept_and_value(
    value_phrases_in => ARRAY['United States'],
    nl_config_id_in  => 'my_app_config'
  );

    Ad esempio, se un utente pone una domanda come "Qual è la popolazione degli Stati Uniti?" che utilizza la seguente query get_sql, l'AI di AlloyDB in linguaggio naturale utilizza la funzione get_concept_and_value con la frase di valore United States per eseguire una ricerca fuzzy negli indici dei valori. Una ricerca approssimativa è una tecnica di ricerca che trova corrispondenze anche quando la query di ricerca non corrisponde esattamente ai relativi dati.

    Il linguaggio naturale trova un risultato, il valore USA, vicino alla query di ricerca e lo utilizza per generare la query SQL.

    SELECT
  alloydb_ai_nl.get_sql(
    nl_config_id    => 'my_app_config',
    nl_question     => 'What is the population of the United States?',
    additional_info => json_build_object('enrich_nl_question', TRUE)
  ) ->> 'sql';

    La tabella seguente elenca i tipi di concetti integrati definiti dal linguaggio naturale di AlloyDB AI:

    Nome del concept Descrizione
    generic_entity_name Una singola colonna di tipo stringa può essere utilizzata per un nome di entità generico. Ad esempio:
      SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
    country_name, city_name, region_name Nomi di paesi, città e regioni. L'utilizzo è esattamente lo stesso del tipo di concetto generic_entity_name.
    full_person_name Il nome della persona, composto da nome, cognome e secondo nome. È possibile utilizzare fino a tre colonne di tipo stringa per il nome completo di una persona. È possibile saltare una qualsiasi delle colonne durante l'associazione delle colonne dei nomi a full_person_name. Ad esempio:
      SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
    ssn Una singola colonna di stringhe contenente un codice fiscale. Ad esempio:
      SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
    date Una data o un timestamp. Ad esempio:
     SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

Generare istruzioni SQL da input in linguaggio naturale

Puoi utilizzare il linguaggio naturale di AlloyDB AI per generare istruzioni SQL dagli input in linguaggio naturale. Quando esegui l'istruzione SQL generata, vengono forniti i dati del database necessari per rispondere alla domanda in linguaggio naturale.

  1. Per utilizzare il linguaggio naturale per ottenere risultati dal database utilizzando la funzione alloydb_ai_nl.get_sql, utilizza il seguente esempio:

    SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  );

    Viene restituito il seguente output JSON:

    {
  "sql": "SELECT T3.balance FROM public.client AS T1 INNER JOIN public.account AS T2 ON T1.district_id = T2.district_id INNER JOIN public.trans AS T3 ON T2.account_id = T3.account_id WHERE T1.client_id = 4 AND T3.trans_id = 851",
  "prompt": "",
  "retries": 0,
  "error_msg": "",
  "nl_question": "What is the sum that client number 4's account has following transaction 851?"
}

  2. (Facoltativo) Per estrarre la query SQL generata come stringa di testo, aggiungi ->>'sql':

    SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  ) ->> 'sql';

    L'operatore ->> viene utilizzato per estrarre un valore JSON come testo. La funzione alloydb_ai_nl.get_sql restituisce un oggetto JSON, ovvero la parte dell'istruzione che recupera il valore associato alla chiave sql. Questo valore è la query SQL generata.

Testare e perfezionare

Per ottenere query generate automaticamente migliori, modifica o aggiungi un contesto migliore, modelli di query e indici di valori, quindi esegui iterazioni finché non ottieni i risultati che desideri.

Passaggi successivi