Búsqueda semántica con pgvector: lo que el cliente quiso decir
En la práctica/ 18 min de lectura
Guarda los embeddings de tus productos en Postgres con pgvector, busca por similitud con un índice HNSW y combina texto y significado con RRF. Probado en PGlite.
- IA
- Bases de datos
En este artículo (9)
La búsqueda semántica encuentra productos por lo que el cliente quiso decir, no por las palabras exactas que escribió. Conviertes cada producto y cada búsqueda en un embedding, una lista de números, lo guardas en Postgres con pgvector y ordenas por distancia: «algo calientito para la nieve» encuentra la chamarra de plumas aunque su ficha no diga «nieve».
Abajo tienes la tabla, el índice HNSW, la consulta de similitud, la búsqueda híbrida que combina texto y significado y el script que genera los embeddings, con la salida real de cada consulta. Lo probamos con PGlite 0.5.10 (PostgreSQL 18.6 en WebAssembly) y su extensión pgvector 0.8.7. La llamada al proveedor de embeddings la sustituimos con vectores de juguete: el SQL es real; la calidad de un modelo de verdad no la medimos.
Por qué la búsqueda por palabras falla
El buscador de una tienda suele comparar palabras. En Postgres eso es la búsqueda de texto completo: cada producto se guarda como tsvector, sus palabras reducidas a la raíz, y lo que escribe el cliente se convierte en tsquery. Funciona cuando el cliente escribe el nombre del producto. Falla cuando escribe lo que necesita:
- Describe el uso, no el producto. Nadie titula una chamarra «algo calientito para la nieve».
- Usa otra palabra. Chamarra, chaqueta, campera y casaca son la misma prenda según el país, y tu catálogo usa solo una.
- Escribe frases. Con
websearch_to_tsquery, las palabras sin comillas se unen con&: todas tienen que aparecer en el producto.
Esta es la búsqueda por texto de nuestras pruebas, sobre un catálogo inventado de diez productos:
export async function textSearch(sql, q, limit = 5) {
return sql`
SELECT handle, title, round(ts_rank_cd(search, query)::numeric, 3) AS rank
FROM products, websearch_to_tsquery('spanish', ${q}) query
WHERE search @@ query
ORDER BY ts_rank_cd(search, query) DESC
LIMIT ${limit}`;
}
websearch_to_tsquery('spanish', …)convierte el texto del cliente en una consulta con las reglas del español. Según la documentación de búsqueda de texto de PostgreSQL, entiende comillas,ORy el guion, y nunca lanza errores de sintaxis, así que acepta el texto tal cual llega.search @@ queryse queda con los productos cuyotsvectorcumple la consulta.searches una columna de la tabla que verás más abajo.ts_rank_cdordena por relevancia; la documentación lo describe como un ranking de densidad de cobertura, que toma en cuenta qué tan cerca aparecen las palabras entre sí.
Esto devolvió para «algo calientito para la nieve». «algo», «para» y «la» son palabras vacías en español y se descartan; quedan dos raíces y ningún producto tiene las dos:
SELECT websearch_to_tsquery('spanish', 'algo calientito para la nieve');
-- 'calientit' & 'niev'
-- textSearch('algo calientito para la nieve')
handle | title | rank
--------+-------+------
(0 rows)
- La consulta quedó en
'calientit' & 'niev': las dos raíces deben estar en el mismo producto. - Cero filas. El cliente ve «no encontramos resultados» en una tienda que sí vende chamarras, gorros y calcetines térmicos.
Qué es un embedding
La documentación de embeddings de Anthropic los define como representaciones numéricas de un texto que permiten medir su similitud semántica. En la práctica, un modelo de embeddings recibe un texto y devuelve un vector: una lista de tamaño fijo, por ejemplo de 1024 números. Los textos con significado parecido quedan cerca en ese espacio aunque no compartan palabras, y buscar se reduce a calcular qué productos están más cerca del vector de la búsqueda.
Desliza la figura para verla completa
Tres datos de esa documentación cambian el diseño:
- Anthropic no ofrece un modelo de embeddings propio. La página lo dice tal cual, usa como ejemplo a Voyage AI y recomienda evaluar varios proveedores. Aquí hablamos de «el proveedor que uses»: el SQL es el mismo.
- La dimensión la decide el modelo. Los modelos que lista esa página devuelven 1024 números por defecto, y varios aceptan 256, 512 o 2048. La columna de Postgres se declara con esa dimensión exacta.
- El proveedor puede pedirte si el texto es documento o consulta. En el ejemplo de la página, el catálogo se envía con
input_type="document"y la búsqueda coninput_type="query". Si tu proveedor lo pide, usa una función para cada caso.
En nuestras pruebas no llamamos a ningún proveedor. La función embed(texts) es un stub: un diccionario hecho a mano que asigna unas cuarenta palabras a 8 conceptos (frío, lluvia, calzado, deporte, café, calor, ropa y cocina) y devuelve el vector normalizado a longitud 1. Es determinista y repetible, pero no es un modelo: solo conoce las palabras de su lista. Sirve para probar el SQL, no la calidad de la búsqueda.
Guardar embeddings con pgvector
pgvector es una extensión de Postgres que agrega el tipo vector, operadores de distancia e índices de vecinos más cercanos. Antes de crear la tabla, comprueba que tu servidor la tenga disponible con SELECT * FROM pg_available_extensions WHERE name = 'vector'. Este es schema.sql, el de las pruebas:
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE products (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
handle text NOT NULL UNIQUE,
title text NOT NULL,
description text NOT NULL DEFAULT '',
search tsvector GENERATED ALWAYS AS
(to_tsvector('spanish', title || ' ' || description)) STORED,
content_hash text GENERATED ALWAYS AS (md5(title || ' ' || description)) STORED,
embedding vector(1024),
embedded_hash text,
embedded_with text
);
CREATE INDEX products_search_idx ON products USING gin (search);
CREATE INDEX products_embedding_idx ON products USING hnsw (embedding vector_cosine_ops);
CREATE EXTENSIONactiva pgvector en la base. En PGlite no viene incluida: se instala aparte como@electric-sql/pglite-pgvector, según su página de extensiones.searches una columna generada con el texto listo para buscar. La documentación de PostgreSQL sobre tablas e índices de texto usa una columna generada para que se mantenga al día sola. La usa la búsqueda híbrida.content_hashes elmd5del texto que se convierte en vector; si alguien edita el título o la descripción, cambia solo.embedding vector(1024)guarda el vector, con la dimensión de tu modelo. pgvector rechaza otro tamaño: en las pruebas usamosvector(8)y un vector de 3 números falló conexpected 8 dimensions, not 3.embedded_hashyembedded_withdicen de qué texto y con qué modelo salió el vector guardado. Si no coinciden concontent_hashy con el modelo actual, toca regenerarlo.- El índice GIN acelera la búsqueda de texto y el HNSW, la de vectores por distancia coseno (
vector_cosine_ops).
Del índice HNSW, el README de pgvector dice cuatro cosas que conviene saber antes de crearlo:
- Sin índice, pgvector hace búsqueda exacta, con recall perfecto (encuentra todos los vecinos reales). Con HNSW o IVFFlat la búsqueda es aproximada: cambia algo de recall por velocidad, y el README avisa que verás resultados distintos al agregar el índice.
- HNSW tiene mejor relación entre velocidad y recall que IVFFlat, pero tarda más en construirse y usa más memoria. A diferencia de IVFFlat, se puede crear con la tabla vacía.
- Indexa columnas
vectorde hasta 2,000 dimensiones yhalfvecde hasta 4,000. - Al buscar revisa una lista de 40 candidatos por defecto (
hnsw.ef_search). Si te faltan resultados, súbela dentro de una transacción conSET LOCAL hnsw.ef_search = 100.
Estos son los operadores de distancia del README que vas a usar con texto:
| Operador | Distancia | Clase del índice | Cuándo |
|---|---|---|---|
<=> | Coseno | vector_cosine_ops | La opción general; es la que usamos. |
<#> | Producto interno, negativo | vector_ip_ops | Si tu proveedor devuelve vectores de longitud 1: el README la recomienda por rendimiento. |
<-> | Euclidiana (L2) | vector_l2_ops | Cuando la documentación de tu modelo la pide. |
<#> devuelve el producto interno en negativo porque Postgres solo recorre índices en orden ascendente. Y el operador de la consulta debe ser el de la clase del índice: uno con vector_cosine_ops solo acelera ORDER BY embedding <=> ….
El vector de cada producto lo genera index-products.mjs, con Postgres.js, el mismo driver de la cola de trabajos en Postgres con SKIP LOCKED:
// Embeds every product whose text or model changed since its last embedding.
// embed(texts) calls your provider and returns one vector per text, in order.
export async function indexProducts(sql, embed, { model, dimensions, batchSize = 64 }) {
let total = 0;
for (;;) {
const rows = await sql`
SELECT id, title || ' ' || description AS text, content_hash
FROM products
WHERE embedded_hash IS DISTINCT FROM content_hash
OR embedded_with IS DISTINCT FROM ${model}
ORDER BY id
LIMIT ${batchSize}`;
if (rows.length === 0) return total;
const vectors = await embed(rows.map((r) => r.text));
if (vectors.length !== rows.length) {
throw new Error(`expected ${rows.length} vectors, got ${vectors.length}`);
}
for (const v of vectors) {
if (v.length !== dimensions || !v.every(Number.isFinite)) {
throw new Error(`expected ${dimensions} finite numbers per vector`);
}
}
await sql.begin(async (tx) => {
for (const [i, row] of rows.entries()) {
await tx`
UPDATE products
SET embedding = ${JSON.stringify(vectors[i])}::vector,
embedded_hash = ${row.content_hash}, embedded_with = ${model}
WHERE id = ${row.id}`;
}
});
total += rows.length;
}
}
- Busca hasta 64 productos cuyo
embedded_hashno coincide concontent_hasho cuyo vector salió de otro modelo.IS DISTINCT FROMtrataNULLcomo un valor más, así que también entran los productos nuevos. - Manda los textos en un solo lote a
embed, la función que llama a tu proveedor. - Valida la respuesta antes de escribir: un vector por producto, la dimensión exacta y solo números finitos. Si el proveedor responde mal, lanza un error y no toca la tabla; dos pruebas lo comprueban.
- Guarda cada vector como texto
[0.1,0.2,…]con::vector, junto con el hash del texto que se envió y el nombre del modelo, en una sola transacción. - Repite hasta que no queda nada pendiente y devuelve cuántos productos procesó: 10 en la primera corrida, 0 en la segunda.
El detalle está en el paso 4: se guarda el hash del texto que se mandó al proveedor, no el de la fila en ese momento. Si alguien edita el producto mientras el proveedor responde, el hash guardado ya no coincide y la siguiente vuelta lo regenera. Lo probamos: con embedded_hash = content_hash en el UPDATE, la prueba de esa carrera falla y el producto se queda con un vector viejo marcado como al día.
Desliza la figura para verla completa
La consulta de búsqueda semántica
Para buscar, conviertes la búsqueda del cliente en un vector con el mismo modelo y pides los productos más cercanos:
export async function semanticSearch(sql, embed, q, limit = 5) {
const [vector] = await embed([q]);
const v = JSON.stringify(vector);
return sql`
SELECT handle, title, round((1 - (embedding <=> ${v}::vector))::numeric, 3) AS similarity
FROM products
WHERE embedding IS NOT NULL
ORDER BY embedding <=> ${v}::vector
LIMIT ${limit}`;
}
embed([q])genera el vector de la búsqueda: una llamada al proveedor por cada búsqueda.embedding <=> …es la distancia coseno.ORDER BYesa distancia conLIMITes la forma de consulta que el índice HNSW acelera.1 - distanciaes la similitud coseno, como indica el README; la mostramos con tres decimales.WHERE embedding IS NOT NULLdeja fuera los productos que aún no tienen vector.
Con el catálogo de prueba y los vectores de juguete, esto devolvió:
-- semanticSearch('algo calientito para la nieve')
handle | title | similarity
---------------------+----------------------+------------
chamarra-plumas | Chamarra de plumas | 0.920
gorro-lana | Gorro de lana | 0.901
calcetines-termicos | Calcetines térmicos | 0.780
sudadera-capucha | Sudadera con capucha | 0.474
impermeable-ligero | Impermeable ligero | 0.303
(5 rows)
-- semanticSearch('botas')
handle | title | similarity
---------------------+---------------------+------------
tenis-correr | Tenis para correr | 0.539
calcetines-termicos | Calcetines térmicos | 0.520
botas-lluvia | Botas de lluvia | 0.489
playera-algodon | Playera de algodón | 0.000
termo-acero | Termo de acero | 0.000
(5 rows)
- La búsqueda que por texto dio cero filas ahora trae primero la chamarra, el gorro y los calcetines térmicos.
- Con «botas», el producto que se llama así quedó tercero, detrás de los tenis. Se debe a cómo armamos los vectores de juguete, pero muestra un riesgo real: la similitud mide parecido, no coincidencia exacta.
- Las dos últimas filas tienen similitud 0.000 y aun así aparecen. Una búsqueda por vectores no responde «sin resultados»: siempre trae los más cercanos, aunque estén lejos.
Con diez filas, el planificador prefiere recorrer la tabla entera. Para comprobar que la consulta puede usar el índice la corrimos con SET LOCAL enable_seqscan = off, y EXPLAIN mostró Index Scan using products_embedding_idx con Order By: (embedding <=> …).
Búsqueda híbrida: texto y significado
El README de pgvector propone usarlo junto con la búsqueda de texto completo de Postgres y combinar los resultados con Reciprocal Rank Fusion (RRF) o con un cross-encoder. RRF es lo más simple: cada lista ordena con su criterio y cada producto suma 1 / (k + posición) por cada lista donde aparece. Usamos k = 60, el valor del ejemplo de RRF de pgvector-python:
export async function hybridSearch(sql, embed, q, limit = 5) {
const [vector] = await embed([q]);
const v = JSON.stringify(vector);
return sql`
WITH semantic AS (
SELECT id, rank() OVER (ORDER BY embedding <=> ${v}::vector) AS rank
FROM products
WHERE embedding IS NOT NULL
ORDER BY embedding <=> ${v}::vector
LIMIT 20
),
keyword AS (
SELECT id, rank() OVER (ORDER BY ts_rank_cd(search, query) DESC) AS rank
FROM products, websearch_to_tsquery('spanish', ${q}) query
WHERE search @@ query
ORDER BY ts_rank_cd(search, query) DESC
LIMIT 20
)
SELECT p.handle, semantic.rank AS by_meaning, keyword.rank AS by_text,
round(COALESCE(1.0 / (60 + semantic.rank), 0)
+ COALESCE(1.0 / (60 + keyword.rank), 0), 4) AS score
FROM semantic
FULL OUTER JOIN keyword ON keyword.id = semantic.id
JOIN products p ON p.id = COALESCE(semantic.id, keyword.id)
ORDER BY score DESC, p.id
LIMIT ${limit}`;
}
- El CTE
semantictoma los 20 productos más cercanos por significado y numera su posición conrank(). - El CTE
keywordtoma los 20 mejores por texto, con la misma consulta de la primera sección. FULL OUTER JOINjunta las dos listas: un producto puede estar en una, en la otra o en ambas.- Cada producto suma
1 / (60 + posición)por lista yCOALESCE(…, 0)pone cero donde no aparece. Gana el que sale bien en las dos. - El orden final es por
score, con elidpara desempatar siempre igual.
-- hybridSearch('botas')
handle | by_meaning | by_text | score
---------------------+------------+---------+--------
botas-lluvia | 3 | 1 | 0.0323
tenis-correr | 1 | | 0.0164
calcetines-termicos | 2 | | 0.0161
chamarra-plumas | 4 | | 0.0156
gorro-lana | 4 | | 0.0156
(5 rows)
- Las botas de lluvia suben al primer lugar: 1/63 por significado más 1/61 por texto da 0.0323, casi el doble que los tenis, que solo aparecen en una lista.
- Para «algo calientito para la nieve», la lista de texto está vacía y el resultado híbrido queda en el mismo orden que el semántico: chamarra, gorro y calcetines.
- La chamarra y el gorro empatan en la posición 4 con similitud cero: aparecen porque la lista semántica siempre llena sus lugares. En tu tienda, muestra menos resultados o corta por una similitud mínima que calibres con búsquedas reales.
Desliza la figura para verla completa
El texto cubre lo que el significado no garantiza: un nombre exacto, un SKU, una marca o una talla. El significado cubre lo que el texto no alcanza: sinónimos, frases y necesidades. Y como RRF solo usa la posición, no tienes que ajustar pesos entre puntuaciones que se miden en escalas distintas.
Costo y cuándo regenerar los embeddings
No citamos precios: cambian y dependen del proveedor (para Voyage AI, la documentación de Anthropic remite a la de MongoDB). Lo que sí puedes calcular con tus datos:
| Concepto | Fórmula | Ejemplo ilustrativo |
|---|---|---|
| Indexar el catálogo | productos × tokens por producto × precio por token | 5,000 × 150 = 750,000 tokens, una vez |
| Cada búsqueda | búsquedas × tokens por búsqueda × precio por token | 100,000 × 8 = 800,000 tokens al mes |
| Regenerar | productos editados × tokens por producto × precio por token | 200 × 150 = 30,000 tokens |
| Almacenamiento | 4 × dimensiones + 8 bytes por vector, según el README | 4,104 bytes con 1024 dimensiones; 5,000 productos ≈ 20.5 MB, más el índice |
Los tokens de la tabla son un ejemplo ilustrativo, no una medición. Para tener los tuyos, el ejemplo HTTP de la documentación de Anthropic muestra que la respuesta trae el uso en usage.total_tokens: guárdalo en la primera indexación y saca el promedio por producto. El tamaño sí lo medimos: pg_column_size de un vector(1024) dio 4104 bytes en PGlite.
Cuándo regenerar:
- Cuando cambia el texto que conviertes en vector. En nuestro caso, título y descripción. Si agregas el tipo de producto o las etiquetas, agrégalos también a
content_hash. - Cuando cambias de modelo o de dimensión. El vector de un modelo no se compara con el de otro: la búsqueda y los productos tienen que salir del mismo. Cambiar
modelen el script regenera todo el catálogo; la prueba lo confirma con los diez productos. - No cuando cambia el precio o el stock. Eso no va en el vector: fíltralo con
WHERE.
Y no lo hagas dentro del request de quien edita el producto. Cuando llegue el webhook de actualización, verifica el HMAC del webhook de Shopify, encola un trabajo y deja que un worker llame a indexProducts: la cola de trabajos en Postgres lo reintenta si el proveedor falla. Como el script solo procesa lo que cambió, una corrida sin cambios no llama al proveedor.
Errores comunes
- Mezclar modelos. Buscar con el vector de un modelo nuevo sobre productos del anterior compara vectores de espacios distintos; si además cambió la dimensión, falla (en nuestra prueba:
different vector dimensions 2 and 3). Regenera todo antes de cambiar la consulta. - Elegir una dimensión que el índice no acepta. Si tu modelo devuelve 2048 números, el índice HNSW sobre
vectorno los indexa: el límite es 2,000. Usahalfvec, que llega a 4,000, o pide una dimensión menor. - Filtrar sin saber cuándo se filtra. Con índices aproximados, el
WHEREse aplica después de recorrer el índice. El README da el ejemplo: si la condición deja el 10% de las filas, con HNSW yhnsw.ef_searchen 40 obtienes en promedio solo 4. Desde pgvector 0.8.0 existen los recorridos iterativos:SET hnsw.iterative_scan = strict_order. - Tratar la similitud como relevancia. La consulta siempre devuelve el
LIMITcompleto, aunque lo último no tenga nada que ver. Corta los resultados lejanos. - Generar el vector dentro del request. Indexar en el request de guardado hace esperar al administrador y pierde el trabajo si el proveedor falla. Hazlo en segundo plano.
- Olvidar el tipo de entrada. Si tu proveedor distingue documento y consulta, indícalo siempre. La documentación de embeddings de Anthropic, en su parte de Voyage AI, pide no omitir
input_typeporque indicarlo puede mejorar la calidad de la recuperación.
Preguntas frecuentes
¿Puedo generar los embeddings con Claude?
No. La documentación de Anthropic dice que Anthropic no ofrece su propio modelo de embeddings, usa a Voyage AI como ejemplo de proveedor y recomienda evaluar varios. El vector sale de un modelo de embeddings; el SQL de este artículo funciona con el que elijas.
¿Necesito una base de datos vectorial aparte?
Si ya usas Postgres, pgvector guarda los vectores en la misma tabla que el producto, con transacciones, joins y filtros normales. El README da como límite el de una tabla de Postgres sin particionar: 32 TB por defecto. Nuestra regla: empieza en tu Postgres y cambia solo si mides un problema que no puedas resolver ahí.
¿Cuántas dimensiones elijo?
Las que devuelva tu modelo. Si ofrece varias, como 256, 512, 1024 o 2048 en los modelos que lista la documentación de Anthropic, menos dimensiones ocupan menos espacio (4 × dimensiones + 8 bytes) y caben en el índice HNSW sobre vector hasta 2,000. Compara la calidad con tus búsquedas reales antes de reducirlas.
¿Qué pasa si el proveedor de embeddings se cae?
La parte semántica necesita el vector de la consulta, así que sin proveedor no hay similitud. Nuestra recomendación: atrapa el error y responde solo con la parte de texto, que no depende de nadie más. Ese respaldo no está en el código probado.
Checklist
- pgvector está disponible en tu Postgres (
pg_available_extensions) y activado conCREATE EXTENSION. - La columna
vector(n)tiene la dimensión exacta de tu modelo, como máximo 2,000 si la indexas con HNSW comovector. - La tabla tiene
content_hashgenerado,embedded_hashyembedded_with. - El índice HNSW usa la clase del operador de tu consulta:
vector_cosine_opscon<=>. indexProductsvalida cantidad, dimensión y números antes de escribir.- Los vectores se regeneran en segundo plano, desde una cola, cuando cambia el texto o el modelo.
- La búsqueda combina texto y significado con RRF y corta los resultados lejanos.
- Probaste con búsquedas reales de tu tienda antes de cambiar el buscador.
Empieza con la búsqueda híbrida y una lista de búsquedas reales que hoy no dan resultados: es la forma más rápida de ver si los embeddings ayudan en tu catálogo. Para regenerar en segundo plano, monta la cola de trabajos en Postgres con SKIP LOCKED, y si los cambios llegan por webhook, verifica su HMAC antes de encolarlos.
Con la misma tabla puedes armar un chatbot RAG que responde con tus documentos.
¿Viste esto en Instagram? Comenta EMBEDDINGS en el Reel y te mando la guía.
Escrito por

Publicado el 11 de noviembre de 2026 · actualizado el 18 de noviembre de 2026