Busca y filtra con embeddings de vectores

En esta página, se describen las diferentes formas en que puedes consultar los embeddings de vector. Para obtener una descripción general de las búsquedas de similitud de ANN y KNN, consulta Búsquedas de vectores.

Antes de comenzar

Habilita la marca de base de datos cloudsql_vector en tu instancia de Cloud SQL.

En el caso de las instancias que usan Cloud SQL para MySQL 9.7 o versiones posteriores, aunque no es necesario habilitar cloudsql_vector para crear y almacenar embeddings de vector, debes habilitar la marca de base de datos cloudsql_vector en tu instancia de Cloud SQL para crear índices de vectores y realizar búsquedas ANN en tus datos vectoriales.

Busca vecinos más cercanos aproximados (ANN)

Para realizar una búsqueda ANN, usa la approx_distance función en una SELECT y ORDER BY cláusula. Debes usar una cláusula LIMIT en una búsqueda ANN. También puedes obtener el valor de distancia colocando approx_distance en una lista SELECT.

Usa la siguiente sintaxis para las consultas ANN:

# Ordering by distance
SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=l2_squared')
LIMIT 4;

# Selecting the distance value
SELECT
  approx_distance(
    embedding_name,
    string_to_vector('[1,2,3]'),
    'distance_measure=cosine,num_leaves_to_search=3')
    dist
FROM table
ORDER BY dist
LIMIT limit_value;

La función approx_distance usa las siguientes opciones:

  • embedding: Usa el nombre de la columna de embeddings de vector de la tabla base.
  • string_to_vector o vector_to_string: Convierte un vector en una cadena y una cadena en un vector para que el vector sea legible para las personas.
  • distance_measure: Especifica la medida de distancia que se usará para una búsqueda de similitud de vectores. Este valor debe coincidir con el valor que estableciste en el parámetro distance_measure cuando creaste el índice. Este parámetro es obligatorio. Los valores posibles para este parámetro son los siguientes:
    • COSINE
    • L2_SQUARED
    • DOT_PRODUCT
  • num_leaves_to_search: Opcional. Especifica la cantidad de hojas que se sondearán para una búsqueda de similitud de vectores ANN. Si no especificas la cantidad de hojas, Cloud SQL usa un valor generado según el tamaño de la tabla, la cantidad de hojas en el índice de vectores y otros factores. Puedes ver este valor en information_schema.innodb_vector_indexes. Te recomendamos que ajustes num_leaves_to_search para lograr el mejor equilibrio entre la calidad de la búsqueda y el rendimiento para tu carga de trabajo específica. Si se aumenta, afecta el rendimiento, pero mejora la recuperación.

En el siguiente ejemplo, se muestra cómo usar approx_distance para encontrar las K filas más cercanas con la medida de distancia l2_squared y ordenar los resultados por distancia.

# Ordering by distance
SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'),
                         'distance_measure=l2_squared')
LIMIT 4;

# Selecting the distance value
SELECT
    approx_distance
        (embedding, string_to_vector('[1,2,3]'),
         'distance_measure=l2_squared') dist
FROM table
ORDER BY dist
LIMIT 4;

Filtra los resultados de las consultas approx_distance

Puedes usar la función approx_distance con condiciones WHERE que filtran los resultados de la consulta con un predicado no vectorial para realizar el filtrado posterior. La función approx_distance se evalúa antes de aplicar el filtro, lo que significa que la cantidad de resultados que se muestran no es determinista.

Por ejemplo, en la siguiente consulta:

SELECT id FROM products WHERE price < 100
ORDER BY approx_distance(embedding, @query_vector,'distance_measure=cosine')
LIMIT 11;

La función approx_distance muestra los 11 vecinos más cercanos al vector de consulta, independientemente del precio. En el filtrado posterior, se seleccionan los productos con un precio < 100. Es posible que todos los vecinos más cercanos tengan un precio < 100, por lo que hay 11 resultados para la consulta. Como alternativa, si ninguno de los vecinos más cercanos tiene un precio < 100, se muestran 0 filas.

Si prevés que tu filtro en la condición WHERE es muy selectivo, una búsqueda exacta (KNN) es una opción para garantizar que se muestre una cantidad suficiente de filas.

Otra opción es usar el filtrado iterativo para analizar más del índice de búsqueda ANN.

Usa el filtrado iterativo para aumentar los resultados de la búsqueda ANN

Puedes usar el filtrado iterativo cuando los filtros selectivos de la cláusula WHERE en tu consulta de búsqueda ANN producen menos resultados que la cantidad de resultados especificada en tu cláusula LIMIT.

Por ejemplo, en la siguiente consulta, cuando habilitas el filtrado iterativo, la consulta analiza más del índice de vectores, menos el primer conjunto de resultados filtrados.

EXPLAIN FORMAT=TREE
SELECT * FROM t1 WHERE next_id BETWEEN 15 AND 100
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=l2_squared')
LIMIT 10;

EXPLAIN
-> Limit: 10 row(s)  (rows=10)
   -> Vector index loop with iterative filtering
      -> Vector index scan on t1
      -> Filter: (t1.next_id between 15 and 100)
         -> Single-row index lookup on t1 using PRIMARY (id=t1.id)

Recuperas más vecinos del índice de vectores de búsqueda de forma iterativa hasta que se alcanza el máximo configurado (cloudsql_vector_iterative_filtering_max_neighbors). Cualquier coincidencia de filtro se cuenta para LIMIT y se quita de los análisis adicionales del índice de vectores.

Habilita el filtrado iterativo

De forma predeterminada, el filtrado iterativo está desactivado para todas las sesiones y las instancias de Cloud SQL.

Para habilitar el filtrado iterativo para una sesión existente, usa la siguiente instrucción de SQL.

SET SESSION cloudsql_vector_iterative_filtering=on;

También puedes habilitar el filtrado iterativo de forma global para todas las sesiones de cliente que se conectan a la instancia configurando la marca en la instancia. Para configurar una marca para una instancia, consulta Configura una marca de base de datos.

Para obtener más información sobre cómo configurar variables de sistema a nivel de sesión o global, consulta Uso de variables de sistema en la documentación de MySQL.

Ajusta el filtrado iterativo

Para controlar cuántos vecinos más cercanos se muestran para una consulta de búsqueda ANN con el filtrado iterativo habilitado, puedes usar la variable de sistema global o de sesión cloudsql_vector_iterative_filtering_max_neighbors. Puedes usar esta configuración para aumentar la cantidad de vecinos más cercanos que se solicitan. Sin embargo, para evitar almacenar demasiados resultados en la memoria, el máximo para esta variable es 1000.

Para configurar esta variable para una sesión, usa la siguiente instrucción de SQL:

SET cloudsql_vector_iterative_filtering_max_neighbors=600;

El valor predeterminado es 500 y el número mínimo es 10.

Limitaciones

Las siguientes son limitaciones del uso del filtrado iterativo:

  • No es una garantía: Cuando usas el filtrado iterativo, Cloud SQL intenta encontrar la cantidad de resultados especificada en la cláusula LIMIT, pero no garantiza que se encuentre la cantidad. Esto puede suceder si se alcanza la cantidad máxima de vecinos (cloudsql_vector_iterative_filtering_max_neighbors) antes de que se cumpla LIMIT o si no hay suficientes filas que coincidan con el filtro en la tabla.

  • Consultas complejas: El filtrado iterativo solo funciona cuando los predicados de filtro se envían a la ruta de acceso de la tabla base. No se admite para filtros sobre tablas temporales, por ejemplo, tablas que usan una cláusula HAVING. En las subconsultas, solo se consideran los filtros en la tabla base dentro de la subconsulta para el filtrado iterativo.

Verifica el estado de resguardo en las búsquedas ANN

Hay ciertos casos en los que una búsqueda ANN recurre a una búsqueda KNN. Estos incluyen los siguientes:

  • No hay ningún índice de vectores en la tabla base.
  • Hay un índice de vectores en la tabla base, pero usa una medida de distancia diferente del parámetro distance_measure en las opciones de búsqueda approx_distance.
  • El índice de vectores está dañado o no es visible para la transacción actual.
  • El LIMIT especificado es mayor que 10,000.
  • No se especificó ningún LIMIT.
  • La consulta actual implica más de una llamada approx_distance en la misma tabla base.
  • El optimizador calcula que es más eficiente usar KNN.

En todos estos casos, se envía una advertencia al cliente que indica que se realizó una búsqueda exacta y el motivo.

Usa el siguiente comando en el cliente mysql para ver el estado de resguardo:

SHOW global status LIKE '%cloudsql_vector_knn_fallback%';

Si quieres usar ANN y recurre a KNN, es posible que la consulta se ejecute más lento. Debes encontrar el motivo por el que recurre y evaluar si debes realizar cambios para que se use ANN en su lugar.

Ejemplo: Crea un índice de vectores y ejecuta una consulta ANN

En la siguiente explicación de ejemplo, se proporcionan pasos para crear un índice de vectores y ejecutar una consulta ANN en Cloud SQL.

  1. Genera embeddings de vectores. Puedes crear embeddings de vectores de forma manual o usar una API de embedding de texto que elijas. Para ver un ejemplo que usa Vertex AI, consulta Genera embeddings de vectores según los datos de la fila.

  2. Crea una tabla en Cloud SQL que contenga una columna de embeddings de vector con tres dimensiones.

    CREATE TABLE books(
id INTEGER PRIMARY KEY AUTO_INCREMENT, title VARCHAR(60), embedding VECTOR(3) USING VARBINARY);

  3. Inserta un embedding de vectores en la columna.

    INSERT INTO books VALUES ((1, 'book title', string_to_vector('[1,2,3]')));

  4. Confirma los cambios.

    commit;

  5. Crea el índice de vectores con la función L2_squared para medir la distancia.

    CREATE
  VECTOR INDEX vectorIndex
ON dbname.books(embeddings)
USING SCANN QUANTIZER = SQ8 DISTANCE_MEASURE = l2_squared;

  6. Usa la siguiente sintaxis para realizar una búsqueda ANN con un LIMIT de 4 resultados de búsqueda:

    SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=l2_squared')
LIMIT 4;

SELECT approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=cosine') dist
FROM books
ORDER BY dist
LIMIT 4;

Busca K vecinos más cercanos (KNN)

Para realizar una búsqueda de K vecinos más cercanos, usa la vector_distance función con una opción de medida de distancia y una función de conversión de vectores (string_to_vector o vector_to_string) en una SELECT instrucción. Usa la siguiente sintaxis:

SELECT vector_distance(string_to_vector('[1,2,3]'),
                      string_to_vector('[1,2,3]'),
                      'Distance_Measure=dot_product');

Reemplaza los valores [1,2,3] por los valores de embedding de tus datos.

En el siguiente ejemplo, se muestra cómo usar esta consulta con la función cosine_distance y la función de conversión de vectores string_to_vector.

SELECT id,cosine_distance(embedding, string_to_vector('[1,2,3]')) dist
FROM books
ORDER BY distance
LIMIT 10;

Obtén la distancia de coseno en una consulta KNN

Usa la función cosine_distance de Cloud SQL para calcular la distancia con el coseno.

SELECT cosine_distance(embedding, string_to_vector('[3,1,2]')) AS distance FROM books WHERE id = 10;

Obtén la distancia del producto escalar en una consulta KNN

Usa la función dot_product de Cloud SQL para calcular la distancia con el producto escalar.

SELECT dot_product(embedding, string_to_vector('[3,1,2]')) AS distance FROM books WHERE id = 10;

Obtén la distancia de L2 al cuadrado en una consulta KNN

Usa la función l2_squared_distance de Cloud SQL para calcular la distancia con L2 al cuadrado.

SELECT
  l2_squared_distance(embedding, string_to_vector('[3,1,2]'))
    AS distance
FROM books
WHERE id = 10;

¿Qué sigue?