AI Engineering Academy · Aula

Agrupando e visualizando embeddings

Aplique agrupamento k-means a um conjunto de embeddings e visualize-os em 2D usando UMAP para descobrir agrupamentos naturais de tópicos em seus dados.

Agrupando e visualizando embeddings é uma aula grátis de AI Engineering Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Engineering Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Engineering Academy inclui 4 aulas no total.

Por que agrupar incorporações?

Quando você tem centenas ou milhares de documentos, muitas vezes quer descobrir quais tópicos existem sem ler tudo manualmente. O agrupamento de incorporações reúne automaticamente documentos semanticamente semelhantes, revelando a estrutura natural dos seus dados.

Entre as aplicações comuns estão: atribuir etiquetas automaticamente a chamados de suporte, descobrir categorias de conteúdo, encontrar documentos redundantes e entender sobre o que os usuários mais perguntam.

Visão geral do agrupamento K-means

O K-means particiona n pontos de dados em k grupos, atribuindo iterativamente cada ponto ao centróide mais próximo e, em seguida, recalculando os centróides como a média dos pontos atribuídos. Ele converge quando as atribuições param de mudar.

Para incorporações, o K-means encontra documentos próximos uns dos outros no espaço de incorporações de alta dimensão, agrupando-os efetivamente por similaridade semântica.

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)}')

Escolhendo o número correto de grupos

Escolher k (o número de grupos) é a parte mais difícil. O método do cotovelo plota a inércia (a soma das distâncias quadráticas até os centróides) para diferentes valores de k e procura o ponto em que adicionar mais grupos deixa de reduzir significativamente a inércia.

A pontuação de silhueta mede quanto melhor um ponto se ajusta ao próprio grupo em comparação com o grupo mais próximo — pontuações mais próximas de 1 são melhores. Experimente valores de k de 3 a 20 e escolha a melhor pontuação.

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}')

Atribuindo etiquetas aos grupos com um LLM

Depois do agrupamento, você pode pedir a um LLM que gere uma etiqueta legível por humanos para cada grupo, enviando ao modelo alguns documentos representativos desse grupo. Isso transforma automaticamente números brutos de grupos em nomes de categorias significativos.

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))

Redução de dimensionalidade com UMAP

Vetores de 1536 dimensões não podem ser plotados diretamente. O UMAP (Aproximação e Projeção Uniforme de Variedades) reduz dados de alta dimensão para 2D ou 3D, preservando a estrutura dos vizinhos locais. Diferentemente do PCA, o UMAP é não linear e muito melhor para preservar grupos.

O UMAP é a escolha padrão para visualizar incorporações de texto, porque documentos semelhantes permanecem próximos no gráfico 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)

Visualizando grupos com Matplotlib

Depois de obter coordenadas 2D do UMAP e etiquetas de grupos do K-means, um simples gráfico de dispersão torna visível a estrutura dos grupos. Colora cada ponto de acordo com a etiqueta do grupo e adicione os títulos de documentos representativos como anotações de texto para tornar o gráfico interpretável.

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')

Parâmetros do UMAP que importam

Hiperparâmetros principais do UMAP que afetam a qualidade da visualização:

n_neighbors (padrão 15): valores maiores capturam mais estrutura global; valores menores revelam grupos locais
min_dist (padrão 0,1): indica o quão juntos os pontos ficam; valores menores = grupos mais compactos, mas com mais sobreposição entre eles
metric: use sempre 'cosine' para incorporações de texto — a distância euclidiana não é apropriada

Experimente n_neighbors entre 5 e 50 para encontrar a visualização que melhor revele a estrutura dos seus dados.

Alternativa: agrupamento hierárquico

O agrupamento hierárquico aglomerativo constrói uma árvore de grupos aninhados sem exigir que você especifique k antecipadamente. Você corta a árvore em um limite de distância escolhido para obter os grupos finais. Isso é útil quando você não sabe quantos tópicos naturais existem nos seus dados.

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')

Encontrando valores atípicos e quase duplicatas

As incorporações também são excelentes para encontrar documentos quase duplicados. Calcule a similaridade de cosseno entre todos os pares de documentos e sinalize como possíveis duplicatas os pares com similaridade acima de 0,95. Isso é mais robusto do que comparar diferenças entre textos, pois identifica duplicatas com reformulação.

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')

Fluxo de trabalho prático de agrupamento

Um fluxo de trabalho real de agrupamento segue estas etapas, nesta ordem:

Gere incorporações para todos os documentos com text-embedding-3-small
Opcionalmente, reduza para 50D com UMAP antes do agrupamento (acelera o K-means)
Faça o agrupamento com K-means e teste vários valores de k para encontrar a melhor pontuação de silhueta
Atribua uma etiqueta a cada grupo com um LLM usando 5 documentos representativos
Visualize o gráfico de dispersão 2D do UMAP, colorido por grupo
Revise os valores atípicos (pontos distantes de qualquer centróide)

Limitações do agrupamento

O agrupamento de incorporações tem limitações importantes que devem ser consideradas:

O K-means pressupõe grupos esféricos — grupos temáticos alongados ou irregulares podem ser divididos incorretamente
As incorporações comprimem o significado — dois documentos podem ser semanticamente próximos, mas pertencer a categorias diferentes para fins práticos
As etiquetas dos grupos precisam ser verificadas — sempre examine uma amostra de documentos de cada grupo para verificar a coerência da etiqueta gerada pelo LLM

Use o agrupamento como ferramenta de exploração, não como um sistema de categorização baseado em verdade absoluta.

Verificação rápida

Teste sua compreensão dos conceitos de Engenharia de IA desta lição.

Recapitulação da lição

Nesta lição, você aprendeu: k-means agrupa documentos por proximidade semântica no espaço de embeddings, UMAP reduz embeddings de alta dimensionalidade a 2D para visualização usando distância de cosseno e o índice de silhueta ajuda a escolher o número certo de agrupamentos sem dados rotulados. A seguir, vamos além da busca em memória e explorar bancos de dados vetoriais para produção.

Perguntas Frequentes

A aula “Agrupando e visualizando embeddings” é grátis?

Sim — o texto completo de “Agrupando e visualizando embeddings” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Engineering Academy, atualize para CoddyKit PRO. O curso de AI Engineering Academy inclui 4 aulas no total.

O que vou aprender em “Agrupando e visualizando embeddings”?

Aplique agrupamento k-means a um conjunto de embeddings e visualize-os em 2D usando UMAP para descobrir agrupamentos naturais de tópicos em seus dados. Você pratica AI Engineering Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Engineering Academy?

Nenhuma experiência prévia é necessária. AI Engineering Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Agrupando e visualizando embeddings”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Engineering Academy?

Sim. Cada aula de AI Engineering Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para AI Engineering Academy