lakebase_vector

La lakebase_vector extensión agrega una búsqueda vectorial aproximada del vecino más cercano (ANN) a Lakebase a través del tipo de lakebase_ann índice. Es un complemento desplegable para pgvector: los mismos tipos vectoriales, operadores de distancia y sintaxis de consulta funcionan sin modificaciones.

Install

En primer lugar, habilite Lakebase Search en la configuración del proyecto. A continuación, instale la extensión:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

La CASCADE palabra clave se pgvector instala automáticamente como una dependencia.

Mejora la extensión y los índices

Una nueva versión de Lakebase Search puede añadir funciones, correcciones y mejoras de rendimiento. Aunque Lakebase Search se publica como parte de las actualizaciones de Lakebase, no actualiza todo automáticamente. En lakebase_vector, dos cosas se actualizan por separado y llevan números de versión que no están relacionados entre sí:

  • La versión de extensión es la versión de los objetos SQL que CREATE EXTENSION lakebase_vector crea, incluyendo sus tipos de datos, funciones, operadores y el lakebase_ann método de acceso al índice. Esta versión es reportada por SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'. ALTER EXTENSION lakebase_vector UPDATE actualiza esta versión.
  • El formato de almacenamiento de índice es la disposición en disco de un lakebase_ann índice. La extensión podría introducir formatos actualizados de almacenamiento de índice en una actualización, desbloqueando más funciones y ofreciendo un mejor rendimiento. Todos los índices recién creados usan automáticamente el último formato de almacenamiento, mientras que los índices existentes pueden actualizarse al nuevo formato después REINDEX INDEX CONCURRENTLY de que haya disponible un formato de almacenamiento más reciente.

La actualización no es urgente. La extensión es compatible con objetos SQL y formatos de almacenamiento de índices de versiones anteriores, pero mantenerse actualizado te mantiene en la ruta soportada y con mejor rendimiento y evita una migración mayor más adelante, así que actualiza cuando te conviene en lugar de posponerlo indefinidamente.

Note

La última versión de extensión disponible es reportada por SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'.

La última versión del formato de almacenamiento es _2. La siguiente consulta encuentra todos los índices que usan un formato de almacenamiento más antiguo. Luego puedes reconstruirlos al formato de almacenamiento más reciente con REINDEX INDEX o REINDEX INDEX CONCURRENTLY:

SELECT oid::regclass AS index, lakebase_ann_index_info(oid::regclass)::json ->> 'version' AS storage_format_version
FROM pg_class
WHERE relam = (SELECT oid FROM pg_am WHERE amname = 'lakebase_ann') AND relkind = 'i';

Note

REINDEX INDEX CONCURRENTLY permite que las lecturas y escrituras continúen, pero tarda más.

Inicio rápido

-- Create a table with a vector column
CREATE TABLE items (id BIGSERIAL PRIMARY KEY, embedding VECTOR(3));

-- Insert sample data
INSERT INTO items (embedding)
SELECT ARRAY[random(), random(), random()]::real[]
FROM generate_series(1, 1000);

-- Create a lakebase_ann index
CREATE INDEX items_embedding_idx ON items
  USING lakebase_ann (embedding vector_l2_ops);

-- Query using standard pgvector distance operators
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

Poblar desde tablas sincronizadas

Si cargas incrustaciones desde Unity Catalog en lugar de insertarlas directamente, las tablas sincronizadas pueden mapear una columna de incrustación lakehouse directamente a una columna de Postgres vector durante la sincronización, en lugar del mapeo por defecto JSONB . Consulta Mapeado de tipos personalizado para Lakebase Search.

Configuración del índice

Establézcalo build_mode en la creación del índice para controlar el equilibrio de precisión y velocidad:

  • standard (por defecto): Tiempo de recuperación de balances y de construcción del índice. Se usa para la mayoría de las cargas de trabajo.
  • quality: mejora la llamada pero tarda más en construirse.
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'quality');

El fast modo de compilación sigue siendo compatible con versiones anteriores.

Por defecto, lakebase_ann elige listas basándose en las estadísticas de la tabla y la configuración del índice. Configura lists para controlar explícitamente la disposición de la partición:

CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (lists = '1000');

Tiempo de compilación del índice

Una mayor shared_buffers capacidad puede reducir significativamente el tiempo de construcción del índice. Lakebase permite esta optimización solo en cálculos de tamaño fijo más grandes. Revisa el valor actual antes de optimizar una construcción de índice:

SHOW shared_buffers;

Si shared_buffers es 1 GB o menos, considera redimensionar temporalmente a un cálculo de tamaño fijo mayor antes de comenzar la compilación del índice.

También puedes acelerar la creación de índices aumentando el número de trabajadores paralelos.

El max_parallel_maintenance_workers parámetro de configuración establece el número máximo de trabajadores paralelos que pueden iniciarse mediante un solo comando de utilidad como CREATE INDEX.

El max_parallel_workers parámetro de configuración establece el número máximo de trabajadores que el cálculo puede soportar para operaciones paralelas. Los valores superiores max_parallel_maintenance_workers a este límite no tienen efecto.

El max_worker_processes parámetro de configuración establece el número máximo de procesos en segundo plano que el cálculo puede soportar. Lakebase gestiona esta configuración en función del tamaño de cálculo. Los valores superiores max_parallel_workers a este límite no tienen efecto.

SHOW max_worker_processes;
-- Set both values to the desired parallelism minus one.
SET max_parallel_workers = 15;
SET max_parallel_maintenance_workers = 15;

Compilación de índices simultáneamente

CREATE INDEX CONCURRENTLY y REINDEX INDEX CONCURRENTLY permiten que las lecturas y escrituras continúen mientras se construye o reconstruye un índice:

CREATE INDEX CONCURRENTLY items_embedding_idx_concurrent ON items
  USING lakebase_ann (embedding vector_l2_ops);

REINDEX INDEX CONCURRENTLY items_embedding_idx_concurrent;

Ajuste de la precisión de la búsqueda

Antes de optimizar, llame lakebase_ann_index_info(index_name) a para obtener los valores , listsy default_probes del default_epsiloníndice.

Úsalo lakebase_ann.probes en el momento de la consulta para controlar cuántas particiones de FIV se buscan. Los valores más altos mejoran la recuperación a costa de la velocidad de consulta. El valor predeterminado es 'auto'. Prueba diferentes valores para alcanzar tu objetivo de recuerdo.

La forma de probes debe coincidir con la forma de lists. Llama lakebase_ann_index_info para encontrar tu lists array, luego establece un valor para un índice de un nivel o dos valores separados por comas para un índice de dos niveles:

lists De la información del índice probes para establecer
[] (vacío) ''
[222] '22'
[3333, 33333] '33, 333'

Note

En un conjunto de datos pequeño, lakebase_ann se utiliza búsqueda exacta (plana) en lugar de particionamiento por FIV, y lakebase_ann_index_info devuelve vacío lists y default_probes. En este caso, deja probes el set en ''. Cuando lists no está vacío, un probes valor cuya forma no coincide lists causa un error.

-- Check your index's lists array first
SELECT lakebase_ann_index_info('items_embedding_idx');

-- Then set probes to match the shape of lists.
-- One-level index (single-value lists): set one value.
SET lakebase_ann.probes TO '10';

-- Two-level index: set two ascending comma-separated values, for example '10, 20'.
-- Flat index (empty lists): leave probes set to ''.

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

lakebase_ann.epsilon Controla cuántos candidatos se reclasifican usando distancias de máxima precisión. Valores más altos reclasifican a más candidatos y tardan más. El valor predeterminado de funciona bien para la mayoría de las cargas de 'auto' trabajo. Durante la búsqueda plana en un conjunto de datos pequeño, epsilon sigue controlando el reposicionamiento con total precisión.

Prefiltro

Por defecto, Postgres aplica condiciones de filtro no vectorial después de que el índice ANN devuelva filas candidatas. Permitir lakebase_ann.prefilter evaluar esas condiciones antes de reclasificar la distancia con máxima precisión:

SET lakebase_ann.prefilter TO on;

SELECT * FROM items
WHERE id % 100 = 0
ORDER BY embedding <-> '[3,1,2]'
LIMIT 10;

El prefiltrado funciona mejor cuando el filtro es barato de evaluar y elimina la mayoría de las filas. Déjalo desactivado para filtros que coincidan con muchas filas o que requieran cálculos costosos, ya que evaluar el filtro dentro del índice puede añadir sobrecarga.

Precalenta un índice

Úsalo lakebase_ann_prewarm después de que empiece un cálculo para cargar las partes frecuentemente accedidas de un índice en memoria. El scope argumento acepta los siguientes valores:

  • search (por defecto): Precalienta la parte caliente completa utilizada para la búsqueda.
  • routing: Precalienta solo las estructuras de enrutamiento. Esta opción es más rápida y ofrece un mejor equilibrio coste-rendimiento para índices grandes.
-- Prewarm the full search scope
SELECT lakebase_ann_prewarm('items_embedding_idx');

-- Prewarm only routing structures
SELECT lakebase_ann_prewarm('items_embedding_idx', scope => 'routing');

Clases de operador

Métrica de distancia Clase de operador Operador de consulta
L2 (euclidano) vector_l2_ops <->
Producto interno negativo vector_ip_ops <#>
Similitud coseno vector_cosine_ops <=>

Elija la clase de operador que coincida con la forma en que se entrenaron las inserciones y use la misma métrica para el índice y la consulta:

  • vector_cosine_ops (<=>) es similitud coseno. Úselo para la mayoría de las incrustaciones de texto. Esta es la opción más común.
  • vector_l2_ops (<->) es la distancia euclidiana (L2). Úselo cuando la distancia espacial absoluta importa y los vectores no se normalizan.
  • vector_ip_ops (<#>) es un producto interno negativo. Úselo cuando los vectores se normalicen previamente a la longitud de la unidad. En el caso de los vectores de unidad, el producto interno es igual a la similitud de coseno y suele ser más rápido.

Referencia de opciones de índice

Opción Type Predeterminado Description
build_mode string 'standard' Controla el equilibrio entre precisión y velocidad. Úsalo 'quality' para mejor recuperación a costa de una construcción de índice más larga. 'fast' sigue siendo compatible con versiones anteriores.
lists string 'auto' Establece la disposición de la partición de la FIV. Con 'auto', la extensión elige un valor basado en las estadísticas de la tabla y la configuración del índice. Establece un solo entero como '1000' para un índice de un nivel, o dos enteros ascendentes separados por comas, como para '100, 1000' un índice de dos niveles.

Referencia de GUC

Parámetro Type Predeterminado Description
lakebase_ann.probes string 'auto' Número de particiones de FIV para escanear en cada nivel. Los valores más altos mejoran la recuperación a costa de la velocidad de consulta. La forma debe coincidir con el lists array de lakebase_ann_index_info.
lakebase_ann.epsilon string 'auto' Controla cuántos candidatos se reclasifican usando distancias de máxima precisión. Valores más altos reclasifican a más candidatos y tardan más.
lakebase_ann.prefilter enum off Evalúa filtros no vectoriales antes de un reordenamiento de distancia de máxima precisión. Los valores válidos son on y off. Es ideal para filtros baratos que eliminan la mayoría de las filas candidatas.

Funciones de utilidad

Function Returns Description
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search') void Carga datos indexados frecuentemente accedidos a la memoria. Los valores válidos scope son search y routing.
lakebase_ann_index_info(regclass) text Devuelve metadatos del índice como texto JSON, incluyendo version, lists, default_probes, y default_epsilon.

Pasos siguientes

  • Last updated on