Inicio / Artículos

Búsqueda semántica en PostgreSQL con pgvector y .NET: Una configuración práctica

Almacene los embeddings junto a los datos relacionales, cree índices HNSW o IVFFlat, filtre y combine rangos híbridos, y determine cuándo pgvector es suficiente para su aplicación.

Editor: REACTAPP.TOP9 min de lectura2030 palabras

Fuentes: Semantic Search with PostgreSQL: Pragmatism Beats Hype – Most of the Time

Agregar búsqueda semántica a una aplicación suele plantear la misma lista corta: Pinecone, Weaviate, Qdrant, Milvus o alguna otra base de datos vectorial especializada. Cualquiera de ellas puede ser la respuesta adecuada. Sin embargo, muchas aplicaciones ya ejecutan una instancia de PostgreSQL, y para muchas necesidades de búsqueda semántica esa base de datos puede manejar el trabajo por sí sola.

Lo que hace que funcione es pgvector, una extensión de código abierto que le brinda a Postgres un tipo vectorial y búsqueda de similitud. Las representaciones vectoriales se encuentran junto a los datos relacionales y se consultan con SQL estándar. Además de tener menos componentes que ejecutar, la ventaja es estructural: no hay nada que sincronizar, solo hay un lugar donde reside la información real, y se añade infraestructura únicamente cuando la carga lo exige.

Búsqueda semántica en una frase

La búsqueda clásica coincide con palabras, mientras que la búsqueda semántica coincide con significados. Una consulta como “¿Cómo supero el paso de montaña?” puede encontrar texto sobre un paso de montaña en lugar de un pasillo escolar, porque tanto la consulta como los documentos se convierten en vectores numéricos conocidos como embeddings.

El proceso consta de cuatro pasos:

  1. Convertir el texto en un vector de embedding.
  2. Almacenar el vector en PostgreSQL.
  3. Convertir la consulta de búsqueda al mismo espacio vectorial.
  4. Recuperar los vectores almacenados más cercanos al vector de la consulta.

La expresión “mismo espacio vectorial” es importante; los embeddings de modelos diferentes no pueden mezclarse libremente.

Elige primero el modelo de embedding

El modelo viene antes que el esquema, ya que determina la dimensión del vector, el costo por solicitud, los idiomas que se pueden manejar y si se puede ejecutar localmente. Con text-embedding-3-small de OpenAI, una columna vector(1536) es la opción habitual. Otro modelo, incluido uno local servido a través de Ollama, puede generar una dimensión diferente.

Eso no es un detalle menor. PostgreSQL rechaza los vectores con el número incorrecto de dimensiones.

Cambiar de modelo más tarde implica una migración de datos. Tendrías que:

  • agregar una nueva columna o tabla de vectores;
  • volver a incrustar cada documento;
  • reconstruir el índice de vectores;
  • nunca comparar directamente las incrustaciones antiguas y nuevas.

Instalación de pgvector

Activa la extensión una vez por base de datos:

CREATE EXTENSION IF NOT EXISTS vector;

En los servicios gestionados de PostgreSQL, confirme que pgvector esté disponible para su plan y versión de Postgres. Muchos lo soportan, pero verifique antes de planificar su uso.

Estructura: almacenar fragmentos

Para registros cortos, basta con un vector por fila. En el caso de documentos reales, suele ser mejor incrustar fragmentos, ya que un documento largo puede abarcar varios temas y un único vector para todo tiende a mezclarlos. Una estructura viable:

CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       TEXT NOT NULL,
    source      TEXT,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE document_chunks (
    id           BIGSERIAL PRIMARY KEY,
    document_id  BIGINT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
    chunk_index  INTEGER NOT NULL,
    content      TEXT NOT NULL,
    embedding    vector(1536) NOT NULL,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (document_id, chunk_index)
);

Mantenga vector(1536) solo si su modelo realmente devuelve 1536 números; de lo contrario, cámbielo para que coincida.

Uso desde .NET con Npgsql

Agregue los paquetes:

dotnet add package Npgsql
dotnet add package Pgvector

Los usuarios de Dapper también necesitan uno más:

dotnet add package Pgvector.Dapper

Con Npgsql estándar, llame a UseVector() en el constructor de la fuente de datos:

using Npgsql;
using Pgvector;

var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseVector();

await using var dataSource = dataSourceBuilder.Build();

En producción, cree la extensión y las tablas mediante migraciones o provisioning. Si la extensión se crea en tiempo de ejecución, recargue los tipos de PostgreSQL de la conexión antes de utilizar el nuevo tipo.

Obtener embeddings de OpenAI

El SDK .NET de OpenAI ofrece un cliente para embeddings:

using OpenAI.Embeddings;

var embeddingClient = new EmbeddingClient("text-embedding-3-small", apiKey);

async Task<float[]> GetEmbeddingAsync(string text)
{
    var result = await embeddingClient.GenerateEmbeddingAsync(text);
    return result.Value.ToFloats().ToArray();
}

Para los embeddings locales, utilice un modelo local a través del proveedor que prefiera. La regla sigue siendo la misma: el modelo que indexa los documentos y el modelo que procesa las consultas deben coincidir, o al menos ser deliberadamente compatibles. Nunca indexe con un modelo y busque con otro.

Guardar un fragmento

async Task InsertChunkAsync(
    long documentId,
    int chunkIndex,
    string content,
    CancellationToken cancellationToken = default)
{
    var embedding = await GetEmbeddingAsync(content);
    var vector = new Vector(embedding);

    await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        INSERT INTO document_chunks (document_id, chunk_index, content, embedding)
        VALUES (@documentId, @chunkIndex, @content, @embedding)
        ON CONFLICT (document_id, chunk_index)
        DO UPDATE SET
            content = EXCLUDED.content,
            embedding = EXCLUDED.embedding
        """, conn);

    cmd.Parameters.AddWithValue("documentId", documentId);
    cmd.Parameters.AddWithValue("chunkIndex", chunkIndex);
    cmd.Parameters.AddWithValue("content", content);
    cmd.Parameters.AddWithValue("embedding", vector);

    await cmd.ExecuteNonQueryAsync(cancellationToken);
}

La ruta de actualización es el detalle clave. Si el texto de un fragmento cambia, su representación también debe cambiar, y por eso la instrucción actualiza ambos al mismo tiempo.

Ejecutar una búsqueda

El operador <=> calcula la distancia de coseno, donde un valor más pequeño indica una coincidencia más cercana. Al ordenar de forma ascendente, se obtienen primero los vectores más cercanos.

public sealed record SearchResult(
    long DocumentId,
    long ChunkId,
    string Title,
    string Content,
    double Distance);

async Task<List<SearchResult>> SearchAsync(
    string query,
    int limit = 5,
    CancellationToken cancellationToken = default)
{
    var queryEmbedding = await GetEmbeddingAsync(query);
    var queryVector = new Vector(queryEmbedding);

    await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        SELECT d.id,
               c.id,
               d.title,
               c.content,
               c.embedding <=> @queryVector AS distance
        FROM document_chunks c
        JOIN documents d ON d.id = c.document_id
        ORDER BY c.embedding <=> @queryVector
        LIMIT @limit
        """, conn);

    cmd.Parameters.AddWithValue("queryVector", queryVector);
    cmd.Parameters.AddWithValue("limit", limit);

    var results = new List<SearchResult>();

    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
    while (await reader.ReadAsync(cancellationToken))
    {
        results.Add(new SearchResult(
            DocumentId: reader.GetInt64(0),
            ChunkId: reader.GetInt64(1),
            Title: reader.GetString(2),
            Content: reader.GetString(3),
            Distance: reader.GetDouble(4)));
    }

    return results;
}

Tenga en cuenta que la consulta ordena directamente según la expresión de distancia. Con índices pgvector, la estructura ORDER BY embedding <=> @query LIMIT n es lo que permite al planificador utilizar el índice.

Operadores de distancia

pgvector ofrece varios operadores:

Operador Qué mide
<-> Distancia euclidiana (L2)
<=> Distancia coseno
<#> Producto interno negativo
<+> Distancia taxicab (L1)

Para las incrustaciones de texto, la distancia coseno es una opción predeterminada adecuada.

Índices HNSW

Al no tener índice, PostgreSQL escanea toda la tabla para cada búsqueda vectorial. Eso es preciso y sencillo, pero ralentiza el proceso a medida que aumenta la cantidad de vectores. HNSW suele ser el mejor índice inicial para búsquedas en aplicaciones:

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

Los dos parámetros son:

  • m, el número máximo de conexiones por capa, cuyo valor por defecto es 16;
  • ef_construction, el tamaño de la lista de candidatos durante la construcción, cuyo valor por defecto es 64.

Valores más altos pueden mejorar el recuerdo, pero consumen más memoria y tiempo de procesamiento.

El recuerdo también puede ajustarse en el momento de la consulta para una sesión:

SET hnsw.ef_search = 100;

o solo dentro de una única transacción:

BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;

Tenga en cuenta que HNSW es aproximado. Renuncia a una recuperación perfecta a cambio de mayor velocidad.

IVFFlat como alternativa

IVFFlat puede utilizar menos memoria y construirse más rápidamente que HNSW, aunque su equilibrio entre velocidad y recuperación suele ser peor.

CREATE INDEX document_chunks_embedding_ivfflat_idx
ON document_chunks
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

No cree un índice IVFFlat sobre una tabla vacía, ya que necesita filas existentes para formar sus listas. Como punto de partida aproximado para lists, una tabla con 10,000 vectores es adecuada para unas 10 listas, no para 100.

En el momento de la consulta, ajuste las sondas:

SET ivfflat.probes = 10;

Más sondas mejoran la recuperación de datos y ralentizan las consultas.

Filtrado y búsqueda híbrida

Una razón principal para elegir pgvector es que los vectores se almacenan junto a los datos relacionales. Puedes filtrar primero y luego clasificar los resultados:

SELECT d.id, d.title, c.content, c.embedding <=> @queryVector AS distance
FROM document_chunks c
JOIN documents d ON d.id = c.document_id
WHERE d.created_at > NOW() - INTERVAL '30 days'
  AND d.source = 'documentation'
ORDER BY c.embedding <=> @queryVector
LIMIT 10;

Para una búsqueda híbrida real, no calcule el ranking de una palabra clave y luego lo ignore. Combine los rankings semánticos y de palabras clave. Un enfoque práctico es la puntuación al estilo de la Fusión de Rankings Recíprocos:

WITH semantic AS (
    SELECT c.id,
           row_number() OVER (ORDER BY c.embedding <=> @queryVector) AS semantic_rank
    FROM document_chunks c
    LIMIT 100
),
keyword AS (
    SELECT c.id,
           row_number() OVER (
               ORDER BY ts_rank_cd(
                   to_tsvector('english', c.content),
                   plainto_tsquery('english', @query)
               ) DESC
           ) AS keyword_rank
    FROM document_chunks c
    WHERE to_tsvector('english', c.content) @@ plainto_tsquery('english', @query)
    LIMIT 100
)
SELECT d.id AS document_id,
       c.id AS chunk_id,
       d.title,
       c.content,
       COALESCE(1.0 / (60 + semantic.semantic_rank), 0) +
       COALESCE(1.0 / (60 + keyword.keyword_rank), 0) AS score
FROM semantic
FULL OUTER JOIN keyword ON keyword.id = semantic.id
JOIN document_chunks c ON c.id = COALESCE(semantic.id, keyword.id)
JOIN documents d ON d.id = c.document_id
ORDER BY score DESC
LIMIT 10;

No es la única forma de combinar ambos, pero hace que la lógica de clasificación sea visible.

Cuándo es adecuado pgvector

Es una opción sólida cuando:

  • PostgreSQL ya es la base de datos principal;
  • los vectores necesitan combinarse de forma natural con tablas relacionales;
  • la consistencia transaccional es importante;
  • el equipo ya sabe cómo utilizar Postgres;
  • el conjunto de datos es pequeño o de tamaño medio;
  • se desea evitar otro servicio y tarea de sincronización.

Los usos típicos son la búsqueda interna, la búsqueda de productos, las herramientas de soporte y la búsqueda de documentación, además de configuraciones RAG cuyos datos provienen ya de la base de datos relacional.

Cuándo puede ser mejor un almacén de vectores dedicado

Considere una base de datos de vectores diseñada específicamente cuando:

  • el número de vectores alcanza decenas de millones o más;
  • el volumen de consultas es muy alto y los límites de latencia son estrictos;
  • desea un servicio gestionado con operaciones especializadas de búsqueda vectorial;
  • necesita una recuperación híbrida, un reordenamiento o un filtrado más avanzados que los que ofrece Postgres;
  • su equipo no tiene un conocimiento profundo de PostgreSQL;
  • la isolación multiinquilino y la escalabilidad son necesidades fundamentales.

Esto no se trata de ideología. Se trata de la adecuación operativa.

Un endpoint completo de ASP.NET Core

app.MapGet("/search", async (
    string q,
    NpgsqlDataSource db,
    CancellationToken cancellationToken) =>
{
    var queryEmbedding = await GetEmbeddingAsync(q);
    var queryVector = new Vector(queryEmbedding);

    await using var conn = await db.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        SELECT d.id,
               c.id,
               d.title,
               c.content,
               c.embedding <=> @v AS distance
        FROM document_chunks c
        JOIN documents d ON d.id = c.document_id
        ORDER BY c.embedding <=> @v
        LIMIT 5
        """, conn);

    cmd.Parameters.AddWithValue("v", queryVector);

    var results = new List<object>();

    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
    while (await reader.ReadAsync(cancellationToken))
    {
        results.Add(new
        {
            documentId = reader.GetInt64(0),
            chunkId = reader.GetInt64(1),
            title = reader.GetString(2),
            content = reader.GetString(3),
            distance = reader.GetDouble(4)
        });
    }

    return Results.Ok(results);
});

Qué significa esto para usted

La búsqueda semántica no siempre requiere una base de datos vectorial separada. Cuando PostgreSQL ya alberga su fuente de datos fiable, pgvector le permite almacenar los embeddings junto a los datos relacionales, consultarlos con SQL, filtrarlos con condiciones habituales y mantener las transacciones en un único sistema.

Algunas reglas ayudan a mantener la configuración ordenada:

  • elija el modelo de embedding antes que la dimensión vectorial;
  • nunca mezcle embeddings de modelos diferentes;
  • divida en partes los documentos largos o que abarcan varios temas;
  • agregue un índice solo cuando la tabla sea lo suficientemente grande como para necesitarlo;
  • tenga en cuenta que HNSW e IVFFlat son aproximados;
  • considere cualquier cambio de modelo como una migración de datos.

Para muchas aplicaciones de producción, pgvector es suficiente durante mucho tiempo. Eso no significa que las bases de datos vectoriales dedicadas sean innecesarias. Simplemente, la arquitectura más sencilla y fiable suele mantener los datos donde ya se encuentran.

Para leer más, consulte el README de pgvector y su paquete .NET, la guía del SDK .NET de OpenAI y las guías sobre embeddings, así como la documentación de Microsoft.Extensions.AI.