本頁面由 Cloud Translation API 翻譯而成。

使用 AlloyDB AI 自然語言生成 SQL

本教學課程說明如何使用 Google Cloud 控制台，設定及使用 AlloyDB AI 自然語言 API。瞭解如何設定 AlloyDB AI 自然語言 API，以便提出自然語言問題，並取得 SQL 查詢和結果。

目標

建立及填入資料表，並使用自動生成功能建立內容。
為資料庫中的資料欄建立值索引。
建立及設定自然語言設定 (nl_config) 物件。
在應用程式中為範例查詢建立範本。
使用 get_sql() 函式產生可回答問題的 SQL 查詢。
使用 execute_nl_query() 函式，透過資料庫回答自然語言問題。

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用資格。

完成本文所述工作後，您可以刪除已建立的資源，避免繼續計費。詳情請參閱清除所用資源一節。

事前準備

要求存取權

如要使用 AlloyDB AI 自然語言生成 SQL，請先要求存取 AlloyDB AI 自然語言，並等待收到啟用確認訊息，再按照本教學課程的指示操作。

啟用計費功能和必要的 API

在 Google Cloud 控制台中選取專案。

前往專案選取器
請確認您已為 Google Cloud 專案啟用計費功能。
啟用建立及連線至 PostgreSQL 適用的 AlloyDB 時所需的 Cloud API。

啟用 API
1. 在「確認專案」步驟中，按一下「下一步」，確認要變更的專案名稱。
2. 在「啟用 API」步驟中，按一下「啟用」，啟用下列項目：
  - AlloyDB API

建立及連線至資料庫

建立叢集及其主要執行個體。
連線至執行個體並建立資料庫。
啟用 Vertex AI 整合功能。詳情請參閱「與 Vertex AI 整合」。

安裝必要擴充功能

如要安裝 alloydb_ai_nl 擴充功能 (即 AlloyDB AI 自然語言支援 API)，請執行下列查詢：

CREATE EXTENSION alloydb_ai_nl cascade;

建立 nla_demo 結構定義和資料表

在下列步驟中，您將在結構定義中建立 nla_demo 結構定義和資料表。您可以使用合成資料填入資料表。提供的結構定義和資料旨在支援線上零售業務的基本作業，潛在應用範圍可擴及客戶管理、分析、行銷和營運層面。

範例資料會說明如何使用 AlloyDB AI 自然語言進行開發、測試和展示，特別是自然語言介面等功能。

執行下列查詢來建立結構定義：
```
CREATE SCHEMA nla_demo;
```

在 nla_demo 結構定義中建立資料表。addresses 資料表會儲存顧客和訂單的地址資訊。

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

執行下列查詢，建立 customers 資料表。這個資料表會儲存顧客資訊，包括顧客 ID、姓名、聯絡資訊、地址參照、出生日期和記錄建立時間。

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
);

建立 categories 資料表，用於儲存產品類別。

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

建立 brands 資料表，用於儲存品牌名稱。

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

建立 products 表格，儲存產品 ID、名稱、說明、品牌、類別連結和記錄建立時間等產品資訊。

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
);

建立 orders 資料表。這個資料表會儲存顧客訂單的相關資訊，包括顧客、日期、總金額、運送和帳單地址，以及訂單狀態。

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)
);

建立 order_items 資料表。這份表格會記錄訂單中的個別項目、連結至訂單和產品子類，並指定數量和價格。

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
);

在 nla_demo 結構定義中填入資料表

執行下列查詢，填入 addresses 資料表：

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

在 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');

在 categories 資料表中填入資料。

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

在 brands 資料表中填入資料。

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

在 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');

在 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');

在 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);

建立自然語言設定

如要使用 AlloyDB AI 自然語言，請務必設定 Vertex AI 端點。然後建立設定並註冊結構定義。 g_alloydb_ai_nl.g_create_configuration 建立模型。

建立自然語言設定。

SELECT alloydb_ai_nl.g_create_configuration( 'nla_demo_cfg' );

將資料表註冊到 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}'
);

建立及套用表格和資料欄的內容

如要準確回答自然語言問題，請使用 AlloyDB AI 自然語言 API 提供表格、檢視區塊和資料欄的相關背景資訊。您可以使用 AlloyDB AI 自然語言 API 的自動產生內容功能，從表格和資料欄產生內容，並將內容套用為附加至表格、檢視區塊和資料欄的 COMMENTS。

如要為 nla_demo_cfg 設定中註冊的資料表及其資料欄產生結構定義內容，請執行下列指令：
```
SELECT alloydb_ai_nl.generate_schema_context(
  'nla_demo_cfg',
  TRUE
);
```
上述查詢會填入含有內容的 alloydb_ai_nl.generated_schema_context_view 檢視畫面。傳遞 TRUE 會覆寫先前執行作業中這個檢視區塊的內容。

如要驗證 nla_demo.products 資料表產生的內容，請執行下列查詢：

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

產生的內容類似於下列內容：

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

如要驗證資料欄產生的內容 (例如 nla_demo.products.name)，請執行下列指令：

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

查詢輸出內容類似於下列內容：

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.

在 alloydb_ai_nl.generated_schema_context_view 檢視畫面中查看產生的內容，並更新需要修訂的內容。

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

套用要附加至對應物件的生成式內容：

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
);

alloydb_ai_nl.generated_schema_context_view 檢視畫面中產生的內容項目會套用至對應的結構定義物件，並覆寫註解。

建構值索引

AlloyDB AI 自然語言 API 會使用值連結功能，產生準確的 SQL 查詢。值連結會將自然語言陳述式中的值詞組，與預先註冊的概念類型和資料欄名稱建立關聯，進而豐富自然語言問題。

舉例來說，如果「連帽上衣」Hoodie與「連帽上衣」product_name概念相關聯，而「連帽上衣」概念又與「連帽上衣」nla_demo.products.name相關聯，那麼「連帽上衣的價格是多少？」這個問題就能獲得更準確的答案。資料欄。

如要定義 product_name 概念類型並與 nla_demo.products.name 資料欄建立關聯，請執行下列查詢：

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

如要確認 product_name 概念類型已新增至概念類型清單，請執行下列查詢，確保 product_name 包含在查詢結果中：
```
SELECT alloydb_ai_nl.list_concept_types();
```
如要確認 nla_demo.products.name 欄是否與 product_name 概念類型相關聯，請執行下列查詢：
```
SELECT *
FROM alloydb_ai_nl.value_index_columns
WHERE column_names = 'nla_demo.products.name';
```

如要定義 brand_name 概念類型並與 nla_demo.brands.brand_name 資料欄建立關聯，請執行下列查詢：

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

定義概念類型並將資料欄與其建立關聯後，請建立值索引。

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

定義查詢範本

您可以定義範本，提升 AlloyDB AI 自然語言 API 生成的答案品質。

如要提供業務關鍵問題的範本，以及預期可獲得高準確度的問題，請執行下列查詢來新增範本：

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
);

如要查看已新增範本的清單，請查詢 alloydb_ai_nl.template_store_view：

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

系統會傳回下列輸出內容：

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.

在這個範本中，對應 psql 屬性的值是參數化的 SQL 查詢，而 pintent 欄的值則是參數化的意圖陳述式。最近新增範本的 id 可能會有所不同，具體取決於先前新增的範本。範本可提供問題的準確答案。

根據自然語言問題生成 SQL 結果

如要使用 AlloyDB AI 自然語言 API 產生 SQL 查詢和結果集，請執行下列查詢：

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

系統會傳回下列輸出內容：

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';

JSON 輸出內容是使用您在「定義查詢範本」中新增範本的 SQL 查詢。

如要使用 AlloyDB AI 自然語言 API 產生 SQL 查詢，請執行下列查詢：

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

系統會傳回下列輸出內容：

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';

AlloyDB AI 自然語言 API 會使用值索引，辨識 CymbalShoe 是產品名稱。在下列查詢中，將 CymbalShoe 替換為品牌名稱 (CymbalPrime)：

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

會產生下列輸出內容：

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 會使用「建構值索引」中建立的值索引，將 CymbalPrime 解析為 brand_name 概念類型，並使用與 brand_name 相關聯的 nla_demo.brands.brand_name 資料欄。

如要使用 AlloyDB AI 自然語言 API 產生問題的結果，請執行下列查詢：

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

系統會傳回下列輸出內容：

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

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，請刪除含有該項資源的專案，或者保留專案但刪除個別資源。

下列各節將說明如何刪除這些資源和物件。

刪除叢集

刪除在「事前準備」中建立的叢集時，您建立的所有物件也會一併刪除。

前往 Google Cloud 控制台的「Clusters」(叢集) 頁面。

前往「Clusters」(叢集) 頁面
在「資源名稱」資料欄中，按一下叢集名稱 my-cluster。
按一下「刪除叢集」。
在「Delete cluster my-cluster」(刪除叢集 my-cluster) 中輸入 my-cluster，確認要刪除叢集。
點選「刪除」。
如果您在建立叢集時建立了私人連線，請前往 Google Cloud 控制台虛擬私有雲網路頁面，然後按一下「刪除虛擬私有雲網路」。

刪除物件

您可以選擇保留「開始前」設定的資源，並只刪除在 Google Cloud 專案中建立的物件。

如要移除在「定義查詢範本」中定義的範本，請執行下列查詢：

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

如要移除在「建構值索引」中定義的 product_name 概念類型，請執行下列查詢：
```
SELECT alloydb_ai_nl.drop_concept_type('product_name');
```
如要在移除 product_name 概念類型後重新整理值索引，請執行下列查詢：
```
SELECT alloydb_ai_nl.refresh_value_index();
```

如要移除在「建立自然語言設定」中建立的 nla_demo_cfg 設定，請執行下列查詢：

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

如要移除您在「建立 nla_demo 結構定義和資料表」和「在 nla_demo 結構定義中填入資料表」中建立並填入的 nla_demo 結構定義和資料表，請執行下列查詢：
```
DROP SCHEMA nla_demo CASCADE;
```

使用 AlloyDB AI 自然語言生成 SQL 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

要求存取權

啟用計費功能和必要的 API

建立及連線至資料庫

安裝必要擴充功能

建立 nla_demo 結構定義和資料表

在 nla_demo 結構定義中填入資料表

建立自然語言設定

建立及套用表格和資料欄的內容

建構值索引

定義查詢範本

根據自然語言問題生成 SQL 結果

清除所用資源

刪除叢集

刪除物件

後續步驟

使用 AlloyDB AI 自然語言生成 SQL