pgvector : définition, fonctionnement et exemple SQL

pgvector est une extension de PostgreSQL qui lui donne les moyens de stocker et de comparer des vecteurs. Dans une application d'IA générative, chaque document, paragraphe ou image est converti en embedding, une liste de nombres qui encode son sens. Retrouver les contenus pertinents pour une question revient alors à chercher les vecteurs les plus proches de celui de la question, ce que pgvector permet directement en SQL.

Le projet a été créé par Andrew Kane et développé en open source, sous la PostgreSQL License. Son atout est de ne pas ajouter de système : au lieu de déployer une base vectorielle séparée comme Pinecone, Qdrant ou Weaviate, on active une extension sur la base que l'on exploite déjà. L'essor du RAG en a fait l'un des choix par défaut pour les corpus de taille modeste.

Les index HNSW, qui ont fait passer l'extension du prototype à la production, sont disponibles depuis la version 0.5.0. Les versions suivantes ont ajouté les types halfvec (demi-précision), sparsevec (vecteurs creux) et bit, ainsi que des améliorations pour combiner filtres et index approximatif.

À retenir : pgvector n'est pas une base de données à part. C'est une capacité ajoutée à PostgreSQL, avec ses avantages (SQL, transactions, écosystème) et ses limites (une base généraliste).

pgvector repose sur un type, trois familles de distances et deux index, à choisir avant d'indexer le premier vecteur.

• Type vector(n) : un vecteur de n dimensions, qui doit correspondre à la taille du modèle d'embedding. halfvec stocke les valeurs en demi-précision pour réduire la taille.
• Opérateurs de distance : <-> pour la distance euclidienne, <=> pour la distance cosinus et <#> pour le produit scalaire négatif.
• Index : sans index, la recherche est exacte et parcourt toutes les lignes. Avec un index, elle devient approximative et rapide.

HNSW et IVFFlat

L'index HNSW (Hierarchical Navigable Small World) organise les vecteurs en graphe à plusieurs niveaux. Il offre en général un meilleur compromis entre vitesse et rappel, ne demande pas de données préexistantes, mais consomme plus de mémoire et se construit plus lentement. Ses paramètres m et ef_construction règlent la construction, et hnsw.ef_search règle la recherche.

L'index IVFFlat répartit les vecteurs en listes autour de centroïdes. Il se construit plus vite et occupe moins de mémoire, mais il faut le créer une fois la table remplie et régler le nombre de listes, puis le nombre de listes sondées (ivfflat.probes) à la requête.

Une équipe veut retrouver les articles d'une base de connaissances les plus proches d'une question, filtrés par langue. Le script suivant utilise le pilote psycopg face à une base PostgreSQL où l'extension est disponible, par exemple lancée avec l'image Docker pgvector/pgvector. Les vecteurs sont fictifs, sur trois dimensions : en pratique, ils proviennent d'un modèle d'embedding.

import psycopg

with psycopg.connect("postgresql://postgres:postgres@localhost:5432/postgres") as conn:
    # 1. Activer l'extension et créer la table avec une colonne vectorielle
    conn.execute("CREATE EXTENSION IF NOT EXISTS vector")
    conn.execute("""
        CREATE TABLE IF NOT EXISTS articles (
            id bigserial PRIMARY KEY,
            contenu text,
            langue text,
            embedding vector(3)
        )
    """)

    # 2. Insérer un contenu avec son embedding (au format texte pgvector)
    conn.execute(
        "INSERT INTO articles (contenu, langue, embedding) VALUES (%s, %s, %s::vector)",
        ("Le remboursement intervient sous 14 jours.", "fr", "[0.01, 0.45, 0.67]"),
    )

    # 3. Index HNSW pour la distance cosinus
    conn.execute(
        "CREATE INDEX IF NOT EXISTS articles_hnsw ON articles "
        "USING hnsw (embedding vector_cosine_ops)"
    )

    # 4. Recherche : filtre sur la langue, tri par distance cosinus
    lignes = conn.execute(
        """
        SELECT contenu, embedding <=> %s::vector AS distance
        FROM articles
        WHERE langue = 'fr'
        ORDER BY embedding <=> %s::vector
        LIMIT 3
        """,
        ("[0.02, 0.40, 0.70]", "[0.02, 0.40, 0.70]"),
    ).fetchall()

    for contenu, distance in lignes:
        print(round(distance, 4), contenu)

La requête est vectorisée avec le même modèle que les documents, et la classe d'opérateurs de l'index (vector_cosine_ops) doit correspondre à l'opérateur utilisé dans le ORDER BY, sinon PostgreSQL n'emploie pas l'index. Le texte reste dans la même ligne que son vecteur, ce qui évite une seconde requête. Dans un RAG, les lignes renvoyées sont ensuite injectées dans le prompt du LLM, souvent par LangChain ou LlamaIndex, qui disposent d'intégrations avec PostgreSQL.

Le choix se joue moins sur la qualité de la recherche, comparable à index équivalent, que sur le modèle d'exploitation et le volume. Voici comment pgvector se situe face à Pinecone et Qdrant.

Une démarche fréquente consiste à démarrer avec pgvector, qui évite toute infrastructure nouvelle, puis à migrer vers une base dédiée si le volume ou la charge l'exigent. Notre article Pinecone : la base de données vectorielle managée détaille le fonctionnement des bases vectorielles côté managé.

Ce n'est pas un choix définitif. Conservez les documents sources et le pipeline de vectorisation : changer de base reste alors une simple réindexation.

Beaucoup d'agents IA persistent déjà leur état dans PostgreSQL. Ajouter une colonne vectorielle à cette base permet de retrouver les souvenirs d'un agent par similarité, filtrés par utilisateur ou par session, dans la même transaction que l'état. Les articles Mémoire des agents IA et Gérer l'état des agents IA détaillent ces stratégies.