Salvare e cercare gli embedding di Ollama in PostgreSQL con pgvector

Il README di pgvector lo descrive come ricerca per similarità di vettori open source per Postgres. Supporta la ricerca esatta e approssimata dei vicini più prossimi; vettori a precisione singola, a mezza precisione, binari e sparsi; e distanza L2, prodotto interno, distanza del coseno, distanza L1, distanza di Hamming e distanza di Jaccard. Poiché i vettori sono normali colonne di PostgreSQL, hanno anche la conformità ACID, il ripristino a un punto nel tempo e i JOIN.

Per una ricerca nei tuoi documenti, salvi una riga per ogni frammento con il suo testo e il suo vettore, calcoli l'embedding della domanda con lo stesso modello e ordini le righe in base alla loro distanza dal vettore della domanda.

pgvector supporta PostgreSQL 13 e successivi. Il README elenca vari modi per installarlo, tra cui questi:

Una colonna di tipo vector(n) contiene vettori con esattamente n dimensioni, e n deve essere la lunghezza dei vettori del tuo modello di embedding. Un vettore di lunghezza diversa viene rifiutato: quando abbiamo inserito un vettore con 2 dimensioni in una colonna vector(3), PostgreSQL ha restituito "expected 3 dimensions, not 2". all-minilm restituisce 384 dimensioni, quindi la sua colonna è vector(384).

Il README indica che ogni vettore occupa 4 × dimensioni + 8 byte, con ogni elemento a virgola mobile a precisione singola, e consente fino a 16,000 dimensioni in una colonna. Un indice supporta meno dimensioni, come mostrato più avanti. Il tipo halfvec memorizza valori a mezza precisione in 2 × dimensioni + 8 byte.

pgvector legge un vettore come testo tra parentesi quadre, come '[1,2,3]', e il README dice che tutti gli elementi devono essere finiti (niente NaN, Infinity o -Infinity). Ogni array nel campo embeddings di una risposta di /api/embed ha già questa forma, e la risposta mantiene l'ordine dell'input, quindi il primo testo corrisponde al primo vettore.

Il README mostra INSERT per poche righe, INSERT … ON CONFLICT per gli upsert e COPY per il caricamento in blocco. Il convertitore qui sotto abbina i tuoi testi alla risposta e scrive istruzioni INSERT con gli apici escapati. Abbiamo eseguito il suo output con testi contenenti apici, backslash, a capo ed emoji, e sono tornati invariati.

La documentazione di Ollama consiglia la similarità del coseno per la maggior parte dei casi di ricerca semantica e dice che /api/embed restituisce vettori di lunghezza 1. Per tali vettori, la distanza del coseno, la distanza L2 e il prodotto interno ordinano le righe allo stesso modo, perché il quadrato della distanza L2 è 2 meno 2 volte la similarità del coseno. Nel nostro test con all-minilm, le prime tre righe erano le stesse con tutte e tre, e la distanza L2 di 0.931 corrispondeva alla similarità del coseno di 0.566.

Ogni distanza ha il proprio operatore. Una ricerca ordina per l'operatore e prende le prime righe con LIMIT, e un indice viene creato per una classe di operatori.

Senza indice, pgvector esegue una ricerca esatta dei vicini più prossimi, che secondo il README offre un recall perfetto. Un indice approssimato cede un po' di recall in cambio di velocità, e il README avverte che le query possono restituire risultati diversi dopo averne aggiunto uno.

Un indice viene usato solo quando la query ha ORDER BY e LIMIT e l'ORDER BY è l'operatore di distanza stesso in ordine crescente. ORDER BY embedding <=> $1 LIMIT 5 può usare l'indice; ORDER BY 1 - (embedding <=> $1) DESC no. Il README osserva anche che una scansione della tabella può essere più veloce quando la tabella è piccola.

Con HNSW, i risultati sono limitati da hnsw.ef_search, che è 40 per impostazione predefinita. Su una tabella di prova di 200 righe con un indice HNSW, LIMIT 100 ha restituito 40 righe; dopo SET hnsw.ef_search = 100, ne ha restituite 100. Imposta hnsw.ef_search ad almeno il numero di righe che ti servono. SET LOCAL all'interno di una transazione lo cambia per una sola query.

Anche il filtraggio riduce i risultati. Con gli indici approssimati, il README dice che la condizione WHERE viene applicata dopo la scansione dell'indice: se una condizione corrisponde al 10% delle righe, HNSW con il valore predefinito di hnsw.ef_search, 40, restituisce in media solo 4 righe. Dalla versione 0.8.0, le scansioni iterative dell'indice (SET hnsw.iterative_scan = strict_order, oppure relaxed_order) scorrono più parte dell'indice finché non trovano abbastanza righe, fino a hnsw.max_scan_tuples (20,000 per impostazione predefinita).

Quando la ricerca restituisce le righe più vicine, il modello ne ha bisogno nel suo prompt. /api/chat di Ollama accetta un elenco di messaggi, ciascuno con un ruolo (system, user, assistant o tool) e il suo content. Una struttura semplice è un messaggio system con le regole e un messaggio user che elenca le righe, ognuna con un numero, come [1] e [2], seguite dalla domanda. Con i numeri, la risposta può dire quali righe ha usato, e puoi ricondurre ogni numero alla sua riga.

Per ottenere le citazioni in una forma fissa, dai al campo format un JSON Schema con la risposta e un elenco di citazioni, ciascuna con il numero della fonte e un breve testo citato. La pagina di Ollama sugli output strutturati consiglia di scrivere lo schema anche nel prompt e di abbassare la temperatura (temperature), per esempio a 0, per un output più deterministico. In psql, la funzione json_agg raccoglie le righe di una query in un array JSON, che lo strumento qui sotto legge direttamente.

Le regole, le righe e la domanda devono stare tutte nella lunghezza del contesto. La pagina di Ollama sulla lunghezza del contesto indica un valore predefinito di 4k token con meno di 24 GiB di VRAM, e le sue FAQ indicano 4096 token; ollama ps sulla nostra macchina di prova mostrava 4096. num_ctx in options o la variabile d'ambiente OLLAMA_CONTEXT_LENGTH lo cambiano.

Quando il prompt è più lungo, /api/chat per impostazione predefinita non restituisce un errore. Nel codice sorgente di Ollama (0.40.11), il server scarta prima interi messaggi precedenti, mantenendo i messaggi system e l'ultimo messaggio. Se il prompt rimasto è ancora troppo lungo, mantiene i primi token (num_keep, 4 per impostazione predefinita) e la fine del prompt e scarta la parte in mezzo. Nel nostro test con qwen2.5:7b e num_ctx 1024, un prompt di 2,068 token è stato ridotto a 514. Il messaggio system e le prime fonti sono andati persi: con la risposta nella fonte [1], il modello ha risposto con una parola in codice che non era in nessuna fonte, e con la risposta nell'ultima fonte ha risposto correttamente ma senza il numero della fonte che il messaggio system richiedeva. La risposta non conteneva alcun errore; il log del server riportava l'avviso "truncating input prompt".

Il codice sorgente di Ollama ha anche un campo truncate per le richieste di chat, che non è elencato nella pagina di /api/chat. Con "truncate": false, la stessa richiesta ha restituito HTTP 400 con l'errore "request (2068 tokens) exceeds the available context size (1024 tokens), try increasing it". Il campo prompt_eval_count di una risposta è il numero di token del prompt; nel test con il taglio era 514, non 2,068.

Una citazione si può verificare in modo meccanico: il numero deve riferirsi a una fonte che è stata inviata, e il testo citato dovrebbe comparire in quella fonte. Nel nostro test con quattro fonti e qwen2.5:7b, i testi citati nelle risposte in JSON corrispondevano parola per parola alle fonti. Questo non dimostra che la risposta sia giusta: alla domanda sulla dimensione di un vettore a 384 dimensioni, il modello ha citato la regola corretta (4 volte le dimensioni più 8 byte) e ha comunque risposto 1552 byte invece di 1,544.

Guarda anche le risposte senza citazioni. Quando le fonti non contenevano la risposta, il modello una volta ha risposto con le proprie conoscenze senza citazioni, e un'altra volta ha detto di non saperlo ma ha citato comunque una fonte senza attinenza. Se done_reason nella risposta è "length", la risposta è stata interrotta da num_predict e potrebbero mancare le citazioni.

Il README dice che un indice HNSW si costruisce in modo molto più veloce quando il grafo sta in maintenance_work_mem, mostra un avviso quando non ci sta più e avverte di non impostare maintenance_work_mem così alto da esaurire la memoria del server. Come per gli altri indici, è più veloce creare l'indice dopo aver caricato i dati iniziali. Gli indici non devono per forza stare in memoria, ma probabilmente otterrai prestazioni migliori se ci stanno; SELECT pg_size_pretty(pg_relation_size('index_name')) mostra la dimensione di un indice.

Per un insieme di lavoro e indici più piccoli, il README suggerisce halfvec, l'indicizzazione a mezza precisione o la quantizzazione binaria. Se Ollama gira sullo stesso server, PostgreSQL e i modelli condividono la stessa memoria; il nostro articolo su come tenere d'occhio la memoria di Ollama spiega cosa decide quanta ne usano i modelli.