Clustering: Raggruppamento Automatico
In questa pagina
Obiettivi
- Raggruppare testi per tema senza etichette predefinite
- Utilizzare K-Means e HDBSCAN sugli embedding
- Assegnare automaticamente un nome ai cluster
Perché il clustering?
La lezione sulla classificazione presumeva che tu conoscessi già le categorie esistenti. Il clustering affronta la situazione opposta, che è anche la più comune quando si esplora un corpus: nessuno sa cosa contenga. Recuperi ottomila verbatim da un sondaggio di soddisfazione o sei mesi di ticket di supporto, e la prima domanda non è “quanti bug ci sono”, ma “di cosa stanno parlando effettivamente le persone”. Il clustering scopre gruppi tematici senza ricevere alcuna informazione preliminare.
Tre casi d’uso ricorrono costantemente: analizzare migliaia di feedback clienti per estrarre modelli dominanti, identificare argomenti ricorrenti nei ticket di supporto per popolare una knowledge base ed esplorare un corpus di documenti sconosciuto prima di decidere come indicizzarlo.
K-Means sugli embedding
K-Means è l’algoritmo di riferimento: gli fornisci un numero di gruppi, lui posiziona altrettanti centri e sposta iterativamente ogni centro verso la media dei punti che attrae. Applicato agli embedding invece che a un bag of words, raggruppa per significato: “l’app crasha all’avvio” e “impossibile accedere da ieri” finiscono insieme anche se non condividono nessuna parola.
Il corpus di esempio sottostante contiene intenzionalmente quattro famiglie—bug, richieste di funzionalità, domande e complimenti—così puoi verificare visivamente il raggruppamento risultante. L’impostazione random_state=42 garantisce di ottenere gli stessi cluster da un’esecuzione all’altra, cosa essenziale ogni volta che devi confrontare due configurazioni.
from openai import OpenAI
from sklearn.cluster import KMeans
import numpy as np
client = OpenAI()
# Example corpus
textes = [
"L'application crash au démarrage sur Android",
"Bug : impossible de se connecter depuis hier",
"Le bouton de validation ne fonctionne pas",
"Pourriez-vous ajouter un export Excel ?",
"Suggestion : un mode hors-ligne serait utile",
"Feature request : intégrer Slack",
"Comment changer mon adresse email ?",
"Où trouver ma facture de janvier ?",
"Quel est le prix de l'abonnement annuel ?",
"Votre produit est excellent, bravo !",
"Merci pour le support réactif",
"Je recommande vivement cette application",
]
# Generate embeddings
response = client.embeddings.create(
input=textes,
model="text-embedding-3-large"
)
embeddings = np.array(
[d.embedding for d in sorted(response.data, key=lambda x: x.index)]
)
# K-Means clustering
n_clusters = 4
kmeans = KMeans(n_clusters=n_clusters, random_state=42, n_init=10)
labels = kmeans.fit_predict(embeddings)
# Display clusters
for cluster_id in range(n_clusters):
print(f"\n--- Cluster {cluster_id} ---")
indices = [i for i, l in enumerate(labels) if l == cluster_id]
for idx in indices:
print(f" {textes[idx]}")
Trovare il numero giusto di cluster
Con dodici frasi preparate, scegliere quattro era ovvio. Con ottomila verbatim, nessuno conosce il valore corretto. Due metriche ti aiutano a indovinare. L’inerzia, ovvero la dispersione residua all’interno dei gruppi, diminuisce meccanicamente man mano che aggiungi cluster: cerchi il “gomito”, il punto oltre il quale non scende più significativamente. Lo silhouette score è più decisivo perché misura qualcos’altro: quanto ogni punto è più vicino al proprio gruppo rispetto al gruppo vicino più prossimo. A differenza dell’inerzia, ha un massimo, e quel massimo indica direttamente un valore candidato.
from sklearn.metrics import silhouette_score
import matplotlib.pyplot as plt
inertias = []
silhouettes = []
K_range = range(2, 10)
for k in K_range:
km = KMeans(n_clusters=k, random_state=42, n_init=10)
km.fit(embeddings)
inertias.append(km.inertia_)
silhouettes.append(silhouette_score(embeddings, km.labels_))
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 5))
ax1.plot(K_range, inertias, "bo-")
ax1.set_xlabel("Number of clusters")
ax1.set_ylabel("Inertia")
ax1.set_title("Elbow method")
ax2.plot(K_range, silhouettes, "ro-")
ax2.set_xlabel("Number of clusters")
ax2.set_ylabel("Silhouette score")
ax2.set_title("Silhouette score")
plt.tight_layout()
plt.savefig("choix_k.png", dpi=150)
plt.show()
meilleur_k = K_range[np.argmax(silhouettes)]
print(f"Best k according to silhouette: {meilleur_k}")
HDBSCAN: Clustering senza K
K-Means soffre di un difetto strutturale sui dati del mondo reale: deve assegnare ogni punto a un cluster. Un verbatim isolato che non assomiglia a nient’altro finisce forzatamente attaccato al gruppo meno distante, dove inquina l’interpretazione. HDBSCAN ragiona in termini di densità e accetta di dire no: determina da sé il numero di gruppi e colloca i punti isolati in una categoria separata etichettata come -1.
Questi outlier non sono spazzatura. In un corpus di ticket, sono spesso incidenti rari, richieste fuori scope o segnali deboli—esattamente ciò che merita una revisione umana. Il codice sottostante li visualizza separatamente invece di scartarli.
import hdbscan
clusterer = hdbscan.HDBSCAN(
min_cluster_size=3,
min_samples=2,
metric="euclidean"
)
labels_hdbscan = clusterer.fit_predict(embeddings)
n_clusters = len(set(labels_hdbscan)) - (1 if -1 in labels_hdbscan else 0)
n_outliers = list(labels_hdbscan).count(-1)
print(f"Clusters found: {n_clusters}")
print(f"Outliers: {n_outliers}")
for cluster_id in range(n_clusters):
print(f"\n--- Cluster {cluster_id} ---")
indices = [i for i, l in enumerate(labels_hdbscan) if l == cluster_id]
for idx in indices:
print(f" {textes[idx]}")
if n_outliers > 0:
print("\n--- Outliers ---")
for i, l in enumerate(labels_hdbscan):
if l == -1:
print(f" {textes[i]}")
Assegnare automaticamente un nome ai cluster
Un algoritmo di clustering ti fornisce numeri. “Cluster 2” non ha posto in un report o in una dashboard. Il passaggio che rende il risultato utilizzabile consiste nel sottomettere una dozzina di membri rappresentativi all’LLM e chiedergli un nome breve: “Problemi di Connessione”, “Richieste di Integrazione”, “Domande sulla Fatturazione”. Limitarsi a dieci esempi controlla i costi, impostare la temperatura a zero assicura che lo stesso cluster riceva sempre lo stesso nome, e il ciclo ignora l’etichetta -1 poiché gli outlier, per definizione, non hanno un tema comune.
def nommer_clusters(
textes: list[str],
labels: list[int]
) -> dict[int, str]:
"""Names each cluster using an LLM."""
noms = {}
clusters = set(l for l in labels if l >= 0)
for cluster_id in clusters:
exemples = [
textes[i] for i, l in enumerate(labels)
if l == cluster_id
][:10] # Max 10 examples
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[{
"role": "user",
"content": (
f"Voici des textes regroupés dans un même cluster :\n\n"
+ "\n".join(f"- {e}" for e in exemples) +
f"\n\nDonne un nom court (2-4 mots) qui décrit "
f"le thème commun de ce groupe. "
f"Retourne uniquement le nom."
)
}],
temperature=0,
max_tokens=20
)
noms[cluster_id] = response.choices[0].message.content.strip()
return noms
# Usage
noms = nommer_clusters(textes, labels)
for cluster_id, nom in noms.items():
print(f"Cluster {cluster_id}: {nom}")
indices = [i for i, l in enumerate(labels) if l == cluster_id]
for idx in indices:
print(f" - {textes[idx]}")
Pipeline di clustering completa
I tre passaggi—embedding, clustering, assegnazione nomi—si uniscono naturalmente in un’unica classe. Il parametro methode accetta "auto", che delega la scelta del numero di gruppi a HDBSCAN, oppure un valore numerico passato come stringa quando vuoi imporre una K a K-Means. Il dizionario restituito contiene le etichette, i nomi leggibili e due contatori che ti dicono immediatamente se il risultato vale la pena di essere utilizzato: un n_outliers vicino al totale significa che il tuo corpus manca di struttura densa e dovresti tornare a K-Means.
class PipelineClustering:
def __init__(self, model: str = "text-embedding-3-large"):
self.client = OpenAI()
self.model = model
def analyser(self, textes: list[str], methode: str = "auto") -> dict:
"""Complete pipeline: embedding → clustering → naming."""
# 1. Embeddings
response = self.client.embeddings.create(
input=textes, model=self.model
)
embs = np.array([
d.embedding for d in sorted(response.data, key=lambda x: x.index)
])
# 2. Clustering
if methode == "auto":
clusterer = hdbscan.HDBSCAN(min_cluster_size=3)
labels = clusterer.fit_predict(embs)
else:
km = KMeans(n_clusters=int(methode), random_state=42)
labels = km.fit_predict(embs)
# 3. Name clusters
noms = nommer_clusters(textes, labels)
return {
"labels": labels.tolist(),
"noms": noms,
"n_clusters": len(set(l for l in labels if l >= 0)),
"n_outliers": list(labels).count(-1)
}
pipeline = PipelineClustering()
resultats = pipeline.analyser(textes)
Punti chiave
- Usa K-Means quando conosci il numero di cluster
- Usa HDBSCAN per rilevare automaticamente gruppi e outlier
- Lo silhouette score aiuta a scegliere la K corretta
- Un LLM assegna automaticamente un nome ai cluster scoperti
- Gli embedding rendono il clustering semantico, non solo lessicale