Sentence Transformers : gli embedding in locale

#Cosa è un embedding e cosa fa la libreria

Un modello di embedding trasforma un testo in una lista di numeri, un vettore, in modo che due testi dal significato simile abbiano vettori vicini. La documentazione di Sentence Transformers descrive questi modelli, detti bi-encoder, come modelli che calcolano una rappresentazione di dimensione fissa per un testo, con un calcolo degli embedding spesso efficiente e un calcolo della similarità molto rapido. È il componente di partenza del RAG: si codifica la domanda, si cercano i passaggi i cui vettori sono più vicini e li si fornisce al modello linguistico. Due conseguenze da ricordare: il modello che codifica i documenti deve essere lo stesso che codifica le domande, e la sua nozione di «vicino» deriva dal suo addestramento. Un modello addestrato soprattutto sull'inglese è un giudice poco affidabile del francese.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium.",
]
embeddings = model.encode(sentences)
print(embeddings.shape)  # [3, 384]
similarities = model.similarity(embeddings, embeddings)

Questo modello genera vettori di 384 dimensioni e funge da esempio di partenza, ma è progettato per l'inglese: per un corpus francese, sostituiscilo come indicato più in basso. La libreria colloca automaticamente il modello sul miglior dispositivo disponibile (cuda, mps o cpu) e puoi forzare la scelta con il parametro device.

#Installare e codificare un corpus francese

1. 01
   Installare la libreria

   Usa pip install -U sentence-transformers in un ambiente Python. La versione 6.1.0 è stata pubblicata il 18 settembre 2026 e richiede Python 3.10 o successivo, secondo PyPI.
2. 02
   Scegliere un modello multilingue

   Scegli un modello annunciato come multilingue (vedi la tabella più sotto), non un modello all-*, addestrato per l'inglese.
3. 03
   Codificare i documenti in blocco

   Passa una lista di testi a encode: la libreria li elabora in batch, sfruttando così l'hardware molto meglio rispetto a una chiamata per ogni testo.
4. 04
   Codificare la domanda con lo stesso modello

   Usa lo stesso modello e gli stessi prefissi usati per i documenti, poi confronta con similarity.
5. 05
   Mantenere il nome del modello con l'indice

   Annotalo nei metadati: se cambi modello, dovrai ricodificare tutto il corpus.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("intfloat/multilingual-e5-large")

docs = [
    "Le contrat peut être résilié avec un préavis de trois mois.",
    "La facture est payable à trente jours fin de mois.",
]
question = "Quel est le délai pour mettre fin au contrat ?"

doc_emb = model.encode(docs, prompt="passage: ", normalize_embeddings=True)
q_emb = model.encode(question, prompt="query: ", normalize_embeddings=True)
print(model.similarity(q_emb, doc_emb))

Il prefisso query: per le domande e passage: per i documenti è quello citato nella documentazione di Sentence Transformers per questo modello. Senza di esso, la qualità del recupero peggiora senza alcun messaggio di errore. Il parametro prompt di encode applica il prefisso a ogni testo.

#Scegliere un modello che comprenda il francese

La documentazione propone modelli originali e invita a consultare la classifica MTEB come fonte di ispirazione, con due avvertenze: escludere i modelli troppo grandi per il tuo hardware e sperimentare, perché i modelli ben posizionati in classifica non danno necessariamente buoni risultati sui tuoi compiti. La tabella seguente riporta ciò che la documentazione dice sui modelli citati.

#Errori che rovinano un corpus senza messaggio d'errore

Un modello anglofono su testi in francese

Tutto funziona, ma il recupero è comunque distorto. È l'errore più comune.

Passaggi più lunghi del limite del modello

La documentazione specifica che, dei testi più lunghi, vengono mantenuti soltanto i primi max_seq_length token: la parte finale di ogni passaggio lungo diventa invisibile.

Un modello diverso per documenti e domande

I vettori non parlano più della stessa cosa: risultati anomali, generalmente introdotti aggiornando solo una parte della catena.

Prefissi dimenticati

Alcuni modelli richiedono un prefisso diverso per le domande e i documenti; l'omissione degrada la ricerca.

Vettori non normalizzati con un punteggio inadeguato

Se il modello richiede una similarità coseno, normalizza i vettori o usa la misura corrispondente, altrimenti il ranking si degrada.

#Misurare la vicinanza: normalizzazione e coseno

Due vettori vengono confrontati mediante una misura di similarità, il più delle volte il coseno. La documentazione di Ollama indica che il suo endpoint restituisce vettori normalizzati e consiglia il coseno per la maggior parte delle ricerche semantiche. Con vettori normalizzati, coseno e prodotto scalare danno lo stesso ordinamento, il che consente di utilizzare un indice ottimizzato per il prodotto scalare. L'aspetto da controllare è la coerenza: la misura del database vettoriale deve corrispondere a quella prevista dal modello ed è indicata nella scheda del modello.

Quanto alla lunghezza, la documentazione dà un ordine di grandezza: 512 token per molti modelli di tipo BERT, pari a 300–400 parole in inglese, e 256 token per all-MiniLM-L6-v2. Il francese consuma più token per parola: suddividi i tuoi passaggi mantenendoli al di sotto del limite con un margine, e verifica model.max_seq_length. Puoi ridurlo, ma non aumentarlo oltre quanto il modello supporta. La documentazione aggiunge che un modello addestrato su testi brevi rappresenta meno bene i testi lunghi.

#Indicizzare rapidamente sulla propria macchina

Processore o GPU

Il modello viene eseguito sul miglior dispositivo disponibile. Una GPU accelera l'indicizzazione in massa e fa poca differenza per una singola query.

Precisione ridotta

Su GPU, il passaggio a float16 o bfloat16 accelera l'inferenza con una perdita minima di precisione, secondo la documentazione.

Backend ONNX e OpenVINO

La documentazione indica possibili accelerazioni fino a 2–3 volte, a seconda dell'hardware e del backend; verificale sulla tua macchina.

Più GPU o processi

encode accetta una lista di dispositivi: utile per corpus di grandi dimensioni, meno per quelli piccoli a causa del costo di avvio.

Vettori più compatti

La quantizzazione binaria o a numeri interi dei vettori e i modelli con dimensioni troncabili riducono lo spazio di archiviazione e il costo della ricerca.

Cache e indicizzazione

Non ricodificare i documenti invariati: la chiave della cache si basa sul contenuto, non sul nome del file. Su una macchina che serve anche un modello linguistico, esegui l'indicizzazione quando nessuno lo sta usando.

#Quanto pesa un indice di vettori

La dimensione di un indice si calcola moltiplicando il numero di vettori per la loro dimensione e per quattro byte se i numeri sono in float32. Un vettore di 384 dimensioni occupa 1.536 byte: un milione di passaggi rappresenta circa 1,5 GB. A 1.024 dimensioni, lo stesso milione occupa circa 4 GB. Questi valori escludono i metadati e le strutture di indicizzazione del database vettoriale. La scelta del modello ha quindi un'incidenza diretta sulla memoria RAM necessaria alla ricerca, e la quantizzazione dei vettori menzionata in precedenza può ridurre questa occupazione di memoria.

#Sentence Transformers o l'API di embedding di Ollama

Ollama offre anche degli embedding: la documentazione indica che il comando ollama run peut genera vettori e che l'endpoint api/embed restituisce vettori normalizzati in L2. Consiglia i modelli embeddinggemma, qwen3-embedding e all-minilm, con vettori tipicamente di 384 a 1.024 dimensioni, e ricorda due regole: coseno per la maggior parte delle ricerche, e modello identico per l'indexazione e la query.

#L'embedding è solo un primo filtro

La documentazione di Sentence Transformers descrive il bi-encoder come la prima fase di una ricerca in due fasi, in cui un cross-encoder, o reranker, riordina i migliori risultati. Il cross-encoder legge insieme la domanda e ciascun passaggio: è più lento, ma più preciso su un numero limitato di candidati. Recuperare una ventina di passaggi in base alla similarità, poi riordinarli per conservarne solo alcuni, è uno dei miglioramenti meno costosi di una pipeline RAG. La guida dedicata al reranker ne illustra nel dettaglio l’implementazione; misura il beneficio sulle tue venti domande prima di mantenerlo, perché aggiunge latenza a ogni richiesta, un secondo modello da mantenere e un consumo di memoria aggiuntivo.

Una buona abitudine, prima ancora di confrontare i modelli, è esaminare ciò che contiene il tuo corpus: frasi brevi e autonome o lunghi paragrafi tecnici? Domande formulate come parole chiave o frasi intere? La risposta orienta la scelta del limite di lunghezza, della segmentazione e del modello. Un corpus giuridico denso non richiede le stesse impostazioni di una raccolta di domande e risposte brevi, e nessuna classifica pubblica può saperlo al posto tuo.

#Valuta la scelta del modello prima di indicizzare

1. 01
   Scrivere venti domande reali

   Scegli domande che i tuoi utenti porranno, formulate con le loro parole, non con quelle del documento.
2. 02
   Annotare il passaggio atteso

   Per ogni domanda, identifica il passaggio o i passaggi che contengono la risposta.
3. 03
   Confrontare due o tre modelli

   Codifica lo stesso corpus con ogni modello e osserva se il passaggio corretto appare tra i primi cinque risultati.
4. 04
   Rieseguire a ogni modifica

   Modello, suddivisione o prefisso modificati: esegui di nuovo questo breve test prima di reindicizzare.

#FAQ

#Per approfondire

• I migliori modelli di embedding per il francese
• BGE-M3: embedding che parlano davvero francese
• Aggiungere un reranker alla propria pipeline
• Strategie di chunking
• Qdrant: il database vettoriale di un RAG locale
• RAG locale: introduzione

• Fonte: Sentence Transformers, avvio rapido
• Fonte: Sentence Transformers, calcolo degli embedding
• Fonte: Sentence Transformers, modelli preaddestrati
• Fonte: Ollama, embedding