lakebase_vector

A lakebase_vector extensão adiciona pesquisa vetorial aproximada por vizinho mais próximo (ANN) ao Lakebase através do lakebase_ann tipo de índice. É um companheiro drop-in do pgvector: os mesmos tipos de vetores, operadores de distância e sintaxe de consulta funcionam sem modificações.

Install

Primeiro, ativa o Lakebase Search nas definições do teu projeto. Depois instala a extensão:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

A CASCADE palavra-chave instala-se pgvector automaticamente como uma dependência.

Atualizar a extensão e os índices

Uma nova versão do Lakebase Search pode adicionar funcionalidades, correções e melhorias de desempenho. Embora o Lakebase Search seja lançado como parte das atualizações do Lakebase, não atualiza tudo automaticamente. Em lakebase_vector, duas coisas são atualizadas separadamente e têm números de versão que não estão relacionados entre si:

• A versão da extensão é a versão dos objetos SQL que CREATE EXTENSION lakebase_vector cria, incluindo os seus tipos de dados, funções, operadores e o lakebase_ann método de acesso ao índice. Esta versão é reportada por SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'. ALTER EXTENSION lakebase_vector UPDATE Atualiza esta versão.
• O formato de armazenamento de índice é o layout em disco de um lakebase_ann índice. A extensão pode introduzir formatos de armazenamento de índice atualizados numa atualização, desbloqueando mais funcionalidades e oferecendo melhor desempenho. Todos os índices recém-criados usam automaticamente o formato de armazenamento mais recente, enquanto os índices existentes podem ser atualizados para o novo formato depois REINDEX INDEX CONCURRENTLY de um formato de armazenamento mais recente estar disponível.

A atualização não é urgente. A extensão é compatível com objetos SQL e formatos de armazenamento de índice de versões anteriores, mas manter-se atualizado mantém-no no caminho suportado e com melhor desempenho e evita uma migração maior mais tarde, por isso atualize quando for conveniente em vez de adiar indefinidamente.

Note

A versão mais recente disponível da extensão é reportada por SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'.

A versão mais recente do formato de armazenamento é _2. A consulta seguinte encontra todos os índices que utilizam um formato de armazenamento mais antigo. Depois pode reconstruí-los para o formato de armazenamento mais recente com REINDEX INDEX ou 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 as leituras e escritas continuem, mas demora mais tempo.

Início 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;

Preencher a partir de tabelas sincronizadas

Se estiveres a carregar embeddings do Unity Catalog em vez de os inserir diretamente, as tabelas sincronizadas podem mapear uma coluna de embedding lakehouse diretamente para uma coluna Postgres vector durante a sincronização, em vez do mapeamento padrão JSONB . Veja Mapeamento de tipos personalizado para a Pesquisa Lakebase.

Configurar o índice

Definir build_mode na criação do índice para controlar o equilíbrio entre precisão e velocidade:

• standard (padrão): balança o recall e o tempo de construção do índice. Uso para a maioria das cargas de trabalho.
• quality: melhora a chamada mas demora mais a construir.

CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'quality');

O fast modo de construção continua suportado para compatibilidade retroativa.

Por defeito, lakebase_ann escolhe listas com base nas estatísticas da tabela e na configuração do índice. Definido lists para controlar explicitamente o layout da partição:

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

Tempo de construção do índice

Maior shared_buffers pode reduzir significativamente o tempo de construção do índice. O Lakebase permite esta otimização apenas em cálculos de tamanho fixo maiores. Verifique o valor atual antes de otimizar uma construção de índice:

SHOW shared_buffers;

Se shared_buffers for 1 GB ou menos, considere redimensionar temporariamente para um cálculo de tamanho fixo maior antes de iniciar a construção do índice.

Também pode acelerar a criação de índices aumentando o número de trabalhadores paralelos.

O max_parallel_maintenance_workers parâmetro de configuração define o número máximo de trabalhadores paralelos que podem ser iniciados por um único comando utilitário, como CREATE INDEX.

O max_parallel_workers parâmetro de configuração define o número máximo de trabalhadores que o cálculo pode suportar para operações paralelas. Valores superiores max_parallel_maintenance_workers a este limite não têm efeito.

O max_worker_processes parâmetro de configuração define o número máximo de processos em segundo plano que o cálculo pode suportar. O Lakebase gere esta configuração com base no tamanho do cálculo. Valores superiores max_parallel_workers a este limite não têm efeito.

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

Índices de build em simultâneo

CREATE INDEX CONCURRENTLY e REINDEX INDEX CONCURRENTLY permitem que as leituras e escritas continuem enquanto um índice é construído ou reconstruído:

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

REINDEX INDEX CONCURRENTLY items_embedding_idx_concurrent;

Ajustar a precisão da pesquisa

Antes de afinar, chame lakebase_ann_index_info(index_name) para obter os valores do índice lists, default_probes, default_epsilon , e

Use lakebase_ann.probes no momento da consulta para controlar quantas partições de FIV são pesquisadas. Valores mais elevados melhoram a recordação à custa da velocidade da consulta. A predefinição é 'auto'. Teste diferentes valores para atingir a sua meta de recordação.

A forma de probes deve corresponder à forma de lists. Chame lakebase_ann_index_info para encontrar o seu lists array, depois defina um valor para um índice de um nível ou dois valores separados por vírgulas para um índice de dois níveis:

lists A partir de informações do índice	probes para definir
[] (vazio)	''
[222]	'22'
[3333, 33333]	'33, 333'

Note

Num conjunto de dados pequeno, lakebase_ann usa pesquisa exata (plana) em vez de particionamento por FIV, e lakebase_ann_index_info retorna vazios lists e default_probes. Neste caso, deixe-se probes definido para ''. Quando lists não está vazio, um probes valor cuja forma não coincide lists causa um erro.

-- 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 quantos candidatos são reclassificados usando distâncias de precisão total. Valores mais altos reclassificam mais candidatos e demoram mais tempo. O valor padrão de 'auto' funciona bem para a maioria das cargas de trabalho. Durante a pesquisa plana num conjunto de dados pequeno, epsilon ainda controla a reclassificação em precisão total.

Pré-filtro

Por defeito, o Postgres aplica condições de filtro não vetorial depois de o índice ANN devolver linhas candidatas. Permitir lakebase_ann.prefilter avaliar essas condições antes de uma reclassificação de distância com precisão total:

SET lakebase_ann.prefilter TO on;

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

A pré-filtragem funciona melhor quando o filtro é barato de avaliar e remove a maioria das linhas. Deixe-o desligado para filtros que coincidam com muitas linhas ou que exijam cálculos dispendiosos, pois avaliar o filtro dentro do índice pode aumentar a sobrecarga.

Pré-aquece um índice

Utilize-se lakebase_ann_prewarm após o início do cálculo para carregar as partes de um índice frequentemente acedidas na memória. O scope argumento aceita os seguintes valores:

• search (predefinido): Pré-aquece a parte completa de quente usada para a pesquisa.
• routing: Pré-aquece apenas as estruturas de roteamento. Esta opção é mais rápida e proporciona um melhor equilíbrio custo-desempenho 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');

Classes de operadores

Métrica de distância	Classe de operador	Operador de consulta
L2 (Euclidiano)	vector_l2_ops	<->
Produto interno negativo	vector_ip_ops	<#>
Similaridade cosseno	vector_cosine_ops	<=>

Escolha a classe de operador que corresponda à forma como os seus embeddings foram treinados e use a mesma métrica para o índice e para a consulta:

• vector_cosine_ops (<=>) é a similaridade cosseno. Use-o para a maioria das incorporações de texto. Esta é a escolha mais comum.
• vector_l2_ops (<->) é a distância euclidiana (L2). Use-o quando a distância espacial absoluta for importante e os vetores não forem normalizados.
• vector_ip_ops (<#>) é o produto interno negativo. Use-o quando os vetores estiverem pré-normalizados para unidade de comprimento. Para vetores unitários, o produto interno é igual à similaridade cosseno e é tipicamente mais rápido.

Referência de opções de índice

Option	Tipo	Default	Description
build_mode	cadeia (de caracteres)	'standard'	Controla a troca entre precisão e velocidade. Use 'quality' para melhor recordação, à custa de uma construção de índice mais longa. 'fast' mantém-se suportado para compatibilidade retroativa.
lists	cadeia (de caracteres)	'auto'	Define o layout da partição da FIV. Com 'auto', a extensão escolhe um valor com base nas estatísticas da tabela e na configuração do índice. Defina um único inteiro, como '1000' para um índice de um nível, ou dois inteiros ascendentes separados por vírgulas, como '100, 1000' para um índice de dois níveis.

Referência GUC

Parâmetro	Tipo	Default	Description
lakebase_ann.probes	cadeia (de caracteres)	'auto'	Número de partições de FIV a analisar em cada nível. Valores mais elevados melhoram a recordação à custa da velocidade da consulta. A forma deve corresponder ao lists array de lakebase_ann_index_info.
lakebase_ann.epsilon	cadeia (de caracteres)	'auto'	Controla quantos candidatos são reclassificados usando distâncias de precisão total. Valores mais altos reclassificam mais candidatos e demoram mais tempo.
lakebase_ann.prefilter	enumeração	off	Avalia filtros não vetoriais antes de uma reclassificação de distância de precisão total. Os valores válidos são on e off. É melhor para filtros baratos que removem a maioria das linhas candidatas.

Funções utilitárias

Function	Devoluções	Description
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search')	Vazio	Carrega dados de índice frequentemente acedidos na memória. Os valores válidos scope são search e routing.
lakebase_ann_index_info(regclass)	enviar SMS	Devolve metadados do índice como texto JSON, incluindo version, lists, default_probes, e default_epsilon.

Passos seguintes

• lakebase_text
• Lakebase Search