Handleiding: pgvector PostgreSQL-extensie gebruiken in ServBay

pgvector is een krachtige third-party extensie voor de PostgreSQL-database, waarmee je een vectoortype en een efficiënte indexering voor vectors toevoegt, zoals IVFFlat en HNSW. Hierdoor kan PostgreSQL native vectoropslag en gelijkeniszoekopdrachten ondersteunen, wat het een ideale keuze maakt voor AI-applicaties, aanbevelingssystemen, beeldherkenning en natuurlijke taalverwerking waarbij gewerkt wordt met hoog-dimensionale vectoren.

Als geïntegreerde lokale webontwikkelomgeving levert ServBay standaard PostgreSQL én de pgvector-extensie mee. Dit vereenvoudigt het activeren en gebruiken van vectordatabases in je lokale ontwikkelomgeving aanzienlijk. In dit artikel lees je hoe je optimaal gebruikmaakt van pgvector in ServBay.

Wat is pgvector en waarom is het belangrijk?

In veel moderne toepassingen bestaat data niet meer enkel uit gestructureerde tekst of getallen. Dankzij de opkomst van AI en machine learning wordt data vaak gerepresenteerd als hoog-dimensionale vectoren, ook wel "embeddings" genoemd. Deze vectoren vangen semantische betekenis of kenmerken van data, zoals de visuele eigenschappen van een afbeelding, de betekenis van tekst, of gebruikersvoorkeuren.

Met de pgvector-extensie kan PostgreSQL rechtstreeks deze vectoren opslaan en efficiënt zoeken op basis van vector-gelijkenis uitvoeren (ook wel ‘nearest neighbor search’ genoemd). Hierdoor kun je met vertrouwde SQL-taal zoeken naar data die het meest lijkt op een bepaalde vector, zónder dat je een aparte vectordatabase hoeft te onderhouden. Dit vereenvoudigt je technische stack.

Voorwaarden

Voordat je pgvector gaat gebruiken, controleer je het volgende:

1. ServBay is geïnstalleerd en draait op macOS.
2. Het PostgreSQL-pakket is geactiveerd in de 'Packages'-lijst binnen ServBay. Indien nog niet geactiveerd, zoek PostgreSQL dan op in de ServBay-app en zet de status op "Enabled".

pgvector-extensie inschakelen in de PostgreSQL van ServBay

ServBay heeft het pgvector-extensiebestand al in de PostgreSQL-installatiemap geplaatst. Je hoeft zelf niets te downloaden of te compileren. Je hoeft de extensie enkel te activeren in de database waarin je het wilt gebruiken.

Workflow om pgvector in te schakelen in ServBay’s PostgreSQL:

1. Verbinding maken met PostgreSQL: Gebruik het psql commando om verbinding te maken met de PostgreSQL-database van ServBay. Meestal is lokaal verbinden toegestaan, met gebruikers als postgres of servbay, en de standaardpoort is 5432. Wijkt jouw installatie af, raadpleeg dan de ServBay-databasehandleiding.

   Open de Terminal en voer het volgende uit (pas gebruikersnaam en databasenaam aan):

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

   • -U servbay: Geeft de gebruikersnaam op (servbay of postgres)
   • -d your_database_name: Doel-database; maak deze eerst aan als deze nog niet bestaat (bv. CREATE DATABASE servbay_demo_db;)
   • -h localhost: Host is lokaal.
   • -p 5432: Poortnummer (standaard voor ServBay’s PostgreSQL).

2. Extensie vector aanmaken: Eenmaal verbonden in psql, activeer je de pgvector-extensie met:

   CREATE EXTENSION vector;

   Bestaat de extensie al, dan krijg je een melding.

3. Installatie verifiëren: Controleer of pgvector succesvol werkt door alle extensies op te vragen:

   \dx

   Je zou nu een regel met vector en wat versiedetails moeten zien:

                              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: het versienummer kan afwijken afhankelijk van de geïntegreerde versie in ServBay)

pgvector configureren en gebruiken

Nu de pgvector-extensie is geactiveerd, kun je vector-data opslaan en bewerken.

Een tabel met vector-data aanmaken

Eerst maak je een tabel voor je vectors. pgvector biedt het nieuwe datatype VECTOR(aantal_dimensies), waarbij aantal_dimensies het aantal vectorwaarden is.

Voorbeeld: maak een tabel embeddings voor 3D-vectoren:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Definieer een 3D vectorveld
    vector VECTOR(3)
);

Daarna voeg je een aantal voorbeeldvectoren toe:

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]'); -- Meer data toevoegen vergroot inzicht bij queryvoorbeelden

Opmerking: vectoren worden tussen rechte haken [] gezet, waardes gescheiden door komma’s.

Vector-indexen aanmaken voor betere zoekprestaties

Voor tabellen met veel vectoren is indexeren essentieel om zoekopdrachten snel te houden. pgvector ondersteunt twee hoofdsoorten indexen: IVFFlat en HNSW. De keus hangt af van jouw wensen qua snelheid, geheugengebruik, en nauwkeurigheid.

• IVFFlat (Inverted File Index met Flat compressie): Ideaal voor grotere datasets als iets lagere recall acceptabel is. Snelle bouwtijd.
• HNSW (Hierarchical Navigable Small World): Gewoonlijk hogere recall en sneller in queries, maar bouwen duurt langer en gebruikt meer geheugen.

Voorbeelden van indexen creëren op de kolom vector in de tabel embeddings:

1. IVFFlat-index maken:

   -- Voer ANALYZE uit om statistieken te verzamelen, aanbevolen vóór IVFFlat-indexen
   ANALYZE embeddings;
   
   -- IVFFlat-index aanmaken
   -- WITH (lists = 100): Aantal inverted lists, stem dit af op je datasetgrootte.
   -- Meer lists: langzamer bouwen, mogelijk tragere scans, maar hogere recall.
   -- Richtlijn: lists = wortel uit aantal rijen.
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. HNSW-index maken:

   -- HNSW-index aanmaken
   -- WITH (m = 16, ef_construction = 200): Belangrijkste HNSW-parameters.
   -- m: Max aantal verbindingen per knoop; beïnvloedt connectiviteit, snelheid en geheugen.
   -- ef_construction: Zoekbereik tijdens maken; heeft invloed op snelheid/geheugen/kwaliteit (recall).
   -- Deze parameters kunnen per dataset/prestatiebehoefte worden aangepast.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Let op: Indexparameters (lists, m, ef_construction) beïnvloeden prestatie en recall sterk. Je moet deze afstellen op basis van je data en querygebruik; experimenteren is aan te raden. Zie de officiële pgvector-documentatie voor uitleg en tips.

Vectorqueries met pgvector

pgvector biedt operatoren voor het berekenen van de afstand tussen vectoren; hiermee kun je zoeken op gelijkenis. De belangrijkste zijn:

• <->: L2-afstand (Euclidisch); meet de ‘rechte lijn’-afstand.
• <#>: Inwendig product (Inner Product); gerelateerd aan cosinusgelijkenis.
• <=>: Cosinus-afstand. 1 - cosinus gelijkenis; meet richtingsovereenkomst, ongeacht lengte.

Hieronder enkele typische queries:

Dichtstbijzijnde buur zoeken (Nearest Neighbor)

Zoek de 5 vectoren die het dichtst bij een gegeven queryvector liggen (d.w.z. kleinste afstand). Gebruik ORDER BY en een afstandsoperator, en LIMIT:

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

   SELECT
       id,
       vector,
       -- Bereken de L2-afstand tot de queryvector
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- Oplopend sorteren; kleinste afstand = meeste gelijkenis
   LIMIT 5;

Vector gelijkenis/Similarity Search

Vergelijkbaar met de buurzoeken, maar toont vaak een gelijkenisscore.

1. Toon de 5 vectoren met de laagste cosinus-afstand tot [0.2, 0.3, 0.4]:

   SELECT
       id,
       vector,
       -- Bereken de cosinus-afstand tot de queryvector
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Oplopend op afstand (kleiner = meer gelijkend)
   LIMIT 5;

Vectorvisualisatie (optioneel)

Het visualiseren van hoogdimensionale vectoren helpt om verdeling en clustering te begrijpen. 2D- of 3D-vectoren kun je direct plotten. Voor hogere dimensies gebruik je vaak dimensiereductie (zoals PCA of t-SNE), waarna je op 2D/3D kunt plotten.

Hier een kort Python-voorbeeld met Matplotlib voor 3D-vectoren:

1. Python-omgeving instellen: Gebruik een Python-omgeving binnen of buiten ServBay. Zorg dat het Python-pakket van ServBay actief is (indien gewenst). Installeer de packages psycopg2 (PostgreSQL-driver) en matplotlib:

   # Gebruik standaard Python of je eigen installatie
   pip install psycopg2 matplotlib
   
   # Met ServBay’s Python kan het pad anders zijn, bijvoorbeeld:
   # /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib

   Pas het pip-commando aan op het pad van jouw Python.

2. Python-script maken: Maak een Python-bestand (bijvoorbeeld visualize_vectors.py) en plak de volgende code. Pas de connectieparameters (dbname, user, password, host, port) aan naar jouw ServBay-configuratie.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Module voor 3D scatterplots
   
   # Database connectieparameters - pas aan naar jouw ServBay-gegevens
   db_params = {
       "dbname": "your_database_name", # Vervang door je databasenaam
       "user": "servbay",              # Vervang door je gebruikersnaam (servbay of postgres)
       "password": "",                 # Vervang door je wachtwoord (kan leeg zijn bij lokale verbinding)
       "host": "localhost",            # ServBay PostgreSQL draait meestal lokaal
       "port": "5432"                  # Standaardpoort ServBay PostgreSQL
   }
   
   conn = None
   cur = None
   
   try:
       # Verbinden met PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Vectoren ophalen
       # Let op: psycopg2 leest het vector-type als string '[x, y, z]'
       # Parse handmatig of zorg voor recente pgvector/psycopg2
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # String parsen naar nummerlijst
       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 vectorgegevens gevonden.")
           exit()
   
       # Controleer of alles 3D is, anders stoppen
       if any(len(v) != 3 for v in vectors):
            print("Waarschuwing: vectoren hebben geen consistente of 3D-dimensie, 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]
   
       # Maak 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"Fout bij verbinden of query uitvoeren: {e}")
   except Exception as e:
       print(f"Er trad een fout op: {e}")
   finally:
       # Sluit de databaseverbinding
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Script uitvoeren: Start het script vanaf de terminal:

   python visualize_vectors.py

   Het script haalt de vectoren uit je database en toont een 3D scatterplot in Matplotlib.

Veelgestelde vragen (FAQ)

• Vraag: Ik zie geen vector-extensie in de uitvoer van \dx. Wat nu? Antwoord: Controleer eerst of je het commando CREATE EXTENSION vector; correct hebt uitgevoerd zonder foutmelding. Controleer dat het PostgreSQL-pakket van ServBay correct geïnstalleerd/actief is. Het pgvector-extensiebestand moet staan in de submap share/extension onder PostgreSQL. Ontbreekt het bestand echt, probeer dan herinstallatie of update van ServBay’s PostgreSQL-pakket.
• Vraag: Ik krijg een authenticatiefout bij het verbinden met de database. Wat nu? Antwoord: Controleer of je de juiste gebruikersnaam, wachtwoord, host en poort gebruikt in je psql-commando of Python-script. Bij lokale ServBay-installaties is de gebruiker vaak servbay of postgres, mogelijk zonder wachtwoord.
• Vraag: Hoe kies ik de juiste indexparameters, zoals lists, m, ef_construction? Antwoord: Deze instellingen beïnvloeden prestatie en recall significant – een universeel optimale waarde bestaat niet. Experimenteer en stem af op jouw datasetgrootte, aantal dimensies, snelheidseisen, en gewenste recall. Zie de pgvector-documentatie voor details en tips.

Samenvatting

pgvector brengt krachtige functionaliteit voor vectordatabases naar het robuuste PostgreSQL-platform en maakt lokale ontwikkeling van AI- en vectorapplicaties veel gemakkelijker. ServBay vereenvoudigt het hele proces door pgvector standaard mee te leveren.

Na deze handleiding kun je pgvector activeren in ServBay’s PostgreSQL, tabellen aanmaken voor vectoropslag, efficiënte indexen bouwen, en geavanceerde gelijkenisqueries uitvoeren. Samen met de andere tools en pakketten van ServBay leg je een krachtig fundament voor moderne webdevelopment en data-intensieve applicaties.