RAG minimo con PostgreSQL, pgvector e un modello locale (Python)
Salvare gli embedding in PostgreSQL con pgvector, cercarli con un indice HNSW e la distanza coseno, e rispondere con un modello Ollama locale che cita le fonti. Testato in CI senza modello.

La retrieval-augmented generation (RAG) è un'idea semplice: prima di interrogare il modello, trovi i passaggi dei tuoi documenti che più probabilmente contengono la risposta e li metti nel prompt. Il modello risponde dal tuo testo invece che a memoria, e può dire quale documento ha usato.
Per cominciare non serve un database vettoriale dedicato. Se usi già PostgreSQL, l'estensione pgvector aggiunge un tipo di colonna vettoriale, operatori di distanza e indici per la ricerca approssimata dei vicini. Documenti, embedding e dati applicativi condividono un solo database, con i suoi backup e i suoi permessi.
Questa guida costruisce il RAG più piccolo che fa comunque le cose per bene: suddivisione in blocchi, embedding da un modello locale, indice HNSW, soglia di distanza e risposta con fonti numerate. Versioni verificate il 31 ottobre 2026: psycopg 3.3.6 e pgvector 0.5.1 (l'adattatore Python) su PyPI, l'immagine Docker pgvector/pgvector:0.8.7-pg18 (pgvector 0.8.7 su PostgreSQL 18) e Ollama 0.40.5 con mxbai-embed-large per gli embedding e llama3.2:1b per le risposte.
Come si incastrano i pezzi
L'indicizzazione gira quando un documento cambia: lo dividi in blocchi, trasformi ogni blocco in un vettore e salvi entrambi. La risposta gira a ogni domanda: calcoli l'embedding della domanda con lo stesso modello, recuperi i blocchi più vicini e li mandi con la domanda a un modello di chat.
| Passo | Chi lo esegue | In questo esempio |
|---|---|---|
| Suddivisione | Il tuo codice | Paragrafi raggruppati in blocchi fino a 1.200 caratteri |
| Embedding | Modello di embedding | mxbai-embed-large tramite POST /api/embed di Ollama |
| Salvataggio e ricerca | PostgreSQL + pgvector | Colonna vector(1024), indice HNSW, distanza coseno <=> |
| Risposta | Modello di chat | llama3.2:1b tramite POST /api/chat di Ollama |
Avviare PostgreSQL con pgvector
Il progetto pgvector pubblica immagini Docker con l'estensione già compilata. Per lavorare in locale:
docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5432:5432 pgvector/pgvector:0.8.7-pg18
pip install "psycopg[binary]==3.3.6" pgvector==0.5.1
ollama pull mxbai-embed-large && ollama pull llama3.2:1b
Creare la tabella e l'indice
L'estensione va attivata una volta per database. L'adattatore Python registra poi il tipo vector in psycopg, così puoi passare i vettori come parametri delle query. L'ordine conta: register_vector cerca il tipo, quindi fallisce se l'estensione non esiste ancora.
import psycopg
from pgvector import Vector
from pgvector.psycopg import register_vector
def connect(dsn: str) -> psycopg.Connection:
conn = psycopg.connect(dsn, autocommit=True)
conn.execute("CREATE EXTENSION IF NOT EXISTS vector")
register_vector(conn) # after CREATE EXTENSION: it looks up the vector type
return conn
def create_schema(conn: psycopg.Connection, dim: int) -> None:
conn.execute(f"""
CREATE TABLE IF NOT EXISTS chunks (
id bigserial PRIMARY KEY,
source text NOT NULL,
content text NOT NULL,
embedding vector({int(dim)}) NOT NULL
)""")
conn.execute("CREATE INDEX IF NOT EXISTS chunks_embedding_idx "
"ON chunks USING hnsw (embedding vector_cosine_ops)")
In queste righe ci sono tre scelte.
La dimensione la decide il modello. mxbai-embed-large restituisce 1024 numeri per testo, quindi la colonna è vector(1024). Se cambi modello di embedding devi creare una nuova colonna e ricalcolare tutto: i vettori di modelli diversi non sono confrontabili.
La distanza si sceglie con la classe di operatori. pgvector offre distanza L2 (<->), prodotto scalare negativo (<#>), distanza coseno (<=>) e distanza L1 (<+>), e un indice serve solo la distanza per cui è stato costruito. Per gli embedding di testo si usa di solito la distanza coseno, che ignora la lunghezza dei vettori e ne confronta solo la direzione: per questo l'indice usa vector_cosine_ops e la query deve usare <=>.
HNSW è approssimato. Senza indice la ricerca è esatta su ogni riga, e per qualche migliaio di blocchi basta. Un indice HNSW è molto più veloce sulle tabelle grandi, ma può perdere una riga che la ricerca esatta avrebbe trovato. I parametri sono m (16 di default) ed ef_construction (64) in costruzione, e hnsw.ef_search (40) in ricerca: valori più alti danno più richiamo e costano velocità. Il tipo vector si può indicizzare fino a 2.000 dimensioni.
Suddividere i documenti e calcolare gli embedding
I modelli di embedding hanno una finestra di contesto piccola: mxbai-embed-large legge 512 token e, di default, Ollama tronca l'input più lungo senza avvisare. Un documento intero quindi non può diventare un solo vettore: va diviso in pezzi che abbiano senso da soli. I paragrafi sono un buon punto di partenza:
def chunk_text(text: str, max_chars: int = 1200) -> list[str]:
"""Split on blank lines, then pack paragraphs into chunks of at most max_chars.
A paragraph longer than max_chars becomes a chunk of its own: split it further if
your embedding model has a small context window."""
chunks, current = [], ""
for para in (p.strip() for p in re.split(r"\n\s*\n", text)):
if not para:
continue
if current and len(current) + 2 + len(para) > max_chars:
chunks.append(current)
current = para
else:
current = f"{current}\n\n{para}" if current else para
if current:
chunks.append(current)
return chunks
1.200 caratteri di inglese sono circa 250-300 token, dentro la finestra di 512. L'italiano e il codice usano più token per carattere (lo mostra la nostra guida su come contare i token), quindi misura.
L'endpoint embed di Ollama accetta una lista di testi in una sola richiesta e restituisce un vettore per testo, nello stesso ordine. Basta una semplice chiamata HTTP:
def ollama_embedder(model: str = EMBED_MODEL, base_url: str = OLLAMA_URL) -> Embedder:
"""Embeddings from Ollama's POST /api/embed (several texts per request)."""
def embed(texts: Sequence[str]) -> list[list[float]]:
return _post_json(f"{base_url}/api/embed", {"model": model, "input": list(texts)})["embeddings"]
return embed
L'indicizzazione di un documento cancella i vecchi blocchi e inserisce i nuovi in un'unica transazione, così una ricerca non vede mai mezzo documento e reindicizzare un file modificato non lascia duplicati:
def index_document(conn: psycopg.Connection, source: str, text: str, embed: Embedder) -> int:
"""Replace the chunks of one document. Returns the number of chunks stored."""
chunks = chunk_text(text)
vectors = embed(chunks)
with conn.transaction():
conn.execute("DELETE FROM chunks WHERE source = %s", (source,))
with conn.cursor() as cur:
cur.executemany(
"INSERT INTO chunks (source, content, embedding) VALUES (%s, %s, %s)",
[(source, c, Vector(v)) for c, v in zip(chunks, vectors)])
return len(chunks)
La chiamata al modello avviene prima della transazione di proposito: un modello lento non deve tenere aperta una transazione del database.
Cercare per distanza coseno
La ricerca calcola l'embedding della domanda con lo stesso modello; la forma ORDER BY embedding <=> %s LIMIT k permette a PostgreSQL di usare l'indice HNSW:
def search(conn: psycopg.Connection, query: str, embed: Embedder, k: int = 4,
query_prefix: str = "") -> list[tuple[str, str, float]]:
"""The k chunks closest to the query by cosine distance (0 = same direction)."""
qvec = Vector(embed([query_prefix + query])[0])
return conn.execute(
"SELECT source, content, embedding <=> %s AS distance "
"FROM chunks ORDER BY embedding <=> %s LIMIT %s",
(qvec, qvec, k)).fetchall()
query_prefix esiste perché alcuni modelli di embedding sono addestrati a trattare in modo diverso domande e documenti. La scheda di mxbai-embed-large mostra le query di ricerca con il prefisso Represent this sentence for searching relevant passages: e i documenti senza prefisso. Leggi la scheda del modello che scegli: sbagliare qui non produce errori, peggiora solo i risultati in silenzio.
Con i tre documenti di esempio del repository (una politica di rimborso, le istruzioni per la VPN e un turno di reperibilità, in inglese), le distanze misurate con mxbai-embed-large sono state:
| Domanda | refunds.md | oncall.md | vpn.md |
|---|---|---|---|
| How long do customers have to ask for a refund? | 0.216 | 0.520 | 0.686 |
| What is the capital of France? | 0.794 | 0.748 | 0.779 |
Il documento giusto si distingue. Conta però anche la seconda riga: una domanda a cui nessun documento risponde ottiene comunque tre blocchi "più vicini". Un vicino più vicino esiste sempre; non è detto che sia pertinente.
Rispondere solo dai passaggi pertinenti
Per questo la fase di risposta scarta i blocchi oltre una soglia di distanza e, se non resta nulla, non chiama proprio il modello. Il prompt numera i passaggi e chiede al modello di citarli:
def build_messages(question: str, hits: list[tuple[str, str, float]]) -> list[dict]:
context = "\n\n".join(f"[{i}] ({src})\n{content}" for i, (src, content, _) in enumerate(hits, 1))
system = ("Answer using only the numbered context passages. Cite them like [1]. "
"If the answer is not in the context, say you don't know.")
return [{"role": "system", "content": system},
{"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"}]
def ask(conn, question: str, embed: Embedder, k: int = 4, max_distance: float = 0.5,
chat_model: str = CHAT_MODEL, base_url: str = OLLAMA_URL, query_prefix: str = "") -> dict:
hits = [h for h in search(conn, question, embed, k, query_prefix) if h[2] <= max_distance]
if not hits:
return {"answer": "I don't know: no relevant passage found.", "sources": []}
res = _post_json(f"{base_url}/api/chat", {"model": chat_model, "stream": False,
"messages": build_messages(question, hits)})
return {"answer": res["message"]["content"], "sources": [h[0] for h in hits]}
La soglia di 0,5 viene dalla tabella qui sopra e vale solo per questo modello e questi documenti. Le distanze di modelli di embedding diversi non sono sulla stessa scala: scegli il valore provando qualche decina di domande reali con risposta nota e guardando dove si separano i blocchi pertinenti da quelli no.
La soglia ha migliorato anche la risposta. Con una soglia più larga, nel prompt finivano tutti e tre i documenti e il modello da 1B rispondeva che il contesto non indicava un termine per il rimborso; con la sola politica di rimborso, ha risposto "Customers can ask for a full refund within 30 days of purchase." Per i modelli piccoli, pochi passaggi buoni valgono più di un contesto lungo. Per mostrare la risposta parola per parola in una pagina web, combina questo esempio con la nostra guida sullo streaming nel browser con SSE.
Testarlo in CI senza modello
I modelli di embedding sono troppo grandi da scaricare a ogni esecuzione della CI. I test usano quindi un PostgreSQL vero con pgvector, ma sostituiscono il modello con un finto modello deterministico: ogni parola viene trasformata con un hash in una di dim posizioni (256 nei test) e il vettore viene normalizzato a lunghezza 1. Testi con parole in comune ottengono vettori simili. Non sa nulla del significato, ma in un test serve proprio questo: risultati identici a ogni esecuzione.
def fake_embedder(dim: int = 1024) -> Embedder:
"""Deterministic test embeddings: hashed bag of words, normalised to length 1.
Texts that share words get similar vectors. Good for tests, useless for real meaning."""
def embed(texts: Sequence[str]) -> list[list[float]]:
out = []
for text in texts:
v = [0.0] * dim
for word in re.findall(r"\w+", text.lower()):
h = int.from_bytes(hashlib.sha256(word.encode()).digest()[:8], "big")
v[h % dim] += 1.0
norm = math.sqrt(sum(x * x for x in v)) or 1.0
out.append([x / norm for x in v])
return out
return embed
L'hash è SHA-256 e non hash() di Python, che cambia da un processo all'altro. In GitHub Actions PostgreSQL gira come container di servizio (pgvector/pgvector:0.8.7-pg18) accanto al job, e un piccolo server HTTP prende il posto di Ollama, così i test controllano anche le richieste esatte inviate a /api/embed e /api/chat:
test_chunking_packs_paragraphs ... ok
test_hnsw_index_exists ... ok
test_no_relevant_passage_skips_the_model ... ok
test_ollama_client_and_ask ... ok
test_reindex_replaces_old_chunks ... ok
test_search_finds_the_right_document ... ok
I vettori "a sacchetto di parole" danno distanze più grandi di un modello vero (0,74 per il risultato migliore invece di 0,22), quindi i test passano un proprio max_distance: la soglia appartiene al modello, non al codice.
Collegare un altro modello di embedding
Il resto del codice ha bisogno solo di una funzione che trasformi una lista di testi in una lista di vettori. Per un altro modello Ollama basta passarne il nome a ollama_embedder; per un'API di embedding in cloud, avvolgi la chiamata all'SDK del fornitore nella stessa firma. In entrambi i casi:
- imposta la colonna alla nuova dimensione e ricalcola tutti i blocchi; non mescolare mai vettori di due modelli nella stessa colonna;
- controlla nella scheda del modello se servono prefissi per query e documenti;
- misura di nuovo la soglia di distanza;
- ricorda che con un'API in cloud i documenti escono dalla tua rete. Se contengono dati personali o segreti, toglili prima di indicizzare; il nostro redattore di log e payload mostra che tipo di dati si nasconde spesso nel testo.
Le chiamate di embedding hanno latenza e limiti: raggruppale, e stima con lo strumento di dimensionamento della capacità API quante richieste contemporanee devono reggere i backend nei momenti di punta.
Limiti di questa versione minima
- Richiamo di HNSW. I risultati possono cambiare dopo aver aggiunto l'indice, e una query con un filtro
WHEREpuò restituire meno dikrighe, perché il filtro si applica dopo la scansione dell'indice. Il README di pgvector descrive le scansioni iterative dell'indice per questo caso. - La suddivisione per paragrafi è un punto di partenza. Tabelle, codice e paragrafi lunghi richiedono regole proprie.
- La ricerca vettoriale perde i termini esatti come i codici di errore; molti sistemi aggiungono la ricerca full-text di PostgreSQL (ricerca ibrida).
- Un modello piccolo può sbagliare anche con il passaggio giusto. Mostra le fonti all'utente e valuta le risposte su un insieme fisso di domande prima di cambiare modello, prompt o soglia.
- Il controllo degli accessi tocca a te. Filtra i blocchi per permesso nella query SQL, prima che il modello li veda.
Il codice completo, i documenti di esempio e i test sono nella cartella dell'esempio e girano in GitHub Actions a ogni modifica.
L'esempio completo e testato di questo articolo è nel nostro repository pubblico: adamant-solutions/ai-dev-examples/rag-pgvector