Recherche sémantique dans PostgreSQL avec pgvector et .NET : une configuration pratique
Stockez les embeddings à côté des données relationnelles, créez des index HNSW ou IVFFlat, filtrez et combinez des classements hybrides, et déterminez quand pgvector est suffisant pour votre application.
Sources: Semantic Search with PostgreSQL: Pragmatism Beats Hype – Most of the Time
Intégrer une recherche sémantique dans une application entraîne généralement le même choix limité : Pinecone, Weaviate, Qdrant, Milvus ou une autre base de données vectorielle spécialisée. Chacune d’elles peut être la solution idéale. Cependant, de nombreuses applications fonctionnent déjà avec une instance PostgreSQL, et pour de nombreuses besoins de recherche sémantique, cette base de données peut gérer la tâche toute seule.
Ce qui permet cela, c’est pgvector, une extension open source qui ajoute à Postgres un type vectoriel ainsi que des fonctionnalités de recherche de similarité. Les embeddings sont stockés aux côtés des données relationnelles et peuvent être consultés à l’aide de SQL classique. En plus du nombre réduit d’éléments à gérer, l’avantage est structurel : il n’y a rien à synchroniser, il n’y a qu’un seul endroit où se trouve la vérité, et l’infrastructure n’est ajoutée que lorsque la charge le nécessite.
Recherche sémantique en une phrase
La recherche classique correspond aux mots, tandis que la recherche sémantique correspond au sens. Une requête telle que « Comment franchir le col ? » peut trouver du texte concernant un col de montagne plutôt qu’un couloir d’école, car la requête et les documents sont tous deux transformés en vecteurs numériques appelés embeddings.
Le processus comporte quatre étapes :
- Transformer le texte en un vecteur d’embedding.
- Stocker le vecteur dans PostgreSQL.
- Convertir la requête de recherche dans le même espace vectoriel.
- Récupérer les vecteurs stockés les plus proches du vecteur de la requête.
L’expression « même espace vectoriel » est importante : les embeddings provenant de modèles différents ne peuvent pas être mélangés librement.
Choisissez d’abord le modèle d’embedding
Le modèle précède le schéma, car il définit la dimension du vecteur, le coût par requête, les langues pris en charge ainsi que la possibilité de l’exécuter localement. Avec text-embedding-3-small d’OpenAI, une colonne vector(1536) est généralement utilisée. Un autre modèle, y compris ceux exécutés localement via Ollama, peut générer une dimension différente.
Ce n’est pas un détail insignifiant : PostgreSQL refuse les vecteurs ayant un nombre de dimensions incorrect.
Changer de modèle ultérieurement implique une migration des données. Vous devrez :
- ajouter une nouvelle colonne ou table vectorielle ;
- re-générer les embeddings de chaque document ;
- reconstruire l’index vectoriel ;
- ne jamais comparer directement les embeddings anciens et nouveaux.
Installation de pgvector
Activez l’extension une fois par base de données :
CREATE EXTENSION IF NOT EXISTS vector;
Géré des services PostgreSQL, assurez-vous que pgvector est disponible pour votre forfait et votre version de Postgres. Beaucoup le prennent en charge, mais vérifiez avant de l’intégrer dans votre conception.
Schéma : stockage des fragments
Pour de courtes entrées, un vecteur par ligne suffit. Pour de véritables documents, il est généralement préférable d’incorporer des fragments, car un document long peut aborder plusieurs sujets, et un seul vecteur pour l’ensemble a tendance à les mélanger. Un schéma fonctionnel :
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)
);
Conservez vector(1536) uniquement si votre modèle renvoie réellement 1536 nombres, sinon modifiez-le en conséquence.
L’utiliser depuis .NET avec Npgsql
Ajoutez les packages :
dotnet add package Npgsql
dotnet add package Pgvector
Les utilisateurs Dapper ont également besoin d’un élément supplémentaire :
dotnet add package Pgvector.Dapper
Avec Npgsql classique, appelez UseVector() sur le constructeur de source de données :
using Npgsql;
using Pgvector;
var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseVector();
await using var dataSource = dataSourceBuilder.Build();
Dans un environnement de production, créez l’extension et les tables au moyen de migrations ou de procédures de provisionnement. Si l’extension est créée à l’exécution, rechargez les types PostgreSQL de la connexion avant d’utiliser le nouveau type.
Récupération d’embeddings auprès d’OpenAI
Le SDK .NET d’OpenAI met à disposition un client d’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();
}
Pour les embeddings locaux, utilisez un modèle local via le fournisseur de votre choix. La règle reste la même : le modèle qui indexe les documents et le modèle qui gère les embeddings des requêtes doivent correspondre, ou du moins être délibérément compatibles. Ne jamais indexer avec un modèle et rechercher avec un autre.
Enregistrer un chunk
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);
}
Le chemin de mise à jour est le détail essentiel. Si le texte d’un chunk change, son embedding doit également changer, c’est pourquoi l’instruction met à jour les deux en même temps.
Exécution d’une recherche
L’opérateur <=> calcule la distance cosinus, où une valeur plus faible indique une correspondance plus proche. Un tri ascendant affiche d’abord les vecteurs les plus proches.
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;
}
Notez que la requête est triée directement selon l’expression de distance. Avec les index pgvector, la commande ORDER BY embedding <=> @query LIMIT n permet au planificateur d’utiliser l’index.
Opérateurs de distance
pgvector propose plusieurs opérateurs :
| Opérateur | Mesure |
|---|---|
<-> | Distance euclidienne (L2) |
<=> | Distance cosinus |
<#> | Produit scalaire négatif |
<+> | Distance taxicab (L1) |
Pour les embeddings de texte, la distance cosinus constitue un choix par défaut approprié.
Index HNSW
En l’absence d’index, PostgreSQL parcourt toute la table pour chaque recherche vectorielle. Cela est précis et simple, mais la vitesse diminue à mesure que le nombre de vecteurs augmente. HNSW est souvent le meilleur premier index pour les recherches dans les applications :
CREATE INDEX document_chunks_embedding_hnsw_idx
ON document_chunks
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
Les deux paramètres sont :
m, le nombre maximal de connexions par couche, dont la valeur par défaut est 16 ;ef_construction, la taille de la liste des candidats lors de la construction, dont la valeur par défaut est 64.
Des valeurs plus élevées peuvent améliorer le taux de rappel mais nécessitent plus de mémoire et allongent le temps de construction.
Le taux de rappel peut également être ajusté au moment de la requête pour une session :
SET hnsw.ef_search = 100;
ou uniquement à l’intérieur d’une seule transaction :
BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;
N’oubliez pas que HNSW est approximatif. Il renonce à une reprise parfaite en échange de la vitesse.
IVFFlat comme alternative
IVFFlat peut utiliser moins de mémoire et se construire plus rapidement que HNSW, bien que son compromis entre vitesse et reprise soit généralement moins favorable.
CREATE INDEX document_chunks_embedding_ivfflat_idx
ON document_chunks
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
Ne créez pas d’index IVFFlat sur une table vide, car il a besoin de lignes existantes pour former ses listes. Comme point de départ approximatif pour les lists, une table contenant 10 000 vecteurs convient à environ 10 listes, et non à 100.
Lors de la requête, ajustez les sondes :
SET ivfflat.probes = 10;
Plus de sondes améliorent le taux de rappel mais ralentissent les requêtes.
Filtrage et recherche hybride
Une raison majeure de choisir pgvector est que les vecteurs sont stockés à côté des données relationnelles. Vous pouvez d’abord filtrer puis classer les résultats :
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;
Pour une recherche hybride authentique, ne calculez pas le classement des mots-clés pour ensuite l’ignorer. Fusionnez les classements sémantiques et ceux basés sur les mots-clés. Une approche pratique consiste à attribuer des scores selon le principe de la Fusion des classements réciproques :
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;
Ce n’est pas la seule façon de combiner les deux, mais cela rend la logique de classement visible.
Quand pgvector convient
C’est un choix judicieux lorsque :
- PostgreSQL est déjà la base de données principale ;
- les vecteurs doivent être associés naturellement aux tables relationnelles ;
- la cohérence transactionnelle est importante ;
- l’équipe sait déjà comment utiliser Postgres ;
- l’ensemble des données est de petite ou moyenne taille ;
- vous souhaitez éviter un autre service ainsi qu’une tâche de synchronisation.
Ses utilisations typiques sont la recherche interne, la recherche de produits, les outils d’assistance et la recherche de documentation, ainsi que les configurations RAG dont les données proviennent déjà de la base de données relationnelle.
Quand un stockage vectoriel dédié peut être préférable
Préférez une base de données vectorielle conçue spécifiquement lorsque :
- le nombre de vecteurs atteint des dizaines de millions ou plus ;
- le volume des requêtes est très élevé et les délais de réponse sont strictement limités ;
- vous souhaitez un service géré avec des opérations de recherche vectorielle spécialisées ;
- vous avez besoin d’une récupération hybride, d’un réclassement ou d’un filtrage plus avancés que ceux offerts par Postgres ;
- votre équipe ne maîtrise pas en profondeur PostgreSQL ;
- l’isolation multi-locataires et l’échelle sont des besoins essentiels.
Il ne s’agit pas d’idéologie, mais d’adaptation opérationnelle.
Une extrémité ASP.NET Core complète
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);
});
Où cela vous mène
La recherche sémantique n’exige pas toujours une base de données vectorielle distincte. Lorsque PostgreSQL contient déjà votre source de vérité, pgvector vous permet de conserver les embeddings à côté des données relationnelles, de les interroger en SQL, de les filtrer avec des conditions ordinaires et de gérer les transactions dans un seul système.
Quelques règles permettent de maintenir une configuration propre :
- choisir le modèle d’embedding avant la dimension vectorielle ;
- ne jamais mélanger des embeddings provenant de modèles différents ;
- diviser en blocs les documents longs ou couvrant plusieurs sujets ;
- ajouter un index uniquement lorsque la table est suffisamment grande pour en avoir besoin ;
- se rappeler que HNSW et IVFFlat sont approximatifs ;
- considérer tout changement de modèle comme une migration de données.
Pour de nombreuses applications de production, pgvector suffit pendant longtemps. Cela ne signifie pas pour autant que les bases de données vectorielles dédiées sont inutiles. Il s’agit simplement du fait que l’architecture la plus simple et fiable conserve souvent les données là où elles se trouvent déjà.
Pour en savoir plus, consultez le README de pgvector ainsi que son package .NET, le SDK .NET d’OpenAI et son guide sur les embeddings, ainsi que la documentation Microsoft.Extensions.AI.