Clustering: Agrupamento Automático
Nesta página
Objetivos
- Agrupar textos por tema sem rótulos predefinidos
- Utilizar K-Means e HDBSCAN em embeddings
- Nomear automaticamente os clusters
Porquê o clustering?
A lição sobre classificação partiu do princípio de que já sabia quais as categorias existentes. O clustering aborda a situação oposta, que é também a mais comum ao explorar um corpus: ninguém sabe o que ele contém. Recupera oito mil verbatims de um inquérito de satisfação, ou seis meses de tickets de suporte, e a primeira pergunta não é «quantos bugs», mas «sobre o que é que as pessoas estão realmente a falar». O clustering descobre grupos temáticos sem que lhe seja dito nada antecipadamente.
Três casos de uso surgem constantemente: analisar milhares de feedbacks de clientes para extrair padrões dominantes, identificar tópicos recorrentes em tickets de suporte para povoar uma base de conhecimento e explorar um corpus de documentos desconhecido antes de decidir como o indexar.
K-Means em embeddings
O K-Means é o algoritmo de referência: indica-lhe um número de grupos, ele coloca esse mesmo número de centros e move iterativamente cada centro em direção à média dos pontos que atrai. Aplicado a embeddings em vez de um saco de palavras, agrupa por significado: «a aplicação falha no arranque no Android» e «não consigo fazer login desde ontem» acabam juntos, mesmo que não partilhem palavras.
O corpus de exemplo abaixo contém intencionalmente quatro famílias — bugs, pedidos de funcionalidades, perguntas e elogios — para que possa verificar visualmente o agrupamento resultante. A definição random_state=42 garante que obterá os mesmos clusters de uma execução para a outra, o que é essencial sempre que precisar de comparar duas configurações.
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]}")
Encontrar o número certo de clusters
Com doze frases preparadas, escolher quatro foi óbvio. Com oito mil verbatims, ninguém sabe o valor correto. Duas métricas ajudam a estimar. A inércia, ou seja, a dispersão residual dentro dos grupos, diminui mecanicamente à medida que adiciona clusters: procura o «cotovelo», o ponto além do qual ela já não desce significativamente. O coeficiente de silhueta (silhouette score) é mais decisivo porque mede outra coisa: o quanto cada ponto está mais próximo do seu próprio grupo do que do grupo vizinho mais próximo. Ao contrário da inércia, tem um máximo, e esse máximo aponta diretamente para um valor 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 sem K
O K-Means sofre de uma falha estrutural em dados do mundo real: deve atribuir todos os pontos a um cluster. Um verbatim isolado que não se assemelha a nada acaba forçosamente ligado ao grupo menos distante, onde polui a interpretação. O HDBSCAN raciocina em termos de densidade e aceita dizer não: determina ele próprio o número de grupos e coloca os pontos isolados numa categoria separada rotulada como -1.
Estes outliers não são lixo. Num corpus de tickets, são frequentemente incidentes raros, pedidos fora do âmbito ou sinais fracos — exatamente o que merece revisão humana. O código abaixo exibe-os separadamente em vez de os descartar.
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]}")
Nomear automaticamente os clusters
Um algoritmo de clustering dá-lhe números. «Cluster 2» não pertence a um relatório ou a um dashboard. O passo que torna o resultado utilizável consiste em submeter uma dúzia de membros representativos ao LLM e pedir-lhe um nome curto: «Problemas de Ligação», «Pedidos de Integração», «Questões de Faturação». Limitar a dez exemplos controla o custo, definir a temperatura como zero garante que o mesmo cluster receba sempre o mesmo nome, e o ciclo ignora o rótulo -1, uma vez que os outliers, por definição, não têm tema comum.
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 completo de clustering
Os três passos — embedding, clustering, nomeação — juntam-se naturalmente numa única classe. O parâmetro methode aceita "auto", que delega a escolha do número de grupos ao HDBSCAN, ou um valor numérico passado como string quando quer impor um K ao K-Means. O dicionário devolvido contém os rótulos, nomes legíveis e dois contadores que indicam imediatamente se o resultado vale a pena utilizar: um n_outliers próximo do total significa que o seu corpus carece de estrutura densa, e deve voltar ao 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)
Pontos-chave
- Utilize o K-Means quando souber o número de clusters
- Utilize o HDBSCAN para detetar automaticamente grupos e outliers
- O coeficiente de silhueta ajuda a escolher o K correto
- Um LLM nomeia automaticamente os clusters descobertos
- Os embeddings tornam o clustering semântico, e não apenas lexical