Gids: pgvector PostgreSQL-extensie gebruiken in ServBay

pgvector is een krachtige, externe extensie voor PostgreSQL die een vector data type en efficiënte indexmethoden toevoegt, zoals IVFFlat en HNSW. Hierdoor kan PostgreSQL native vectoropslag en gelijkeniszoekopdrachten uitvoeren — ideaal voor AI-apps, aanbevelingssystemen, beeldherkenning en natuurlijke taalverwerking waarbij hoge-dimensionale vectoren cruciaal zijn.

ServBay is een geïntegreerde lokale webontwikkelomgeving die PostgreSQL en de pgvector extensie vooraf heeft geïnstalleerd, waardoor het eenvoudig is om lokaal een vector database te gebruiken. In deze handleiding lees je hoe je pgvector effectief inzet binnen ServBay.

Wat is pgvector? Waarom is het belangrijk?

In moderne toepassingen is data vaak méér dan alleen gestructureerde tekst en cijfers. Door de groei van kunstmatige intelligentie en machine learning worden gegevens geregeld weergegeven als hoge-dimensionale vectoren, ook wel “embeddings” genoemd. Deze vectoren vatten semantische informatie samen — zoals visuele kenmerken van afbeeldingen, betekenis van tekst of voorkeuren van gebruikers.

De pgvector extensie stelt PostgreSQL in staat om vectoren direct op te slaan en krachtige gelijkeniszoekopdrachten (ook wel “nearest neighbor search”) uit te voeren. Dit biedt de mogelijkheid om met vertrouwde SQL de meest overeenkomstige datapunten bij een opgegeven vector te vinden, zonder dat je een apart vector database systeem nodig hebt. Dit vereenvoudigt je technologie-stack aanzienlijk.

Voorwaarden

Controleer voor je aan de slag gaat met pgvector dat je aan de volgende voorwaarden voldoet:

1. ServBay is geïnstalleerd en draait op macOS.
2. Het PostgreSQL-pakket in ServBay is geactiveerd in het “Packages”-overzicht. Indien nodig, activeer PostgreSQL via het ServBay-applicatiepanel.

pgvector-extensie activeren in ServBay's PostgreSQL

ServBay bevat standaard de pgvector extensiebestanden in de PostgreSQL-installatiemap. Downloaden of compileren is niet meer nodig — activeer de extensie alleen in de database die je wilt gebruiken.

Stappen om pgvector in ServBay's PostgreSQL-database te activeren:

1. Verbind met de PostgreSQL-database
   Gebruik het psql command line tool om verbinding te maken met PostgreSQL in ServBay. Standaard kun je lokaal verbinden als postgres of servbay gebruiker via poort 5432. Controleer ServBay's documentatie indien je configuratie afwijkt.

   Open je terminal en verbind als volgt (pas gebruikersnaam/database aan):

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

   • -U servbay: Geeft de gebruikersnaam aan (servbay of postgres).
   • -d your_database_name: Je te gebruiken database. Maak deze aan indien nodig (bijvoorbeeld CREATE DATABASE servbay_demo_db;).
   • -h localhost: Verbindt met de lokale host.
   • -p 5432: Standaard PostgreSQL poort in ServBay.

2. Maak de vector extensie aan
   Na verbinding, activeer pgvector in psql met:

   CREATE EXTENSION vector;

   Als de extensie al bestaat, krijg je daarover bericht.

3. Controleer installatie
   Toon geïnstalleerde extensies om te checken dat pgvector geactiveerd is:

   \dx

   Je ziet een lijst met onder andere vector en versie-informatie.

                              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)

   (Let op: versienummers kunnen afwijken)

pgvector configureren & gebruiken

Zodra de extensie actief is, kun je vectoren in je database opslaan en beheren.

Een tabel maken die vectoren opslaat

Maak een tabel met een vector-kolom (VECTOR(dimensions)), waarbij dimensions het aantal vectorcomponenten is.

Voorbeeld: een embeddings tabel met 3-dimensionale vectoren:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Definieer een vector-kolom met 3 dimensies
    vector VECTOR(3)
);

Nu kun je voorbeeldvectoren invoegen:

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]'); -- Voeg meer data toe voor duidelijke zoekvoorbeelden

Let op: vectoren moeten tussen vierkante haken staan, gescheiden door komma’s.

Indexen maken voor snellere vector-zoekopdrachten

Bij grote tabellen is een index essentieel voor performance. pgvector ondersteunt IVFFlat en HNSW indexmethoden — je keuze hangt af van datasetgrootte, snelheid, geheugenverbruik en recall.

• IVFFlat (Inverted File Index met platte compressie): Snel te bouwen, geschikt voor grotere datasets maar lagere recall.
• HNSW (Hierarchical Navigable Small World): Vaak sneller en nauwkeuriger, maar traag te bouwen en meer geheugenintensief.

Voorbeelden voor het maken van IVFFlat en HNSW indexen:

1. IVFFlat-index maken:

   -- Draai eerst ANALYZE om statistieken te verzamelen
   ANALYZE embeddings;
   
   -- Maak IVFFlat-index aan
   -- WITH (lists = 100): Aantal inverted lists, af te stemmen op je dataset.
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. HNSW-index maken:

   -- Maak HNSW-index aan
   -- WITH (m = 16, ef_construction = 200): HNSW parameters.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Let op: Parameters als lists, m, ef_construction hebben veel invloed op performance en recall. Kies de juiste waarden aan de hand van je data en testresultaten. Zie de pgvector documentatie voor details en tuning-tips.

Vectorzoekopdrachten uitvoeren met pgvector

pgvector biedt operatoren om afstanden tussen vectoren te berekenen en gelijkenis te zoeken:

• <->: L2-afstand (Euclidische afstand) — lineaire afstand tussen vectoren.
• <#>: Inwendige vermenigvuldiging (Inner Product) — gerelateerd aan cosinusgelijkenis.
• <=>: Cosinusafstand — 1 - cosinusgelijkenis, ongevoelig voor vectorlengte.

Enkele veelgebruikte queryvoorbeelden:

Dichtstbijzijnde buren zoeken (Nearest Neighbor Search)

Zoek vectoren die het meest lijken op een gegeven inputvector. Gebruik ORDER BY met een afstandsoperator en LIMIT.

1. Zoek de 5 vectoren met kleinste L2-afstand tot [0.2, 0.3, 0.4]:

   SELECT
       id,
       vector,
       -- Bereken L2-afstand tot de query-vector
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- Sorteer op afstand (laagst eerst)
   LIMIT 5;

Vector gelijkenis zoeken (Similarity Search)

Vergelijkbaar met “nearest neighbor”, maar met focus op gelijkenisscores.

1. Zoek de 5 vectoren met kleinste cosinusafstand tot [0.2, 0.3, 0.4] en toon score:

   SELECT
       id,
       vector,
       -- Bereken cosinusafstand tot de query-vector
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Sorteer op afstand (laagst eerst)
   LIMIT 5;

Vectoren visualiseren (optioneel)

Het visualiseren van hoge-dimensionale vectoren helpt om clustering en distributie te begrijpen. 2D en 3D-vectoren kunnen direct als scatterplot worden getekend. Voor hogere dimensies kun je bijvoorbeeld PCA of t-SNE toepassen om te reduceren naar 2D/3D.

Voorbeeld: 3D vectordata visualiseren met Python en Matplotlib.

1. Bereid je Python-omgeving voor:
   Installeer psycopg2 (voor PostgreSQL-connectie) en matplotlib (plotten):

   # Met standaard Python:
   pip install psycopg2 matplotlib
   
   # Met ServBay Python kun je hun eigen pip gebruiken:
   # /Applications/ServBay/SoftwarePackages/python/bin/pip install psycopg2 matplotlib

   Pas het pip-pad aan bij gebruik van ServBay's Python.

2. Maak een Python script:
   Maak bijvoorbeeld visualize_vectors.py aan. Pas de database connectieparameters aan aan jouw ServBay-configuratie (dbname, user, password, host, port).

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Importeer voor 3D scatterplots
   
   # Database connectieparameters - pas aan!
   db_params = {
       "dbname": "your_database_name", # Jouw database
       "user": "servbay",              # PostgreSQL gebruiker
       "password": "",                 # Leeg voor lokale connectie
       "host": "localhost",            # Meestal localhost
       "port": "5432"                  # Standaardpoort
   }
   
   conn = None
   cur = None
   
   try:
       # Verbinding maken met PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Query vector data
       # Let op: psycopg2 leest het vector type als string '[x, y, z]'
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # String naar float list parsen
       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("Geen vector data gevonden.")
           exit()
   
       # Check dat alle vectors 3D zijn
       if any(len(v) != 3 for v in vectors):
            print("Waarschuwing: Onjuiste dimensionaliteit, kan geen 3D plot maken.")
            exit()
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # Plot als 3D scatterplot
       fig = plt.figure()
       ax = fig.add_subplot(111, projection='3d')
       ax.scatter(x, y, z)
   
       ax.set_xlabel('Dimensie 1')
       ax.set_ylabel('Dimensie 2')
       ax.set_zlabel('Dimensie 3')
       ax.set_title('3D Vector Visualisatie')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Database connectie of query fout: {e}")
   except Exception as e:
       print(f"Fout opgetreden: {e}")
   finally:
       # Sluit connectie
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Script uitvoeren:
   Start het Python script vanuit je terminal:

   python visualize_vectors.py

   Het script verbindt met PostgreSQL, haalt vectoren op en toont een 3D scatterplot.

Veelgestelde Vragen (FAQ)

• Vraag: Ik zie de vector extensie niet in de output van \dx, wat nu?
  Antwoord: Controleer eerst of je CREATE EXTENSION vector; correct hebt uitgevoerd. Controleer of ServBay's PostgreSQL-pakket goed geïnstalleerd en geactiveerd is. De pgvector-extensie hoort te staan in de submap share/extension van PostgreSQL. Ontbreekt het bestand alsnog, herinstalleer of update dan PostgreSQL via ServBay.
• Vraag: Authenticatiefout bij databaseverbinding, wat doe ik?
  Antwoord: Controleer of gebruikersnaam, wachtwoord, host en poort bij psql of in je Python script overeenkomen met ServBay's PostgreSQL-configuratie. Voor lokale verbindingen is de gebruiker meestal servbay of postgres zonder wachtwoord.
• Vraag: Hoe kies ik de index parameters lists, m, ef_construction?
  Antwoord: Deze parameters hebben veel effect op performance en recall. Er is geen standaardwaarde: test en optimaliseer afhankelijk van de omvang van je data, aantal vectoren, dimensies, snelheidseisen en gewenste recall. Zie de officiële pgvector documentatie voor richtlijnen.

Samenvatting

pgvector brengt de krachtige functionaliteit van vector databases naar het robuuste PostgreSQL-platform, waardoor lokale ontwikkeling van AI- en vector gebaseerde toepassingen eenvoudiger wordt. ServBay maakt het activeren en gebruiken van pgvector een fluitje van een cent.

Met deze gids kun je pgvector activeren in ServBay's PostgreSQL, tabellen met vectors aanmaken, gebruikmaken van geavanceerde indexing voor snelle zoekopdrachten en diverse gelijkenisqueries draaien. Samen met ServBay's overige tools bouw en test je razendsnel moderne webapplicaties en datagedreven projecten.