Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Clustering: Raggruppamento Automatico

Lezione 18 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Perché il clustering?
  3. K-Means sugli embedding
  4. Trovare il numero giusto di cluster
  5. HDBSCAN: Clustering senza K
  6. Assegnare automaticamente un nome ai cluster
  7. Pipeline di clustering completa
  8. Punti chiave

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