Realiza una búsqueda vectorial

Vector Search en AlloyDB para PostgreSQL te permite encontrar registros semánticamente similares almacenando y consultando embeddings de vectores en tu base de datos. En este instructivo, configurarás una tabla de base de datos, cargarás embeddings de vectores de muestra, crearás un índice de ScaNN y ejecutarás consultas de similitud de vectores con la consola de Google Cloud . Los ejemplos de este instructivo se proporcionan solo con fines de demostración.

Para obtener información sobre cómo usar la búsqueda de vectores filtrada para definir mejor tus búsquedas de similitud, consulta Búsqueda de vectores filtrada en AlloyDB para PostgreSQL.

Para aprender a realizar una Vector Search con embeddings de Gemini Enterprise Agent Platform, consulta Comienza a usar embeddings de vectores con AlloyDB AI.

Objetivos

• Crear un clúster y una instancia principal de AlloyDB
• Conéctate a tu base de datos e instala las extensiones necesarias.
• Crea una tabla product y product inventory.
• Inserta datos en las tablas product y product inventory, y realiza una búsqueda vectorial básica.
• Crea un índice de ScaNN en la tabla products.
• Realizar una búsqueda vectorial básica
• Realizar una Vector Search compleja con un filtro y una unión.

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

Nota: AlloyDB no cobra por las llamadas a funciones de IA. Sin embargo, cuando llamas a modelos y servicios de Gemini Enterprise Agent Platform, de terceros o alojados de forma independiente desde tu base de datos, el proveedor del modelo o de la infraestructura te cobra directamente. Para obtener más información sobre los costos de Gemini Enterprise Agent Platform, consulta Precios.

Nota: Si ya realizaste los pasos de esta sección, ve directamente a Inserta datos de productos y de inventario de productos, y realiza una búsqueda de vectores básica y continúa con el instructivo.

Habilita la facturación y las APIs requeridas

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

   Ir al selector de proyectos

2. Asegúrate de tener habilitada la facturación para tu proyecto de Google Cloud .

3. Habilita las API de Cloud necesarias para crear AlloyDB para PostgreSQL y conectarte a él.

   Habilita las APIs

   1. En el paso Confirmar proyecto, haz clic en Siguiente 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
      • API de Compute Engine
      • API de Service Networking
      • API de Agent Platform

Crea un clúster y una instancia principal de AlloyDB

Nota: Algunas regiones que están disponibles para AlloyDB no están disponibles para los modelos de embedding de texto de Agent Platform. Para saber qué funciones de Agent Platform están disponibles en cada región de Agent Platform, consulta Ubicaciones de los servicios de aprendizaje automático.

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

   Ir a los clústeres

2. Haga clic en Crear clúster.

3. En ID del clúster, ingresa my-cluster.

4. Ingresa una contraseña. Toma nota de esta contraseña, ya que la usarás en este instructivo.

5. Selecciona una región, por ejemplo, us-central1 (Iowa).

6. Selecciona la red predeterminada.

   Si tienes una conexión de acceso privado, continúa con el siguiente paso. De lo contrario, haz clic en Configurar conexión y sigue estos pasos:

   1. En Asigna un rango de IP, haz clic en Usar un rango de IP asignado automáticamente.
   2. Haz clic en Continuar y, luego, en Crear conexión.

7. En Disponibilidad zonal, selecciona Zona única.

8. Selecciona el tipo de máquina 2 vCPU,16 GB.

9. En Conectividad, selecciona Habilitar IP pública.

10. Haga clic en Crear clúster. Es posible que AlloyDB tarde varios minutos en crear el clúster y mostrarlo en la página Descripción general del clúster principal.

11. En Instancias en tu clúster, expande el panel Conectividad. Toma nota del URI de conexión, ya que lo usarás en este instructivo.

    El URI de conexión tiene el formato projects/PROJECT_ID/locations/REGION_ID/clusters/my-cluster/instances/my-cluster-primary.

Otorga el permiso de usuario de Agent Platform al agente de servicio de AlloyDB

Para permitir que AlloyDB use los modelos de embedding de texto de Agent Platform, debes agregar permisos de usuario de Agent Platform al agente de servicio de AlloyDB para el proyecto en el que se encuentran el clúster y la instancia.

Para obtener más información sobre cómo agregar los permisos, consulta Otorga el permiso de usuario de Agent Platform al agente de servicio de AlloyDB.

Conéctate a tu base de datos con un navegador web

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

   Ir a los clústeres

2. En la columna Nombre del recurso, haz clic en el nombre de tu clúster, my-cluster.

3. En el panel de navegación, haz clic en AlloyDB Studio.

4. En la página Accede a AlloyDB Studio, sigue estos pasos:

   1. Selecciona la base de datos postgres.
   2. Selecciona el usuario postgres.
   3. Ingresa la contraseña que creaste en Crea un clúster y su instancia principal.
   4. Haz clic en Autenticar. En el panel Explorador, se muestra una lista de los objetos de la base de datos postgres.

5. Para abrir una pestaña nueva, haz clic en + Nueva pestaña del editor de SQL o + Nueva pestaña.

Instala las extensiones necesarias

Ejecuta la siguiente consulta para instalar las extensiones vector y alloydb_scann:

  CREATE EXTENSION IF NOT EXISTS vector;
  CREATE EXTENSION IF NOT EXISTS alloydb_scann;

Inserta datos de productos y de inventario de productos, y realiza una búsqueda de vectores básica

1. Ejecuta la siguiente sentencia para crear una tabla product que haga lo siguiente:

   • Almacena información básica del producto.
   • Incluye una columna de vector embedding que calcula y almacena un vector de embedding para una descripción de cada producto.
   Nota: Si tienes más de 100,000 filas en una tabla, no te recomendamos usar la función embedding() para generar incorporaciones almacenadas en datos existentes en una tabla. Es más adecuado para la generación de incorporaciones intercaladas.

     CREATE TABLE product (
       id INT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       description TEXT,
       category VARCHAR(255),
       color VARCHAR(255),
       embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-005', description)) STORED
     );
   

   Si es necesario, puedes usar el Explorador de registros para ver los registros y solucionar problemas.

2. Ejecuta la siguiente consulta para crear una tabla product_inventory que almacene información sobre el inventario disponible y los precios correspondientes. En este instructivo, se usan las tablas product_inventory y product para ejecutar consultas de búsqueda de vectores complejas.

   CREATE TABLE product_inventory (
     id INT PRIMARY KEY,
     product_id INT REFERENCES product(id),
     inventory INT,
     price DECIMAL(10,2)
   );
   

3. Ejecuta la siguiente consulta para insertar datos de productos en la tabla product:

   INSERT INTO product (id, name, description,category, color) VALUES
   (1, 'Stuffed Elephant', 'Soft plush elephant with floppy ears.', 'Plush Toys', 'Gray'),
   (2, 'Remote Control Airplane', 'Easy-to-fly remote control airplane.', 'Vehicles', 'Red'),
   (3, 'Wooden Train Set', 'Classic wooden train set with tracks and trains.', 'Vehicles', 'Multicolor'),
   (4, 'Kids Tool Set', 'Toy tool set with realistic tools.', 'Pretend Play', 'Multicolor'),
   (5, 'Play Food Set', 'Set of realistic play food items.', 'Pretend Play', 'Multicolor'),
   (6, 'Magnetic Tiles', 'Set of colorful magnetic tiles for building.', 'Construction Toys', 'Multicolor'),
   (7, 'Kids Microscope', 'Microscope for kids with different magnification levels.', 'Educational Toys', 'White'),
   (8, 'Telescope for Kids', 'Telescope designed for kids to explore the night sky.', 'Educational Toys', 'Blue'),
   (9, 'Coding Robot', 'Robot that teaches kids basic coding concepts.', 'Educational Toys', 'White'),
   (10, 'Kids Camera', 'Durable camera for kids to take pictures and videos.', 'Electronics', 'Pink'),
   (11, 'Walkie Talkies', 'Set of walkie talkies for kids to communicate.', 'Electronics', 'Blue'),
   (12, 'Karaoke Machine', 'Karaoke machine with built-in microphone and speaker.', 'Electronics', 'Black'),
   (13, 'Kids Drum Set', 'Drum set designed for kids with adjustable height.', 'Musical Instruments', 'Blue'),
   (14, 'Kids Guitar', 'Acoustic guitar for kids with nylon strings.', 'Musical Instruments', 'Brown'),
   (15, 'Kids Keyboard', 'Electronic keyboard with different instrument sounds.', 'Musical Instruments', 'Black'),
   (16, 'Art Easel', 'Double-sided art easel with chalkboard and whiteboard.', 'Arts & Crafts', 'White'),
   (17, 'Finger Paints', 'Set of non-toxic finger paints for kids.', 'Arts & Crafts', 'Multicolor'),
   (18, 'Modeling Clay', 'Set of colorful modeling clay.', 'Arts & Crafts', 'Multicolor'),
   (19, 'Watercolor Paint Set', 'Watercolor paint set with brushes and palette.', 'Arts & Crafts', 'Multicolor'),
   (20, 'Beading Kit', 'Kit for making bracelets and necklaces with beads.', 'Arts & Crafts', 'Multicolor'),
   (21, '3D Puzzle', '3D puzzle of a famous landmark.', 'Puzzles', 'Multicolor'),
   (22, 'Race Car Track Set', 'Race car track set with cars and accessories.', 'Vehicles', 'Multicolor'),
   (23, 'RC Monster Truck', 'Remote control monster truck with oversized tires.', 'Vehicles', 'Green'),
   (24, 'Train Track Expansion Set', 'Expansion set for wooden train tracks.', 'Vehicles', 'Multicolor');
   

4. Opcional: Ejecuta la siguiente consulta para verificar que los datos se inserten en la tabla product:

   SELECT * FROM product;
   

5. Ejecuta la siguiente consulta para insertar datos de inventario en la tabla product_inventory:

   INSERT INTO product_inventory (id, product_id, inventory, price) VALUES
   (1, 1, 9, 13.09),
   (2, 2, 40, 79.82),
   (3, 3, 34, 52.49),
   (4, 4, 9, 12.03),
   (5, 5, 36, 71.29),
   (6, 6, 10, 51.49),
   (7, 7, 7, 37.35),
   (8, 8, 6, 10.87),
   (9, 9, 7, 42.47),
   (10, 10, 3, 24.35),
   (11, 11, 4, 10.20),
   (12, 12, 47, 74.57),
   (13, 13, 5, 28.54),
   (14, 14, 11, 25.58),
   (15, 15, 21, 69.84),
   (16, 16, 6, 47.73),
   (17, 17, 26, 81.00),
   (18, 18, 11, 91.60),
   (19, 19, 8, 78.53),
   (20, 20, 43, 84.33),
   (21, 21, 46, 90.01),
   (22, 22, 6, 49.82),
   (23, 23, 37, 50.20),
   (24, 24, 27, 99.27);
   

6. Ejecuta la siguiente consulta de búsqueda de vectores que intenta encontrar productos que sean similares a la palabra music. Esto significa que, aunque la palabra music no se mencione de forma explícita en la descripción del producto, el resultado muestra productos que son relevantes para la consulta:

   SELECT * FROM product
   ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
   LIMIT 3;
   

   El resultado de la consulta es el siguiente:

   Realizar una búsqueda de vectores básica sin crear un índice usa la búsqueda de vecino más cercano exacta (KNN), que proporciona una recuperación eficiente. A gran escala, el uso de KNN podría afectar el rendimiento. Para obtener un mejor rendimiento de las consultas, te recomendamos que uses el índice ScaNN para la búsqueda de vecinos más cercanos aproximados (ANN), que proporciona una alta recuperación con latencias bajas.

   Sin crear un índice, AlloyDB usa de forma predeterminada la búsqueda exacta de vecino más cercano (KNN).

   Para obtener más información sobre el uso de ScaNN a gran escala, consulta Comienza a usar embeddings de vectores con AlloyDB AI.

Crea un índice de ScaNN ajustado de forma manual en la tabla de productos

Importante: Los ejemplos de este instructivo solo tienen fines de demostración. Te recomendamos que solo crees índices de ScaNN en tablas que superen los 10,000 registros.

Ejecuta la siguiente consulta para crear un índice de ScaNN de product_index en la tabla product:

CREATE INDEX product_index ON product
USING scann (embedding cosine)
WITH (mode='MANUAL', num_leaves=4);

Para obtener más información sobre cómo crear un índice de ScaNN, consulta Crea un índice de ScaNN.

Realiza una búsqueda de vectores

Ejecuta la siguiente consulta de búsqueda de vectores que intenta encontrar productos similares a la consulta en lenguaje natural music. Aunque la palabra music no se incluye en la descripción del producto, el resultado muestra productos que son relevantes para la consulta:

SET LOCAL scann.num_leaves_to_search = 2;

SELECT * FROM product
ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
  LIMIT 3;

Los resultados de la consulta son los siguientes:

El parámetro de consulta scann.num_leaves_to_search controla la cantidad de nodos de hoja que se buscan durante una búsqueda de similitud. Los valores de los parámetros num_leaves y scann.num_leaves_to_search ayudan a lograr un equilibrio entre el rendimiento y la recuperación.

Realiza una búsqueda de vectores que use un filtro y una unión

Puedes ejecutar consultas de búsqueda de vectores filtradas de manera eficiente, incluso cuando usas el índice de ScaNN. Ejecuta la siguiente consulta de búsqueda de vectores compleja, que devuelve resultados pertinentes que cumplen con las condiciones de la consulta, incluso con filtros:

SET LOCAL scann.num_leaves_to_search = 2;

SELECT * FROM product p
JOIN product_inventory pi ON p.id = pi.product_id
WHERE pi.price < 80.00
ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
LIMIT 3;

Acelera tu búsqueda de vectores filtrada

Puedes usar el almacén de contenido del motor de columnas para mejorar el rendimiento de las búsquedas de similitud de vectores, específicamente las búsquedas de vecino más cercano (KNN), cuando se combinan con un filtrado de predicados altamente selectivo, por ejemplo, con LIKE, en las bases de datos. En esta sección, usarás la extensión vector y la extensión google_columnar_engine de AlloyDB. Para obtener más información sobre cómo funciona el motor de columnas, consulta Acerca del motor de columnas de AlloyDB.

Las mejoras de rendimiento provienen de la eficiencia integrada del motor de columnas para analizar grandes conjuntos de datos y aplicar filtros, como los predicados LIKE, junto con su capacidad, con la compatibilidad con vectores, de prefiltrado de las filas. Esta funcionalidad reduce la cantidad de subconjuntos de datos necesarios para los cálculos posteriores de distancia de vectores de KNN y ayuda a optimizar las consultas analíticas complejas que involucran el filtrado estándar y la búsqueda de vectores.

El almacén de columnas ofrece dos opciones para administrar su contenido:

• Administra automáticamente el contenido del almacén de columnas: Las instancias nuevas de AlloyDB usan la estructuración automática en columnas de forma predeterminada. Como alternativa, puedes ejecutar de forma manual la función de estructuración automática en columnas.
• Administra el contenido del almacén de columnas de forma manual: Si necesitas administrar de forma manual las columnas en el almacén de columnas para tu carga de trabajo, puedes inhabilitar la estructuración automática en columnas.

Para comparar el tiempo de ejecución de una búsqueda de vectores de KNN filtrada por un predicado LIKE antes y después de habilitar el motor de columnas, sigue estos pasos:

1. Habilita la extensión vector para admitir tipos de datos y operaciones de vectores. Ejecuta las siguientes declaraciones para crear una tabla de ejemplo (items) con un ID, una descripción de texto y una columna de embedding de vector de 512 dimensiones.

   CREATE EXTENSION IF NOT EXISTS vector;
   
   CREATE TABLE items (
       id SERIAL PRIMARY KEY,
       description TEXT,
       embedding VECTOR(512)
   );
   

2. Ejecuta las siguientes declaraciones para insertar 1 millón de filas en la tabla items de ejemplo y propagar los datos.

   -- Simplified example of inserting matching (~0.1%) and non-matching data
   INSERT INTO items (description, embedding)
   SELECT
       CASE WHEN g % 1000 = 0 THEN 'product_' || md5(random()::text) || '_common' -- ~0.1% match
       ELSE 'generic_item_' || g || '_' || md5(random()::text)    -- ~99.9% don't match
       END,
       random_vector(512) -- Assumes random_vector function exists
   FROM generate_series(1, 999999) g;
   

3. Mide el rendimiento de referencia de la búsqueda de similitud de vectores sin el motor de columnas.

   SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

4. Habilita el motor de columnas y la compatibilidad con vectores ejecutando el siguiente comando en la Google Cloud CLI. Para usar gcloud CLI, puedes instalarla e inicializarla.

   gcloud alloydb instances update INSTANCE_ID \
       --cluster=CLUSTER_ID \
       --region=REGION_ID \
       --project=PROJECT_ID \
       --database-flags=google_columnar_engine.enabled=on,google_columnar_engine.enable_vector_support=on

   Reemplaza lo siguiente:

   • INSTANCE_ID: el ID de la instancia
   • CLUSTER_ID: Es el ID del clúster.
   • REGION_ID: Es la región en la que se encuentra el clúster.
   • PROJECT_ID: Es el ID del proyecto en el que se encuentra el clúster.

5. Agrega la tabla items al motor de columnas:

   SELECT google_columnar_engine_add('items');
   

6. Medir el rendimiento de la búsqueda de similitud de vectores con el motor de columnas Vuelve a ejecutar la consulta que ejecutaste antes para medir el rendimiento de referencia.

   SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

7. Para verificar si la consulta se ejecutó con el motor de columnas, ejecuta el siguiente comando:

   explain (analyze) SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

Realiza una limpieza

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

   Ir a los clústeres

2. Haz clic en el nombre de tu clúster, my-cluster, en la columna Nombre del recurso.

3. Haz clic en Borrar clúster.

4. En Borrar el clúster my-cluster, ingresa my-cluster para confirmar que deseas borrar el clúster.

5. Haz clic en Borrar.

6. Si creaste una conexión privada cuando creaste un clúster, ve a la página Herramientas de redes de la consola de Google Cloud y haz clic en Borrar red de VPC.

¿Qué sigue?

• Conoce los casos de uso reales de la búsqueda de vectores.
• Comienza a usar embeddings de vectores con AlloyDB AI.
• Aprende a compilar aplicaciones de IA generativa con AlloyDB AI.
• Crea un índice de ScaNN.
• Ajusta tus índices de ScaNN.
• Aprende a crear un asistente de compras inteligente con AlloyDB, pgvector y la administración de extremos de modelos.
• Acelera la búsqueda de vectores con el motor de columnas.