Clustering e visualizzazione degli embeddings
Applicherà il clustering k-means a un insieme di embeddings e li visualizzerà in 2D usando UMAP per scoprire i raggruppamenti naturali degli argomenti nei dati.
Clustering e visualizzazione degli embeddings è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.
Perché raggruppare gli embedding?
Quando avete centinaia o migliaia di documenti, spesso desiderate scoprire quali argomenti sono presenti senza dover leggere tutto manualmente. Il clustering degli embedding raggruppa automaticamente i documenti semanticamente simili, rivelando la struttura naturale dei vostri dati.
Tra le applicazioni comuni figurano l'assegnazione automatica di tag ai ticket di supporto, l'individuazione di categorie di contenuti, la ricerca di documenti ridondanti e la comprensione degli argomenti più frequenti nelle richieste degli utenti.
Panoramica del clustering K-means
K-means suddivide n punti dati in k cluster assegnando iterativamente ogni punto al centroide più vicino, quindi ricalcolando i centroidi come media dei punti assegnati. Converge quando le assegnazioni smettono di cambiare.
Per gli embedding, k-means individua i documenti vicini nello spazio degli embedding ad alta dimensionalità, raggruppandoli di fatto in base alla similarità semantica.
from sklearn.cluster import KMeans
import numpy as np
# corpus_embeddings: (n_docs, 1536) — pre-computed
corpus_embeddings = np.random.randn(200, 1536) # placeholder
kmeans = KMeans(n_clusters=5, random_state=42, n_init='auto')
kmeans.fit(corpus_embeddings)
labels = kmeans.labels_
print(f'Cluster assignments: {labels[:10]}')
print(f'Unique clusters: {set(labels)}')Scelta del numero corretto di cluster
Scegliere k, cioè il numero di cluster, è la parte più difficile. Il metodo del gomito rappresenta l'inerzia, ovvero la somma delle distanze quadrate dai centroidi, per diversi valori di k e cerca il punto in cui l'aggiunta di altri cluster smette di ridurre significativamente l'inerzia.
Il silhouette score misura quanto un punto si adatti meglio al proprio cluster rispetto al cluster alternativo più vicino: i punteggi prossimi a 1 sono migliori. Provate valori di k da 3 a 20 e scegliete il punteggio migliore.
from sklearn.cluster import KMeans
from sklearn.metrics import silhouette_score
import numpy as np
corpus_embeddings = np.random.randn(200, 50) # placeholder (50D for speed)
best_k, best_score = 2, -1
for k in range(2, 11):
km = KMeans(n_clusters=k, random_state=42, n_init='auto')
labels = km.fit_predict(corpus_embeddings)
score = silhouette_score(corpus_embeddings, labels, sample_size=100)
print(f'k={k}: silhouette={score:.3f}')
if score > best_score:
best_score, best_k = score, k
print(f'Best k: {best_k}')Assegnazione di etichette ai cluster con un LLM
Dopo il clustering, potete chiedere a un LLM di generare un'etichetta leggibile per ogni cluster, passando al modello alcuni documenti rappresentativi di quel cluster. In questo modo i numeri grezzi dei cluster vengono trasformati automaticamente in nomi di categorie significativi.
from openai import OpenAI
client = OpenAI()
def label_cluster(cluster_docs, n_examples=3):
examples = '\n'.join(f'- {d}' for d in cluster_docs[:n_examples])
prompt = f'Given these documents, provide a 3-word category label:\n{examples}\nLabel:'
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': prompt}],
max_tokens=20
)
return response.choices[0].message.content.strip()
# Example usage:
# cluster_0_docs = [documents[i] for i in range(len(documents)) if labels[i] == 0]
# print(label_cluster(cluster_0_docs))Riduzione della dimensionalità con UMAP
I vettori a 1536 dimensioni non possono essere rappresentati direttamente in un grafico. UMAP (Uniform Manifold Approximation and Projection) riduce i dati ad alta dimensionalità a 2D o 3D, preservando la struttura delle vicinanze locali. A differenza di PCA, UMAP è non lineare e preserva i cluster molto meglio.
UMAP è la scelta standard per visualizzare gli embedding di testo, perché i documenti simili rimangono vicini nel grafico 2D.
import umap
import numpy as np
corpus_embeddings = np.random.randn(200, 1536) # placeholder
reducer = umap.UMAP(
n_components=2,
metric='cosine', # important for text embeddings
random_state=42
)
embeddings_2d = reducer.fit_transform(corpus_embeddings)
print(f'Reduced shape: {embeddings_2d.shape}') # (200, 2)Visualizzazione dei cluster con Matplotlib
Una volta ottenute da UMAP le coordinate 2D e le etichette dei cluster da k-means, un semplice grafico a dispersione rende visibile la struttura dei cluster. Assegnate a ogni punto un colore in base all'etichetta del cluster e aggiungete come annotazioni testuali i titoli dei documenti rappresentativi, così da rendere il grafico interpretabile.
import matplotlib.pyplot as plt
import numpy as np
# Assume: embeddings_2d (n, 2), labels (n,), documents list
# Placeholder data:
np.random.seed(42)
embeddings_2d = np.random.randn(50, 2)
labels = np.random.randint(0, 5, 50)
fig, ax = plt.subplots(figsize=(10, 7))
scatter = ax.scatter(
embeddings_2d[:, 0],
embeddings_2d[:, 1],
c=labels,
cmap='tab10',
s=60,
alpha=0.8
)
plt.colorbar(scatter, label='Cluster')
ax.set_title('Document Embedding Clusters (UMAP)')
plt.tight_layout()
plt.savefig('/tmp/clusters.png', dpi=150)
print('Saved cluster plot')Parametri UMAP importanti
Principali iperparametri di UMAP che influenzano la qualità della visualizzazione:
- n_neighbors (valore predefinito 15): valori più grandi catturano una maggiore struttura globale, mentre valori più piccoli rivelano i cluster locali
- min_dist (valore predefinito 0.1): indica quanto i punti si dispongono ravvicinati; valori più piccoli producono cluster più compatti, ma anche una maggiore sovrapposizione tra loro
- metric: utilizzate sempre
'cosine'per gli embedding di testo; la distanza euclidea non è appropriata
Sperimentate con n_neighbors compreso tra 5 e 50 per trovare la visualizzazione che evidenzia al meglio la struttura dei vostri dati.
Alternativa: clustering gerarchico
Il clustering gerarchico agglomerativo costruisce un albero di cluster annidati senza richiedere di specificare k in anticipo. Per ottenere i cluster finali, si taglia l'albero in corrispondenza di una soglia di distanza scelta. È utile quando non si conosce il numero di argomenti naturali presenti nei dati.
from sklearn.cluster import AgglomerativeClustering
import numpy as np
corpus_embeddings = np.random.randn(100, 50) # placeholder
cluster = AgglomerativeClustering(
n_clusters=None,
distance_threshold=1.5,
metric='cosine',
linkage='average'
)
labels = cluster.fit_predict(corpus_embeddings)
n_clusters = len(set(labels))
print(f'Found {n_clusters} natural clusters')Individuazione di outlier e quasi duplicati
Gli embedding sono ottimi anche per trovare documenti quasi duplicati. Calcolate la similarità coseno a coppie tra tutti i documenti e segnalate come potenziali duplicati le coppie con una similarità superiore a 0,95. Questo approccio è più robusto del confronto diretto dei testi, perché individua anche i duplicati riformulati.
import numpy as np
def find_near_duplicates(corpus_vecs, threshold=0.95):
# corpus_vecs assumed L2-normalized
sim_matrix = corpus_vecs @ corpus_vecs.T # (n, n)
duplicates = []
n = len(corpus_vecs)
for i in range(n):
for j in range(i + 1, n):
if sim_matrix[i, j] >= threshold:
duplicates.append((i, j, float(sim_matrix[i, j])))
return duplicates
# pairs = find_near_duplicates(corpus_embeddings)
# print(f'Found {len(pairs)} near-duplicate pairs')Flusso di lavoro pratico per il clustering
Un flusso di lavoro reale per il clustering segue questi passaggi, nell'ordine:
- Generate gli embedding di tutti i documenti con
text-embedding-3-small - Facoltativamente, riducete la dimensionalità a 50D con UMAP prima del clustering, per velocizzare k-means
- Eseguite il clustering con k-means e provate diversi valori di k per trovare il silhouette score migliore
- Assegnate un'etichetta a ogni cluster con un LLM, utilizzando 5 documenti rappresentativi
- Visualizzate il grafico a dispersione UMAP 2D, colorato in base al cluster
- Esaminate gli outlier, cioè i punti lontani da qualsiasi centroide
Limiti del clustering
Il clustering degli embedding presenta importanti limiti da tenere presenti:
- K-means presuppone cluster sferici: i gruppi di argomenti allungati o di forma irregolare potrebbero essere suddivisi in modo errato
- Gli embedding comprimono il significato: due documenti possono essere semanticamente vicini, ma appartenere a categorie operative diverse
- Le etichette dei cluster devono essere verificate: esaminate sempre alcuni documenti di ogni cluster per verificare la coerenza dell'etichetta generata dall'LLM
Utilizzate il clustering come strumento di esplorazione, non come sistema di categorizzazione di riferimento.
Verifica rapida
Verificate la vostra comprensione dei concetti di AI Engineering trattati in questa lezione.
Riepilogo della lezione
In questa lezione ha imparato: k-means raggruppa i documenti in base alla prossimità semantica nello spazio degli embedding, UMAP riduce gli embedding ad alta dimensionalità a 2D per la visualizzazione utilizzando la distanza coseno e il punteggio silhouette aiuta a scegliere il numero corretto di cluster senza dati etichettati. Ora andremo oltre la ricerca in memoria ed esploreremo i database vettoriali per la produzione.
Domande Frequenti
La lezione «Clustering e visualizzazione degli embeddings» è gratuita?
Sì — il testo completo di «Clustering e visualizzazione degli embeddings» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.
Cosa imparerò in «Clustering e visualizzazione degli embeddings»?
Applicherà il clustering k-means a un insieme di embeddings e li visualizzerà in 2D usando UMAP per scoprire i raggruppamenti naturali degli argomenti nei dati. Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Engineering Academy?
Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.
Quanto tempo richiede la lezione «Clustering e visualizzazione degli embeddings»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?
Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Che cosa sono gli embeddings vettoriali?
- Generare embeddings con OpenAI
- Ricerca semantica con NumPy
- Clustering e visualizzazione degli embeddings