pgvector em Profundidade
pgvector é uma extensão do Postgres que ensina ao banco de dados um novo tipo de dado e uma nova forma de classificar linhas: por distância geométrica em vez de igualdade ou intervalo.
//
Busque em todas as páginas da documentação
pgvector é uma extensão do Postgres que ensina ao banco de dados um novo tipo de dado e uma nova forma de classificar linhas: por distância geométrica em vez de igualdade ou intervalo.
Esta página permanece conceitual e não repete a sintaxe de tipo, DDL de índice ou padrões de esquema já cobertos pelas outras páginas desta seção.
Um embedding é uma lista de números produzida por um modelo de machine learning, e essa lista deve ser lida como coordenadas de um ponto em um espaço de alta dimensionalidade.
Dois pedaços de texto, imagens ou clipes de áudio que significam coisas semelhantes são treinados para pousar perto um do outro nesse espaço, enquanto conteúdo não relacionado pousa longe.
pgvector armazena cada embedding como um valor vector, e trata esse valor da mesma forma que o Postgres trata um inteiro ou um timestamp: uma coluna tipada com operadores definidos.
A principal percepção por trás da busca vetorial é que "significado semelhante" se torna "pequena distância", o que transforma uma pergunta semântica em uma pergunta de geometria que o SQL pode responder com ORDER BY e LIMIT.
A própria distância não é uma ideia fixa, pois existem várias maneiras matematicamente válidas de medir quão distantes dois pontos estão.
A distância Euclidiana (L2) mede a distância em linha reta através do espaço, da mesma forma que uma régua mediria a distância entre dois pontos em um papel.
A distância de cosseno ignora o comprimento de cada vetor e mede apenas o ângulo entre eles, o que importa quando os embeddings de um modelo variam em magnitude, mas não em direção.
O produto interno mede uma mistura de ângulo e magnitude de uma vez, e é o ajuste natural para modelos explicitamente treinados para maximizar uma pontuação de produto escalar.
Nenhuma dessas métricas é universalmente "correta", pois a escolha certa depende de como o modelo de embedding foi treinado e normalizado.
Uma analogia simples ajuda aqui: imagine cada documento como uma cidade em um mapa, onde cidades que discutem tópicos semelhantes se agrupam em bairros.
Encontrar "os documentos mais relevantes" se torna "as cidades mais próximas", e o próprio mapa é definido pelo modelo de embedding, não pelo pgvector.
pgvector não cria esse mapa, ele apenas fornece ao Postgres as ferramentas para medi-lo e pesquisá-lo eficientemente.
Em pequena escala, a busca por similaridade é um problema de geometria de força bruta: compute a distância do vetor de consulta para cada vetor armazenado, depois ordene e pegue os melhores resultados.
Essa abordagem é exata, mas seu custo cresce linearmente com o número de linhas, então deixa de ser rápida assim que uma tabela atinge dezenas de milhares de vetores.
A indexação de vizinhos mais próximos aproximados (ANN) existe para quebrar essa relação linear, organizando os vetores com antecedência para que uma consulta precise apenas olhar para um subconjunto pequeno e promissor.
A troca feita é explícita: um índice ANN renuncia à garantia de encontrar os vizinhos mais próximos exatos em troca de encontrar vizinhos que provavelmente estão próximos o suficiente, a uma fração do custo.
Isso é fundamentalmente diferente de um índice B-tree, que nunca sacrifica a correção pela velocidade.
Recall é o termo para a frequência com que um índice ANN realmente retorna os verdadeiros vizinhos mais próximos em comparação com um scan exato de força bruta, e é um dial ajustável em vez de uma garantia fixa.
Aumentar esse dial para um recall mais alto geralmente custa mais latência de consulta e mais tempo de construção, e diminuí-lo para um recall mais baixo compra velocidade de volta.
O que torna o pgvector interessante arquiteturalmente é que ele não adiciona a busca ANN ao Postgres como um serviço separado.
Ele registra o tipo vector e seus operadores de distância através do mesmo sistema de classe de operador em que todos os métodos de índice do Postgres já dependem para saber como comparar valores.
Por causa disso, um índice ANN sobre vetores é um índice de primeira classe do Postgres, não uma estrutura externa que o banco de dados apenas tolera.
O planejador de consulta trata um scan de índice vetorial da mesma forma que trata um scan B-tree ou GiST ao estimar o custo e decidir se usa o índice ou não.
-- As classes de operador são como o Postgres sabe que um operador de distância pode impulsionar um scan de índice
SELECT opcname, amname
FROM pg_opclass oc
JOIN pg_am am ON am.oid = oc.opcmethod
WHERE opcname LIKE 'vector%';É por isso que trocar o operador de distância da consulta sem corresponder à classe de operador do índice derrota silenciosamente o índice: o planejador não pode mais provar que a ordenação do índice corresponde à ordenação solicitada pela consulta.
Espaços de alta dimensionalidade se comportam contraintuitivamente, e isso se manifesta como a "maldição da dimensionalidade", onde os pontos tendem a se tornar aproximadamente equidistantes uns dos outros à medida que o número de dimensões aumenta.
Esse efeito é uma das razões pelas quais os índices ANN aceitam aproximação: em dimensões muito altas, encontrar o vizinho mais próximo matematicamente exato muitas vezes não é significativamente melhor do que encontrar um muito próximo.
Combinar busca vetorial com filtros tradicionais, como "documentos semelhantes pertencentes a este tenant", é mais difícil do que parece, pois um índice ANN é otimizado para ordenação de distância, não para seletividade de predicado arbitrária.
Filtrar antes ou depois do scan ANN pode alterar o recall de maneiras fáceis de perder durante testes em pequenos conjuntos de dados.
A busca híbrida, que combina relevância de palavras-chave e vetores, existe precisamente porque a similaridade vetorial pura às vezes retorna resultados que são geometricamente próximos, mas pragmaticamente errados.
O desvio de embedding é um risco de produção que não tem nada a ver com a mecânica do pgvector e tudo a ver com o modelo que gerou os vetores mudando ao longo do tempo.
Se o modelo de embedding for atualizado, vetores antigos e novos não têm mais garantia de residir em um espaço comparável, e misturá-los corrompe silenciosamente as classificações de distância.
A observabilidade para um recurso de busca vetorial deve rastrear o recall contra um conjunto de consultas rotulado ao longo do tempo, não apenas a latência da consulta, pois a latência sozinha não pode revelar um índice que está degradando silenciosamente.
Representações quantizadas, como vetores de meia precisão, fazem parte de como o ecossistema gerencia o custo de armazenamento e memória dos índices ANN à medida que os corpora crescem.
A lição arquitetural mais ampla é que o pgvector tem sucesso estendendo os pontos de extensibilidade existentes do Postgres em vez de reinventá-los, o que também é por que ele herda as garantias transacionais do Postgres gratuitamente.
| Estratégia de Busca | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Scan exato de força bruta | Sempre correto, zero manutenção de índice | Custo escala linearmente com o número de linhas | Tabelas pequenas ou análise única |
| Índice de vizinho mais próximo aproximado | Custo de consulta sub-linear em escala | Recall é probabilístico, não garantido | Busca semântica de produção em escala significativa |
| Híbrido palavra-chave + vetor | Captura correspondências de termos exatos que ANN pode perder | Mais partes móveis para ajustar e monitorar | Busca voltada para o usuário onde a precisão em nomes ou códigos importa |
Ele permite que o Postgres classifique linhas por proximidade geométrica entre vetores de embedding, que é a operação da qual a busca semântica, a recuperação RAG e as recomendações dependem.
Apenas na medida em que o modelo de embedding codificou esse significado como geometria, então a distância é um proxy para similaridade, não uma garantia dela.
O custo de comparação de força bruta cresce linearmente com o número de linhas, então se torna muito lento quando uma tabela contém mais do que aproximadamente dezenas de milhares de vetores.
Significa que o índice tem permissão para ocasionalmente perder as linhas mais próximas verdadeiras em troca de responder muito mais rápido do que um scan exato.
Ele registra seus operadores de distância através do mesmo sistema de classe de operador que todos os métodos de acesso a índice do Postgres usam, então o planejador de consulta pode raciocinar sobre scans de índice vetorial exatamente como scans B-tree ou GiST.
Sim, ele estima o custo da mesma forma que faz para qualquer outro tipo de índice e escolhe entre um scan sequencial e um scan de índice de acordo.
Recall mede a frequência com que um índice ANN retorna os verdadeiros vizinhos mais próximos em comparação com um scan exato, e um índice rápido que silenciosamente retorna correspondências ruins é pior do que um ligeiramente mais lento que não o faz.
Versões diferentes do modelo geralmente produzem vetores em espaços incomparáveis, então misturar embeddings antigos e novos pode corromper silenciosamente as classificações de distância.
Índices ANN são construídos para otimizar a ordenação de distância, não a seletividade de predicado arbitrária, então a filtragem interage com o recall de maneiras fáceis de negligenciar.
O recall contra um conjunto de consultas fixo e rotulado deve ser rastreado ao longo do tempo, pois a latência sozinha não pode revelar um índice cuja qualidade de resultado está degradando silenciosamente.
vector, operadores de distância e limites de dimensão que esta página assume.Versões do Stack: Esta página foi escrita para pgvector 0.8+. Caso contrário, é conceitual e não está vinculada a uma versão menor específica do PostgreSQL.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026