Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Basi di dati vettoriali (Pinecone, Qdrant, Weaviate)

Lezione 8 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Perché una base di dati vettoriale?
  3. Pinecone
  4. Qdrant
  5. Weaviate
  6. Chroma e pgvector
  7. Confronto
  8. Punti chiave

Obiettivi

  • Comprendere perché le basi di dati vettoriali sono necessarie
  • Confrontare Pinecone, Qdrant, Weaviate, Chroma e pgvector
  • Implementare la ricerca con ciascuna di esse

Perché una base di dati vettoriale?

L’indice NumPy della lezione precedente funziona perfettamente per alcune migliaia di documenti, poiché una scansione esaustiva di diecimila vettori rimane impercettibile. A un milione, quello stesso calcolo diventa un secondo di latenza per query e la matrice non entra più comodamente in memoria.

Emergono quattro esigenze congiunte. La ricerca ANN (Approximate Nearest Neighbors) abbandona la garanzia di un risultato esatto a favore di una risposta in millisecondi su milioni di vettori: un compromesso quasi sempre accettabile, dato che restituire il quinto documento migliore invece del quarto non cambia nulla per l’esperienza utente. Il filtraggio per metadati, combinato con la ricerca vettoriale, ti permette di limitare una query a una categoria, una lingua o un intervallo di date senza post-elaborazione. La persistenza e gli aggiornamenti in tempo reale evitano di ricostruire un intero file solo per aggiungere un documento. Infine, lo scaling orizzontale è ciò che distingue un prototipo da un servizio di produzione.

Pinecone

Pinecone è un servizio gestito: non devi provisioning server, crei un indice specificandone la dimensione e la metrica, e il resto viene gestito per te. Nota il filtro categorie passato direttamente a query: la ricerca vettoriale e il filtraggio vengono eseguiti insieme, non uno dopo l’altro.

from pinecone import Pinecone
from openai import OpenAI

pc = Pinecone(api_key="your-pinecone-key")
openai_client = OpenAI()

# Create an index
pc.create_index(
    name="my-corpus",
    dimension=3072,
    metric="cosine",
    spec={"serverless": {"cloud": "aws", "region": "eu-west-1"}}
)

index = pc.Index("my-corpus")

# Index documents
documents = [
    {"id": "doc1", "texte": "Python Installation Guide",
     "categorie": "tutorial"},
    {"id": "doc2", "texte": "Deploying a Flask Application",
     "categorie": "tutorial"},
    {"id": "doc3", "texte": "Q1 2026 Quarterly Report",
     "categorie": "report"},
]

# Generate embeddings
textes = [d["texte"] for d in documents]
response = openai_client.embeddings.create(
    input=textes,
    model="text-embedding-3-large"
)

# Upsert into Pinecone
vecteurs = [
    {
        "id": doc["id"],
        "values": emb.embedding,
        "metadata": {"texte": doc["texte"], "categorie": doc["categorie"]}
    }
    for doc, emb in zip(documents, response.data)
]
index.upsert(vectors=vecteurs)

# Search
query_emb = openai_client.embeddings.create(
    input="how to install Python",
    model="text-embedding-3-large"
).data[0].embedding

resultats = index.query(
    vector=query_emb,
    top_k=3,
    include_metadata=True,
    filter={"categorie": {"$eq": "tutorial"}}
)

for match in resultats.matches:
    print(f"[{match.score:.3f}] {match.metadata['texte']}")

La dimensione dichiarata alla creazione è definitiva: passare da text-embedding-3-large a text-embedding-3-small richiede la ricreazione dell’indice. Decidi quindi il modello prima, non dopo.

Qdrant

Qdrant è open source, auto-ospitato e offre prestazioni eccellenti. Il vocabolario differisce: parliamo di collezioni, punti e payload dove Pinecone parla di indici, vettori e metadati, ma lo schema rimane identico. Nota che l’esempio chiama l’API di embedding documento per documento all’interno del ciclo: questo è accettabile per tre documenti, ma pensa di tornare ai batch non appena il corpus cresce.

from qdrant_client import QdrantClient
from qdrant_client.models import (
    Distance, VectorParams, PointStruct, Filter,
    FieldCondition, MatchValue
)
from openai import OpenAI

qclient = QdrantClient(url="http://localhost:6333")
openai_client = OpenAI()

# Create a collection
qclient.create_collection(
    collection_name="my-corpus",
    vectors_config=VectorParams(
        size=3072,
        distance=Distance.COSINE
    )
)

# Index documents
points = []
for i, doc in enumerate(documents):
    emb = openai_client.embeddings.create(
        input=doc["texte"],
        model="text-embedding-3-large"
    ).data[0].embedding

    points.append(PointStruct(
        id=i,
        vector=emb,
        payload={"texte": doc["texte"], "categorie": doc["categorie"]}
    ))

qclient.upsert(collection_name="my-corpus", points=points)

# Search with filter
query_emb = openai_client.embeddings.create(
    input="deploy a web application",
    model="text-embedding-3-large"
).data[0].embedding

resultats = qclient.search(
    collection_name="my-corpus",
    query_vector=query_emb,
    limit=3,
    query_filter=Filter(
        must=[FieldCondition(
            key="categorie",
            match=MatchValue(value="tutorial")
        )]
    )
)

for r in resultats:
    print(f"[{r.score:.3f}] {r.payload['texte']}")

Weaviate

Weaviate si distingue per la sua ricerca ibrida nativa, che rivedremo nella lezione 9. Il suo modello di dati è più strutturato rispetto a quello dei concorrenti: dichiari esplicitamente le proprietà e i loro tipi prima di inserire qualsiasi cosa, avvicinando l’esperienza a quella di un database classico.

import weaviate
from openai import OpenAI

wclient = weaviate.connect_to_local()
openai_client = OpenAI()

# Create a collection
from weaviate.classes.config import Property, DataType

collection = wclient.collections.create(
    name="Document",
    properties=[
        Property(name="texte", data_type=DataType.TEXT),
        Property(name="categorie", data_type=DataType.TEXT),
    ]
)

# Index
for doc in documents:
    emb = openai_client.embeddings.create(
        input=doc["texte"],
        model="text-embedding-3-large"
    ).data[0].embedding

    collection.data.insert(
        properties={"texte": doc["texte"], "categorie": doc["categorie"]},
        vector=emb
    )

# Search
query_emb = openai_client.embeddings.create(
    input="install Python",
    model="text-embedding-3-large"
).data[0].embedding

resultats = collection.query.near_vector(
    near_vector=query_emb,
    limit=3
)

Chroma e pgvector

Chroma punta al prototipaggio: un client persistente puntato su una cartella locale, una collezione creata al volo, nessuna infrastruttura. È l’opzione che ti porta da un indice NumPy a un vero database senza cambiare il tuo ambiente di lavoro.

import chromadb
from openai import OpenAI

chroma = chromadb.PersistentClient(path="./chroma_db")
openai_client = OpenAI()

collection = chroma.get_or_create_collection("my-corpus")

# Index
for doc in documents:
    emb = openai_client.embeddings.create(
        input=doc["texte"],
        model="text-embedding-3-large"
    ).data[0].embedding

    collection.add(
        ids=[doc["id"]],
        embeddings=[emb],
        documents=[doc["texte"]],
        metadatas=[{"categorie": doc["categorie"]}]
    )

# Search
query_emb = openai_client.embeddings.create(
    input="how to install Python",
    model="text-embedding-3-large"
).data[0].embedding

resultats = collection.query(query_embeddings=[query_emb], n_results=3)

pgvector affronta una situazione molto diversa: i tuoi documenti sono già in PostgreSQL, con le loro join, i diritti di accesso e i backup. Piuttosto che introdurre un secondo sistema da sincronizzare, l’estensione aggiunge un tipo vector e operatori di distanza al database esistente. L’operatore <=> calcola la distanza del coseno e l’indice HNSW è ciò che rende la query utilizzabile oltre poche migliaia di righe.

-- pgvector extension
CREATE EXTENSION vector;

CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    texte TEXT,
    categorie TEXT,
    embedding vector(3072)
);

-- HNSW index for performance
CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops);

-- Search for the 5 nearest neighbors
SELECT id, texte, 1 - (embedding <=> $1::vector) AS score
FROM documents
ORDER BY embedding <=> $1::vector
LIMIT 5;

Confronto

CriterioPineconeQdrantWeaviateChromapgvector
TipoGestitoOpen sourceOpen sourceOpen sourceEstensione
HostingCloudSelf-hosted/CloudSelf-hosted/CloudLocale/EmbedPostgreSQL
Ricerca ibrida✅✅✅ Nativa❌Via SQL
Produzione✅✅✅⚠️ Prototipaggio✅
Facilità d’uso✅✅✅✅✅✅✅

La scelta dipende meno dalle prestazioni raw, che nella pratica sono molto vicine, quanto dal tuo contesto: un team che già esegue PostgreSQL ha tutto l’interesse a restare su di esso, un team senza ops sceglierà una soluzione gestita e un team che deve ospitare in Europa per motivi normativi si orienterà verso il self-hosted.

Punti chiave

  • Chroma per il prototipaggio rapido
  • pgvector se hai già PostgreSQL
  • Pinecone per una soluzione gestita, senza infrastruttura
  • Qdrant per il self-hosting ad alte prestazioni
  • Weaviate per la ricerca ibrida nativa