Crea un índice ScaNN

En esta página, se describe cómo usar los embeddings almacenados para generar índices y consultar embeddings con el índice ScaNN con AlloyDB para PostgreSQL. Para obtener más información sobre el almacenamiento de embeddings, consulta Almacena embeddings de vectores.

AlloyDB alloydb_scann, una extensión de PostgreSQL desarrollada por Google que implementa un índice de vecinos más cercanos altamente eficiente potenciado por el algoritmo ScaNN.

El índice ScaNN es un índice de cuantificación basado en un árbol para la búsqueda de vecinos más cercanos aproximados. Proporciona un tiempo de compilación de índice más bajo y una huella de memoria más pequeña en comparación con HNSW. Además, proporciona una QPS más rápida en comparación con HNSW según la carga de trabajo.

Antes de comenzar

Antes de comenzar a crear índices, debes completar los siguientes requisitos previos.

  • Los vectores de incorporación se agregan a una tabla en tu base de datos de AlloyDB.

  • Se instala la extensión vector basada en pgvector, que Google amplió para AlloyDB, y la extensión alloydb_scann:

    CREATE EXTENSION IF NOT EXISTS alloydb_scann CASCADE;

  • Si deseas crear índices de ScaNN ajustados automáticamente, asegúrate de que la marca scann.enable_preview_features esté habilitada. Si no quieres habilitar las funciones en versión preliminar o si se trata de instancias de producción, puedes crear un índice de ScaNN con parámetros específicos.

Crea un índice de ScaNN ajustado automáticamente

Con la función de indexación automática, puedes simplificar la creación de índices para crear automáticamente índices optimizados para el rendimiento de la búsqueda o tiempos de compilación de índices y rendimiento de la búsqueda equilibrados.

Cuando usas el modo AUTO, solo necesitas especificar el nombre de la tabla y la columna de embedding junto con la función de distancia que deseas usar. Puedes optimizar el índice para el rendimiento de la búsqueda o equilibrar los tiempos de compilación del índice y el rendimiento de la búsqueda.

También existe la opción de usar el modo MANUAL para crear índices con un control detallado sobre otros parámetros de ajuste del índice.

Crea un índice de ScaNN en modo AUTO

A continuación, se incluyen algunos puntos que debes tener en cuenta antes de crear índices en el modo AUTO:

  • AlloyDB no puede crear un índice ScaNN para tablas con datos insuficientes.
  • No puedes establecer parámetros de creación de índices, como num_leaves, cuando creas índices en el modo AUTO.
  • El mantenimiento automático está habilitado de forma predeterminada para todos los índices creados en el modo AUTO.

Para crear un índice en el modo AUTO, ejecuta el siguiente comando:

      CREATE INDEX INDEX_NAME ON TABLE \
      USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION) \
      WITH (mode=AUTO', optimization='OPTIMIZATION');

Reemplaza lo siguiente:

  • INDEX_NAME: Es el nombre del índice que deseas crear, por ejemplo, my-scann-index. Los nombres de los índices se comparten en toda tu base de datos. Verifica que cada nombre de índice sea único para cada tabla de tu base de datos.

  • TABLE: Es la tabla a la que se agregará el índice.

  • EMBEDDING_COLUMN: Es la columna que almacena datos vector.

  • DISTANCE_FUNCTION: Es la función de distancia que se usará con este índice. Elige una de estas opciones:

    • Distancia de L2: l2

    • Producto escalar: dot_product

    • Distancia de coseno: cosine

  • OPTIMIZATION: Configúralo con uno de los siguientes valores:

    • SEARCH_OPTIMIZED: Para optimizar la recuperación y la latencia de la búsqueda de vectores a costa de un tiempo de compilación del índice más largo.
    • BALANCED: Para crear un índice que equilibre el tiempo de compilación del índice y el rendimiento de la búsqueda

Crea un índice ScaNN en modo MANUAL

Si habilitaste la marca scann.enable_preview_features y deseas tener un control detallado sobre los parámetros de ajuste, puedes crear el índice en el modo MANUAL.

Para crear un índice ScaNN en el modo MANUAL, ejecuta el siguiente comando:

      CREATE INDEX INDEX_NAME ON TABLE \
      USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION) \
      WITH (mode='MANUAL, num_leaves=NUM_LEAVES_VALUE, [quantizer =QUANTIZER, max_num_levels=MAX_NUM_LEVELS]);

Reemplaza lo siguiente:

  • INDEX_NAME: Es el nombre del índice que deseas crear, por ejemplo, my-scann-index. Los nombres de los índices se comparten en toda tu base de datos. Verifica que cada nombre de índice sea único para cada tabla de tu base de datos.

  • TABLE: Es la tabla a la que se agregará el índice.

  • EMBEDDING_COLUMN: Es la columna que almacena datos vector.

  • DISTANCE_FUNCTION: Es la función de distancia que se usará con este índice. Elige una de estas opciones:

    • Distancia de L2: l2

    • Producto escalar: dot_product

    • Distancia de coseno: cosine

  • NUM_LEAVES_VALUE: Es la cantidad de particiones que se aplicarán a este índice. Se puede establecer en cualquier valor entre 1 y 1048576.

  • QUANTIZER: Es el tipo de cuantificador que deseas usar para el árbol de K-means. El valor predeterminado se establece en SQ8, que proporciona un mejor rendimiento de las búsquedas con una pérdida mínima de recuperación (por lo general, menos del 1 o el 2%). También puedes establecerlo en FLAT para un retiro del 99% o más.

  • MAX_NUM_LEVELS: Es la cantidad máxima de niveles del árbol de agrupamiento de K-means. Se establece en 1(predeterminado) para la cuantificación basada en árboles de dos niveles y en 2 para la cuantificación basada en árboles de tres niveles.

Puedes agregar otros parámetros de tiempo de ejecución de la creación o la consulta del índice para ajustarlo. Para obtener más información, consulta Cómo ajustar un índice de ScaNN.

Cambia los modos de los índices existentes

Si creaste un índice de ScaNN con el modo AUTO y deseas ajustarlo de forma manual, debes cambiar el modo a MANUAL.

Para cambiar el modo a MANUAL, sigue estos pasos:

  1. Actualiza el índice para establecer el modo en MANUAL:

    ALTER INDEX INDEX_NAME SET (mode = 'MANUAL', num_leaves = NUM_LEAVES_VALUE);

    Reemplaza lo siguiente:

    • INDEX_NAME: El nombre del índice que deseas crear, por ejemplo, my-scann-index. Los nombres de los índices se comparten en toda la base de datos. Verifica que cada nombre de índice sea único para cada tabla de tu base de datos.

    • NUM_LEAVES_VALUE: Es la cantidad de particiones que se aplicarán a este índice. Se puede establecer en cualquier valor entre 1 y 1048576.

    Puedes agregar otros parámetros de tiempo de ejecución de la creación o la consulta del índice para ajustarlo. Para obtener más información, consulta Cómo ajustar un índice de ScaNN.

  2. Vuelve a compilar tu índice para aplicar los parámetros:

    REINDEX INDEX CONCURRENTLY INDEX_NAME;

Para cambiar al modo AUTO, completa los siguientes pasos:

  1. Actualiza el índice para establecer el modo en AUTO:

    ALTER INDEX INDEX_NAME SET (mode = 'AUTO');

  2. Vuelve a compilar tu índice para aplicar los parámetros:

    REINDEX INDEX CONCURRENTLY INDEX_NAME;

Crea un índice ScaNN con parámetros específicos

Si tu aplicación tiene requisitos específicos para los tiempos de recuperación y de compilación del índice, puedes crear el índice de forma manual. Puedes crear un índice de árbol de dos o tres niveles según tu carga de trabajo. Para obtener más información sobre los parámetros de ajuste, consulta Cómo ajustar un índice de ScaNN.

Índice de árbol de dos niveles

Para aplicar un índice de árbol de dos niveles con el algoritmo ScaNN a una columna que contiene embeddings de vectores almacenadas, ejecuta la siguiente consulta DDL:

CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE);

Reemplaza lo siguiente:

  • INDEX_NAME: El nombre del índice que deseas crear, por ejemplo, my-scann-index. Los nombres de los índices se comparten en toda la base de datos. Asegúrate de que cada nombre de índice sea único para cada tabla de tu base de datos.

  • TABLE: Es la tabla a la que se agregará el índice.

  • EMBEDDING_COLUMN: Es una columna que almacena datos vector.

  • DISTANCE_FUNCTION: Es la función de distancia que se usará con este índice. Elige una de estas opciones:

    • Distancia de L2: l2

    • Producto escalar: dot_product

    • Distancia de coseno: cosine

  • NUM_LEAVES_VALUE: Es la cantidad de particiones que se aplicarán a este índice. Se puede establecer en cualquier valor entre 1 y 1048576. Para obtener más información sobre cómo decidir este valor, consulta Cómo ajustar un índice de ScaNN.

Índice de árbol de tres niveles

Para crear un índice de árbol de tres niveles con el algoritmo de ScaNN en una columna que contiene embeddings de vectores almacenados, ejecuta la siguiente consulta en DDL:

CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = 2);

Después de crear el índice, puedes ejecutar consultas de búsqueda de vecinos más cercanos que lo utilicen siguiendo las instrucciones en Realiza una consulta de vecino más cercano con texto determinado.

Los parámetros del índice deben establecerse para lograr un equilibrio adecuado entre las QPS y la recuperación. Para obtener más información sobre cómo ajustar el índice ScaNN, consulta Cómo ajustar un índice ScaNN.

Para crear este índice en una columna de embedding que use el tipo de datos real[] en lugar de vector, convierte la columna en el tipo de datos vector:

CREATE INDEX INDEX_NAME ON TABLE
  USING scann (CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)) DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = MAX_NUM_LEVELS);

Reemplaza DIMENSIONS por el ancho dimensional de la columna de embedding. Para obtener más información sobre cómo encontrar las dimensiones, consulta la función vector_dims en Funciones de vectores.

Para lograr una experiencia de búsqueda coherente, habilita el mantenimiento automático cuando crees un índice de ScaNN. Para obtener más información, consulta Cómo mantener índices vectoriales. Esta función está disponible en vista previa.

Para ver el progreso de la indexación, usa la vista pg_stat_progress_create_index:

SELECT * FROM pg_stat_progress_create_index;

La columna phase muestra el estado actual de la creación de tu índice. Una vez que se completa la fase de compilación del índice, no se ve la fila del índice.

Para ajustar tu índice y lograr un equilibrio entre la recuperación promedio y las QPS, consulta Cómo ajustar un índice de ScaNN.

Compila índices en paralelo

Para compilar tu índice más rápido, es posible que AlloyDB genere automáticamente varios trabajadores paralelos, según tu conjunto de datos y el tipo de índice que elijas.

La compilación de índices paralela suele activarse si creas un índice de ScaNN de 3 niveles o si tu conjunto de datos supera los 100 millones de filas.

Si bien AlloyDB optimiza automáticamente la cantidad de trabajadores paralelos, puedes ajustarlos con los parámetros de planificación de consultas de PostgreSQL max_parallel_maintenance_workers, max_parallel_workers y min_parallel_table_scan_size.

Ejecuta una consulta

Después de almacenar y, también, indexar las embeddings en tu base de datos, puedes comenzar a consultar tus datos. No puedes ejecutar búsquedas masivas con la extensión alloydb_scann.

Para encontrar los vecinos semánticos más cercanos a un vector de embedding, puedes ejecutar la siguiente consulta de ejemplo, en la que estableces la misma función de distancia que usaste durante la creación del índice.

  SELECT * FROM TABLE
    ORDER BY EMBEDDING_COLUMN DISTANCE_FUNCTION_QUERY ['EMBEDDING']
    LIMIT ROW_COUNT

Reemplaza lo siguiente:

  • TABLE: la tabla que contiene la embedding con la que se compara el texto.

  • INDEX_NAME: Es el nombre del índice que deseas usar, por ejemplo, my-scann-index.

  • EMBEDDING_COLUMN: la columna que contiene las incorporaciones almacenadas.

  • DISTANCE_FUNCTION_QUERY: Es la función de distancia que se usará con esta consulta. Elige una de las siguientes opciones según la función de distancia que se usó para crear el índice:

    • Distancia de L2: <->

    • Producto interno: <#>

    • Distancia de coseno: <=>

  • EMBEDDING: Es el vector de incorporación del que deseas encontrar los vecinos semánticos almacenados más cercanos.

  • ROW_COUNT: cantidad de filas que se mostrarán.

    Especifica 1 si solo deseas la mejor coincidencia.

También puedes usar la función embedding() para traducir el texto a un vector. Dado que embedding() devuelve un array real, debes convertir explícitamente la llamada embedding() en vector antes de aplicarla a uno de los operadores de vecinos más cercanos (p.ej., <-> para la distancia L2). Luego, estos operadores pueden usar el índice de ScaNN para encontrar las filas de la base de datos con las incorporaciones semánticamente más similares.

¿Qué sigue?