Se usó la API de Cloud Translation para traducir esta página.

Usa el lenguaje natural de AlloyDB AI para generar SQL

En este instructivo, se describe cómo configurar y usar la API de lenguaje natural de AlloyDB AI con la consola de Google Cloud . Aprenderás a configurar la API de lenguaje natural de AlloyDB AI para que puedas hacer preguntas en lenguaje natural y recibir consultas y resultados en SQL.

Objetivos

Crea y propaga tablas, y usa la generación automática para crear contexto.
Crea un índice de valores para las columnas de la base de datos.
Crea y configura un objeto de configuración de lenguaje natural (nl_config).
Crea plantillas para una consulta de muestra en la aplicación.
Usa la función get_sql() para generar una consulta en SQL que responda una pregunta.
Usa la función execute_nl_query() para responder una pregunta en lenguaje natural con la base de datos.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Cuando completes las tareas que se describen en este documento, podrás borrar los recursos que creaste para evitar que se te siga facturando. Para obtener más información, consulta Realiza una limpieza.

Antes de comenzar

Solicitar acceso

Antes de usar el lenguaje natural de AlloyDB AI para generar código SQL, debes solicitar acceso al lenguaje natural de AlloyDB AI y esperar a recibir la confirmación de habilitación antes de seguir las instrucciones de este instructivo.

Habilita la facturación y las APIs obligatorias

En la consola de Google Cloud , selecciona un proyecto.

Ir al selector de proyectos
Asegúrate de tener habilitada la facturación para tu Google Cloud proyecto.
Habilita las API de Cloud necesarias para crear y conectarte a AlloyDB para PostgreSQL.

Habilitar la API
1. En el paso Confirm project, haz clic en Next para confirmar el nombre del proyecto en el que realizarás cambios.
2. En el paso Habilitar APIs, haz clic en Habilitar para habilitar lo siguiente:
  - API de AlloyDB

Crea una base de datos y conéctate a ella

Crea un clúster y su instancia principal.
Conéctate a tu instancia y crea una base de datos.
Habilita la integración en Vertex AI. Para obtener más información, consulta Integración con Vertex AI.

Instala la extensión requerida

Para instalar la extensión alloydb_ai_nl, que es la API de compatibilidad con lenguaje natural de AlloyDB AI, ejecuta la siguiente consulta:

CREATE EXTENSION alloydb_ai_nl cascade;

Crea el esquema y las tablas de nla_demo

En los siguientes pasos, crearás el esquema nla_demo y las tablas en el esquema. Completas las tablas con datos sintéticos. El esquema y los datos proporcionados están diseñados para admitir las operaciones fundamentales de un negocio de venta minorista en línea, con posibles aplicaciones que se extienden a la administración de clientes, las estadísticas, el marketing y los aspectos operativos.

Los datos de muestra muestran cómo puedes usar el lenguaje natural de AlloyDB AI para fines de desarrollo, prueba y demostración, en especial para funciones como las interfaces de lenguaje natural.

Ejecuta la siguiente consulta para crear el esquema:
```
CREATE SCHEMA nla_demo;
```

Crea tablas en el esquema nla_demo. La tabla addresses almacena la información de dirección de los clientes y los pedidos.

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

Ejecuta la siguiente consulta para crear la tabla customers. En esta tabla, se almacena la información del cliente, como el ID, el nombre, los detalles de contacto, la referencia de la dirección, la fecha de nacimiento y la fecha de creación del registro.

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

Crea la tabla categories, que almacena categorías de productos.

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

Crea la tabla brands, que almacena nombres de marcas.

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

Crea la tabla products, que almacena información del producto, como el ID, el nombre, la descripción, la marca, la vinculación de categorías y la hora de creación del registro.

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

Crea la tabla orders. En esta tabla, se almacena información sobre los pedidos de los clientes, incluidos el cliente, la fecha, el importe total, las direcciones de envío y facturación, y el estado del pedido.

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

Crea la tabla order_items. En esta tabla, se registran los artículos individuales de un pedido, se vinculan al pedido y a la variante del producto, y se especifican la cantidad y el precio.

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

Cómo propagar tablas en el esquema nla_demo

Ejecuta la siguiente consulta para propagar la tabla 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');

Propaga la tabla 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');

Propaga la tabla categories.

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

Propaga la tabla brands.

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

Propaga la tabla 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');

Propaga la tabla 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');

Propaga la tabla 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);

Crea una configuración de lenguaje natural

Para usar el lenguaje natural de AlloyDB AI, asegúrate de que el extremo de Vertex AI esté configurado. Luego, creas una configuración y registras un esquema. g_alloydb_ai_nl.g_create_configuration crea el modelo.

Crea una configuración de lenguaje natural.

SELECT alloydb_ai_nl.g_create_configuration( 'nla_demo_cfg' );

Registra tablas en la configuración de 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}'
);

Crea y aplica contexto para tablas y columnas

Para proporcionar respuestas precisas a preguntas en lenguaje natural, usa la API de lenguaje natural de AlloyDB AI para proporcionar contexto sobre tablas, vistas y columnas. Puedes usar la función de generación de contexto automatizada de la API de lenguaje natural de AlloyDB AI para generar contexto a partir de tablas y columnas, y aplicar el contexto como COMMENTS adjunto a tablas, vistas y columnas.

Para generar contextos de esquema para las tablas y sus columnas que se registran en la configuración de nla_demo_cfg, ejecuta lo siguiente:
```
SELECT alloydb_ai_nl.generate_schema_context(
  'nla_demo_cfg',
  TRUE
);
```
La consulta anterior propaga la vista alloydb_ai_nl.generated_schema_context_view con contexto. Si pasas TRUE, se reemplaza el contexto de esta vista de ejecuciones anteriores.

Para verificar el contexto generado para la tabla nla_demo.products, ejecuta la siguiente consulta:

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

El contexto resultante es similar al siguiente:

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

Para verificar el contexto generado para una columna, como nla_demo.products.name, ejecuta el siguiente comando:

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

El resultado de la consulta es similar al siguiente:

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.

Revisa el contexto generado en la vista alloydb_ai_nl.generated_schema_context_view y actualiza el contexto que necesite revisión.

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

Aplica el contexto generado que se adjuntará a los objetos correspondientes:
```
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
);
```
Las entradas de contexto resultantes en la vista alloydb_ai_nl.generated_schema_context_view se aplican a los objetos de esquema correspondientes, y se reemplazan los comentarios.

Construye el índice de valor

La API de lenguaje natural de AlloyDB AI produce consultas en SQL precisas con la vinculación de valores. La vinculación de valores asocia frases de valor en instrucciones de lenguaje natural con tipos de conceptos y nombres de columnas registrados previamente, lo que puede enriquecer la pregunta en lenguaje natural.

Por ejemplo, la pregunta "Dame el precio de una sudadera" se puede responder con mayor precisión si Hoodie se asocia con un concepto product_name, que se asocia con el nla_demo.products.name. columna.

Para definir el tipo de concepto product_name y asociarlo con la columna nla_demo.products.name, ejecuta las siguientes consultas:

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

Para verificar que el tipo de concepto product_name se agregó a la lista de tipos de conceptos, ejecuta la siguiente consulta para asegurarte de que product_name se incluya en el resultado de esta consulta:
```
SELECT alloydb_ai_nl.list_concept_types();
```
Para verificar que la columna nla_demo.products.name esté asociada con el tipo de concepto product_name, ejecuta la siguiente consulta:
```
SELECT *
FROM alloydb_ai_nl.value_index_columns
WHERE column_names = 'nla_demo.products.name';
```

Para definir el tipo de concepto brand_name y asociarlo con la columna nla_demo.brands.brand_name, ejecuta las siguientes consultas:

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

Después de definir los tipos de conceptos y asociarles columnas, crea un índice de valores.

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

Cómo definir una plantilla de consulta

Puedes definir plantillas para mejorar la calidad de las respuestas que produce la API de lenguaje natural de AlloyDB AI.

Para proporcionar plantillas de ejemplo para preguntas críticas para la empresa y preguntas anticipadas para las que se espera una alta precisión, ejecuta la siguiente consulta para agregar una plantilla:

SELECT alloydb_ai_nl.add_template(
    nl_config_id => 'nla_demo_cfg',
    intent => 'List 3 products most similar to a Swimwear.',
    sql => $$SELECT name FROM nla_demo.products
            ORDER BY description_embedding <=> embedding('text-embedding-004', 'Swimwear')::vector LIMIT 3$$,
    sql_explanation => $$To answer this question, ORDER products in `nla_demo.products` , based by their distance of the descrption_embedding of the product with the embedding of 'Swimwear'. Return the name of top 3 products, based on the distance of the description_embedding with 'Swimwear'.$$,
    check_intent => TRUE
);

Para ver la lista de plantillas agregadas, consulta alloydb_ai_nl.template_store_view:

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

Se mostrará el siguiente resultado:

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.

En esta plantilla, el valor correspondiente al atributo psql es la consulta en SQL parametrizada, y el valor de la columna pintent es la instrucción de intent parametrizada. El id de una plantilla agregada recientemente puede ser diferente, según las plantillas que se agregaron antes. Las plantillas se usan para proporcionar respuestas muy precisas a las preguntas.

Generar resultados en SQL a partir de preguntas en lenguaje natural

Para usar la API de lenguaje natural de AlloyDB AI y generar consultas en SQL y conjuntos de resultados, ejecuta la siguiente consulta:

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

Se mostrará el siguiente resultado:

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

El resultado en formato JSON es una consulta en SQL que usa la plantilla que agregaste en Define una plantilla de consulta.

Para usar la API de lenguaje natural de AlloyDB AI y generar consultas en SQL, ejecuta la siguiente consulta:

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

Se mostrará el siguiente resultado:

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

La API de lenguaje natural de AlloyDB AI reconoce que CymbalShoe es el nombre del producto a través del índice de valores. Reemplazar CymbalShoe por un nombre de marca (CymbalPrime) en la siguiente búsqueda:

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

produce el siguiente resultado:

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 usa el índice de valores creado en Cómo construir el índice de valores para resolver CymbalPrime en el tipo de concepto brand_name y usa la columna nla_demo.brands.brand_name asociada a brand_name.

Para usar la API de lenguaje natural de AlloyDB AI y producir el resultado de una pregunta, ejecuta la siguiente consulta:

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

Se mostrará el siguiente resultado:

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

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

En las siguientes secciones, se describe cómo borrar estos recursos y objetos.

Borra el clúster

Cuando borras el clúster que creaste en Antes de comenzar, también se borran todos los objetos que creaste.

En la consola de Google Cloud , ve a la página Clústeres.

Ir a los clústeres
Haz clic en el nombre de tu clúster, my-cluster, en la columna Nombre del recurso.
Haz clic en Borrar clúster.
En Delete cluster my-cluster, ingresa my-cluster para confirmar que deseas borrar el clúster.
Haz clic en Borrar.
Si creaste una conexión privada cuando creaste un clúster, ve a la Google Cloud consola página Redes de VPC y haz clic en Borrar red de VPC.

Borra los objetos

Puedes conservar los recursos que configuraste en Antes de comenzar y borrar solo los objetos que creaste en el proyecto Google Cloud .

Para quitar la plantilla que definiste en Define una plantilla de consulta, ejecuta la siguiente consulta:

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

Para quitar el tipo de concepto product_name que definiste en Construye el índice de valores, ejecuta la siguiente consulta:
```
SELECT alloydb_ai_nl.drop_concept_type('product_name');
```
Para actualizar el índice de valores después de quitar el tipo de concepto product_name, ejecuta la siguiente consulta:
```
SELECT alloydb_ai_nl.refresh_value_index();
```
Para quitar la configuración de nla_demo_cfg que creaste en Crea una configuración en lenguaje natural, ejecuta la siguiente consulta:
```
SELECT
alloydb_ai_nl.g_manage_configuration(
    'drop_configuration',
    'nla_demo_cfg'
);
```
Para quitar el esquema y las tablas de nla_demo que creaste y propagaste en Crea el esquema y las tablas de nla_demo y Propaga las tablas en el esquema de nla_demo, ejecuta la siguiente consulta:
```
DROP SCHEMA nla_demo CASCADE;
```

¿Qué sigue?

Obtén información sobre los casos de uso y las capacidades clave del lenguaje natural de AlloyDB AI.
Genera consultas en SQL que responden preguntas en lenguaje natural.

Usa el lenguaje natural de AlloyDB AI para generar SQL Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Objetivos

Costos

Antes de comenzar

Solicitar acceso

Habilita la facturación y las APIs obligatorias

Crea una base de datos y conéctate a ella

Instala la extensión requerida

Crea el esquema y las tablas de nla_demo

Cómo propagar tablas en el esquema nla_demo

Crea una configuración de lenguaje natural

Crea y aplica contexto para tablas y columnas

Construye el índice de valor

Cómo definir una plantilla de consulta

Generar resultados en SQL a partir de preguntas en lenguaje natural

Limpia

Borra el clúster

Borra los objetos

¿Qué sigue?

Usa el lenguaje natural de AlloyDB AI para generar SQL