Guida all’Utilizzo dell’Estensione pgvector per PostgreSQL in ServBay

pgvector è una potente estensione di terze parti per il database PostgreSQL che aggiunge il supporto ai dati vettoriali, oltre a metodi di indicizzazione efficienti come IVFFlat e HNSW. Grazie a questo, PostgreSQL può conservare e cercare nativamente vettori, rendendolo ideale per applicazioni AI, sistemi di raccomandazione, riconoscimento immagini e NLP, tutte caratterizzate dalla gestione di dati vettoriali ad alta dimensionalità.

ServBay, un ambiente di sviluppo locale per il web integrato, pre-installa sia PostgreSQL che l’estensione pgvector, semplificando notevolmente l’attivazione e l’utilizzo di database vettoriali in locale. Questa guida illustra in dettaglio come sfruttare pgvector all’interno di ServBay.

Cos’è pgvector e perché è importante?

In molti casi moderni, i dati non sono più semplici testi o numeri strutturati. Con l’avanzamento di AI e machine learning, spesso i dati vengono rappresentati come vettori ad alta dimensionalità, detti anche “embeddings”. Questi vettori racchiudono le informazioni semantiche o le caratteristiche dei dati, come i dettagli visivi di un’immagine, il significato di un testo, o le preferenze di un utente.

L’estensione pgvector permette a PostgreSQL di memorizzare direttamente questi vettori ed effettuare ricerche di similarità (nearest neighbor search) in modo efficiente. Questo consente di utilizzare il linguaggio SQL che già si conosce per trovare gli elementi dati più vicini a uno specifico vettore, senza dover dipendere da un database di vettori separato, semplificando l’infrastruttura tecnica.

Prerequisiti

Prima di utilizzare pgvector, assicurati di:

1. Aver installato e avviato ServBay su macOS.
2. Aver attivato il pacchetto PostgreSQL tramite la lista “Packages” di ServBay. Se non l’hai ancora attivato, trovalo nell’interfaccia ServBay e imposta lo stato su “Enabled”.

Abilitare l’Estensione pgvector in PostgreSQL su ServBay

ServBay fornisce già i file dell’estensione pgvector all’interno della directory di installazione di PostgreSQL. Non serve scaricare o compilare manualmente: basta semplicemente abilitare l’estensione nel database desiderato.

Ecco i passaggi per attivare pgvector in un database PostgreSQL su ServBay:

1. Connettersi al Database PostgreSQL: Puoi utilizzare lo strumento da terminale psql per connetterti all’istanza PostgreSQL fornita da ServBay. In genere, questa istanza accetta connessioni locali, con utente predefinito postgres o servbay e porta 5432. Se la tua configurazione è diversa, consulta la documentazione di ServBay.

   Apri il terminale e connettiti con il comando (adatta username e nome database secondo la tua configurazione):

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

   • -U servbay: specifica l’utente (ad esempio servbay o postgres).
   • -d your_database_name: il nome del database a cui vuoi collegarti. Se non esiste, crealo prima (ad esempio con CREATE DATABASE servbay_demo_db;).
   • -h localhost: connessione locale.
   • -p 5432: porta di default di PostgreSQL in ServBay.

2. Creare l’Estensione vector: Dopo la connessione, abilita l’estensione eseguendo nel prompt di psql:

   CREATE EXTENSION vector;

   Se è già installata, riceverai una notifica.

3. Verifica dell’Installazione: Puoi elencare le estensioni installate con:

   \dx

   Nell’elenco dovrebbe comparire l’estensione vector con la relativa versione.

                              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)

   (Nota: il numero di versione può variare a seconda della release integrata in ServBay)

Configurazione e Utilizzo di pgvector

Una volta attivata, puoi iniziare a creare e gestire dati vettoriali nel database.

Creare una Tabella per i Dati Vettoriali

Dovrai creare una tabella per i tuoi dati vettoriali. pgvector introduce un nuovo tipo di dato: VECTOR(dimensions), dove dimensions indica il numero di dimensioni del vettore.

Esempio: tabella chiamata embeddings per vettori tridimensionali.

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Definisce una colonna vettore con 3 dimensioni
    vector VECTOR(3)
);

Ora puoi inserire dati di esempio:

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]'); -- Aggiungi altri dati in modo che gli esempi di query siano significativi

Nota: usa le parentesi quadre [] per i valori, separando gli elementi con una virgola.

Creare Indici Vettoriali per Migliorare le Query

Con molti dati vettoriali, creare indici migliora drasticamente la velocità delle ricerche di similarità. pgvector supporta due tipi principali di indici: IVFFlat e HNSW. La scelta dipende dalle caratteristiche del tuo scenario (prestazioni, memoria, qualità dei risultati).

• IVFFlat (Inverted File Index con compressione flat): Ideale per dataset grandi, quando la massima accuratezza non è prioritaria. Costruzione veloce.
• HNSW (Hierarchical Navigable Small World): Precisione elevata e ricerche più rapide, ma costruzione più lenta e maggiore consumo RAM.

Esempio di creazione per la colonna vector della tabella embeddings:

1. Indice IVFFlat:

   -- Prima di creare l’indice, esegui ANALYZE per raccogliere statistiche
   ANALYZE embeddings;
   
   -- Crea l’indice IVFFlat
   -- WITH (lists = 100): specifica il numero di liste invertite. Va calibrato rispetto al tuo dataset.
   -- Più liste = indicizzazione/ricerca più lenta, ma migliore recall. Consiglio: lists = sqrt(numero righe).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. Indice HNSW:

   -- Crea l’indice HNSW
   -- WITH (m = 16, ef_construction = 200): parametri HNSW.
   -- m: collegamenti massimi per nodo; ef_construction: ampiezza di ricerca durante la costruzione.
   -- Da ottimizzare in base ai tuoi dati e alle richieste di prestazione.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Nota: i parametri (come lists, m, ef_construction) influenzano fortemente prestazioni e accuratezza. Stima i valori ottimali in base ai tuoi dati/query. Consulta la documentazione ufficiale pgvector per dettagli e consigli di tuning.

Query Vettoriali con pgvector

pgvector offre vari operatori per il calcolo delle distanze tra vettori, utili per la ricerca di similarità. I più comuni sono:

• <->: Distanza L2 (Euclidea) – indica la distanza “diretta” tra vettori.
• <#>: Prodotto interno – legato alla similarità coseno.
• <=>: Distanza coseno – computed as 1 - coseno, ignora la lunghezza e confronta solo la direzione.

Ecco alcuni esempi pratici:

Query dei Vicini Più Prossimi (Nearest Neighbor Search)

Trova i vettori più simili (quelli con la distanza più piccola) a un vettore query. Si usa ORDER BY con l’operatore di distanza e si limita il risultato con LIMIT.

1. Ricerca dei 5 vettori più vicini a [0.2, 0.3, 0.4] usando distanza L2:

   SELECT
       id,
       vector,
       -- Calcola la distanza L2 dal vettore query
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- ORDINA in ordine crescente (più simili prima)
   LIMIT 5;

Query di Similarità Vettoriale

Simile alla ricerca dei vicini, ma focalizzata sulla distanza/similarità.

1. Ricerca dei 5 vettori più vicini a [0.2, 0.3, 0.4] usando distanza coseno:

   SELECT
       id,
       vector,
       -- Calcola la distanza coseno
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- ORDINA in ordine crescente (più simili prima)
   LIMIT 5;

Visualizzazione dei Dati Vettoriali (Opzionale)

Visualizzare i dati vettoriali aiuta nella comprensione delle loro distribuzioni e clusterizzazioni. Per vettori 2D/3D si possono usare scatter plot, mentre per quelli con dimensioni superiori è opportuno ridurli tramite PCA o t-SNE.

Ecco come creare una visualizzazione semplice per vettori 3D con Python e Matplotlib.

1. Preparazione dell’Ambiente Python: Configura un ambiente Python, interno o esterno a ServBay. Se usi il pacchetto Python di ServBay, assicurati che sia attivo. Installa psycopg2 e matplotlib:

   # Usando Python di sistema o una installazione personale
   pip install psycopg2 matplotlib
   
   # Se usi il Python di ServBay, usa il percorso appropriato
   # /Applications/ServBay/Packages/python/bin/pip install psycopg2 matplotlib

   Adatta il comando al path del tuo ambiente Python.

2. Creare uno Script Python: Crea un file chiamato ad esempio visualize_vectors.py e copia il seguente codice. Aggiorna i parametri di connessione (dbname, user, password, host, port) secondo la tua configurazione ServBay.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Importa il modulo per creare scatter plot 3D
   
   # Parametri di connessione al database - aggiorna secondo le tue impostazioni
   db_params = {
       "dbname": "your_database_name", # Sostituisci con il tuo database
       "user": "servbay",              # Sostituisci con username di ServBay (spesso servbay o postgres)
       "password": "",                 # Sostituisci con la tua password (in locale può essere vuota)
       "host": "localhost",            # PostgreSQL di ServBay gira tipicamente su localhost
       "port": "5432"                  # Porta di default
   }
   
   conn = None
   cur = None
   
   try:
       # Connessione al database PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Query sui dati vettoriali
       # Nota: psycopg2 restituisce i vettori come stringhe '[x, y, z]'.
       # Serve una conversione manuale, a meno di usare versioni recenti con parsing automatico.
       # Qui si suppone di ricevere stringhe, quindi si effettua un semplice parsing.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Parsing delle stringhe in liste di float
       vectors = []
       for row in vectors_raw:
           # Rimuovi parentesi quadre, separa con virgola e converti in float
           vec_str = row[0].strip('[]')
           coords = [float(c) for c in vec_str.split(',')]
           vectors.append(coords)
   
       if not vectors:
           print("Nessun dato vettoriale trovato.")
           exit()
   
       # Estrai le coordinate
       # Tutti i vettori devono avere la stessa dimensione (qui 3D)
       if any(len(v) != 3 for v in vectors):
            print("Attenzione: dimensioni vettori inconsistenti o non 3D, impossibile creare plot 3D.")
            exit()
   
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # Crea scatter plot 3D
       fig = plt.figure()
       ax = fig.add_subplot(111, projection='3d')
       ax.scatter(x, y, z)
   
       ax.set_xlabel('Dimensione 1')
       ax.set_ylabel('Dimensione 2')
       ax.set_zlabel('Dimensione 3')
       ax.set_title('Visualizzazione Vettori 3D')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Errore di connessione o query: {e}")
   except Exception as e:
       print(f"Si è verificato un errore: {e}")
   finally:
       # Chiudi la connessione
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Esecuzione dello Script: Esegui il file Python dal terminale:

   python visualize_vectors.py

   Il programma si collegherà al database PostgreSQL, leggerà i dati vettoriali, e aprirà una finestra con lo scatter plot 3D tramite Matplotlib.

FAQ – Domande Frequenti

• D: Non vedo l’estensione vector in output da \dx, cosa devo fare? R: Verifica di aver realmente eseguito CREATE EXTENSION vector; senza errori. In caso contrario, assicurati che ServBay abbia PostgreSQL attivo e correttamente installato. I file di pgvector dovrebbero trovarsi nella cartella share/extension di PostgreSQL. Se mancano, reinstalla o aggiorna il pacchetto ServBay PostgreSQL.
• D: Ottengo errori di autenticazione durante la connessione, che fare? R: Controlla che username, password, host e porta nei tuoi comandi o script corrispondano a quelli della configurazione ServBay. Di solito, l’utente locale è servbay o postgres e spesso non serve una password.
• D: Come decido i valori dei parametri lists, m, ef_construction per l’indicizzazione vettoriale? R: Questi parametri condizionano in modo significativo prestazioni e recall. Non esiste un valore unico ottimale: effettua test in base al tuo dataset, alle dimensioni, ai requisiti di latenza e precisione. Troverai suggerimenti dettagliati nella documentazione ufficiale di pgvector.

Conclusioni

pgvector porta le capacità di database vettoriale direttamente su PostgreSQL, offrendo agli sviluppatori un ambiente robusto per lavorare localmente su applicazioni AI e di ricerca su dati vettoriali. ServBay, grazie all’integrazione nativa di pgvector, rende l’impostazione dell’ambiente ancora più semplice.

Seguendo questa guida puoi abilitare pgvector, creare tabelle vettoriali, sfruttare indici avanzati per query rapide e realizzare ricerche di similarità nel tuo database PostgreSQL su ServBay. Integrando tutto con gli altri strumenti di ServBay, hai a disposizione una piattaforma efficiente per progetti web moderni e data-intensive.