Questa pagina è stata tradotta dall'API Cloud Translation.

Generare query SQL utilizzando domande in linguaggio naturale

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

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

Installa l'estensione alloydb_ai_nl.
Definisci una configurazione del linguaggio naturale per la tua applicazione.
Registra uno schema.
Aggiungi contesto.
Aggiungi modelli di query.
Definisci i tipi di concetti e crea un indice di valori.
Genera istruzioni SQL utilizzando un'interfaccia di linguaggio naturale.

Prima di iniziare

Richiedi l'accesso al linguaggio naturale di AlloyDB AI e attendi di ricevere la conferma dell'attivazione prima di seguire le istruzioni riportate in questa pagina.
Scopri come connetterti al database AlloyDB ed eseguire comandi PostgreSQL. Per ulteriori informazioni, consulta Panoramica delle connessioni.
Compila il database con i dati e lo schema a cui l'utente finale vuole accedere.

Crea un cluster e abilita l'integrazione di Vertex AI

Crea un cluster e un'istanza AlloyDB. Utilizza l'istanza AlloyDB per creare il database e lo schema dell'applicazione.
Attiva l'integrazione di Vertex AI. Per ulteriori informazioni, consulta Eseguire l'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 utilizzi:

roles/alloydb.admin (il ruolo IAM predefinito AlloyDB Admin)

Per ulteriori informazioni, consulta Gestire gli utenti PostgreSQL con 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 i 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, che attiva le estensioni google_ml_integration e alloydb_ai_nl.

CREATE EXTENSION google_ml_integration;
CREATE EXTENSION alloydb_ai_nl cascade;

Crea una configurazione in linguaggio naturale e registra uno schema

Il linguaggio naturale dell'IA di AlloyDB utilizza nl_config per associare le applicazioni a determinati schemi, modelli di query ed endpoint dei modelli. nl_config è una configurazione che associa un'applicazione a schema, modelli e altri contesti. Un'applicazione di grandi dimensioni può anche utilizzare configurazioni diverse per parti diverse 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, visualizzazioni e colonne.

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.

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. Il contesto include la struttura e le relazioni dello schema, i riepiloghi e le descrizioni delle colonne, i valori delle colonne e la relativa semantica, nonché regole o istruzioni di logica di business specifiche per l'applicazione o il dominio.

Aggiungere un contesto generale per le regole specifiche dell'applicazione

Gli elementi di contesto generale includono regole specifiche per l'applicazione, istruzioni di logica aziendale o qualsiasi terminologia specifica per l'applicazione e per il dominio che non è collegata a un oggetto dello schema specifico.

Per aggiungere un contesto generale per regole specifiche dell'applicazione e terminologia specifica per l'applicazione o per il dominio:

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."}'
  );
```
L'istruzione precedente aiuta il linguaggio naturale dell'IA di AlloyDB a fornire risposte di qualità superiore alle domande in linguaggio naturale degli utenti.
Per visualizzare i contesti generali per la configurazione specificata, esegui la seguente dichiarazione:
```
SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);
```

Generare ed esaminare il contesto dello schema

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

Per generare contesti per gli oggetti dello schema, chiama le seguenti API. Per 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
  );

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 generati vengono memorizzati nella visualizzazione precedente.

(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.'
  );

Applica il contesto. Quando applichi il contesto, questo viene applicato immediatamente ed eliminato dal 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
  );

(Facoltativo) Verifica il contesto generato. La seguente API consente di controllare i contesti dello schema, che vengono utilizzati per generare 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'
  );

(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 IA generativa create con gli LLM, puoi aggiungere modelli. Un modello di query è un insieme selezionato di domande in linguaggio naturale comuni o rappresentative, con le query SQL corrispondenti, nonché spiegazioni per fornire una motivazione dichiarativa per la generazione da linguaggio naturale a SQL (NL2SQL). I modelli sono principalmente destinati a 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 parametro corrispondente e sintetizza un'istruzione SQL mediante l'istanziazione dei parametri con i valori della domanda in linguaggio naturale. Tuttavia, se non esiste un modello con la stessa intenzione della domanda posta dall'utente, alloydb_ai_nl utilizza ogni modello e contesto pertinente per comporre un statement SQL.

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

Per aggiungere un modello al repository 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 confermare che lo scopo fornito corrisponda all'istruzione SQL passata. Se l'intent non corrisponde all'istruzione SQL, il modello non viene aggiunto.

Genera automaticamente i modelli

Dopo aver creato un set di dati rappresentativo nelle tabelle, ti consigliamo di eseguire query SQL corrispondenti alle domande comuni che gli utenti finali potrebbero porre. È importante assicurarti 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. Per generare modelli, puoi chiamare le seguenti API. Devi esaminare e applicare i modelli generati prima che vengano applicati.

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: 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 si fa riferimento rientrano nell'ambito di nl_config.

Per generare automaticamente, esaminare e applicare i modelli:

Chiedi ad AlloyDB di generare modelli in base alla tua cronologia delle query:
```
SELECT 
  alloydb_ai_nl.generate_templates(
    'my_app_config', 
);
```
Utilizza la vista fornita, alloydb_ai_nl.generated_templates_view, per esaminare il generated_templates.

L'output seguente mostra il numero di modelli generati:
```
-[ RECORD 1 ]------+--
generate_templates | 1
```

Rivedi i modelli generati utilizzando la visualizzazione generated_templates_view.

SELECT * 
FROM alloydb_ai_nl.generated_templates_view;

Di seguito è riportato un esempio dell'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

Per aggiornare un modello generato, esegui il seguente comando 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?'

);

Applica i modelli. I modelli che applichi vengono aggiunti immediatamente al repository dei modelli ed eliminati dalla visualizzazione di revisione.
```
-- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');
```

Configura la sicurezza per il linguaggio naturale

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

Definisci i tipi di concetti e l'indice di valore

Definisci i tipi di concetti e gli indici di valore per fornire una comprensione più approfondita delle 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 è scritto in maiuscolo, ad esempio USA, e l'altro è scritto in minuscolo, ad esempio usa. In questo caso, il nome del paese è il tipo di concetto. Altri esempi di tipi di concetti sono nome di persona, nome di città e data.

Un indice di valore è un indice in cima ai 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 di valore consente una corrispondenza efficiente delle frasi di valore per la domanda posta e dei valori nel database.

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

Per associare una colonna a un tipo di concetto, esegui la seguente 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'
  );

Per creare un indice di valore basato su tutte le colonne che fanno parte di una configurazione del linguaggio naturale e sono associate a un tipo di concetto, esegui la seguente dichiarazione:
```
SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );
```
Quando associ i tipi di concetti a nuove colonne, aggiorna l'indice dei valori in modo che rifletta le modifiche.
```
SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );
```
Per consentire al linguaggio naturale di AlloyDB AI di trovare i sinonimi di un valore, esegui l'istruzione di esempio seguente:
```
SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );
```
Sebbene i dati nelle tabelle possano utilizzare un valore specifico, ad esempio se United States viene utilizzato per identificare un paese, puoi definire un insieme di sinonimi contenente tutti i sinonimi di United States. Se uno dei sinonimi compare nella domanda in linguaggio naturale, il linguaggio naturale dell'IA di AlloyDB li associa ai valori nelle tabelle.

Esegui una ricerca di valori per trovare i valori corretti del database, in base a un array di frasi di valore.

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 fa una domanda come "Qual è la popolazione degli Stati Uniti?" che utilizza la seguente query get_sql, il linguaggio naturale dell'AI di AlloyDB utilizza la funzione get_concept_and_value con la frase valore United States per eseguire una ricerca fuzzy rispetto agli indici di valore. La ricerca approssimativa è una tecnica di ricerca che trova corrispondenze anche quando la query di ricerca non corrisponde esattamente ai dati corrispondenti.

Il linguaggio naturale trova un risultato, il valore USA, 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 concetto	Descrizione
`generic_entity_name`	È possibile utilizzare una singola colonna di tipo stringa 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`	Nome della persona, composto da nome, cognome e secondo nome. Per un nome completo di una persona è possibile utilizzare fino a tre colonne di tipo stringa. Qualsiasi colonna può essere saltata quando si associano le 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 numero di previdenza sociale. 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 da input in linguaggio naturale. Quando esegui l'istruzione SQL generata, viene fornita la tabella di dati del database necessaria per rispondere alla domanda in linguaggio naturale.

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?"
}

(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, aggiungi un contesto migliore, modelli di query e indici di valore, quindi esegui l'iterazione fino a ottenere i risultati che ti interessano.