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

  • Scopri come connetterti al database AlloyDB ed eseguire i comandi PostgreSQL. Per saperne di più, vedi Panoramica della connessione.
  • Popola il database con i dati e lo schema a cui l'utente finale vuole accedere.

Attiva l'estensione richiesta

Prima di poter installare e utilizzare il linguaggio naturale di AlloyDB AI, devi abilitare l'estensione aggiungendo il flag alloydb_ai_nl.enabled. Per saperne di più, consulta Configurare i flag di database di un'istanza.

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

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;

Esegui l'upgrade dell'estensione alloydb_ai_nl

Assicurati di avere l'ultima versione dell'estensione alloydb_ai_nl. Se hai già installato l'estensione, controlla se è disponibile una nuova versione e aggiornala se non utilizzi l'ultima versione. Per saperne di più sull'estensione alloydb_ai_nl, consulta la panoramica del linguaggio naturale di AlloyDB AI.

  1. Determina se devi eseguire l'upgrade dell'estensione. Se la default_version è successiva alla installed_version, esegui l'upgrade dell'estensione.

    SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';

  2. Esegui l'upgrade dell'estensione.

    ALTER EXTENSION alloydb_ai_nl UPDATE;

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. Registra uno schema per una configurazione specificata utilizzando 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, ad esempio:

  • Struttura e relazioni dello schema
  • Riepiloghi e descrizioni delle colonne
  • Valori delle colonne e relativa semantica
  • Regole o istruzioni di 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, esegui la seguente query:

    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 query seguente:

    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 query:

    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) Aggiorna i contesti dello schema generati.

    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 dalla visualizzazione generated_schema_context_view.

    -- 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 durante la generazione delle 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) Imposta manualmente il contesto dello schema.

    -- 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 finale. template_store esegue le seguenti operazioni:

  • Identifica i modelli con intenzioni simili alla domanda in linguaggio naturale posta dall'utente finale.
  • Identifica l'istruzione SQL con parametri corrispondente.
  • Sintetizza un'istruzione SQL istanziando i parametri con i valori della domanda in linguaggio naturale.

Se non esiste un modello con lo stesso intento della domanda posta dall'utente finale, alloydb_ai_nl utilizza ogni modello e contesto pertinente per comporre un'istruzione SQL.

Aggiungere un modello al negozio di modelli

Aggiungi i modelli specificando la domanda, utilizzando un parametro denominato intent, e la query SQL.

Per aggiungere un modello all'archivio dei modelli, esegui la seguente query:

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => '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.

L'SQL e l'intent sono parametrizzati da alloydb_ai_nl. La visualizzazione alloydb_ai_nl.template_store_view mostra le istruzioni SQL parametrizzate e i relativi intent.

SELECT psql
FROM alloydb_ai_nl.template_store_view
WHERE intent = 'How many accounts associated with loans are located in the Prague region?';

Questa istruzione restituisce quanto segue:

SELECT COUNT(T1.account_id)
FROM account AS T1 INNER JOIN loan AS T2
  ON T1.account_id = T2.account_id
INNER JOIN district AS T3
  ON T1.district_id = T3.district_id WHERE T3."A3" = $1

Fornire una parametrizzazione personalizzata

Per fornire una parametrizzazione personalizzata per un'istruzione SQL utilizzando l'interfaccia manuale della funzione add_template, esegui l'istruzione nell'esempio seguente:

SELECT
  alloydb_ai_nl.add_template(
     nl_config_id => 'my_app_config',
     intent => 'Among the accounts opened, how many customers born before 1950 resided in Slokolov at the time of account opening?',
     sql => $$SELECT COUNT(DISTINCT T2.client_id)
              FROM district AS T1 INNER JOIN client AS T2
                ON T1.district_id = T2.district_id
             INNER JOIN account AS T3 ON T2.client_id IN (
                   SELECT client_id FROM disp WHERE account_id = T3.account_id)
             WHERE to_char(T2.birth_date::timestamp, 'YYYY') < '1950'
               AND T1."A2" = 'Slokolov'$$,
  parameterized_sql => $$SELECT COUNT(DISTINCT T2.client_id)
                         FROM district AS T1 INNER JOIN client AS T2
                           ON T1.district_id = T2.district_id
                   INNER JOIN account AS T3 ON T2.client_id IN (
                         SELECT client_id FROM disp WHERE account_id = T3.account_id)
                   WHERE to_char(T2.birth_date::timestamp, 'YYYY') < $2
                     AND T1."A2" = $1$$,
  parameterized_intent => $$Among the accounts opened, how many customers born before $2 resided in $1 at the time of account opening?$$,
  manifest => $$Among the accounts opened, how many customers born before a given date resided in a given city at the time of account opening?$$,
  check_intent => TRUE);

Nella definizione precedente viene fornita la parametrizzazione dell'istruzione SQL. I parametri sono $1 e $2, rispettivamente, per Slokolov e 1950. Un manifest viene fornito come versione generalizzata dell'intent, in cui i valori dei valori letterali vengono sostituiti con descrizioni generiche dei valori.

In questo esempio, il valore di 1950 nell'intent viene sostituito con a given date e il valore di Slokolov viene sostituito nel manifest con a given city. Quando viene fornito un valore TRUE per l'argomento facoltativo check_intent , durante add_template viene eseguita una verifica dell'intent basata su LLM. Durante questo controllo, quando l'istruzione SQL fornita non acquisisce lo scopo e l'obiettivo dell'istruzione di intent fornita, add_template non riesce e il motivo viene fornito come output.

Nell'esempio seguente, lo scopo del modello, come indicato nell'intent, è recuperare l'ID account degli account associati al carico e che si trovano in una regione. L'istruzione SQL fornita restituisce il numero di account, anziché l'elenco degli ID account, come mostrato nell'esempio seguente.

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'List the account id for all accounts that associated with loans and are located in the Prague region.',
    sql => 'SELECT COUNT(T1.account_id)
            FROM account AS T1 INNER JOIN loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

Quando check_intent è impostato su TRUE, non puoi aggiungere il modello precedente al negozio di modelli. Se esegui l'istruzione precedente, viene restituito un errore simile al seguente:

ERROR:  Checking intent failed, for nl_question:List the account id for all accounts that associated with loans and are located in the Prague region...reason:The SQL query only counts the number of account IDs, but the question asks for a list of the account IDs.

Gestisci modelli

Puoi gestire i modelli nel negozio di modelli utilizzando le seguenti API:

-- To disable a template:
SELECT alloydb_ai_nl.disable_template(INPUT template_id);

-- To enable a template which has been disabled:
SELECT alloydb_ai_nl.enable_template(INPUT template_id);

-- To permanently remove a template:
SELECT alloydb_ai_nl.drop_template(INPUT template_id);

Quando crei un modello, questo è abilitato per impostazione predefinita. Un modello disattivato rimane nello store di modelli, ma non viene utilizzato da alloydb_ai_nl per la sintesi delle query. Puoi abilitare un modello disabilitato utilizzando alloydb_ai_nl.enable_template. L'esecuzione di alloydb_ai_nl.drop_template rimuove definitivamente il modello dallo store di modelli.

Puoi utilizzare alloydb_ai_nl.template_store_view per estrarre il template_id di un modello, dato il suo contenuto. Ad esempio, per trovare l'identificatore dei modelli che hanno l'intent accounts that associated with loans, esegui la seguente query, che restituisce un identificatore del modello e indica se il modello è abilitato da alloydb_ai_nl.template_store_view:

SELECT id, enabled
FROM alloydb_ai_nl.template_store_view
WHERE intent ILIKE '%accounts that associated with loans%';

Aggiornare un modello

Quando utilizzi i modelli in alloydb_ai_nl.template_store_view, assicurati che l'intento di ogni modello sia coerente con quanto segue:

  • L'istruzione SQL
  • L'istruzione SQL con parametri
  • L'intent con parametri
  • Il manifest del modello

alloydb_ai_nl può recuperare i modelli pertinenti se l'incorporamento mantenuto per i modelli corrisponde ai contenuti dei modelli.

Per aggiornare un modello:

  1. Identifica il template_id utilizzando alloydb_ai_nl.template_store_view.
  2. Rimuovi il modello.
  3. Ridefinisci il nuovo modello con la modifica richiesta utilizzando la funzione alloydb_ai_nl.add_template.

Creare frammenti di query

Puoi specializzare i modelli al momento della query utilizzando i frammenti, che aiutano i modelli di query a eseguire ricerche sfaccettate come le domande in linguaggio naturale. Un frammento è un insieme selezionato di condizioni in linguaggio naturale rappresentative o comuni con predicati SQL corrispondenti. I frammenti devono essere specificati dall'applicazione.

Ogni frammento deve essere associato a un nl_config_id e a un array di tabelle e viste con alias a cui si applica il predicato del frammento. Puoi verificare lo scopo di un frammento quando l'argomento check_intent è impostato su TRUE. L'estensione alloydb_ai_nl può utilizzare un modello con una combinazione di frammenti per sintetizzare la risposta a una query in linguaggio naturale.

L'estensione alloydb_ai_nl utilizza fragment_store per incorporare dinamicamente le condizioni in frammenti pertinenti durante la generazione di un'istruzione SQL per rispondere alla domanda dell'utente finale. Innanzitutto, template_store identifica i modelli con intenzioni simili alla domanda in linguaggio naturale posta dall'utente finale. Successivamente, vengono recuperati i frammenti che possono fornire una specializzazione ai modelli identificati. La sostituzione dei parametri viene applicata sia ai modelli sia ai frammenti per sintetizzare un'istruzione SQL.

I valori dei parametri vengono estratti dalla domanda in linguaggio naturale e vengono sostituiti dal LLM utilizzando i pattern impliciti dei modelli e dei frammenti pertinenti. Tuttavia, se la combinazione di modelli e frammenti non ha lo stesso scopo per la domanda posta dall'utente finale, alloydb_ai_nl utilizza ogni modello e contesto pertinente per comporre un'istruzione SQL.

Aggiungere un frammento

Per aggiungere un frammento, esegui le seguenti query di esempio utilizzando la funzione alloydb_ai_nl.add_fragment. Ogni frammento deve essere associato a un identificatore nl_config_id dell'applicazione.

-- A fragment that cannot be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['account AS T'],
  intent => 'Accounts with issuance after transaction',
  fragment => 'T.frequency = ''POPLATEK PO OBRATU''',
  check_intent => True);

-- A fragment that can be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['district AS T'],
  intent => 'Average salary between 6000 and 10000',
  fragment => 'T."A11" BETWEEN 6000 AND 10000',
  check_intent => True);

Quando viene eseguito alloydb_ai_nl.add_fragment, l'estensione alloydb_ai_nl estrae un manifest dall'intent fornito e parametrizza l'intent e la condizione per il frammento, se possibile. I frammenti disponibili vengono esposti da visualizzazioni come alloydb_ai_nl.fragment_store_view, come mostrato nell'esempio seguente:

SELECT manifest, scope, fragment, intent, pfragment, pintent
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = 'Average salary between 6000 and 10000';

La query restituisce un insieme di risultati simile al seguente:

manifest  | Average salary between a given number and a given number
scope     | district AS T
fragment  | T."A11" BETWEEN 6000 AND 10000
intent    | Average salary between 6000 and 10000
pfragment | T."A11" BETWEEN $2 AND $1
pintent   | Average salary between $2 and $1

Un manifest in un fragment viene generato automaticamente dall'intent e rappresenta una versione generalizzata dell'intent. Ad esempio, i numeri 6000 e 10000 nell'intent vengono sostituiti da a given number nel manifest. I numeri vengono sostituiti rispettivamente con $2 e $1 nelle colonne pfragment e pintent. Le colonne pfragment e pintent in alloydb_ai_nl.fragment_store_view sono, rispettivamente, la rappresentazione parametrizzata di fragment e intent.

Per fornire una parametrizzazione personalizzata di un frammento, utilizza la versione manuale di alloydb_ai_nl.add_fragment, come mostrato nell'esempio seguente:

SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['bird_dev_financial.district AS T'],
  intent => $$districts in 'Prague'$$,
  parameterized_intent => $$districts in $1$$,
  fragment => $$T."A3" = 'Prague'$$,
  parameterized_fragment => $$T."A3" = $1$$,
  manifest => $$districts in a given city$$,
  check_intent => TRUE);

Gestire i frammenti

Per gestire i frammenti, utilizza le seguenti API:

-- To disable a fragment:
SELECT alloydb_ai_nl.disable_fragment(INPUT fragment_id);

-- To enable a fragment which has been disabled:
SELECT alloydb_ai_nl.enable_fragment(INPUT fragment_id);

-- To permanently remove a fragment:
SELECT alloydb_ai_nl.drop_fragment(INPUT fragment_id);

Puoi utilizzare la visualizzazione alloydb_ai_nl.fragment_store_view per estrarre l'fragment_id di un frammento, dato il suo contenuto. Ad esempio, per trovare l'identificatore di un frammento con l'intent Average salary between 6000 and 10000, esegui la seguente query di esempio:

SELECT id
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = "Average salary between 6000 and 10000";

Aggiornare un frammento

Quando aggiorni un fragment, assicurati che l'intent del fragment sia coerente con quanto segue:

  • Il manifest e l'istruzione SQL del frammento
  • L'istruzione SQL con parametri
  • L'intent con parametri

Per garantire la coerenza quando aggiorni un frammento, segui questi passaggi:

  1. Rimuovi il frammento che vuoi modificare utilizzando la funzione alloydb_ai_nl.drop_fragment.
  2. Inserisci il frammento aggiornato utilizzando la funzione alloydb_ai_nl.add_fragment.

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. Assicurati che le query abbiano piani di query completi e che offrano un buon rendimento.

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 utilizzate più di frequente nel log delle query, google_db_advisor_workload_statements. Le query vengono filtrate in base ai seguenti criteri:

  • SELECT istruzioni
  • Eseguibili: la query può essere elaborata correttamente dal comando EXPLAIN.
  • 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 gli indici di valore

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.

    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 corretti del database, dato un array di frasi di valori.

    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 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, che è simile 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';

    I tipi di concetti integrati definiti dal linguaggio naturale di AlloyDB AI sono elencati nella tabella seguente.

    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 automaticamente le associazioni di tipi di concetti

Per associare automaticamente le colonne ai tipi di concetti, utilizza la funzionalità di associazione automatica dei tipi di concetti dell'API AlloyDB AI Natural Language. Un'associazione di tipi di concetti definisce la relazione tra un tipo di concetto e una o più colonne del database, un prerequisito per la creazione di indici di valori.

Per generare automaticamente le associazioni di tipi di concetti:

  1. Per generare associazioni, chiama le seguenti API.

    -- To cover all relations within the scope of a provided nl_config.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To cover a specific relation.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config',
  relation_name => 'my_app_table'
);

  2. Esamina le associazioni generate eseguendo la seguente query.

    SELECT * FROM alloydb_ai_nl.generated_value_index_columns_view;

  3. (Facoltativo) Aggiorna le associazioni generate.

    -- NULL means keeping the original value.
SELECT alloydb_ai_nl.update_generated_concept_type_associations(
  id => 1,
  column_names => NULL,
  concept_type => 'generic_entity_name',
  additional_info => NULL
);

  4. (Facoltativo) Rimuovi un'associazione generata.

    SELECT alloydb_ai_nl.drop_generated_concept_type_association(id => 1);

  5. Applica le associazioni generate.

    -- To apply all associations under a nl config.
SELECT alloydb_ai_nl.apply_generated_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To apply a specific association by id.
SELECT alloydb_ai_nl.apply_generated_concept_type_association(
  id => 1
);

  6. Aggiorna l'indice dei valori per riflettere le modifiche.

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

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.

Generare riepiloghi dei risultati da input in linguaggio naturale

Puoi utilizzare il linguaggio naturale di AlloyDB AI per generare riepiloghi dei risultati a partire da input in linguaggio naturale. La funzione alloydb_ai_nl.get_sql_summary esegue in modo sicuro la domanda in linguaggio naturale nella tabella sottostante, riepiloga un campione del set di risultati e restituisce il riepilogo in linguaggio naturale.

Per generare un riepilogo dei risultati per una domanda in linguaggio naturale nel tuo database, utilizza la funzione alloydb_ai_nl.get_sql_summary come mostrato nell'esempio seguente:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?');

La chiamata dell'istruzione precedente produce il seguente oggetto JSON di esempio:

{
  "answer": "The result set indicates that there are 13 accounts that chose issuance after a transaction and are located in the East Bohemia region. The earliest opening date among these accounts is August 21, 1993. Other information about these accounts is not provided in the result set."
}

Puoi proteggere le tabelle e le viste a cui accede una query in alloydb_ai_nl.get_sql_summary utilizzando una o più viste sicure con parametri. I nomi dei parametri e i relativi valori sono disponibili per un'applicazione e sono richiesti da alloydb_ai_nl.get_sql_summary.

Ad esempio, l'applicazione potrebbe voler fornire il parametro user_id per un utente autenticato con un ID utente 123. A questo scopo, fornisci gli input param_names e param_values, come mostrato nell'esempio seguente:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?',
    param_names => ARRAY ['user_id'],
    param_values => ARRAY ['123']
);

Fornire gli argomenti param_names e param_values garantisce che, quando la nl_question può essere risolta da un'istruzione SQL applicata da viste sicure parametrizzate, i filtri di sicurezza designati vengano applicati quando viene prodotto il set di risultati e viene generato il riepilogo.

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