Como montei uma ferramenta de clustering de palavras-chave em Python

Um pipeline com TF-IDF e HDBSCAN para agrupar milhares de queries em tópicos coerentes, sem preencher planilha de intenção à mão.

Agrupar palavras-chave é uma daquelas tarefas de SEO↳SEO4 conteúdosPor que a transição do SEO clássico para a Otimização de Motores Generativos (GEO) exige que se repense a modelagem semânticaMarketing Tech · mai 2026O impacto da pesquisa e do SEO no comércio eletrônico: insights da State of Search Brasil 5Marketing Tech · fev 2025SEO por Elas 2025: Impulsionando e promovendo mulheres no Marketing DigitalMarketing Tech · fev 2025Ver tudo em Marketing Tech → que parecem simples até você encarar uma planilha com 12 mil linhas e uma coluna "agrupar por intenção" pra preencher no braço. O agrupamento manual não escala, e regras fixas por termo perdem a sobreposição semântica entre frases que não compartilham nenhuma palavra mas claramente pertencem ao mesmo tópico.

Refiz um script de clustering que eu tinha há alguns anos, seguindo a abordagem descrita por Simone De Palma no Search Engine Land. A estrutura usa vetorização TF-IDF para gerar os vetores de features e depois aplica HDBSCAN, um algoritmo de clustering baseado em densidade. Aqui vai o passo a passo do que funcionou e onde tropecei.

Nota da redação: este artigo descreve uma ferramenta e um processo autorais, construídos e testados pelo próprio autor em seu ambiente pessoal. Não há como a redação verificar de forma independente a execução do código, os resultados obtidos ou a fidelidade exata à abordagem citada de Simone De Palma no Search Engine Land. Trate o conteúdo como relato de experiência prática, não como resultado auditado.

Por que TF-IDF + HDBSCAN, e não k-means

Quando você analisa dados de keyword, raramente sabe quantos grupos temáticos existem antes de explorar o dataset. Isso descarta algoritmos como o k-means, que exigem que você defina o número de clusters de antemão. Você acabaria chutando.

O TF-IDF transforma cada palavra-chave num vetor numérico, dando mais peso a termos distintivos dentro do conjunto e reduzindo o peso daqueles que aparecem em muitas queries. Esses vetores alimentam o HDBSCAN, que encontra agrupamentos naturais sem precisar saber quantos são.

O detalhe que me fez adotar o HDBSCAN: ele identifica ruído. Em vez de empurrar toda keyword pra dentro de algum cluster, ele marca outliers com o rótulo -1. Na prática, isso isola aquelas long-tail muito específicas que não pertencem a nenhum tópico mais amplo, em vez de sujar os clusters bons com termos jogados de qualquer jeito. Para exports de SEO, isso é ouro.

De onde vem a lista de keywords

Antes de qualquer clustering, você precisa de uma lista. Se seu Search Console já exporta para o BigQuery, essa é a melhor fonte: não tem o teto de 1.000 linhas da interface e não vem amostrada.

O fluxo é direto:

1. Rode uma query contra o schema padrão do export do GSC no BigQuery.
2. Exporte o resultado como CSV.
3. Reduza para uma única coluna query.
4. Salve como .txt, uma keyword por linha.

Se você não tem o export do BigQuery configurado, dá pra usar mesmo assim os dados da interface do Search Console, só que com um dataset mais limitado. O notebook não se importa com a origem: ele só quer uma lista de keywords na entrada.

Rodando o pipeline

Nota da redação: este texto descreve o pipeline (query BigQuery, limpeza, TF-IDF, HDBSCAN, exportação e migração para Colab) em nível conceitual, sem trechos de código executáveis. Os nomes citados para parâmetros do HDBSCAN, como "sensitivity", referem-se à nomenclatura usada pelo autor em seu script pessoal e não correspondem literalmente aos parâmetros documentados da biblioteca oficial (min_cluster_size, min_samples, cluster_selection_epsilon, entre outros). Valide a implementação exata antes de reproduzir em produção.

A lógica é simples: entra uma lista plana de keywords, sai um conjunto de clusters temáticos.

• Você sobe o .txt com uma keyword por linha.
• O script limpa o texto: remove caracteres especiais, stopwords e entradas fora do idioma esperado.
• Você ajusta os parâmetros sensitivity e min_cluster_size conforme o tamanho da lista.
• O TF-IDF pontua a importância de cada palavra; o HDBSCAN fecha o agrupamento.
• Cada cluster ganha um rótulo automático a partir dos termos mais distintivos.
• A saída vai pra um Excel com duas visões: os clusters agrupados e o detalhamento keyword por keyword.

Onde tropecei: os dois parâmetros de sensibilidade se comportam de forma bem diferente com 50 keywords e com 50 mil. Deixá-los hardcoded me obrigava a mexer na lógica toda vez. A saída foi expô-los como variáveis ajustáveis no topo do notebook, pra retunar sem tocar no resto. Vale testar valores diferentes até o número de clusters fazer sentido.

Outro ponto: a primeira versão era um script de terminal com argparse. Como o fluxo real é "puxa keywords, roda notebook, entrega arquivo", migrei para uma versão específica de Google Colab, com try/except em torno dos imports exclusivos do Colab e visualização via Plotly. Muda mais a forma do código do que parece.

O que a IA fez e o que ela não faz

Usei IA↳Inteligência artificial440 conteúdosUX e IA: Transformando Experiências Digitais com Inteligência ArtificialProduto & UX · jan 2025MCP: O que é e por que você vai ouvir falar disso em breve?AI · jul 2025IA generativa e a urgência de reconstruir nossa relação com a verdadeAI · jun 2025Ver tudo em AI → pra refatorar o script, mas deixo claro o limite: as decisões que importam (escolher TF-IDF em vez de word embeddings, optar por HDBSCAN porque o número de tópicos é desconhecido) exigem entender como clustering funciona. O que a IA tirou do caminho foi o trabalho repetitivo de reescrever boilerplate e conectar bibliotecas.

O resultado é uma ferramenta leve que processa milhares de keywords em minutos e entrega um primeiro rascunho da sua taxonomia de tópicos. Ela não substitui julgamento editorial, mas elimina horas de agrupamento manual. Se você já joga o Search Console no BigQuery, isso vira um passo natural: extrai as queries, roda o notebook, revisa os clusters e planeja conteúdo por tópicos, não por keywords isoladas.

Fonte: Search Engine Land