Guida all'uso dell'estensione pgvector per PostgreSQL in ServBay

pgvector è una potente estensione di terze parti per il database PostgreSQL che aggiunge il tipo di dato vettoriale e metodi di indicizzazione efficienti per vettori—come IVFFlat e HNSW. Questo permette a PostgreSQL di supportare nativamente lo storage vettoriale e la ricerca di similarità, rendendolo ideale per costruire applicazioni di IA, sistemi di raccomandazione, riconoscimento immagini e NLP, dove è necessario gestire dati vettoriali ad alta dimensionalità.

ServBay, un ambiente integrato di sviluppo Web locale, include già PostgreSQL e l’estensione pgvector pronti all’uso, semplificando notevolmente l’attivazione e l’utilizzo di un database vettoriale in locale. Questa guida illustra in dettaglio come utilizzare pgvector in ServBay.

Cos’è pgvector e perché è importante?

In molti scenari moderni, i dati non sono più semplicemente testo strutturato o numeri. Soprattutto con l’ascesa dell’intelligenza artificiale e del machine learning, i dati vengono spesso rappresentati come vettori ad alta dimensione, noti anche come “embeddings”. Questi vettori catturano informazioni o caratteristiche semantiche dei dati, ad esempio le caratteristiche visive di un’immagine, il significato di un testo o le preferenze di un utente.

L’estensione pgvector consente a PostgreSQL di memorizzare direttamente tali vettori e di eseguire efficienti ricerche di similarità vettoriale (note anche come “nearest neighbor search”). Ciò significa che puoi sfruttare il linguaggio SQL per cercare gli elementi più simili a un dato vettore, senza ricorrere a database separati di tipo vettoriale, semplificando di molto lo stack tecnologico.

Prerequisiti

Prima di iniziare a usare pgvector, assicurati di avere i seguenti requisiti:

1. ServBay installato e funzionante su macOS.
2. Il pacchetto PostgreSQL abilitato nella sezione “Packages” di ServBay. Se non è abilitato, accedi all’interfaccia di ServBay, trova PostgreSQL e imposta lo stato su “Attivo”.

Attivare l’estensione pgvector in PostgreSQL di ServBay

ServBay ha già incluso i file dell’estensione pgvector nella directory di installazione di PostgreSQL. Non è necessario scaricare o compilare nulla manualmente. Devi semplicemente attivare l’estensione nel database in cui vuoi utilizzare pgvector.

Ecco i passaggi per abilitare pgvector nel database PostgreSQL in ServBay:

1. Connettersi al database PostgreSQL: Puoi collegarti all’istanza PostgreSQL fornita da ServBay tramite lo strumento da linea di comando psql. Di default, la configurazione di ServBay consente la connessione locale, con utente predefinito che potrebbe essere postgres o servbay e porta 5432. Se la configurazione del tuo ServBay è differente, consulta la documentazione di configurazione database di ServBay.

   Apri il terminale ed esegui il comando seguente (personalizza utente e nome database secondo la tua configurazione):

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

   • -U servbay: specifica l’utente, di solito servbay (o postgres).
   • -d your_database_name: indica il nome del database. Se il database non esiste, dovrai crearlo prima (ad es. CREATE DATABASE servbay_demo_db;).
   • -h localhost: specifica l’host locale.
   • -p 5432: la porta predefinita di PostgreSQL in ServBay.

2. Creare l’estensione vector: Una volta connesso, esegui nel prompt di psql il comando SQL per attivare l’estensione pgvector:

   CREATE EXTENSION vector;

   Se l’estensione risulta già presente, il comando restituirà un messaggio informativo.

3. Verifica dell’installazione: Puoi controllare le estensioni installate con:

   \dx

   Nell’output dovresti vedere l’estensione vector con le relative informazioni di 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 potrebbe variare a seconda dell’integrazione di pgvector su ServBay)

Configurare e utilizzare pgvector

Dopo aver abilitato l’estensione pgvector, puoi iniziare a creare e gestire dati vettoriali nel database.

Creare una tabella con colonne vettoriali

Per prima cosa, crea una tabella dove salvare i tuoi dati vettoriali. pgvector introduce un nuovo tipo di dato: VECTOR(dimensions), dove dimensions indica la dimensionalità del vettore.

Esempio: crea una tabella chiamata embeddings per memorizzare vettori a 3 dimensioni:

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

A questo punto, puoi inserire dei dati vettoriali 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 per rendere più evidenti le query successive

Nota: i valori dei vettori devono essere racchiusi tra parentesi quadre [] e separati da virgole.

Creare un indice vettoriale per migliorare le prestazioni delle query

Per tabelle che contengono un numero elevato di vettori, la creazione di un indice è fondamentale per accelerare le ricerche di similarità. pgvector supporta due principali tipi di indice: IVFFlat e HNSW. La scelta dell’indice dipende dalle tue esigenze specifiche (velocità, tempi di costruzione, memoria, tasso di richiamo, ecc.).

• IVFFlat (Inverted File Index con compressione Flat): adatto a dataset grandi ma dove il tasso di richiamo non deve essere necessariamente perfetto. Costruzione relativamente rapida.
• HNSW (Hierarchical Navigable Small World): offre tipicamente un tasso di richiamo superiore e ricerche più veloci, ma la costruzione richiede più tempo/memoria.

Esempio di creazione di indices IVFFlat e HNSW sulla colonna vector della tabella embeddings:

1. Indice IVFFlat:

   -- Esegui ANALYZE prima di creare l’indice, per raccogliere statistiche
   ANALYZE embeddings;
   
   -- Crea indice IVFFlat
   -- WITH (lists = 100): imposta il numero di liste invertite. Da regolare in base al dataset.
   -- Più alto il valore, più lento l'indicizzazione, ma miglior richiamo (fino a un certo punto).
   -- Si suggerisce lists = sqrt(numero righe).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. Indice HNSW:

   -- Crea indice HNSW
   -- WITH (m = 16, ef_construction = 200): parametri di HNSW.
   -- m: massimo numero di connessioni per nodo (influenza memoria e precisione).
   -- ef_construction: ambito di ricerca nella costruzione (influisce su tempo/memoria/qualità dell’indice).
   -- Adattare questi parametri in base ai dati e alle performance richieste.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Nota: i parametri degli indici (lists, m, ef_construction) impattano sensibilmente prestazioni e richiamo. Per i valori ottimali è necessario sperimentare e conoscere i dati ed i pattern di ricerca. Consulta la documentazione ufficiale di pgvector per dettagli e consigli di tuning.

Eseguire query vettoriali con pgvector

pgvector offre una serie di operatori per calcolare le distanze tra vettori e quindi eseguire ricerche di similarità. I principali operatori di distanza sono:

• <->: Distanza L2 (euclidea). Misura la distanza diretta tra due vettori.
• <#>: Prodotto interno. Relativo alla similarità coseno, utilizzato per valutare la direzione condivisa.
• <=>: Distanza coseno (1 - similarità coseno). Misura la similarità nella direzione dei vettori, ignorando la lunghezza.

Ecco alcuni esempi comuni di query:

Ricerca del vicino più prossimo (Nearest Neighbor Search)

Trova i vettori più simili (minima distanza) rispetto a un vettore dato, usando ORDER BY e limitando il numero di risultati con LIMIT.

1. Cercare i 5 vettori con minor distanza L2 rispetto a [0.2, 0.3, 0.4]:

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

Query di similarità vettoriale (Similarity Search)

Come la ricerca dei vicini, ma con focus sulla visualizzazione del punteggio di similarità.

1. Trovare i 5 vettori più vicini in distanza coseno a [0.2, 0.3, 0.4] (mostrando la distanza):

   SELECT
       id,
       vector,
       -- Calcola la distanza coseno rispetto al vettore cercato
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Ordina in ordine crescente (più simile in alto)
   LIMIT 5;

Visualizzazione dei dati vettoriali (opzionale)

La visualizzazione di dati vettoriali ad alta dimensione aiuta a comprenderne la distribuzione e le eventuali strutture a cluster. Per vettori 2D o 3D si può usare direttamente uno scatter plot; per dimensioni superiori si utilizzano tecniche di riduzione dimensionale (PCA, t-SNE, ecc.) per proiettarli in 2D/3D.

Segue un esempio con Python e la libreria Matplotlib per visualizzare vettori a 3 dimensioni.

1. Preparare l’ambiente Python: Serve un ambiente Python, interno o esterno a ServBay. Se usi il pacchetto Python di ServBay, verifica che sia attivo. Installa anche psycopg2 (driver PostgreSQL) e matplotlib:

   # Se usi il Python di sistema
   pip install psycopg2 matplotlib
   
   # Se usi il Python fornito da ServBay, accedi alla CLI o individua la directory pip
   # /Applications/ServBay/Software/python/bin/pip install psycopg2 matplotlib

   Modifica il percorso di pip in base all’ambiente attivo.

2. Crea lo script Python: Crea un file chiamato, ad esempio, visualize_vectors.py e incolla il seguente codice. Adatta i parametri di connessione (dbname, user, password, host, port) secondo le impostazioni di ServBay.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Import per scatter 3D
   
   # Parametri connessione DB - Modifica secondo ServBay
   db_params = {
       "dbname": "your_database_name", # Sostituisci col nome del tuo database
       "user": "servbay",              # Sostituisci col nome utente PostgreSQL di ServBay
       "password": "",                 # Sostituisci con la password (vuota per connessioni locali)
       "host": "localhost",            # ServBay PostgreSQL tipicamente su localhost
       "port": "5432"                  # Porta predefinita di PostgreSQL su ServBay
   }
   
   conn = None
   cur = None
   
   try:
       # Collegamento a PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Query dei dati vettoriali
       # Nota: psycopg2 normalmente recupera il tipo vector come stringa '[x, y, z]'.
       # Necessario parsing manuale o un driver psycopg2 aggiornato e compatibile.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Parsing della stringa vettore in lista numerica
       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("Nessun dato vettoriale trovato.")
           exit()
   
       # Estrai coordinate
       # Assumendo vettori 3D
       if any(len(v) != 3 for v in vectors):
            print("Attenzione: le dimensioni dei vettori non sono consistenti o non sono 3D. Impossibile visualizzare.")
            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 3D Vettori')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Errore nella connessione/query del database: {e}")
   except Exception as e:
       print(f"Errore generico: {e}")
   finally:
       # Chiudi la connessione
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Esegui lo script: Avvia il file Python da terminale:

   python visualize_vectors.py

   Lo script si connetterà al tuo database PostgreSQL, leggerà i dati vettoriali e mostrerà una finestra con un grafico 3D scatter tramite Matplotlib.

Domande frequenti (FAQ)

• D: Non vedo l’estensione vector nell’output di \dx. Cosa fare? R: Verifica di aver eseguito correttamente CREATE EXTENSION vector; senza errori. Se ancora non compare, controlla che il pacchetto PostgreSQL di ServBay sia installato e attivo. Il file di estensione pgvector deve trovarsi nella sotto-cartella share/extension di PostgreSQL. Se assente, reinstalla o aggiorna PostgreSQL da ServBay.
• D: Errore di autenticazione durante la connessione al database. Come risolvere? R: Controlla che utente, password, host e porta siano corretti sia con psql che nello script Python. Per connessioni locali, l’utente tipico è servbay o postgres e spesso non viene definita una password.
• D: Come scegliere i parametri degli indici vettoriali (lists, m, ef_construction)? R: Questi parametri hanno un impatto significativo su prestazioni e qualità dei risultati. Non esiste un valore universale: sperimenta in base a numero di dati, dimensionalità, esigenze di latenza e richiamo. Consulta la documentazione ufficiale di pgvector per raccomandazioni e linee guida dettagliate.

Conclusioni

pgvector porta la potenza del database vettoriale direttamente in PostgreSQL, una soluzione matura e affidabile, semplificando lo sviluppo di applicazioni AI e legate ai vettori in locale. ServBay rende il processo ancora più immediato offrendo l’estensione già pronta all’uso.

Seguendo questa guida potrai abilitare facilmente pgvector in PostgreSQL su ServBay, creare tabelle per vettori, accelerare le ricerche grazie agli indici, ed eseguire varie tipologie di query di similarità. Sfrutta inoltre gli altri strumenti e ambienti di ServBay per una costruzione e test ancora più efficace delle tue webapp e dei tuoi progetti data-intensive.