lakebase_vector
A extensão lakebase_vector adiciona busca vetorial de vizinhos mais próximos aproximados (ANN) ao Lakebase através do tipo de índice lakebase_ann. É um complemento direto para pgvector: os mesmos tipos de vetor, operadores de distância e sintaxe de consulta funcionam sem modificação.
Instalar
Primeiro, habilite a Pesquisa Lakebase nas configurações do seu projeto. Em seguida, instale a extensão:
CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
A palavra-chave CASCADE instala automaticamente pgvector como uma dependência.
Upgrade the extension and indexes
Um novo lançamento 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 são atualizadas separadamente e possuem números de versão que não estão relacionados entre si:
- The extension version is the version of the SQL objects that
CREATE EXTENSION lakebase_vectorcreates, including its data types, functions, operators, and thelakebase_annindex access method. This version is reported bySELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'.ALTER EXTENSION lakebase_vector UPDATEupdates this version. - The index storage format is the on-disk disposição of a
lakebase_annindex. The extension may introduce updated index storage formats in an update, unlocking more recursos and delivering better desempenho. All newly created indexes automatically use the latest storage format, while existing indexes can be upgraded to the new format usingREINDEX INDEX CONCURRENTLYafter a newer storage format is available.
Upgrading is not urgent. The extension is compatible with SQL objects and index storage formats from older versions, but staying current keeps you on the supported, best-performing path and avoids a larger migration later, so upgrade when convenient rather than deferring indefinitely.
A versão de extensão disponível mais recente é informada por SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'.
A versão mais recente do formato de armazenamento é _2. A seguinte query encontra todos os índices que usam um formato de armazenamento mais antigo. Em seguida, você poderá 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';
REINDEX INDEX CONCURRENTLY allows reads and writes to continue, but it takes longer.
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;
Popular a partir de tabelas sincronizadas
Se você estiver carregando incorporações do Unity Catalog em vez de inseri-las diretamente, tabelas sincronizadas podem mapear uma coluna de incorporação de lakehouse diretamente para uma coluna Postgres vector durante a sincronização, em vez do mapeamento default JSONB. Consulte Mapeamento de tipo personalizado para a Lakebase Search.
Configure o índice
Defina build_mode na criação do índice para controlar a relação entre precisão e velocidade:
standard(default): equilibra o recall e o tempo de construção do índice. Use para a maioria das cargas de trabalho.quality: melhora a recuperação, mas leva significativamente mais tempo para construir. Use-o apenas para tabelas com até 50 milhões de vetores.
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'standard');
O modo de compilação fast permanece suportado para compatibilidade com versões anteriores.
Por default, lakebase_ann escolhe listas com base nas estatísticas da tabela e na configuração do índice. Defina lists para controlar a disposição de partição explicitamente:
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (lists = '1000');
Tempo de construção do índice
shared_buffers maiores podem reduzir significativamente o tempo de construção do índice. O Lakebase habilita essa otimização apenas em computes de tamanho fixo maiores. Verifique o valor atual antes de otimizar a criação de um índice:
SHOW shared_buffers;
Se shared_buffers for de 1 GB ou menos, considere redimensionar temporariamente para um compute de tamanho fixo maior antes de iniciar a construção do índice.
Você também pode acelerar a criação do índice aumentando o número de workers paralelos.
O parâmetro de configuração max_parallel_maintenance_workers define o número máximo de workers paralelos que podem ser começados por um único comando de utilidade, como CREATE INDEX.
O parâmetro de configuração max_parallel_workers define o número máximo de workers que o compute pode dar suporte para operações paralelas. Valores de max_parallel_maintenance_workers acima desse limite não têm efeito.
O parâmetro de configuração max_worker_processes define o número máximo de processos em segundo plano que o compute pode dar suporte. O Lakebase gerencia essa configuração com base no tamanho do compute. Valores de max_parallel_workers acima 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;
Crie índices simultaneamente
CREATE INDEX CONCURRENTLY e REINDEX INDEX CONCURRENTLY permitem que as leituras e gravações continuem enquanto um índice é criado 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;
Ajuste a precisão da pesquisa
Antes de ajustar, chame lakebase_ann_index_info(index_name) para obter os valores de lists, default_probes e default_epsilon do índice.
Use lakebase_ann.probes no momento da query para controlar quantas partições de arquivo invertido (IVF) são pesquisadas. Valores mais altos melhoram a recuperação ao custo da latência. O valor default 'auto' oferece um equilíbrio entre eles. Para um controle mais refinado, use lakebase_ann_advise para obter valores de sondas recomendados.
A forma de probes deve corresponder à forma de lists. Chame lakebase_ann_index_info para encontrar seu array lists, então defina um valor para um índice de um nível ou dois valores separados por vírgulas para um índice de dois níveis:
|
|
|---|---|
|
|
|
|
|
|
Em um dataset pequeno, lakebase_ann usa pesquisa exata (plana) em vez de particionamento IVF, e lakebase_ann_index_info retorna lists e default_probes vazios. Nesse caso, mantenha probes definido como ''. Quando lists não estiver vazio, um valor probes cuja forma não corresponda a lists causará 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 default de 'auto' funciona bem para a maioria das cargas de trabalho. Durante a busca plana em um dataset pequeno, epsilon ainda controla a reclassificação de precisão total.
Obter valores de probes recomendados
lakebase_ann_advise, lakebase_ann_tune, lakebase_ann_latency e lakebase_ann_sample exigem lakebase_vector 1.1.2 e acima. Para verificar a versão instalada e atualizar a extensão, consulte Atualizar a extensão e os índices.
lakebase_ann_advise retorna valores de probes candidatos em ordem crescente de recall, de 0,5 a 0,9 em os passos de 0,1 e 0,91 a 0,99 em os passos de 0,01. Cada linha inclui recall estimado e a latência da query medida após o aquecimento. Use queries reais da sua workload de busca como entrada. Se não estiverem disponíveis, amostre vetores da tabela indexada com lakebase_ann_sample. Os exemplos seguintes mostram ambas as opções:
-- Option 1: real queries in a separate table
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
'items_embedding_idx'::regclass,
ARRAY(
SELECT embedding FROM queries
WHERE embedding IS NOT NULL
LIMIT 512
)
);
-- Option 2: sampled from the indexed table
-- NULL::items specifies items as the table to sample from.
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
'items_embedding_idx'::regclass,
ARRAY(
SELECT embedding FROM lakebase_ann_sample(NULL::items, 512)
WHERE embedding IS NOT NULL
)
);
Coluna | Descrição |
|---|---|
| Um valor |
| Estimativa de recall@10 para as consultas de exemplo. |
| Latência média, mediana e de 95º percentil de uma única query em milissegundos. |
Escolha a linha mais rápida que atenda ao seu alvo de recall e, em seguida, aplique seu valor de probes:
SET lakebase_ann.probes TO '10';
A recuperação e a latência são estimadas para as top-10 queries com lakebase_ann.epsilon definido como 1.9, que podem diferir das suas queries reais. Antes de usar um valor probes na produção, verifique sua recuperação e latência em sua carga de trabalho, se possível.
Se o índice tiver lists vazio, lakebase_ann_advise não retorna linhas porque não há nada para ajustar.
Em índices grandes, uma chamada lakebase_ann_advise pode levar mais de 20 minutos. Mais vetores de query tornam a chamada mais lenta. Comece com 512 vetores de query para equilibrar a precisão da recuperação e o tempo de execução.
lakebase_ann_advise chama lakebase_ann_tune para obter valores probes recomendados, então lakebase_ann_latency para medir a latência deles. Você também pode usar lakebase_ann_tune ou lakebase_ann_latency individualmente. Consulte Funções de utilidade.
lakebase_ann_advise e lakebase_ann_tune requerem SELECT de nível de tabela na tabela indexada e retornam um erro se a segurança em nível de linha (RLS) se aplicar à sua função nessa tabela. lakebase_ann_sample e lakebase_ann_latency aplicam políticas RLS e apenas leem linhas que sua função pode ver.
Pré-filtro
Por default, o Postgres aplica condições de filtro não vetoriais após o índice de rede neurais artificiais (ANN) retornar as linhas candidatas. Habilite lakebase_ann.prefilter para avaliar essas condições antes da reclassificação de distância de 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 desativado para filtros que correspondem a muitas linhas ou exigem cálculos caros, já que avaliar o filtro dentro do índice pode adicionar sobrecarga.
Prewarm an index
Use lakebase_ann_prewarm after a compute starts to load the frequently accessed parts of an index into memory. The scope argument accepts the following values:
search(default): pré-aquece toda a porção quente usada para a pesquisa.routing: pré-aquece apenas as estruturas de roteamento. Esta opção é mais rápida e oferece uma melhor relação custo-desempenho para grandes índices.
-- 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) |
|
|
Produto interno negativo |
|
|
Semelhança de cosseno |
|
|
Escolha a classe de operador que corresponda a como suas incorporações foram treinadas e utilize a mesma métrica para o índice e a consulta:
vector_cosine_ops(<=>) é similaridade de cosseno. Utilize-o para a maioria das incorporações de texto. Esta é a escolha mais comum.vector_l2_ops(<->) é a distância euclidiana (L2). Utilize-o quando a distância espacial absoluta for importante e os vetores não forem normalizados.vector_ip_ops(<#>) é produto interno negativo. Utilize-o quando os vetores forem pré-normalizados para comprimento unitário. Para vetores unitários, o produto interno é igual à similaridade de cosseno e é tipicamente mais rápido.
Referência de opções de índice
Opção | Tipo | Padrão | Descrição |
|---|---|---|---|
| string |
| Controla o compromisso entre precisão e velocidade. Use |
| string |
| Define a disposição de partição IVF. Com |
Referência GUC
Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| string |
| Número de partições IVF a serem verificadas em cada nível. Valores mais altos melhoram o recall ao custo da latência. O formato deve corresponder ao array |
| string |
| Controla quantos candidatos são reclassificados usando distâncias de precisão total. Valores mais altos reclassificam mais candidatos e levam mais tempo. |
| enumeração |
| Avalia filtros não vetoriais antes da reclassificação de distância de precisão total. Os valores válidos são |
Funções de utilidade
Função | Devolve | Descrição |
|---|---|---|
| vazio | Carrega dados de índice acessados com frequência na memória. Os valores válidos de |
| TEXT | Returns index metadata as JSON text, including |
|
| Recomenda |
|
| Recomenda |
|
| Mede a latência média, mediana e do 95º percentil da query do índice para cada valor |
|
| Amostras de até |