Guide d'utilisation de l’extension pgvector PostgreSQL avec ServBay

pgvector est une puissante extension tierce pour la base de données PostgreSQL ; elle ajoute de nouveaux types de données vectorielles et des méthodes d’indexation performantes comme IVFFlat et HNSW. Grâce à pgvector, PostgreSQL prend en charge nativement le stockage de vecteurs et la recherche par similarité — un atout incontournable pour créer des applications d’IA, des systèmes de recommandation, de la reconnaissance d’image ou du traitement du langage naturel nécessitant la manipulation de données vectorielles de haute dimension.

ServBay, un environnement local de développement web tout-en-un, intègre déjà PostgreSQL ainsi que l’extension pgvector, ce qui simplifie grandement l’utilisation d’une base vectorielle dans votre environnement local de développement. Ce guide vous explique pas à pas comment tirer parti de pgvector avec ServBay.

Qu’est-ce que pgvector et pourquoi est-ce important ?

Dans de nombreuses applications modernes, les données ne se limitent plus à du texte ou à des chiffres structurés. Avec la montée en puissance de l’intelligence artificielle et du machine learning, les données sont fréquemment représentées sous forme de vecteurs de grande dimension (aussi appelés « embeddings »). Ces vecteurs capturent la sémantique et les caractéristiques des données : les propriétés visuelles d’une image, la signification d’un texte ou les préférences d’un utilisateur.

L’extension pgvector permet à PostgreSQL de stocker ces vecteurs directement et d’effectuer des recherches rapides par similarité (dites « recherches de plus proches voisins »). Vous pouvez ainsi interroger vos vecteurs à l’aide du langage SQL que vous connaissez déjà, sans avoir besoin d’un moteur de base vectorielle séparé ; cela simplifie considérablement votre architecture technique.

Prérequis

Avant de commencer avec pgvector, vérifiez que vous remplissez les conditions suivantes :

1. ServBay est installé et exécuté sur votre macOS.
2. Le package PostgreSQL est activé dans la section “Packages” de ServBay. Si ce n’est pas le cas, trouvez PostgreSQL dans l’interface ServBay et changez son statut sur “Activé”.

Activer l’extension pgvector dans PostgreSQL de ServBay

ServBay inclut les fichiers pgvector nécessaires dans le dossier d’installation de PostgreSQL, inutile de les télécharger ou de les compiler manuellement. Il vous suffit d’activer l’extension sur votre base de données cible.

Voici les étapes pour activer pgvector dans PostgreSQL livré avec ServBay :

1. Se connecter à la base de données PostgreSQL
   Utilisez l’outil en ligne de commande psql pour vous connecter à l’instance PostgreSQL ServBay. La configuration par défaut autorise souvent une connexion locale avec l’utilisateur postgres ou servbay, sur le port 5432. Si la configuration diffère, consultez la documentation ServBay dédiée à PostgreSQL.

   Ouvrez le terminal et lancez :

   psql -U servbay -d your_database_name -h localhost -p 5432

   • -U servbay : définit l’utilisateur (servbay ou postgres).
   • -d your_database_name : nom de la base de données à connecter. Si elle n’existe pas, créez-la au préalable (exemple : CREATE DATABASE servbay_demo_db;).
   • -h localhost : indique l’adresse locale.
   • -p 5432 : le port PostgreSQL par défaut utilisé par ServBay.

2. Créer l’extension vector
   Une fois connecté, saisissez la commande SQL suivante dans l’invite psql pour activer l’extension :

   CREATE EXTENSION vector;

   Si l’extension existe déjà, le système affiche un message d’information.

3. Vérifier l’installation
   Pour confirmer l’activation de pgvector, listez les extensions installées :

   \dx

   Vous devriez voir vector apparaître avec ses informations de version dans la sortie :

                              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)

   (Remarque : la version peut varier selon celle intégrée à ServBay.)

Configurer et utiliser pgvector

Une fois l’extension activée, vous pouvez manipuler des données vectorielles dans votre base.

Créer une table pour stocker des vecteurs

Commencez par créer une table pour vos données vectorielles. pgvector fournit le type VECTOR(dimensions), où dimensions est le nombre de composantes du vecteur.

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

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Déclarer une colonne vecteur à 3 dimensions
    vector VECTOR(3)
);

Insérez maintenant quelques vecteurs d’exemple :

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 des requêtes plus parlantes

Remarque : Entourez les valeurs par des crochets [ ], séparez les éléments par des virgules.

Créer un index vectoriel pour accélérer les recherches

Si votre table contient de nombreux vecteurs, il est indispensable d’indexer pour des recherches efficaces. pgvector propose deux types d’index principaux : IVFFlat et HNSW. Choisissez en fonction de vos besoins (rapidité, temps de construction, mémoire, rappel).

• IVFFlat (Inverted File Index à compression flat) : adapté aux larges ensembles de données avec des exigences de rappel modérées. Construction rapide.
• HNSW (Hierarchical Navigable Small World) : généralement plus performant en rappel et en rapidité de requête ; la construction peut être plus lente et gourmande en mémoire.

Création d’index pour la colonne vector de la table embeddings :

1. IVFFlat :

   -- Avant de créer un index IVFFlat, il est recommandé d’exécuter ANALYZE pour actualiser les statistiques
   ANALYZE embeddings;
   
   -- Créer l’index IVFFlat
   -- WITH (lists = 100) : définit le nombre de listes inversées, à adapter à la taille du jeu de données
   -- Plus le nombre de listes est élevé, plus le rappel peut être amélioré, mais la construction et la requête seront impactées. 
   -- L’équipe pgvector recommande lists = sqrt(nombre de lignes).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. HNSW :

   -- Créer l’index HNSW
   -- WITH (m = 16, ef_construction = 200) : paramètres pour HNSW
   -- m : connexions maximum par nœud (impact sur la rapidité/mémoire/infrastructure du graphe)
   -- ef_construction : extension du champ de recherche en construction (affecte la qualité/rappel)
   -- À ajuster selon vos données et besoins.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Remarque : Les paramètres (lists, m, ef_construction) influent fortement sur les performances et le rappel. Testez différents réglages selon vos usages et consultez la documentation officielle pgvector pour plus de détails.

Interroger les vecteurs avec pgvector

pgvector propose des opérateurs pour calculer la distance entre vecteurs, pour la recherche de similarité. Les principaux sont :

• <-> : distance L2 (euclidienne) — pour la distance “en ligne droite” entre vecteurs
• <#> : produit scalaire (inner product) — lié à la similarité cosinus, compare l’orientation
• <=> : distance cosinus — 1 - similarité cosinus, compare l’angle, indépendamment de la longueur des vecteurs

Recherche de plus proches voisins (Nearest Neighbor Search)

Trouver les vecteurs les plus proches d’un vecteur cible : utilisez ORDER BY avec l’opérateur de distance et limitez le nombre de résultats.

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

   SELECT
       id,
       vector,
       -- Calculer la distance L2 au vecteur cible
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- Plus la distance est faible, plus la similarité est grande
   LIMIT 5;

Recherche de similarité vectorielle

Semblable à la recherche de voisins proches, mais l’accent est mis sur le score de similarité.

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

   SELECT
       id,
       vector,
       -- Calculer la distance cosinus
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Classement par similarité (plus bas = plus similaire)
   LIMIT 5;

Visualisation des données vectorielles (optionnel)

Visualiser des vecteurs de grande dimension aide à comprendre leur répartition et leur regroupement. Pour des vecteurs en 2D ou 3D, utilisez des nuages de points ; pour des vecteurs plus complexes, appliquez une réduction de dimension (PCA, t-SNE…) avant la projection.

Voici un exemple en Python avec Matplotlib pour visualiser des vecteurs 3D.

1. Préparer l’environnement Python
   Configurez un Python dans ou hors de ServBay. Si vous utilisez Python fourni par ServBay, activez-le au préalable. Installez les modules nécessaires :

   # Avec le Python système ou une installation personnelle
   pip install psycopg2 matplotlib
   
   # Avec Python de ServBay, passez via sa CLI ou le pip dans son répertoire bin
   # /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib

   Adaptez la commande selon le chemin vers votre environnement Python.

2. Créer le script Python
   Écrivez un fichier Python (visualize_vectors.py) et copiez le code ci-dessous. Modifiez les paramètres de connexion (dbname, user, password, host, port) selon votre configuration PostgreSQL ServBay.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Import pour les nuages de points 3D
   
   # Paramètres de connexion — à adapter selon votre installation ServBay
   db_params = {
       "dbname": "your_database_name", # remplacez par le nom de votre base
       "user": "servbay",              # remplacez par l’utilisateur PostgreSQL (souvent servbay ou postgres)
       "password": "",                 # remplacez par le mot de passe (connexion locale souvent sans mot de passe)
       "host": "localhost",            # PostgreSQL de ServBay écoute sur localhost
       "port": "5432"                  # port par défaut
   }
   
   conn = None
   cur = None
   
   try:
       # Connexion à PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Requête des vecteurs
       # Remarque : par défaut, psycopg2 lira les 'vector' comme chaînes de caractères '[x, y, z]'.
       # À parser manuellement — sauf si vous utilisez un driver récent adapté pgvector.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Conversion chaîne -> liste de chiffres
       vectors = []
       for row in vectors_raw:
           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
       # Vérifier que tous les vecteurs sont en 3D
       if any(len(v) != 3 for v in vectors):
            print("Attention : tous les vecteurs ne sont pas à trois dimensions, 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]
   
       # Nuage de points 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 de connexion ou de requête PostgreSQL : {e}")
   except Exception as e:
       print(f"Une erreur s'est produite : {e}")
   finally:
       # Fermer la connexion
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Exécuter le script
   Lancez en terminal :

   python visualize_vectors.py

   Le script se connecte à votre base PostgreSQL, récupère les vecteurs et lance la visualisation 3D avec Matplotlib.

FAQ (Foire Aux Questions)

• Je ne vois pas l’extension vector dans la sortie \dx, que faire ?
  Vérifiez d’abord que vous avez bien exécuté CREATE EXTENSION vector; sans erreur. Si l’extension n’apparaît pas, assurez-vous que le package PostgreSQL ServBay est bien installé et activé. Le fichier d’extension pgvector doit être dans le répertoire share/extension de PostgreSQL. S’il est manquant, essayez de réinstaller ou de mettre à jour le package PostgreSQL via ServBay.
• Échec d’authentification lors de la connexion à la base, pourquoi ?
  Vérifiez les informations utilisateur, mot de passe, hôte et port dans votre commande psql ou votre script Python. Par défaut, l’utilisateur local est souvent servbay ou postgres, et le mot de passe peut être vide.
• Comment choisir les paramètres lists, m, ef_construction pour les index vectoriels ?
  Ces paramètres affectent considérablement la performance et le rappel des recherches. Il n’existe pas de valeurs “idéales” universelles : testez plusieurs réglages selon la taille de votre donnée, le nombre de dimensions, vos contraintes de rapidité et votre cible de rappel. Consultez la documentation officielle pgvector pour des recommandations détaillées.

Conclusion

Grâce à pgvector, PostgreSQL acquiert toute la puissance d’une base vectorielle et devient une solution robuste et flexible pour le développement local d’applications IA ou axées sur les vecteurs. ServBay rend encore plus simple la configuration de cet environnement.

En suivant les étapes de ce guide, vous pouvez activer pgvector dans ServBay, créer des tables vectorielles, indexer pour des recherches performantes et effectuer diverses requêtes par similarité. Associé à tous les outils de développement intégrés dans ServBay, vous disposez d’une plateforme efficace pour concevoir et tester vos applications web modernes et vos projets orientés données vectorielles.