Weaviate: ricerca ibrida e multi-location

#Cosa distingue Weaviate dagli altri database vettoriali

Weaviate è un database vettoriale open source, il cui codice è pubblicato su GitHub. A differenza di librerie come FAISS, è un server: memorizza gli oggetti (testo e proprietà), i vettori e l'indice di ricerca, e risponde a richieste tramite API. Tre funzioni lo distinguono da un semplice archivio di vettori. La prima è la codifica integrata: inserisci oggetti, un modulo configurato trasforma il testo in vettori e le query si scrivono in linguaggio naturale anziché come array di numeri in virgola mobile. Questa scelta elimina una classe di bug (dimensioni incompatibili, domanda codificata con un modello diverso da quello usato per il corpus), poiché lo stesso modulo gestisce entrambi i lati.

La seconda è la ricerca ibrida, che combina parole chiave e vettori in un’unica query. La terza è la multi-tenancy: uno stesso deployment può ospitare più set di dati isolati, uno per cliente, servizio o utente. Il prezzo di queste funzionalità è un componente da mantenere in esecuzione, con la memoria che richiede, i suoi backup e i suoi aggiornamenti, mentre ChromaDB in modalità file è soltanto una libreria Python.

#Mantenere tutto in locale: tre impostazioni da verificare

Un modulo di codifica è una dipendenza che viene eseguita in un luogo preciso. Scegliere un vettorizzatore ospitato da terzi significa inviare altrove ogni tuo documento e ogni tua domanda; scegliere il modulo Ollama mantiene il calcolo sul tuo hardware. Altre due impostazioni sono meno visibili e meritano la stessa attenzione.

Il vettorizzatore

Usa text2vec-ollama, che chiama la tua istanza Ollama locale; la documentazione indica che non richiede nessuna chiave API in questo caso. Attenzione all'indirizzo: se Weaviate è in un container e Ollama sulla macchina host, la documentazione consiglia host.docker.internal perché il container raggiunga l'host.

La telemetria

La documentazione di Weaviate indica che raccoglie per impostazione predefinita dati di telemetria: versione del server, sistema operativo, moduli utilizzati, numero di oggetti e di collezioni, inviati ogni 24 ore; precisa che non viene raccolto alcun contenuto dei tuoi dati. Per disattivare la telemetria, imposta la variabile DISABLE_TELEMETRY su true. In un'installazione che deve restare completamente isolata, impostala.

Accesso anonimo

Il comando docker run per l'avvio rapido imposta AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED a true, e la documentazione sconsiglia vivamente l'accesso anonimo al di fuori dello sviluppo o della valutazione. Non appena la porta 8080 è raggiungibile da qualcosa di diverso dal tuo computer, attiva l'autenticazione tramite chiave API.

#Installa Weaviate con Docker e Ollama

1. 01
   Avere Ollama e un modello di embedding

   Installa Ollama e ottieni il modello con ollama pull bge-m3.
2. 02
   Scrivere il file docker-compose.yml

   Definisce il container Weaviate, il suo volume di dati, l'attivazione del modulo Ollama, la disattivazione della telemetria e l'accesso all'host.
3. 03
   Avviare e verificare

   Avvia docker compose up -d, poi prova l'indirizzo http://localhost:8080/v1/meta: la risposta elenca i moduli attivi.
4. 04
   Creare una collezione collegata al modulo

   La collezione indica quale modello Ollama vettorizza quali proprietà.

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.7
    ports:
      - "8080:8080"
      - "50051:50051"
    volumes:
      - weaviate_data:/var/lib/weaviate
    restart: on-failure:0
    extra_hosts:
      - "host.docker.internal:host-gateway"   # utile sous Linux pour joindre Ollama sur l'hôte
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'   # à fermer si le port est exposé
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      ENABLE_MODULES: 'text2vec-ollama'
      DISABLE_TELEMETRY: 'true'
      CLUSTER_HOSTNAME: 'node1'
volumes:
  weaviate_data:

Il numero di versione 1.39.7 è quello della documentazione ufficiale di Weaviate alla data di redazione; usa la versione corrente indicata nella pagina di installazione. Le porte 8080 (HTTP) e 50051 (gRPC) sono quelle della guida introduttiva della documentazione.

#Lo schema: collezioni, proprietà, vettorizzatore, tenant

import weaviate
from weaviate.classes.config import Configure, Property, DataType

client = weaviate.connect_to_local()

client.collections.create(
    "Document",
    vector_config=[
        Configure.Vectors.text2vec_ollama(
            name="contenu_vecteur",
            source_properties=["contenu"],
            api_endpoint="http://host.docker.internal:11434",
            model="bge-m3",
        )
    ],
    properties=[
        Property(name="contenu", data_type=DataType.TEXT),
        Property(name="source", data_type=DataType.TEXT),
    ],
)

coll = client.collections.use("Document")
coll.data.insert_many([
    {"contenu": "Le délai de préavis est de trois mois.", "source": "contrat.pdf"},
    {"contenu": "Le loyer est révisé chaque année au 1er janvier.", "source": "bail.pdf"},
])
client.close()

La struttura segue la documentazione ufficiale: vector_config, un vettorizzatore con un nome, proprietà sorgente e un endpoint Ollama. Weaviate vettorizza per impostazione predefinita le proprietà di tipo testo, ordinate alfabeticamente e poi concatenate; source_properties permette di limitare il calcolo alla proprietà utile e di escludere il nome del file dal vettore.

#La ricerca ibrida in Weaviate

La ricerca semantica trova passaggi dal significato simile e fallisce sulle stringhe esatte: un numero di fattura, un codice di un componente, un codice di errore, un nome proprio. La ricerca ibrida di Weaviate combina i risultati di una ricerca vettoriale e di una ricerca per parole chiave BM25F, fondendo i due insiemi di risultati con pesi e un metodo di fusione configurabili. Il parametro alpha regola l'equilibrio: secondo la documentazione, 1 corrisponde a una ricerca puramente vettoriale e 0 a una ricerca puramente per parole chiave. Senza alpha, il peso effettivo dipende dal client che usi: impostalo sempre esplicitamente.

coll = client.collections.use("Document")
res = coll.query.hybrid(query="préavis contrat CDI", alpha=0.5, limit=5)
for o in res.objects:
    print(o.properties["source"], o.properties["contenu"][:80])

Dalla versione 1.24, il metodo di fusione predefinito è la fusione basata sui punteggi relativi; l'alternativa è la fusione basata sui ranghi. Il principio e la scelta tra i due metodi sono spiegati nella guida sulla ricerca ibrida. Su un corpus tecnico, è spesso la differenza tra un sistema di cui ci si fida e un sistema che si abbandona: i fallimenti della ricerca puramente vettoriale riguardano proprio le ricerche che gli utenti considerano banali.

#Multi-tenancy: un tenant per gruppo di utenti

La multi-tenancy suddivide una collezione in frammenti, uno per tenant. La documentazione la descrive così: ogni tenant è memorizzato in un frammento separato e i dati di un tenant non sono visibili agli altri. È disattivata per impostazione predefinita e si attiva nella definizione della collezione con multi_tenancy_config. Se diversi gruppi interrogano lo stesso sistema (clienti di una PMI, reparti di un'azienda, membri di una famiglia), è una risposta strutturale alla domanda «questa persona può recuperare questo documento?», molto più sicura di un filtro applicato a posteriori e infinitamente più sicura di un'istruzione nel prompt.

from weaviate.classes.config import Configure
from weaviate.classes.tenants import Tenant

client.collections.create(
    "DocumentClient",
    multi_tenancy_config=Configure.multi_tenancy(enabled=True),
)
coll = client.collections.use("DocumentClient")
coll.tenants.create([Tenant(name="client_a"), Tenant(name="client_b")])

# Toute requête passe par un tenant : les autres restent invisibles
res = coll.with_tenant("client_a").query.hybrid(query="préavis", limit=3)

I tenant sono leggeri: la documentazione indica che si possono avere 50.000 frammenti attivi o più per nodo. Hanno uno stato (ACTIVE, INACTIVE, OFFLOADED): un tenant inattivo è su disco e non occupa memoria, il che permette di ospitare molti piccoli set di dati mantenendo attivi solo quelli in uso. Il nome di un tenant accetta solo caratteri alfanumerici, il trattino basso e il trattino.

#Quanto costa far funzionare Weaviate

Weaviate è un vero e proprio servizio: un container, storage persistente e memoria proporzionale ai tuoi vettori. La documentazione sul dimensionamento chiarisce il vincolo: l'indice HNSW deve risiedere in memoria; la memoria determina la dimensione massima del dataset e non influenza direttamente la velocità delle query. La regola empirica indicata nella documentazione è di prevedere il doppio della memoria occupata da tutti i vettori.

empreinte d'un vecteur = dimensions × 4 octets (float32)
mémoire estimée   = 2 × nombre de vecteurs × empreinte d'un vecteur

Exemple, bge-m3 (1 024 dimensions) :
  1 024 × 4 = 4 096 octets par vecteur
  100 000 passages → 2 × 100 000 × 4 096 ≈ 0,8 Go
  1 000 000 passages → 2 × 1 000 000 × 4 096 ≈ 8,2 Go

Le 1 024 dimensioni di bge-m3 sono qui un'ipotesi da verificare nella scheda del tuo modello. Per un corpus personale o di una PMI (qualche decina di migliaia di passaggi), la memoria occupata dall'indice è ridotta; diventa un aspetto da considerare a partire da diversi milioni di passaggi. Weaviate offre la compressione dei vettori: la documentazione raccomanda la quantizzazione rotazionale (RQ) e cita anche la quantizzazione di prodotto (PQ), binaria (BQ) e scalare (SQ), al prezzo di una lieve perdita di informazione. Aggiungi il modulo di codifica locale: Ollama esegue un modello di embedding sulla stessa macchina del tuo modello linguistico. Su una sola macchina, decidi quale dei due occupa la scheda grafica, oppure accetta che l'indicizzazione e l'inferenza si ostacolino a vicenda.

#Fornire i propri vettori o migrare da ChromaDB

Il modulo di codifica non è obbligatorio. La documentazione di Weaviate descrive l'approccio «bring your own vectors»: invece di lasciare che il database calcoli gli embedding, fornisci quelli che hai già, siano essi personalizzati o pregenerati. Nel client Python si dichiara quindi un vettore con nome tramite Configure.Vectors.self_provided. È il modo più economico per migrare da ChromaDB: rileggi i documenti e i vettori già calcolati (Chroma può restituirli con l'opzione include), poi li invii a Weaviate senza richiamare il modello di embedding. Due verifiche evitano brutte sorprese: la dimensione dei vettori deve essere la stessa in tutta la collezione e le domande devono essere codificate con il modello originale, perché Weaviate non lo farà al posto tuo.

Quando conviene preferire la codifica integrata? Se vuoi scrivere le query direttamente in formato testuale, aggiungere documenti senza dover scrivere codice per il calcolo e avere la coerenza del modello garantita dalla configurazione. Quando conviene preferire i tuoi vettori? Se hai già una pipeline di embedding, se devi usare un modello che nessun modulo offre o se vuoi poter cambiare database vettoriale senza ricalcolare tutto.

#Weaviate o un altro database vettoriale

Se sei indeciso, inizia con la soluzione più semplice: ChromaDB per un prototipo, poi passa a un servizio quando emerge un'esigenza specifica (isolamento, supporto ibrido nativo, volume dei dati). La scelta è reversibile finché conservi i documenti sorgente e lo script di indicizzazione.

#Domande frequenti su Weaviate

• Ricerca ibrida: BM25 + vettoriale
• Qdrant: il database vettoriale di un RAG locale
• pgvector: la ricerca vettoriale in PostgreSQL
• FAISS: la libreria dietro la ricerca vettoriale
• RAG locale con ChromaDB e Ollama

• Fonte: Weaviate, ricerca ibrida
• Fonte: Weaviate, modulo Ollama
• Fonte: Weaviate, telemetria
• Fonte: Weaviate, risorse e memoria