Utilizza il linguaggio naturale di AlloyDB AI per generare SQL

Questo tutorial descrive come configurare e utilizzare l'API Natural Language di AlloyDB AI utilizzando la console Google Cloud . Scopri come configurare l'API di linguaggio naturale di AlloyDB AI in modo da poter porre domande in linguaggio naturale e ricevere query SQL e risultati.

Obiettivi

  • Crea e compila tabelle e utilizza la generazione automatica per creare contesto.
  • Crea un indice dei valori per le colonne del database.
  • Crea e configura un oggetto di configurazione del linguaggio naturale (nl_config).
  • Crea modelli per una query di esempio nell'applicazione.
  • Utilizza la funzione get_sql() per generare una query SQL che risponda a una domanda.
  • Utilizza la funzione execute_nl_query() per rispondere a una domanda in linguaggio naturale utilizzando il database.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per ulteriori informazioni, vedi Pulizia.

Prima di iniziare

Richiedi l'accesso

Prima di poter utilizzare il linguaggio naturale di AlloyDB AI per generare SQL, devi richiedere l'accesso al linguaggio naturale di AlloyDB AI e attendere di ricevere la conferma dell'attivazione prima di seguire le istruzioni di questo tutorial.

Abilita la fatturazione e le API richieste

  1. Nella console Google Cloud , seleziona un progetto.

    Vai al selettore dei progetti

  2. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud .

  3. Abilita le API Cloud necessarie per creare e connetterti ad AlloyDB per PostgreSQL.

    Abilita l'API

    1. Nel passaggio Conferma progetto, fai clic su Avanti per confermare il nome del progetto a cui apporterai le modifiche.

    2. Nel passaggio Abilita API, fai clic su Abilita per abilitare quanto segue:

      • API AlloyDB

Creare e connettersi a un database

  1. Crea un cluster e la relativa istanza principale.
  2. Connettiti all'istanza e crea un database.
  3. Attiva l'integrazione di Vertex AI. Per ulteriori informazioni, consulta Integrazione con Vertex AI.

Installare l'estensione richiesta

Per installare l'estensione alloydb_ai_nl, che è l'API di supporto del linguaggio naturale di AlloyDB AI, esegui la seguente query:

CREATE EXTENSION alloydb_ai_nl cascade;

Crea lo schema e le tabelle nla_demo

Nei passaggi successivi, creerai lo schema e le tabelle nla_demo nello schema. Compili le tabelle con dati sintetici. Lo schema e i dati forniti sono progettati per supportare le operazioni fondamentali di un'attività di vendita al dettaglio online, con potenziali applicazioni che si estendono a gestione dei clienti, analisi, marketing e aspetti operativi.

I dati di esempio mostrano come puoi utilizzare il linguaggio naturale di AlloyDB AI per scopi di sviluppo, test e dimostrazione, in particolare per funzionalità come le interfacce di linguaggio naturale.

  1. Crea lo schema eseguendo la query seguente:

    CREATE SCHEMA nla_demo;

  2. Crea tabelle nello schema nla_demo. La tabella addresses memorizza le informazioni sull'indirizzo di clienti e ordini.

    CREATE TABLE nla_demo.addresses (
    address_id      SERIAL         PRIMARY KEY,
    street_address  VARCHAR(255)   NOT NULL,
    city            VARCHAR(255)   NOT NULL,
    country         VARCHAR(255)
);

  3. Crea la tabella customers eseguendo la seguente query. Questa tabella memorizza i dati dei clienti, tra cui ID cliente, nome, dati di contatto, riferimento all'indirizzo, data di nascita e ora di creazione del record.

    CREATE TABLE nla_demo.customers (
    customer_id     SERIAL         PRIMARY KEY,
    first_name      VARCHAR(255)   NOT NULL,
    last_name       VARCHAR(255)   NOT NULL,
    email           VARCHAR(255)   UNIQUE NOT NULL,
    address_id      INTEGER        REFERENCES nla_demo.addresses(address_id),
    date_of_birth   DATE,
    created_at      TIMESTAMP      DEFAULT CURRENT_TIMESTAMP
);

  4. Crea la tabella categories, che memorizza le categorie di prodotti.

    CREATE TABLE nla_demo.categories (
    category_id     INTEGER        PRIMARY KEY,
    category_name   VARCHAR(255)   UNIQUE NOT NULL
);

  5. Crea la tabella brands, che memorizza i nomi dei brand.

    CREATE TABLE nla_demo.brands (
    brand_id      INTEGER        PRIMARY KEY,
    brand_name    VARCHAR(255)   NOT NULL
);

  6. Crea la tabella products, che memorizza informazioni sui prodotti come ID prodotto, nome, descrizione, brand, collegamento alla categoria e ora di creazione del record.

    CREATE TABLE nla_demo.products (
    product_id    INTEGER        PRIMARY KEY,
    name          VARCHAR(255)   NOT NULL,
    description   TEXT           DEFAULT 'Not available',
    brand_id      INTEGER        REFERENCES nla_demo.brands(brand_id),
    category_id   INTEGER        REFERENCES nla_demo.categories(category_id),
    created_at    TIMESTAMP      DEFAULT CURRENT_TIMESTAMP
);

  7. Crea la tabella orders. Questa tabella memorizza le informazioni sugli ordini dei clienti, inclusi cliente, data, importo totale, indirizzi di spedizione e fatturazione e stato dell'ordine.

    CREATE TABLE nla_demo.orders (
    order_id            INTEGER        PRIMARY KEY,
    customer_id         INTEGER        REFERENCES nla_demo.customers(customer_id),
    order_date          TIMESTAMP      DEFAULT CURRENT_TIMESTAMP,
    total_amount        DECIMAL(10, 2) NOT NULL,
    shipping_address_id INTEGER        REFERENCES nla_demo.addresses(address_id),
    billing_address_id  INTEGER        REFERENCES nla_demo.addresses(address_id),
    order_status        VARCHAR(50)
);

  8. Crea la tabella order_items. Questa tabella registra i singoli articoli di un ordine, i link all'ordine e alla variante del prodotto e specifica la quantità e il prezzo.

    CREATE TABLE nla_demo.order_items (
    order_item_id   SERIAL         PRIMARY KEY,
    order_id        INTEGER        REFERENCES nla_demo.orders(order_id),
    product_id      INTEGER        REFERENCES nla_demo.products(product_id),
    quantity        INTEGER        NOT NULL,
    price           DECIMAL(10, 2) NOT NULL
);

Compila le tabelle nello schema nla_demo

  1. Compila la tabella addresses eseguendo la seguente query:

    INSERT INTO nla_demo.addresses (street_address, city, country)
VALUES
    ('1800 Amphibious Blvd', 'Mountain View', 'USA'),
    ('Avenida da Pastelaria, 1903', 'Lisbon', 'Portugal'),
    ('8 Rue du Nom Fictif 341', 'Paris', 'France');

  2. Compila la tabella customers.

    INSERT INTO nla_demo.customers (first_name, last_name, email, address_id, date_of_birth)
VALUES
    ('Alex', 'B.', 'alex.b@example.com', 1, '2003-02-20'),
    ('Amal', 'M.', 'amal.m@example.com', 2, '1998-11-08'),
    ('Dani', 'G.', 'dani.g@example.com', 3, '2002-07-25');

  3. Compila la tabella categories.

    INSERT INTO nla_demo.categories (category_id, category_name)
VALUES
    (1, 'Accessories'),
    (2, 'Apparel'),
    (3, 'Footwear'),
    (4, 'Swimwear');

  4. Compila la tabella brands.

    INSERT INTO nla_demo.brands (brand_id, brand_name)
VALUES
    (1, 'CymbalPrime'),
    (2, 'CymbalPro'),
    (3, 'CymbalSports');

  5. Compila la tabella products.

    INSERT INTO nla_demo.products (product_id, brand_id, category_id, name)
VALUES
    (1, 1, 2, 'Hoodie'),
    (2, 1, 3, 'Running Shoes'),
    (3, 2, 4, 'Swimsuit'),
    (4, 3, 1, 'Tote Bag'),
    (5, 3, 3, 'CymbalShoe');

  6. Compila la tabella orders.

    INSERT INTO nla_demo.orders (order_id, customer_id, total_amount, shipping_address_id, billing_address_id, order_status)
VALUES
    (1, 1, 99.99, 1, 1, 'Shipped'),
    (2, 1, 69.99, 1, 1, 'Delivered'),
    (3, 2, 20.99, 2, 2, 'Processing'),
    (4, 3, 79.99, 3, 3, 'Shipped');

  7. Compila la tabella order_items.

    INSERT INTO nla_demo.order_items (order_id, product_id, quantity, price)
VALUES
    (1, 1, 1, 79.99),
    (1, 3, 1, 20.00),
    (2, 4, 1, 69.99),
    (3, 3, 1, 20.00),
    (4, 2, 1, 79.99);

Creare una configurazione in linguaggio naturale

Per utilizzare il linguaggio naturale di AlloyDB AI, assicurati che l'endpoint Vertex AI sia configurato. Poi crei una configurazione e registri uno schema. g_alloydb_ai_nl.g_create_configuration crea il modello.

  1. Crea una configurazione in linguaggio naturale.

    SELECT alloydb_ai_nl.g_create_configuration( 'nla_demo_cfg' );

  2. Registra le tabelle nella configurazione nla_demo_cfg.

    SELECT alloydb_ai_nl.g_manage_configuration(
    operation => 'register_table_view',
    configuration_id_in => 'nla_demo_cfg',
    table_views_in=>'{nla_demo.customers, nla_demo.addresses, nla_demo.brands, nla_demo.products, nla_demo.categories, nla_demo.orders, nla_demo.order_items}'
);

Creare e applicare il contesto per tabelle e colonne

Per fornire risposte accurate alle domande in linguaggio naturale, utilizza l'API Natural Language di AlloyDB AI per fornire il contesto di tabelle, viste e colonne. Puoi utilizzare la funzionalità di generazione automatica del contesto dell'API di linguaggio naturale AlloyDB AI per produrre il contesto da tabelle e colonne e applicarlo come COMMENTS allegato a tabelle, viste e colonne.

  1. Per generare contesti dello schema per le tabelle e le relative colonne registrate nella configurazione nla_demo_cfg, esegui il comando seguente:

    SELECT alloydb_ai_nl.generate_schema_context(
  'nla_demo_cfg',
  TRUE
);

    La query precedente compila la visualizzazione alloydb_ai_nl.generated_schema_context_view con il contesto. Il passaggio di TRUE sovrascrive il contesto in questa visualizzazione dalle esecuzioni precedenti.

  2. Per verificare il contesto generato per la tabella nla_demo.products, esegui questa query:

    SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'nla_demo.products';

    Il contesto risultante è simile al seguente:

    The products table stores information about products, including their name,
a brief description, the brand they belong to (referenced by brand_id),
and the category they fall under (referenced by category_id). Each product
has a unique identifier (product_id) and a timestamp indicating its creation
time (created_at).

  3. Per verificare il contesto prodotto per una colonna, ad esempio nla_demo.products.name, esegui questo comando:

    SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'nla_demo.products.name';

    L'output della query è simile al seguente:

    The name column in the nla_demo.products table contains the specific
name or title of each product. This is a short, descriptive text string
that clearly identifies the product, like "Hoodie," "Tote Bag,"
"Running Shoes," or "Swimsuit." It helps distinguish individual products
within the broader context of their brand and category. The name column
specifies the exact product. This column is essential for users and
systems to identify and refer to specific products within the database.

  4. Esamina il contesto generato nella visualizzazione alloydb_ai_nl.generated_schema_context_view e aggiorna il contesto che deve essere rivisto.

    SELECT alloydb_ai_nl.update_generated_relation_context(
  'nla_demo.products',
  'The "nla_demo.products" table stores product details such as ID, name, description, brand, category linkage, and record creation time.'
);

SELECT alloydb_ai_nl.update_generated_column_context(
  'nla_demo.products.name',
  'The "name" column in the "nla_demo.products" table contains the specific name or title of each product.'
);

  5. Applica il contesto generato che verrà allegato agli oggetti corrispondenti:

    SELECT alloydb_ai_nl.apply_generated_relation_context(
  'nla_demo.products', true
);

SELECT alloydb_ai_nl.apply_generated_column_context(
  'nla_demo.products.name',
  true
);

    Le voci di contesto risultanti nella visualizzazione alloydb_ai_nl.generated_schema_context_view vengono applicate agli oggetti dello schema corrispondenti e i commenti vengono sovrascritti.

Costruisci l'indice dei valori

L'API Natural Language di AlloyDB AI produce query SQL accurate utilizzando il collegamento dei valori. Il collegamento dei valori associa le frasi di valore nelle istruzioni in linguaggio naturale a tipi di concetti e nomi di colonne preregistrati che possono arricchire la domanda in linguaggio naturale.

Ad esempio, alla domanda "Dammi il prezzo di una felpa" si può rispondere in modo più accurato se Hoodie è associato a un concetto product_name, che è associato a nla_demo.products.name. colonna.

  1. Per definire il tipo di concetto product_name e associarlo alla colonna nla_demo.products.name, esegui le seguenti query:

    SELECT alloydb_ai_nl.add_concept_type(
    concept_type_in => 'product_name',
    match_function_in => 'alloydb_ai_nl.get_concept_and_value_generic_entity_name',
    additional_info_in => '{
      "description": "Concept type for product name.",
      "examples": "SELECT alloydb_ai_nl.get_concept_and_value_generic_entity_name(''Camera'')" }'::jsonb
);
SELECT alloydb_ai_nl.associate_concept_type(
    'nla_demo.products.name',
    'product_name',
    'nla_demo_cfg'
);

  2. Per verificare che il tipo di concetto product_name sia stato aggiunto all'elenco dei tipi di concetto, esegui la seguente query per assicurarti che product_name sia incluso nel risultato di questa query:

    SELECT alloydb_ai_nl.list_concept_types();

  3. Per verificare che la colonna nla_demo.products.name sia associata al tipo di concetto product_name, esegui questa query:

    SELECT *
FROM alloydb_ai_nl.value_index_columns
WHERE column_names = 'nla_demo.products.name';

  4. Per definire il tipo di concetto brand_name e associarlo alla colonna nla_demo.brands.brand_name, esegui le seguenti query:

    SELECT alloydb_ai_nl.add_concept_type(
    concept_type_in => 'brand_name',
    match_function_in => 'alloydb_ai_nl.get_concept_and_value_generic_entity_name',
    additional_info_in => '{
      "description": "Concept type for brand name.",
      "examples": "SELECT alloydb_ai_nl.get_concept_and_value_generic_entity_name(''CymbalPrime'')" }'::jsonb
);
SELECT alloydb_ai_nl.associate_concept_type(
    'nla_demo.brands.brand_name',
    'brand_name',
    'nla_demo_cfg'
);

  5. Dopo aver definito i tipi di concetti e associato le colonne, crea un indice dei valori.

    SELECT alloydb_ai_nl.create_value_index('nla_demo_cfg');
SELECT alloydb_ai_nl.refresh_value_index('nla_demo_cfg');

Definire un modello di query

Puoi definire modelli per migliorare la qualità delle risposte prodotte dall'API di linguaggio naturale di AlloyDB AI.

  1. Per fornire modelli di esempio per domande business-critical e per fornire domande previste per le quali è prevista un'elevata precisione, esegui la seguente query per aggiungere un modello:

    SELECT alloydb_ai_nl.add_template(
    nl_config_id => 'nla_demo_cfg',
    intent => 'List the first names and the last names of all customers who ordered Swimsuit.',
    sql => 'SELECT c.first_name, c.last_name FROM nla_demo.Customers c JOIN nla_demo.orders o ON c.customer_id = o.customer_id JOIN nla_demo.order_items oi ON o.order_id = oi.order_id JOIN nla_demo.products p ON oi.product_id = p.product_id  AND p.name = ''Swimsuit''',
    sql_explanation => 'To answer this question, JOIN `nla_demo.Customers` with `nla_demo.orders` on having the same `customer_id`, and JOIN the result with nla_demo.order_items on having the same `order_id`. Then JOIN the result with `nla_demo.products` on having the same `product_id`, and filter rwos that with p.name = ''Swimsuit''. Return the `first_name` and the `last_name` of the customers with matching records.',
    check_intent => TRUE
);

  2. Per visualizzare l'elenco dei modelli aggiunti, esegui una query su alloydb_ai_nl.template_store_view:

    SELECT nl, sql, intent, psql, pintent
FROM alloydb_ai_nl.template_store_view
WHERE config = 'nla_demo_cfg';

    Viene restituito l'output seguente:

    nl      | List the first names and the last names of all customers who ordered Swimsuit.
sql     | SELECT c.first_name, c.last_name
        | FROM nla_demo.Customers c
        | JOIN nla_demo.orders o ON c.customer_id = o.customer_id
        | JOIN nla_demo.order_items oi ON o.order_id = oi.order_id
        | JOIN nla_demo.products p ON oi.product_id = p.product_id
        | AND p.name = 'Swimsuit'
intent  | List the first names and the last names of all customers who ordered
        | Swimsuit.
psql    | SELECT c.first_name, c.last_name
        | FROM nla_demo.Customers c JOIN nla_demo.orders o
        | ON c.customer_id = o.customer_id 
        | JOIN nla_demo.order_items oi ON o.order_id = oi.order_id
        | JOIN nla_demo.products p ON oi.product_id = p.product_id
        | AND p.name = $1
pintent | List the first names and the last names of all customers who ordered
        | $1.

    In questo modello, il valore corrispondente all'attributo psql è la query SQL parametrizzata, mentre il valore della colonna pintent è l'istruzione di intent parametrizzata. Il id di un modello aggiunto di recente può essere diverso, in base ai modelli aggiunti in precedenza. I modelli vengono utilizzati per fornire risposte molto precise alle domande.

Generare risultati SQL da domande in linguaggio naturale

  1. Per utilizzare l'API di linguaggio naturale di AlloyDB AI per produrre query SQL e set di risultati, esegui la seguente query:

    SELECT
    alloydb_ai_nl.get_sql(
        'nla_demo_cfg',
        'Find the customers who purchased Tote Bag.'
    ) ->> 'sql';

    Viene restituito l'output seguente:

    SELECT DISTINCT "c"."first_name", "c"."last_name"
FROM "nla_demo"."customers" AS "c"
JOIN "nla_demo"."orders" AS "o" ON "c"."customer_id" = "o"."customer_id"
JOIN "nla_demo"."order_items" AS "oi" ON "o"."order_id" = "oi"."order_id"
JOIN "nla_demo"."products" AS "p" ON "oi"."product_id" = "p"."product_id"
WHERE "p"."name" = 'Tote Bag';

    L'output JSON è una query SQL che utilizza il modello che hai aggiunto in Definisci un modello di query.

  2. Per utilizzare l'API Natural Language di AlloyDB AI per produrre query SQL, esegui la seguente query:

    SELECT
    alloydb_ai_nl.get_sql(
        'nla_demo_cfg',
        'List the maximum price of any CymbalShoe.'
    ) ->> 'sql';

    Viene restituito l'output seguente:

    SELECT max("price")
FROM "nla_demo"."order_items" AS t1
JOIN "nla_demo"."products" AS t2 ON t1."product_id" = t2."product_id"
WHERE t2."name" = 'CymbalShoe';

    L'API di linguaggio naturale di AlloyDB AI riconosce che CymbalShoe è il nome del prodotto utilizzando l'indice dei valori. Sostituisci CymbalShoe con un nome del brand (CymbalPrime) nella seguente query:

    SELECT
    alloydb_ai_nl.get_sql(
        'nla_demo_cfg',
        'List the maximum price of any CymbalPrime.'
    ) ->> 'sql';

    produce il seguente output:

    SELECT max("price")
FROM "nla_demo"."order_items" AS "oi"
JOIN "nla_demo"."products" AS "p" ON "oi"."product_id" = "p"."product_id"
JOIN "nla_demo"."brands" AS "b" ON "p"."brand_id" = "b"."brand_id"
WHERE "b"."brand_name" = 'CymbalPrime';

    AlloyDB AI utilizza l'indice dei valori creato in Costruisci l'indice dei valori per risolvere CymbalPrime nel tipo di concetto brand_name e utilizza la colonna nla_demo.brands.brand_name associata a brand_name.

  3. Per utilizzare l'API Natural Language di AlloyDB AI per produrre il risultato di una domanda, esegui la seguente query:

    SELECT
alloydb_ai_nl.execute_nl_query(
    'Find the last name of the customers who live in Lisbon.',
    'nla_demo_cfg'
);

    Viene restituito l'output seguente:

    execute_nl_query     
--------------------------
{"last_name":"M."}

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Le sezioni seguenti descrivono come eliminare queste risorse e questi oggetti.

Elimina il cluster

Quando elimini il cluster che hai creato in Prima di iniziare, vengono eliminati anche tutti gli oggetti che hai creato.

  1. Nella console Google Cloud , vai alla pagina Cluster.

    Vai a Cluster

  2. Fai clic sul nome del tuo cluster, my-cluster, nella colonna Nome risorsa.

  3. Fai clic su Elimina cluster.

  4. In Elimina cluster my-cluster, inserisci my-cluster per confermare che vuoi eliminare il cluster.

  5. Fai clic su Elimina.

  6. Se hai creato una connessione privata quando hai creato un cluster, vai alla console Google Cloud pagina Reti VPC e fai clic su Elimina rete VPC.

Elimina gli oggetti

Puoi scegliere di conservare le risorse che hai configurato in Prima di iniziare e di eliminare solo gli oggetti che hai creato nel progetto Google Cloud .

  1. Per rimuovere il modello che hai definito in Definisci un modello di query, esegui la seguente query:

    SELECT alloydb_ai_nl.drop_template(id)
FROM alloydb_ai_nl.template_store_view
WHERE config = 'nla_demo_cfg';

  2. Per rimuovere il tipo di concetto product_name che hai definito in Costruisci l'indice dei valori, esegui la seguente query:

    SELECT alloydb_ai_nl.drop_concept_type('product_name');

  3. Per aggiornare l'indice dei valori dopo aver rimosso il tipo di concetto product_name, esegui la seguente query:

    SELECT alloydb_ai_nl.refresh_value_index();

  4. Per rimuovere la configurazione nla_demo_cfg che hai creato in Creare una configurazione in linguaggio naturale, esegui la seguente query:

    SELECT
alloydb_ai_nl.g_manage_configuration(
    'drop_configuration',
    'nla_demo_cfg'
);

  5. Per rimuovere lo schema e le tabelle nla_demo che hai creato e compilato in Crea lo schema e le tabelle nla_demo e Compila le tabelle nello schema nla_demo, esegui la seguente query:

    DROP SCHEMA nla_demo CASCADE;

Passaggi successivi