Guide d’utilisation de l’extension pgvector PostgreSQL dans ServBay

pgvector est une puissante extension tierce pour PostgreSQL qui apporte le support natif des types de données vectorielles, ainsi que des méthodes d’indexation performantes comme IVFFlat et HNSW. Grâce à elle, PostgreSQL prend en charge le stockage de vecteurs et la recherche de similarité, ce qui en fait un choix idéal pour les applications d’IA, les systèmes de recommandation, la reconnaissance d’images et le traitement du langage naturel devant manipuler des vecteurs de grande dimension.

ServBay, un environnement de développement Web local tout-en-un, intègre déjà PostgreSQL et l’extension pgvector, simplifiant grandement l’activation et l’utilisation de bases de données vectorielles localement. Ce guide détaille les étapes pour exploiter pgvector dans ServBay.

Qu’est-ce que pgvector ? Pourquoi est-ce important ?

Aujourd’hui, de nombreuses applications manipulent bien plus que du texte ou des chiffres structurés. Avec l’essor de l’IA et du machine learning, les données sont souvent représentées sous forme de vecteurs de grande dimension, également appelés « embeddings ». Ces vecteurs capturent des caractéristiques sémantiques — comme les attributs visuels d’une image, le sens d’un texte ou les préférences d’un utilisateur.

L’extension pgvector permet à PostgreSQL de stocker ces vecteurs et d’effectuer des recherches de similarité (ou « recherche de plus proches voisins ») très efficacement. Cela vous permet d’utiliser le langage SQL habituel pour retrouver les éléments les plus similaires à un vecteur donné, sans devoir recourir à une base de données vectorielle séparée et ainsi simplifier votre architecture technique.

Prérequis

Avant de commencer à utiliser pgvector dans ServBay, assurez-vous que :

ServBay est installé et en fonctionnement sur macOS.
Le package PostgreSQL est activé dans la liste des “Packages” de ServBay. Si ce n’est pas le cas, ouvrez l’interface de l’application ServBay, localisez PostgreSQL et activez-le.

Activation de l’extension pgvector dans PostgreSQL de ServBay

ServBay inclut d’office les fichiers de l’extension pgvector dans le dossier d’installation de PostgreSQL, nul besoin de téléchargement ni compilation supplémentaire. Vous devez simplement activer l’extension dans chaque base de données où vous souhaitez l’utiliser.

Voici les étapes pour activer pgvector dans PostgreSQL fourni par ServBay :

Connexion à la base de données PostgreSQL : Utilisez l’outil en ligne de commande psql pour vous connecter à l’instance PostgreSQL de ServBay. Par défaut, ServBay autorise une connexion locale avec les utilisateurs postgres ou servbay et le port 5432. Pour toute différence, consultez la documentation de ServBay concernant la configuration des bases de données.
Ouvrez le terminal et utilisez la commande suivante (adaptez le nom d’utilisateur et celui de la base de données si besoin) :
bash
```
psql -U servbay -d your_database_name -h localhost -p 5432
```
1
- -U servbay : définit le nom d’utilisateur (servbay ou postgres).
- -d your_database_name : la base cible. Si elle n’existe pas, créez-la d’abord, par exemple CREATE DATABASE servbay_demo_db;.
- -h localhost : l’hôte local.
- -p 5432 : le port PostgreSQL par défaut de ServBay.
Créer l’extension vector : Une fois connecté, exécutez la commande SQL suivante dans psql pour activer pgvector :
sql
```
CREATE EXTENSION vector;
```
1
Si l’extension est déjà installée, un message vous le signalera.

Vérifier l’installation : Vous pouvez lister les extensions installées avec la commande :

sql

\dx

Repérez dans la liste une extension nommée vector avec sa version.

                           List of installed extensions
   Name   | Version |   Schema   |                         Description
----------+---------+------------+--------------------------------------------------------------
 plpgsql  | 1.0     | pg_catalog | PL/pgSQL procedural language
 vector   | 0.7.0   | public     | vector data type and ivfflat and hnsw access methods
(2 rows)

(Note : le numéro de version dépend de celle intégrée avec ServBay)

Configuration et utilisation de pgvector

Une fois l’extension pgvector activée, vous pouvez immédiatement créer et manipuler des colonnes vectorielles dans vos tables PostgreSQL.

Création d’une table avec colonne vectorielle

D’abord, créez une table pour vos données vectorielles. pgvector introduit le type VECTOR(dimensions) où dimensions correspond à la taille du vecteur.

Exemple — création d’une table embeddings pour des vecteurs à 3 dimensions :

sql

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Définition d’une colonne vectorielle à 3 dimensions
    vector VECTOR(3)
);

Insérez quelques exemples de vecteurs :

sql

INSERT INTO embeddings (vector) VALUES
('[0.1, 0.2, 0.3]'),
('[0.4, 0.5, 0.6]'),
('[0.7, 0.8, 0.9]'),
('[0.15, 0.25, 0.35]'),
('[0.6, 0.5, 0.4]'); -- Ajoutez davantage de données pour rendre les exemples de requêtes plus pertinents

Note : les valeurs des vecteurs doivent être entourées de crochets [] et séparées par des virgules.

Indexation vectorielle pour accélérer les recherches

Pour les tables contenant beaucoup de vecteurs, l’indexation est capitale pour la performance des recherches de similarité. pgvector propose deux méthodes d’indexation principales : IVFFlat et HNSW. Le choix dépend de vos besoins (vitesse de requêtes, rapidité de construction de l’index, mémoire, taux de rappel, etc.).

IVFFlat (Inverted File Index with Flat compression) : adapté aux grands ensembles de données quand le taux de rappel peut être un peu réduit. Construction rapide.
HNSW (Hierarchical Navigable Small World) : en général, taux de rappel et rapidité supérieurs mais construction lente et usage mémoire plus élevé.

Voici comment créer des index IVFFlat et HNSW sur la colonne vector de la table embeddings :

Créer un index IVFFlat :

sql

-- Exécuter ANALYZE pour collecter les statistiques de la table avant création d’un index IVFFlat
ANALYZE embeddings;

-- Création de l’index IVFFlat
-- WITH (lists = 100): nombre de listes inversées, ajuster selon la taille des données.
-- Plus "lists" est élevé, plus l’index est long à créer et plus il faudra de temps de recherche, mais cela améliore le rappel.
-- La recommandation officielle : lists = sqrt(nombre de lignes)
CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

Créer un index HNSW :

sql

-- Création de l’index HNSW
-- WITH (m = 16, ef_construction = 200): paramètres HNSW
-- m : nombre maximal de connexions pour chaque nœud (impacte la connectivité de l’index, la rapidité, la mémoire)
-- ef_construction : fenêtre de recherche lors de la construction ; impacte durée, mémoire et qualité finale de l’index.
-- Ajustez en fonction de vos besoins et contraintes.
CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

Remarque : Les paramètres d’index tels que lists, m, ef_construction ont un impact majeur sur la performance et la qualité du rappel. Choisissez-les en fonction de vos données et faites des essais. Consultez la documentation officielle de pgvector pour en savoir plus.

Requêtes vectorielles avec pgvector

pgvector fournit divers opérateurs pour mesurer la distance entre vecteurs, facilitant ainsi la recherche de similarité. Les opérateurs les plus courants sont :

<-> : distance L2 (euclidienne) — calcule la distance directe entre deux vecteurs.
<#> : produit scalaire (Inner Product) — lié à la similarité cosinus, mesure la proximité directionnelle.
<=> : distance cosinus — correspond à 1 – similarité cosinus, idéale pour comparer des directions indépendamment de la norme des vecteurs.

Exemples typiques de requêtes :

Recherche du plus proche voisin (Nearest Neighbor Search)

Trouvez les vecteurs les plus proches (i.e., distance minimale) du vecteur de requête. Ordre croissant par distance, nombre de résultats limité par LIMIT.

Trouver les 5 vecteurs les plus proches de [0.2, 0.3, 0.4] (distance L2) :

sql

SELECT
    id,
    vector,
    -- Calcul de la distance L2 au vecteur de requête
    vector <-> '[0.2, 0.3, 0.4]' AS distance
FROM
    embeddings
ORDER BY
    distance -- distances croissantes (plus proche = plus similaire)
LIMIT 5;

Recherche de similarité vectorielle

Similaire à la recherche de k plus proches voisins, mais mettant l’accent sur l’affichage du score de similarité.

Trouver les 5 vecteurs les plus proches selon la distance cosinus par rapport à [0.2, 0.3, 0.4] :

sql

SELECT
    id,
    vector,
    -- Calcul de la distance cosinus au vecteur de requête
    vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
FROM
    embeddings
ORDER BY
    cosine_distance -- distances croissantes (plus proche = plus similaire)
LIMIT 5;

Visualisation des données vectorielles (optionnel)

Visualiser des vecteurs de grande dimension permet de mieux comprendre leur structure et la façon dont ils s’agrègent ou se répartissent. Pour les vecteurs 2D ou 3D, un simple nuage de points suffit. Pour de plus hautes dimensions, on utilise généralement des techniques de réduction (PCA, t-SNE, etc.) pour projeter les vecteurs en 2D ou 3D.

Exemple simple : visualiser des vecteurs 3D avec Python et Matplotlib.

Préparez l’environnement Python Travaillez avec un environnement Python en dehors ou à l’intérieur de ServBay. Si vous utilisez le package Python fourni par ServBay, activez-le. Installez au préalable les librairies psycopg2 et matplotlib :
bash
```
# Si vous utilisez le Python système ou une installation personnelle
pip install psycopg2 matplotlib

# Avec le Python de ServBay, utilisez le terminal ServBay ou accédez au dossier bin et exécutez :
# /Applications/ServBay/logiciels/python/bin/pip install psycopg2 matplotlib
```
1
2
3
4
5
Adaptez selon le chemin exact de votre Python.

Créer le script Python Créez un fichier Python (par ex. visualize_vectors.py) et copiez le code suivant. Changez les paramètres de connexion (dbname, user, password, host, port) selon votre configuration ServBay.

python

import psycopg2
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D # Importer le module pour les nuages de points 3D

# Paramètres de connexion à la base (à ajuster selon ServBay)
db_params = {
    "dbname": "your_database_name", # Remplacez par le nom de votre base
    "user": "servbay",              # Remplacez par votre nom d'utilisateur PostgreSQL (servbay ou postgres)
    "password": "",                 # Mot de passe éventuel (localement peut être vide)
    "host": "localhost",            # PostgreSQL de ServBay fonctionne sur localhost
    "port": "5432"                  # Port par défaut de PostgreSQL sur ServBay
}

conn = None
cur = None

try:
    # Connexion à la base PostgreSQL
    conn = psycopg2.connect(**db_params)
    cur = conn.cursor()

    # Requête pour récupérer les données vectorielles
    # Remarque : avec psycopg2, les colonnes vector sont lues comme des chaînes.
    # Il faut les parser, sauf si vous avez une version récente de pgvector bien intégrée au driver.
    cur.execute("SELECT vector FROM embeddings")
    vectors_raw = cur.fetchall()

    # Décodage : conversion des chaînes en listes numériques
    vectors = []
    for row in vectors_raw:
        # On retire les crochets, on coupe par virgules et on convertit en float
        vec_str = row[0].strip('[]')
        coords = [float(c) for c in vec_str.split(',')]
        vectors.append(coords)

    if not vectors:
        print("Aucun vecteur trouvé.")
        exit()

    # Extraction des coordonnées, en supposant que tous les vecteurs sont en 3D
    if any(len(v) != 3 for v in vectors):
         print("Avertissement : vecteurs non 3D ou dimensions incohérentes : impossible de tracer en 3D.")
         exit()


    x = [v[0] for v in vectors]
    y = [v[1] for v in vectors]
    z = [v[2] for v in vectors]

    # Création du graphique 3D
    fig = plt.figure()
    ax = fig.add_subplot(111, projection='3d')
    ax.scatter(x, y, z)

    ax.set_xlabel('Dimension 1')
    ax.set_ylabel('Dimension 2')
    ax.set_zlabel('Dimension 3')
    ax.set_title('Visualisation 3D des vecteurs')

    plt.show()

except psycopg2.Error as e:
    print(f"Erreur lors de la connexion ou de la requête SQL : {e}")
except Exception as e:
    print(f"Erreur inattendue : {e}")
finally:
    # Fermeture de la connexion
    if cur:
        cur.close()
    if conn:
        conn.close()

Exécutez le script Lancez le script Python dans le terminal :
bash
```
python visualize_vectors.py
```
1
Le script se connectera à PostgreSQL, extraira les données vectorielles et ouvrira une fenêtre Matplotlib montrant le nuage de points 3D.

Foire Aux Questions (FAQ)

Q : L’extension vector n’apparaît pas dans le résultat de \dx — que faire ? R: Assurez-vous d’avoir bien exécuté la commande CREATE EXTENSION vector; sans erreur. Si le problème persiste, vérifiez que le package PostgreSQL de ServBay est bien installé et activé. Les fichiers de pgvector doivent se trouver dans le sous-dossier share/extension de l’installation PostgreSQL. En cas d’absence, envisagez de réinstaller ou mettre à jour ServBay.
Q : Je rencontre une erreur d’authentification lors de la connexion à la base — que faire ? R : Vérifiez soigneusement les paramètres (utilisateur, mot de passe, hôte, port) dans vos commandes psql ou scripts Python. Pour une connexion locale, l’utilisateur par défaut est souvent servbay ou postgres, parfois sans mot de passe.
Q : Comment choisir les paramètres d’index vectoriels : lists, m, ef_construction ? R : Leur influence sur les performances et le taux de rappel est importante, il n’existe donc pas de valeur « idéale » universelle. Expérimentez en fonction de la taille, de la dimension et des exigences de votre projet. Consultez la documentation officielle de pgvector pour des recommandations plus pointues.

Conclusion

pgvector dote PostgreSQL de capacités vectorielles de pointe, offrant un environnement robuste et mature pour développer localement des applications d’IA et de recherche vectorielle. L’intégration de l’extension par défaut dans ServBay rend la configuration particulièrement aisée.

En suivant ce guide, vous pourrez activer pgvector dans PostgreSQL sur ServBay, créer des tables pour stocker vos vecteurs, indexer efficacement vos données, exécuter des recherches de similarité et visualiser vos résultats. Combiné avec les autres outils de développement intégrés à ServBay, cela vous permet de concevoir et tester rapidement des applications web modernes et des projets data ambitieux.

Guide d’utilisation de l’extension pgvector PostgreSQL dans ServBay ​

Qu’est-ce que pgvector ? Pourquoi est-ce important ? ​

Prérequis ​

Activation de l’extension pgvector dans PostgreSQL de ServBay ​

Configuration et utilisation de pgvector ​

Création d’une table avec colonne vectorielle ​

Indexation vectorielle pour accélérer les recherches ​

Requêtes vectorielles avec pgvector ​

Recherche du plus proche voisin (Nearest Neighbor Search) ​

Recherche de similarité vectorielle ​

Visualisation des données vectorielles (optionnel) ​

Foire Aux Questions (FAQ) ​

Conclusion ​