Nota 03 / Architettura · Ricerca
pgvector con Django: verifica filtri e recall
Il filtro tenant limita i dati visibili. È il piano di esecuzione a determinare se la ricerca ANN trova abbastanza risultati.
Visibilità e qualità sono due domande
PostgreSQL può mantenere metadati, permessi ed embedding nello stesso database. Questo semplifica le relazioni, ma non sostituisce autorizzazione o test della ricerca. Un WHERE su tenant_id limita i dati restituiti; non garantisce che un indice approssimativo trovi abbastanza candidati di quel tenant.
In particolare, l’ordine di filter() e order_by() nel codice Django non impone l’ordine di esecuzione fisica. In questo esempio le due concatenazioni generano la stessa query SQL. PostgreSQL sceglie il piano. Negli indici ANN il filtro viene applicato dopo la scansione dell’indice: i filtri selettivi possono lasciare meno risultati del previsto.
Una query ORM circoscritta
L’esempio usa vettori sintetici a tre dimensioni. Il tenant ricevuto deve essere già autorizzato. Per HNSW attiva scansioni iterative locali a una transazione; serve pgvector dalla versione 0.8.0. Prima della migrazione del modello devi creare l’estensione vector. La lista viene valutata nella transazione, affinché l’impostazione si applichi davvero.
from django.db import models, transaction, connection
from pgvector.django import VectorField, HnswIndex, CosineDistance
class VectorDocument(models.Model):
tenant_id = models.PositiveIntegerField(db_index=True)
embedding = VectorField(dimensions=3)
class Meta:
app_label = "notes_demo"
indexes = [HnswIndex(
name="demo_vector_hnsw", fields=["embedding"],
opclasses=["vector_cosine_ops"])]
def nearest(authorized_tenant_id, query_vector, limit=5):
# Vettori sintetici piccoli per il test funzionale.
if len(query_vector) != 3 or not any(query_vector):
raise ValueError("non-zero three-dimensional vector required")
if limit < 1:
raise ValueError("positive limit required")
with transaction.atomic():
# Vale solo in questa transazione; pgvector dalla versione 0.8.0.
with connection.cursor() as cursor:
cursor.execute("SET LOCAL hnsw.iterative_scan = strict_order")
return list(VectorDocument.objects.filter(
tenant_id=authorized_tenant_id
).order_by(CosineDistance("embedding", query_vector))[:limit])
Cosa dimostra il test locale
Il test usa un container PostgreSQL 16 isolato con pgvector 0.8.6, Django 5.2 e dati sintetici. Crea estensione, tabella e indice HNSW, verifica il risultato nel tenant e confronta l’SQL delle due concatenazioni ORM. Un controllo del piano forza HNSW soltanto nella fixture e verifica l’output della ricerca iterativa. È un test funzionale, non un benchmark di recall o carico.
Verifica il piano, poi scegli l’architettura
Confronta i risultati approssimativi con una ricerca esatta su un campione rappresentativo. Le scansioni iterative restano limitate da soglie di ricerca e memoria: non garantiscono recall completo. Un B-tree sulla colonna di filtro, un indice parziale o il partizionamento possono aiutare secondo la distribuzione dei dati. Molti indici parziali aumentano però il lavoro operativo.
Un database vettoriale separato richiede sincronizzazione, permessi e ripristino aggiuntivi. Decidi sui tuoi dati e sulle tue misure, senza una soglia universale di documenti. Versiona modello di embedding e dimensioni quando cambiano; l’esempio non genera automaticamente embedding durante il salvataggio.