Fine-tuning degli embedding
In questa pagina
Obiettivi
- Capire quando è necessario il fine-tuning degli embedding
- Preparare un dataset di coppie per l’addestramento
- Implementare il fine-tuning con adattatori leggeri
Quando fare il fine-tuning?
Cominciamo con la cattiva notizia, che in realtà è buona: nella maggior parte dei casi, i modelli di embedding pre-addestrati funzionano perfettamente e il fine-tuning è uno spreco di energie. Solo tre situazioni lo giustificano davvero. La prima è un dominio con un vocabolario altamente specializzato—medicina, diritto, industria—dove il modello generico non sa che “MI” e “infarto miocardico” si riferiscono alla stessa cosa. La seconda è il raggiungimento di un plateau: hai ottimizzato il chunking, aggiunto la ricerca ibrida e il reranking, ma le metriche non si muovono. La terza è semplicemente avere a disposizione coppie di testi annotati, simili o dissimili, che restano inutilizzate nei tuoi log di ricerca.
Al contrario, salta il fine-tuning se hai meno di mille coppie annotate: l’addestramento memorizzerà i tuoi esempi senza generalizzare. Saltalo anche se le prestazioni sono già soddisfacenti: un guadagno di due punti nel recall non vale la manutenzione di un modello extra. E soprattutto, verifica che un chunking migliore o un prompt più efficace non risolvano il problema: è quasi sempre più economico e veloce.
Approccio 1: Adattatore lineare (Matryoshka)
L’approccio più economico lascia intatto il modello di embedding. Lo lasci produrre i suoi vettori, poi addestri sopra un piccolo strato di proiezione che deforma lo spazio per avvicinare ciò che deve essere vicino nel tuo dominio. Il modello di OpenAI rimane una scatola nera chiamata via API; vengono addestrati solo poche centinaia di migliaia di parametri, su CPU, in pochi minuti.
L’addestramento si basa su triplette: una query, un documento che vi risponde e un documento che tratta lo stesso argomento ma non risponde. Guarda gli esempi medici qui sotto: il negativo per “effetti collaterali del paracetamolo” non è un testo sul calcio, ma un testo sul paracetamolo venduto nelle farmacie. Questo si chiama hard negative, ed è ciò che insegna qualcosa al modello: un negativo ovvio non corregge nulla, dato che il modello generico l’ha già classificato correttamente.
import numpy as np
from openai import OpenAI
from sklearn.model_selection import train_test_split
client = OpenAI()
# Dataset di coppie (query, documento_positivo, documento_negativo)
triplets = [
{
"query": "paracetamol side effects",
"positive": "Paracetamol can cause liver disorders...",
"negative": "Paracetamol is available in pharmacies..."
},
{
"query": "children's aspirin dosage",
"positive": "For children aged 6 to 12, the recommended dose...",
"negative": "Aspirin was discovered in the 19th century..."
},
# ... altre triplette
]
def prepare_embeddings(triplets: list[dict]) -> dict:
"""Genera embedding per le triplette."""
all_texts = []
for t in triplets:
all_texts.extend([t["query"], t["positive"], t["negative"]])
response = client.embeddings.create(
input=all_texts,
model="text-embedding-3-large"
)
embs = np.array(
[d.embedding for d in sorted(response.data, key=lambda x: x.index)]
)
n = len(triplets)
return {
"queries": embs[0::3],
"positives": embs[1::3],
"negatives": embs[2::3],
}
L’adattatore stesso è una rete a due strati che proietta le 3.072 dimensioni del modello fino a 256, con una normalizzazione finale affinché i vettori di output rimangano confrontabili tramite similarità del coseno. La funzione di perdita è una triplet margin loss: vale zero non appena la query è più vicina al positivo che al negativo di almeno un margine di 0,2, e penalizza proporzionalmente altrimenti. In altre parole, insegni al modello solo ciò che non ha ancora capito, e l’addestramento si stabilizza naturalmente una volta che le triplette sono ben separate.
import torch
import torch.nn as nn
import torch.optim as optim
class EmbeddingAdapter(nn.Module):
"""Strato di proiezione per adattare gli embedding."""
def __init__(self, input_dim: int = 3072, output_dim: int = 256):
super().__init__()
self.projection = nn.Sequential(
nn.Linear(input_dim, output_dim),
nn.ReLU(),
nn.Linear(output_dim, output_dim),
)
def forward(self, x):
projected = self.projection(x)
return projected / projected.norm(dim=-1, keepdim=True)
def triplet_loss(anchor, positive, negative, margin=0.2):
"""Triplet margin loss."""
dist_pos = 1 - torch.cosine_similarity(anchor, positive)
dist_neg = 1 - torch.cosine_similarity(anchor, negative)
return torch.relu(dist_pos - dist_neg + margin).mean()
def train_adapter(data: dict, epochs: int = 50):
"""Addestra l'adattatore sulle triplette."""
model = EmbeddingAdapter()
optimizer = optim.Adam(model.parameters(), lr=1e-3)
queries = torch.tensor(data["queries"], dtype=torch.float32)
positives = torch.tensor(data["positives"], dtype=torch.float32)
negatives = torch.tensor(data["negatives"], dtype=torch.float32)
for epoch in range(epochs):
optimizer.zero_grad()
q_proj = model(queries)
p_proj = model(positives)
n_proj = model(negatives)
loss = triplet_loss(q_proj, p_proj, n_proj)
loss.backward()
optimizer.step()
if (epoch + 1) % 10 == 0:
print(f"Epoch {epoch + 1}/{epochs}, Loss: {loss.item():.4f}")
return model
# Addestramento
data = prepare_embeddings(triplets)
adapter = train_adapter(data)
# Salvataggio
torch.save(adapter.state_dict(), "medical_adapter.pt")
Un punto operativo da non sottovalutare: il giorno in cui distribuisci questo adattatore, ogni vettore già memorizzato nel tuo database deve passare di nuovo attraverso la proiezione, altrimenti confronteresti vettori provenienti da due spazi diversi. Pianifica una reindicizzazione completa del corpus nel tuo rollout in produzione.
Approccio 2: Fine-tuning con Sentence Transformers
Quando l’adattatore non basta, devi modificare il modello di embedding stesso, il che richiede un modello open che ospiti tu—qui BAAI/bge-large-en-v1.5. Sentence Transformers rende questo accessibile: descrivi gli esempi come coppie di testo con un’etichetta continua, dove 1,0 significa “questi due testi dovrebbero essere vicini” e 0,2 significa “sembrano superficialmente simili, allontanali”. La CosineSimilarityLoss spinge quindi la similarità del coseno calcolata verso l’etichetta fornita.
Tre epoche e cento passi di warmup sono valori conservativi, e per una buona ragione: su un dataset modesto, addestrare troppo a lungo distrugge la conoscenza generale del modello, rendendolo eccellente sui tuoi esempi e mediocre ovunque altro.
from sentence_transformers import (
SentenceTransformer, InputExample, losses
)
from torch.utils.data import DataLoader
# Carica un modello base
model = SentenceTransformer("BAAI/bge-large-en-v1.5")
# Prepara gli esempi di addestramento
train_examples = [
InputExample(
texts=["paracetamol side effects",
"Paracetamol can cause liver disorders"],
label=1.0
),
InputExample(
texts=["paracetamol side effects",
"Paracetamol is sold in pharmacies"],
label=0.2
),
]
train_dataloader = DataLoader(train_examples, shuffle=True, batch_size=16)
train_loss = losses.CosineSimilarityLoss(model)
# Addestramento
model.fit(
train_objectives=[(train_dataloader, train_loss)],
epochs=3,
warmup_steps=100,
output_path="./finetuned_medical_model"
)
# Usa il modello fine-tunato
embeddings = model.encode([
"abdominal pain after taking medication",
"adverse drug effects"
])
Preparazione di un dataset di qualità
Ecco il vero ostacolo: nessuno ha mille coppie annotate pronte all’uso. La soluzione è costruirle da ciò che hai già, ovvero i tuoi documenti. Sottoponi ogni documento all’LLM chiedendo le domande a cui risponde precisamente, e ottieni coppie domanda-documento senza alcuna annotazione manuale. Una temperatura di 0,7 assicura che le tre domande generate per lo stesso documento non siano tre varianti della stessa frase, e lstrip pulisce la numerazione che il modello aggiunge spontaneamente.
def generate_training_pairs(
documents: list[str],
n_per_doc: int = 3
) -> list[dict]:
"""Genera coppie query-documento per l'addestramento."""
pairs = []
for doc in documents:
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[{
"role": "user",
"content": (
f"Here is a document:\n\n{doc[:500]}\n\n"
f"Generate {n_per_doc} questions that this document "
f"answers precisely. One question per line."
)
}],
temperature=0.7
)
questions = response.choices[0].message.content.strip().split("\n")
for q in questions[:n_per_doc]:
q = q.strip().lstrip("0123456789.-) ")
if q:
pairs.append({"query": q, "document": doc})
return pairs
Valutazione del fine-tuning
Un addestramento con perdita decrescente non prova nulla: l’unica domanda che conta è se la ricerca sia migliorata. La funzione qui sotto misura il recall@5 sullo stesso insieme di query, con e senza adattatore, semplicemente passando adapter=None per ottenere la baseline. Sia il corpus che le query passano attraverso la proiezione quando fornita, condizione necessaria affinché entrambi i vettori vivano nello stesso spazio.
Esegui sempre questo confronto prima del deploy. Capita regolarmente che un adattatore addestrato su troppe poche triplette degradi il recall, e senza misurazione distribuiresti una regressione credendo di distribuire un miglioramento.
def evaluate_before_after(
queries: list[str],
relevant_docs: list[list[str]],
corpus: list[str],
adapter=None
):
"""Confronta le prestazioni prima e dopo il fine-tuning."""
resp = client.embeddings.create(
input=corpus, model="text-embedding-3-large"
)
corpus_embs = np.array(
[d.embedding for d in sorted(resp.data, key=lambda x: x.index)]
)
if adapter:
corpus_embs_adapted = adapter(
torch.tensor(corpus_embs, dtype=torch.float32)
).detach().numpy()
else:
corpus_embs_adapted = corpus_embs
recall_scores = []
for query, relevants in zip(queries, relevant_docs):
q_resp = client.embeddings.create(
input=query, model="text-embedding-3-large"
)
q_emb = np.array(q_resp.data[0].embedding)
if adapter:
q_emb = adapter(
torch.tensor(q_emb, dtype=torch.float32).unsqueeze(0)
).detach().numpy()[0]
scores = corpus_embs_adapted @ q_emb
top_5 = set(np.argsort(scores)[-5:])
relevant_ids = set(
i for i, d in enumerate(corpus) if d in relevants
)
recall = len(top_5 & relevant_ids) / len(relevant_ids)
recall_scores.append(recall)
return np.mean(recall_scores)
Punti chiave
- Il fine-tuning degli embedding migliora le prestazioni su domini specializzati
- Un adattatore lineare è il metodo più semplice e spesso sufficiente
- Sentence Transformers consente un fine-tuning più profondo dell’intero modello
- Si raccomanda un minimo di 1.000 coppie annotate
- Valuta sempre prima e dopo per convalidare il guadagno