Classificazione del testo con gli embedding
In questa pagina
Obiettivi
- Classificare il testo senza addestrare un modello
- Implementare la classificazione zero-shot e few-shot utilizzando gli embedding
- Confrontare le prestazioni con un classificatore supervisionato leggero
Classificazione zero-shot
La ricerca semantica trova documenti simili a una query tra migliaia di candidati. La classificazione ribalta questo scenario senza modificarne i meccanismi sottostanti: i tuoi “documenti” diventano ora le tue categorie (cinque o dieci), mentre la “query” è il testo che desideri classificare. L’etichetta il cui embedding è più vicino diventa la previsione. Nessun addestramento, nessun dato annotato, basta una singola chiamata API.
Due dettagli implementativi nel codice qui sotto meritano attenzione. Innanzitutto, il testo e i nomi delle categorie vengono inseriti in un’unica chiamata embeddings.create, riducendo la latenza in proporzione al numero di etichette. In secondo luogo, l’applicazione della funzione softmax ai punteggi di similarità converte i valori grezzi (tipicamente compresi tra 0,3 e 0,5) in probabilità che sommano a 1. Puoi mostrare queste probabilità all’utente o confrontarle con una soglia di confidenza.
from openai import OpenAI
import numpy as np
client = OpenAI()
def classifier_zero_shot(
texte: str,
categories: list[str],
model: str = "text-embedding-3-large"
) -> dict:
"""Classifies text into categories without training."""
# Embeddings for categories
all_inputs = [texte] + categories
response = client.embeddings.create(
input=all_inputs,
model=model
)
embs = [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
texte_emb = np.array(embs[0])
cat_embs = np.array(embs[1:])
# Similarity with each category
scores = cat_embs @ texte_emb
# Softmax to get probabilities
exp_scores = np.exp(scores - np.max(scores))
probas = exp_scores / exp_scores.sum()
resultats = sorted(
zip(categories, probas),
key=lambda x: x[1], reverse=True
)
return {
"prediction": resultats[0][0],
"confiance": float(resultats[0][1]),
"scores": {cat: float(p) for cat, p in resultats}
}
# Usage
texte = "Le cours de l'action a chuté de 15% après l'annonce"
categories = ["Finance", "Sport", "Technologie", "Politique", "Santé"]
resultat = classifier_zero_shot(texte, categories)
print(f"Prédiction : {resultat['prediction']} "
f"({resultat['confiance']:.1%})")
print("Scores :", resultat["scores"])
In questo esempio, “il prezzo delle azioni è crollato del 15% dopo l’annuncio” finisce ovviamente nella categoria Finanza. Questo approccio mostra i suoi limiti quando le categorie sono etichette interne i cui nomi non rivelano nulla sul loro contenuto. Un’etichetta come “P1” o “escalation di livello 2” non porta alcun significato semantico sfruttabile, rendendo la classificazione essenzialmente casuale.
Classificazione few-shot
È esattamente qui che interviene la classificazione few-shot. Invece di rappresentare una categoria tramite il suo nome, la rappresenti tramite il centroide di alcuni esempi reali. La categoria “bug” non è più la parola “bug”, ma la media degli embedding per “l’app si blocca all’avvio”, “errore 500 sulla pagina di login” e “il pulsante non funziona su mobile”. Di solito bastano da tre a cinque esempi per classe e il costo rimane quello di una singola chiamata API, poiché tutti i testi vengono inviati insieme.
def classifier_few_shot(
texte: str,
exemples: dict[str, list[str]],
model: str = "text-embedding-3-large"
) -> dict:
"""Classifies by similarity to labeled examples.
Args:
exemples: {"category": ["example1", "example2", ...]}
"""
# Prepare all texts
tous_textes = [texte]
mapping = []
for cat, txts in exemples.items():
for t in txts:
tous_textes.append(t)
mapping.append(cat)
# Embeddings in a single call
response = client.embeddings.create(
input=tous_textes, model=model
)
embs = [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
texte_emb = np.array(embs[0])
# Average embeddings per category
cat_embeddings = {}
for i, cat in enumerate(mapping):
emb = np.array(embs[i + 1])
if cat not in cat_embeddings:
cat_embeddings[cat] = []
cat_embeddings[cat].append(emb)
cat_moyennes = {
cat: np.mean(embs_list, axis=0)
for cat, embs_list in cat_embeddings.items()
}
# Similarity
scores = {
cat: float(np.dot(texte_emb, emb_moy) /
(np.linalg.norm(texte_emb) * np.linalg.norm(emb_moy)))
for cat, emb_moy in cat_moyennes.items()
}
prediction = max(scores, key=scores.get)
return {"prediction": prediction, "scores": scores}
# Usage
exemples = {
"bug": [
"L'application crash au démarrage",
"Erreur 500 sur la page de connexion",
"Le bouton ne fonctionne pas sur mobile",
],
"feature": [
"Pourriez-vous ajouter un mode sombre ?",
"Il serait utile d'exporter en PDF",
"Suggestion : intégrer un calendrier",
],
"question": [
"Comment changer mon mot de passe ?",
"Où trouver les paramètres de notification ?",
"Quelle est la limite de stockage ?",
],
}
texte = "L'export CSV ne contient pas toutes les colonnes"
resultat = classifier_few_shot(texte, exemples)
print(f"Catégorie : {resultat['prediction']}")
Il ticket di test—“l’esportazione CSV non contiene tutte le colonne”—non include né la parola “bug” né “errore”, ma assomiglia ai tre esempi di malfunzionamento forniti, quindi è lì che viene classificato. Tieni presente che fare la media degli embedding presuppone una categoria omogenea. Se i tuoi esempi per “domanda” mescolano richieste di fatturazione con domande sulle API, il loro centroide cadrà in una terra di nessuno semantica. In tal caso, è meglio suddividere la categoria.
Classificatore supervisionato leggero
Quando disponi di alcune decine di esempi per classe, fare la media diventa uno spreco di informazioni: appiattisce la forma della nuvola di punti. Un classificatore lineare addestrato sugli stessi embedding impara invece un confine decisionale. L’embedding gestisce la comprensione del linguaggio, mentre LogisticRegression traccia semplicemente una linea geometrica in quello spazio. Questo si traduce in tempi di addestramento di pochi secondi su una CPU standard, mentre il fine-tuning di un modello linguistico richiederebbe una GPU.
La cross-validazione a cinque fold non è solo una formalità. Ti fornisce la deviazione standard dell’accuratezza, dandoti un’idea dell’affidabilità della tua stima. Un punteggio di 0,91 ± 0,02 è utilizzabile; 0,91 ± 0,15 segnala un dataset troppo piccolo o sbilanciato.
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import cross_val_score
import numpy as np
def entrainer_classifieur(
textes: list[str],
labels: list[str],
model: str = "text-embedding-3-large"
) -> LogisticRegression:
"""Trains a classifier on embeddings."""
# Generate embeddings
response = client.embeddings.create(
input=textes, model=model
)
X = np.array([d.embedding for d in sorted(response.data, key=lambda x: x.index)])
# Train a classifier
clf = LogisticRegression(max_iter=1000)
# Cross-validation
scores = cross_val_score(clf, X, labels, cv=5)
print(f"Accuracy (5-fold CV) : {scores.mean():.3f} ± {scores.std():.3f}")
# Train on the full dataset
clf.fit(X, labels)
return clf
def predire(clf, texte: str, model: str = "text-embedding-3-large") -> str:
"""Predicts the category of a text."""
emb = client.embeddings.create(
input=texte, model=model
).data[0].embedding
return clf.predict([emb])[0]
Confronto tra gli approcci
| Approccio | Esempi richiesti | Accuratezza | Latenza |
|---|---|---|---|
| Zero-shot | 0 | ~70-80% | 1 chiamata API |
| Few-shot (3-5/classe) | 15-25 | ~80-90% | 1 chiamata API |
| Supervisionato (50+/classe) | 250+ | ~90-95% | 1 chiamata API + inferenza |
Lette in ordine, queste tre righe descrivono una progressione che puoi seguire durante l’intero ciclo di vita del prodotto. Inizia con lo zero-shot il primo giorno, senza alcun dato. Una volta corretti manualmente una ventina di previsioni, riutilizzali come esempi few-shot. Quando il volume di annotazioni supera i cinquanta per classe, addestra il classificatore supervisionato. Tieni presente che la riga “latenza” ti ricorda che anche il modello supervisionato rimane veloce; l’inferenza locale aggiunge un overhead trascurabile rispetto alla chiamata API degli embedding.
Punti chiave
- La classificazione zero-shot confronta il testo con le etichette tramite gli embedding
- Il few-shot utilizza esempi per definire ogni categoria
- Un classificatore supervisionato (LogisticRegression) ottiene le migliori prestazioni
- Inizia con lo zero-shot, poi aggiungi esempi se l’accuratezza è insufficiente