pgvector en producción: RAG dentro de tu base de datos
La mayoría de equipos que implementan RAG por primera vez siguen el mismo camino: ven un tutorial, crean una cuenta en Pinecone, y en dos semanas tienen dos fuentes de verdad que se desincronizan, un servicio más que monitorizar y una factura mensual que nadie presupuestó.
Si ya tienes PostgreSQL en producción, lo estás mirando. pgvector convierte tu base de datos existente en un motor de búsqueda vectorial sin añadir infraestructura, sin sincronización y sin coste adicional.
El error que se repite en cada proyecto RAG
El flujo habitual: decides añadir RAG a tu agente, lees la documentación de algún framework, el ejemplo usa Pinecone, sigues el ejemplo. Resultado: tu aplicación ahora tiene dos bases de datos que necesitan estar sincronizadas.
Cuando actualizas un documento en PostgreSQL, tienes que acordarte de actualizar el embedding en Pinecone. Cuando Pinecone tiene un outage, tu agente deja de recuperar contexto. Cuando el volumen de datos crece, la factura de Pinecone crece con él.
La alternativa no requiere migrar nada: pgvector es una extensión de PostgreSQL que añade el tipo vector y operadores de similitud. Tu base de datos ya existente, con una extensión.
Índices: HNSW vs IVFFlat
pgvector ofrece dos tipos de índice vectorial:
IVFFlat divide el espacio vectorial en clusters y busca solo en los más cercanos al vector de consulta. Rápido de construir, pero necesita datos previos para clusterizar correctamente. Si arrancas con una tabla vacía y construyes el índice antes de insertar datos, el recall será malo.
HNSW (hierarchical navigable small world) construye una estructura de grafos multicapa. Más lento de construir, mejor recall, menor latencia de consulta, y funciona bien desde el primer registro.
-- HNSW: punto de partida para producción
CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
-- Para aumentar recall en búsqueda (a costa de latencia):
SET hnsw.ef_search = 100;
El parámetro m controla las conexiones por nodo: más conexiones = mejor recall, más memoria. ef_construction controla la precisión durante la construcción del índice. Para la mayoría de proyectos, m=16, ef_construction=64 es el punto de partida correcto. Ajusta ef_search en tiempo de ejecución según tus SLAs.
Setup en TypeScript
import { Pool } from 'pg';
import { embed } from 'ai';
import { openai } from '@ai-sdk/openai';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
async function setupSchema() {
await pool.query(`
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS documents (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
content TEXT NOT NULL,
metadata JSONB DEFAULT '{}',
embedding vector(1536),
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX IF NOT EXISTS documents_embedding_idx
ON documents USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
`);
}
async function indexDocument(content: string, metadata: object) {
const { embedding } = await embed({
model: openai.embedding('text-embedding-3-small'),
value: content,
});
await pool.query(
'INSERT INTO documents (content, metadata, embedding) VALUES ($1, $2, $3)',
[content, metadata, JSON.stringify(embedding)]
);
}
async function search(query: string, limit = 5) {
const { embedding } = await embed({
model: openai.embedding('text-embedding-3-small'),
value: query,
});
const { rows } = await pool.query(
`SELECT id, content, metadata,
1 - (embedding <=> $1::vector) AS similarity
FROM documents
ORDER BY embedding <=> $1::vector
LIMIT $2`,
[JSON.stringify(embedding), limit]
);
return rows;
}
Fíjate en el cast explícito $1::vector: sin él, PostgreSQL no puede inferir el tipo del parámetro y el índice HNSW no se usa, cayendo en un seq scan completo.
Búsqueda híbrida: vector + texto completo
La búsqueda vectorial falla con términos exactos: IDs, nombres propios, números de referencia, códigos de producto. La búsqueda de texto completo falla con sinónimos y contexto semántico. Combinando ambas con Reciprocal Rank Fusion (RRF) obtienes lo mejor de cada una:
async function hybridSearch(query: string, limit = 5) {
const { embedding } = await embed({
model: openai.embedding('text-embedding-3-small'),
value: query,
});
const { rows } = await pool.query(`
WITH
vector_results AS (
SELECT id,
ROW_NUMBER() OVER (ORDER BY embedding <=> $1::vector) AS rank
FROM documents
ORDER BY embedding <=> $1::vector
LIMIT 20
),
text_results AS (
SELECT id,
ROW_NUMBER() OVER (
ORDER BY ts_rank(
to_tsvector('spanish', content),
plainto_tsquery('spanish', $2)
) DESC
) AS rank
FROM documents
WHERE to_tsvector('spanish', content) @@
plainto_tsquery('spanish', $2)
LIMIT 20
)
SELECT d.id, d.content, d.metadata,
COALESCE(1.0 / (60 + vr.rank), 0) +
COALESCE(1.0 / (60 + tr.rank), 0) AS rrf_score
FROM documents d
LEFT JOIN vector_results vr ON d.id = vr.id
LEFT JOIN text_results tr ON d.id = tr.id
WHERE vr.id IS NOT NULL OR tr.id IS NOT NULL
ORDER BY rrf_score DESC
LIMIT $3
`, [JSON.stringify(embedding), query, limit]);
return rows;
}
El valor 60 en el denominador es el parámetro estándar de RRF — controla el peso relativo de posiciones bajas. Puedes ajustarlo, pero 60 funciona bien como punto de partida.
Este patrón es parte del stack estándar de los proyectos de integración IA que construimos sobre PostgreSQL.
Cuándo sí necesitas un vector store dedicado
pgvector no es la solución universal. Hay casos donde Pinecone, Qdrant o Weaviate tienen sentido:
- Más de 10 millones de vectores con SLAs de latencia por debajo de 50 ms
- Escrituras masivas en tiempo real — miles de inserciones por segundo con búsquedas simultáneas
- Filtros complejos sobre metadatos a escala: Qdrant tiene un motor de filtrado más eficiente que
jsonb @> - Multi-tenancy a cientos de clientes donde el schema isolation de PostgreSQL se convierte en un cuello de botella operacional
Para el 90% de los proyectos de agentes IA en empresas medianas, esto no aplica. Si en el futuro necesitas migrar, el patrón de doble índice del artículo sobre actualización de modelo de embeddings sin downtime funciona de la misma manera aquí.
Implementar bien desde el principio
La decisión de usar pgvector no es solo técnica, es operacional. Un servicio que monitorizar en vez de dos, una única conexión a base de datos, backups que incluyen los embeddings automáticamente, y cero tiempo de sincronización entre fuentes de verdad.
El setup correcto — tipo de índice, parámetros, búsqueda híbrida — es lo que separa un prototipo de un sistema que se mantiene en producción sin sorpresas a los tres meses.
Si tu equipo está construyendo un agente RAG y quiere implementarlo sobre vuestro PostgreSQL sin arquitecturas frágiles, hablamos por aquí.