~/tools / Embeddings y búsqueda (RAG) / pgvector SQL Builder

pgvector SQL Builder — Escribe SQL de pgvector: tabla, índice HNSW/IVFFlat y consulta de vecinos

Escribe el SQL para guardar y buscar embeddings en PostgreSQL con pgvector: una tabla con una columna vector(n) o halfvec(n), un índice HNSW o IVFFlat con la clase de operador que corresponde a tu distancia y una consulta de vecinos más cercanos con una puntuación legible. Comprueba los límites indicados en la documentación de pgvector y estima cuánto espacio ocupan los vectores. Nada sale de tu 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, ...]');

pgvector es una extensión de código abierto que añade a PostgreSQL la búsqueda por similitud de vectores, de modo que los embeddings que creas con Ollama pueden guardarse en la misma base de datos que el resto de tus datos. Hay varios detalles fáciles de equivocar. La columna debe tener el mismo número de dimensiones que tu modelo de embeddings. Cada distancia tiene su propio operador: <=> para la distancia del coseno, <-> para la distancia L2, <#> para el producto interno negativo y <+> para la distancia L1. Un índice aproximado solo se usa si se creó con la clase de operador de la misma distancia, como vector_cosine_ops para <=>, y si la consulta ordena por el propio operador en orden ascendente con un LIMIT. Esta herramienta escribe las tres partes a partir de un único conjunto de opciones: CREATE EXTENSION y CREATE TABLE, CREATE INDEX, y una sentencia PREPARE que devuelve las filas más cercanas con una puntuación legible (la similitud del coseno es 1 menos la distancia del coseno, y el producto interno es <#> multiplicado por -1). Aplica los límites del README y del código fuente de pgvector para la versión 0.8.7: hasta 16,000 dimensiones en una columna, índices de hasta 2,000 dimensiones para vector y 4,000 para halfvec, sin clase de operador L1 para IVFFlat, m de HNSW de 2 a 100, y ef_construction de 4 a 1,000 y al menos 2 × m. Con HNSW, una búsqueda devuelve como máximo hnsw.ef_search filas (40 por defecto), así que la herramienta avisa cuando LIMIT es mayor. Para IVFFlat rellena lists y probes con los puntos de partida del README: rows / 1000 hasta 1M filas, sqrt(rows) por encima de eso, y sqrt(lists) para probes. El SQL generado se ejecutó en pgvector 0.8.7 con PostgreSQL 16 usando vectores reales de 384 dimensiones de Ollama, y EXPLAIN mostró que se usaba el índice.

La lógica principal de esta herramienta es de código abierto, con licencia MIT. github.com/seigo5555/toolkitbox-lib/src/pgvector-sql.ts