O que é o pgvector

O pgvector e uma extensão open source para o PostgreSQL que adiciona suporte nativo a armazenamento e busca de vetores. Ele foi criado para resolver um problema cada vez mais comum: aplicações de inteligência artificial precisam guardar e comparar embeddings, e até pouco tempo isso exigia um banco de dados separado só para essa finalidade.

Com o pgvector, o mesmo Postgres que já guarda os dados relacionais da aplicação passa a guardar também os vetores gerados por modelos de linguagem, sem precisar migrar para uma solução dedicada de banco vetorial.

O projeto ganhou força especialmente com a popularização de aplicações RAG (Retrieval Augmented Generation), onde e preciso buscar trechos de texto semanticamente parecidos com uma pergunta do usuário antes de enviar tudo para um modelo de linguagem gerar a resposta.

Como funciona

Um embedding e uma representação numérica de um texto, imagem ou outro dado, gerada por um modelo de IA. Textos com significados parecidos geram vetores numericamente próximos entre si.

O pgvector adiciona um novo tipo de coluna ao Postgres, chamado vector, que guarda esses números. Junto com isso, ele oferece operadores para calcular a distancia entre vetores, como distancia euclidiana, produto interno e similaridade de cosseno.

Na prática, quando você quer buscar os documentos mais parecidos com uma pergunta, o pgvector calcula a distancia entre o vetor da pergunta e os vetores armazenados, retornando os mais próximos. E como perguntar 'quais números estão mais pertinho deste aqui' em varias dimensões ao mesmo tempo.

Principais recursos

O pgvector cobre as necessidades essenciais de busca vetorial dentro do ecossistema Postgres:

  • Tipo de dado vector: armazena arrays de números de ponto flutuante com dimensão definida.
  • Operadores de distancia: cosseno, euclidiana (L2) e produto interno, escolhidos conforme o modelo de embedding usado.
  • Índices HNSW e IVFFlat: estruturas de indexação que aceleram buscas por similaridade em grandes volumes de dados.
  • Integração SQL nativa: buscas vetoriais podem ser combinadas com filtros relacionais comuns na mesma query.
  • Compatibilidade com extensões do ecossistema Postgres: funciona junto com replicação, backup e ferramentas já usadas pela equipe.

O diferencial principal e não exigir infraestrutura extra. Times que já usam Postgres podem adicionar busca vetorial sem introduzir um novo banco de dados no stack.

Como começar: instalação ou acesso passo a passo

Passo 1: instale a extensão no seu servidor Postgres. Em distribuições Linux, geralmente basta:

sudo apt install PostgreSQL-16-pgvector

Passo 2: ative a extensão dentro do banco de dados desejado:

CREATE EXTENSION vector;

Passo 3: crie uma tabela com uma coluna do tipo vector, definindo a dimensão de acordo com o modelo de embedding usado (por exemplo, 1536 dimensões para alguns modelos populares):

CREATE TABLE documentos (
  id serial PRIMARY KEY,
  conteúdo text,
  embedding vector(1536)
);

Passo 4: crie um índice para acelerar as buscas em tabelas grandes:

CREATE ÍNDEX ON documentos USING hnsw (embedding vector_cosine_ops);
💡
Dica

Serviços gerenciados como Supabase e Néon já vem com o pgvector pre-instalado, bastando ativar a extensão com um comando SQL.

Exemplo prático

Imagine uma aplicação de busca em documentação técnica. Cada trecho de texto e transformado em embedding por um modelo de IA e salvo na tabela documentos.

Quando o usuário faz uma pergunta, a aplicação gera o embedding da pergunta e busca os trechos mais próximos no banco:

SELECT conteúdo
FROM documentos
ORDER BY embedding <=> '[0.012, -0.034, ...]'
LIMIT 5;

O operador <=> calcula a distancia de cosseno entre o vetor da pergunta e cada vetor armazenado. Os cinco resultados mais próximos são os trechos mais relevantes, que depois podem ser enviados junto com a pergunta original para um modelo de linguagem gerar a resposta final.

Comparação com alternativas

Bancos de dados vetoriais dedicados, como Pinecone e Weaviate, oferecem recursos avançados de escala horizontal e foram construidos desde o inicio para esse único propósito, o que pode trazer melhor performance em volumes extremamente grandes.

O Qdrant também é uma opcao popular, com foco específico em busca vetorial de alta performance e recursos de filtragem avançados.

O diferencial do pgvector e a simplicidade operacional: se sua aplicação já usa Postgres, adicionar busca vetorial e uma questão de instalar uma extensão, sem precisar manter um banco de dados adicional, replicar dados entre sistemas ou aprender uma API diferente.

Pontos positivos e limitações

Entre os pontos fortes: menos peças na infraestrutura, uso do SQL que o time já conhece, e a possibilidade de combinar busca vetorial com filtros relacionais tradicionais na mesma consulta.

As limitações aparecem em escala muito grande. Para coleções com dezenas de milhões de vetores e exigência de latência mínima, bancos vetoriais dedicados tendem a performar melhor, já que foram otimizados especificamente para esse cenário.

⚠️
Atenção

Escolher a dimensão errada do vetor na criação da tabela e um erro comum. A dimensão precisa bater exatamente com a saída do modelo de embedding usado, senão a inserção falha.

Casos de uso reais

Time construindo um chatbot com RAG: já tem Postgres rodando e quer adicionar busca semântica na documentação sem introduzir novo banco.

Startup de e-commerce: usa embeddings para recomendar produtos parecidos com base em descrição e imagem, mantendo tudo no mesmo banco de dados dos pedidos.

Aplicação de suporte ao cliente: busca respostas anteriores parecidas com a pergunta atual para sugerir soluções automaticamente.

Projeto pessoal ou MVP: quer testar uma feature de busca semântica rápido, sem custo adicional de infraestrutura de banco vetorial dedicado.

Dicas e boas práticas

🚀
Pro tip

Use o índice HNSW em vez do IVFFlat quando precisar de buscas mais precisas, mesmo que a construção do índice seja um pouco mais lenta.

💡
Dica

Normalize os vetores antes de salvar se for usar produto interno como métrica de distancia, isso evita resultados distorcidos.

🔴
Cuidado

Não esqueça de recriar o índice após uma inserção em massa de vetores. Sem isso, as buscas continuam rápidas mas podem retornar resultados menos precisos até a reindexação.

Vale a pena?

Para quem já usa Postgres e precisa adicionar busca semântica ou recursos de IA baseados em embeddings, o pgvector e quase sempre a escolha certa. Ele elimina a necessidade de aprender e manter uma peca extra de infraestrutura.

Projetos com volume gigantesco de vetores e exigência extrema de latência podem justificar um banco vetorial dedicado, mas para a grande maioria dos casos, o pgvector entrega o necessário com muito menos complexidade.

O próximo passo e simples: se você já tem um Postgres rodando, ative a extensão e comece a guardar seus primeiros embeddings ainda hoje.