~/tools / Embeddings e busca (RAG) / pgvector SQL Builder

pgvector SQL Builder — Escreva SQL do pgvector: tabela, índice HNSW/IVFFlat e consulta de vizinhos

Escreva o SQL para guardar e pesquisar embeddings no PostgreSQL com o pgvector: uma tabela com uma coluna vector(n) ou halfvec(n), um índice HNSW ou IVFFlat com a classe de operador que corresponde à sua distância e uma consulta de vizinhos mais próximos com uma pontuação legível. Ela verifica os limites indicados na documentação do pgvector e estima quanto espaço os vetores ocupam. Nada sai do seu navegador.

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE documents (
  id bigserial PRIMARY KEY,
  content text NOT NULL,
  embedding vector(384) NOT NULL
);

CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);

PREPARE search_documents(vector(384)) AS
  SELECT id, content, 1 - (embedding <=> $1) AS cosine_similarity
  FROM documents
  ORDER BY embedding <=> $1
  LIMIT 5;

-- EXECUTE search_documents('[0.0123, -0.0456, ...]');

O pgvector é uma extensão de código aberto que adiciona ao PostgreSQL a busca por similaridade de vetores, de modo que os embeddings que você cria com o Ollama podem ser guardados no mesmo banco de dados que o restante dos seus dados. Alguns detalhes são fáceis de errar. A coluna deve ter o mesmo número de dimensões que o seu modelo de embeddings. Cada distância tem o seu próprio operador: <=> para a distância de cosseno, <-> para a distância L2, <#> para o produto interno negativo e <+> para a distância L1. Um índice aproximado só é usado se foi criado com a classe de operador da mesma distância, como vector_cosine_ops para <=>, e se a consulta ordena pelo próprio operador em ordem crescente com um LIMIT. Esta ferramenta escreve as três partes a partir de um único conjunto de escolhas: CREATE EXTENSION e CREATE TABLE, CREATE INDEX, e uma instrução PREPARE que devolve as linhas mais próximas com uma pontuação legível (a similaridade de cosseno é 1 menos a distância de cosseno, e o produto interno é <#> multiplicado por -1). Ela aplica os limites do README e do código-fonte do pgvector para a versão 0.8.7: até 16,000 dimensões em uma coluna, índices de até 2,000 dimensões para vector e 4,000 para halfvec, sem classe de operador L1 para IVFFlat, m do HNSW de 2 a 100, e ef_construction de 4 a 1,000 e pelo menos 2 × m. Com HNSW, uma busca devolve no máximo hnsw.ef_search linhas (40 por padrão), então a ferramenta avisa quando LIMIT é maior. Para o IVFFlat, ela preenche lists e probes com os pontos de partida do README: rows / 1000 até 1M linhas, sqrt(rows) acima disso, e sqrt(lists) para probes. O SQL gerado foi executado no pgvector 0.8.7 com PostgreSQL 16 usando vetores reais de 384 dimensões do Ollama, e o EXPLAIN mostrou o índice sendo usado.

A lógica principal desta ferramenta é de código aberto, sob a licença MIT. github.com/seigo5555/toolkitbox-lib/src/pgvector-sql.ts