lakebase_vector

A lakebase_vector extensão adiciona uma pesquisa de vetor aproximada de vizinho mais próximo (ANN) ao Lakebase por meio do tipo de lakebase_ann índice. É um complemento de entrada para pgvector: os mesmos tipos de vetor, operadores de distância e sintaxe de consulta funcionam sem modificação.

Install

Primeiro, habilite o Lakebase Search nas configurações do projeto. Em seguida, instale a extensão:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

A CASCADE palavra-chave é instalada pgvector automaticamente como uma dependência.

Atualize a extensão e os índices

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

  • A versão da extensão é a versão dos objetos SQL que CREATE EXTENSION lakebase_vector cria, incluindo 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 no disco de um lakebase_ann índice. A extensão pode introduzir formatos atualizados de armazenamento de índice em uma atualização, desbloqueando mais recursos 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 após REINDEX INDEX CONCURRENTLY um formato de armazenamento mais novo estar disponível.

Atualizar 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 você no caminho suportado e com melhor desempenho e evita uma migração maior depois, então 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 a seguir encontra todos os índices que usam um formato de armazenamento mais antigo. Você pode então 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 leituras e escritas continuem, mas leva 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 você estiver carregando embeddings do Unity Catalog em vez de inseri-los diretamente, tabelas sincronizadas podem mapear uma coluna de embedding do lakehouse direto para uma coluna do Postgres vector durante a sincronização, em vez do mapeamento padrão JSONB . Veja Mapeamento de tipos personalizado para Lakebase Search.

Configurar o índice

Defina build_mode na criação do índice para controlar a compensação de precisão/velocidade:

  • standard (padrão): balança o recall e o tempo de construção do índice. Use para a maioria das cargas de trabalho.
  • quality: melhora o recall, mas demora mais para ser construída.
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 padrão, escolhe lakebase_ann listas com base nas estatísticas da tabela e na configuração do índice. Defina 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 essa otimização apenas em computações maiores de tamanho fixo. Verifique o valor atual antes de otimizar uma build 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.

Você 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 acima max_parallel_maintenance_workers desse 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 gerencia essa configuração com base no tamanho do cálculo. Valores acima max_parallel_workers desse 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;

Compilar índices simultaneamente

CREATE INDEX CONCURRENTLY e REINDEX INDEX CONCURRENTLY permitem que 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 ajustar, chame lakebase_ann_index_info(index_name) para obter os valores e lists os índices do default_probesdefault_epsiloníndice.

Use lakebase_ann.probes no momento da consulta para controlar quantas partições de FIV são pesquisadas. Valores mais altos melhoram o recall ao custo da velocidade da consulta. O padrão é 'auto'. Teste diferentes valores para atingir sua meta de recall.

A forma de probes deve coincidir com a forma de lists. Chame lakebase_ann_index_info para encontrar 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 de índice probes para definir
[] (vazio) ''
[222] '22'
[3333, 33333] '33, 333'

Note

Em um conjunto de dados pequeno, lakebase_ann usa busca exata (plana) em vez de particionamento por FIV, e lakebase_ann_index_info retorna vazio lists e default_probes. Nesse caso, deixe probes definir para ''. Quando lists não está vazio, um probes valor cuja forma não corresponde 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. O valor padrão funciona bem para a maioria das 'auto' cargas de trabalho. Durante a busca plana em um conjunto de dados pequeno, epsilon ainda controla a reclassificação em precisão total.

Pré-filtro

Por padrão, o Postgres aplica condições de filtro não vetorial após o índice ANN retornar linhas candidatas. Permitir lakebase_ann.prefilter avaliar essas condições antes de reclassificar a 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;

O pré-filtro funciona melhor quando o filtro é barato de avaliar e remove a maioria das linhas. Deixe-o de lado para filtros que combinam com muitas linhas ou que exigem cálculos caros, pois avaliar o filtro dentro do índice pode gerar sobrecarga.

Pré-aqueça um índice

Use-o lakebase_ann_prewarm após o início do cálculo para carregar as partes acessadas com frequência de um índice na memória. O scope argumento aceita os seguintes valores:

  • search (padrão): Pré-aquece a parte quente completa usada para busca.
  • routing: Pré-aquece apenas as estruturas de roteamento. Essa opção é mais rápida e oferece 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 operador

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 corresponde à forma como suas inserções foram treinadas e use a mesma métrica para o índice e a consulta:

  • vector_cosine_ops (<=>) é similaridade de cosseno. Use-o para a maioria das inserções de texto. Essa é a escolha mais comum.
  • vector_l2_ops (<->) é a distância euclidiana (L2). Use-o quando a distância espacial absoluta importa e os vetores não são normalizados.
  • vector_ip_ops (<#>) é um produto interno negativo. Use-o quando os vetores forem pré-normalizados para o comprimento da unidade. Para vetores de unidade, o produto interno é igual à similaridade de cosseno e normalmente é mais rápido.

Referência de opções de índice

Opção Tipo Padrão Description
build_mode cadeia 'standard' Ele controla a troca entre precisão e velocidade. Use 'quality' para melhor recall ao custo de uma build de índice mais longa. 'fast' permanece suportado para compatibilidade retroativa.
lists cadeia 'auto' Define o layout da partição da FIV. Com 'auto', a extensão escolhe um valor baseado 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 de GUC

Parâmetro Tipo Padrão Description
lakebase_ann.probes cadeia 'auto' Número de partições de FIV para escanear em cada nível. Valores mais altos melhoram o recall ao custo da velocidade da consulta. A forma deve corresponder ao lists array de lakebase_ann_index_info.
lakebase_ann.epsilon cadeia 'auto' Controle quantos candidatos são reclassificados usando distâncias de precisão total. Valores mais altos reclassificam mais candidatos e demoram mais.
lakebase_ann.prefilter enumeração off Avalia filtros não vetoriais antes de reclassificação de distância com precisão total. Os valores válidos são on e off. Ideal para filtros baratos que removem a maioria das linhas candidatas.

Funções utilitárias

Function Returns Description
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search') vazio Carrega dados de índice acessados com frequência na memória. Valores válidos scope são search e routing.
lakebase_ann_index_info(regclass) enviar SMS Retorna metadados do índice como texto JSON, incluindo version, lists, default_probes, e default_epsilon.

Próximas Etapas 

  • Last updated on