# Detetor de Grupos Temáticos (Topic Clusters): documentação

> Esta documentação descreve a instalação, a configuração e a utilização do módulo Detetor de Grupos Temáticos no PrestaShop 8 e 9. O módulo deteta automaticamente os agrupamentos temáticos do seu…

- Página: <https://www.datafirefly.com/pt/documentation/topic-cluster-detector/>
- Idioma: pt
- Atualizado em: 2026-09-16
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/topic-cluster-detector/index.md), [en](https://www.datafirefly.com/en/documentation/topic-cluster-detector/index.md), [es](https://www.datafirefly.com/es/documentation/topic-cluster-detector/index.md), [de](https://www.datafirefly.com/de/documentation/topic-cluster-detector/index.md), [it](https://www.datafirefly.com/it/documentation/topic-cluster-detector/index.md), [pl](https://www.datafirefly.com/pl/documentation/topic-cluster-detector/index.md), [nl](https://www.datafirefly.com/nl/documentation/topic-cluster-detector/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

Esta documentação descreve a instalação, a configuração e a utilização do módulo **Detetor de Grupos Temáticos** no PrestaShop 8 e 9. O módulo deteta automaticamente os agrupamentos temáticos do seu catálogo por clustering semântico e sugere as pillar pages em falta, com um rascunho SEO completo para cada oportunidade.

## Apresentação

O Detetor de Grupos Temáticos analisa o seu catálogo de produtos para fazer emergir os **topic clusters realmente presentes** na sua oferta e depois deteta as **pillar pages em falta**: temas transversais muito cobertos pelos seus produtos, mas sem uma página-mãe estruturante (CMS ou categoria).

Para cada gap detetado, o módulo gera um rascunho completo:

- Título H1 otimizado para SEO
- Slug seguro para URL
- Meta description
- Plano H2 completo em markdown
- Lista das palavras-chave alvo
- Pontuação de prioridade (dimensão × coesão)

**A reter.** O módulo não cria páginas diretamente no PrestaShop. Dá-lhe um rascunho para copiar e colar numa nova página CMS ou numa landing de categoria, mantendo a decisão editorial do seu lado.

## Instalação

### Pré-requisitos

- PrestaShop **8.0+** ou **9.x**
- PHP **8.0 no mínimo** (PHP 8.1 ou 8.2 recomendado)
- `memory_limit` de 512 MB no mínimo (1024 MB recomendado para catálogos grandes)
- Opcional: chave de API OpenAI ou Mistral para o modo embeddings

### Procedimento de instalação

1. Descarregue o ficheiro `dftopicclusters.zip` a partir da sua área de cliente DataFirefly.
2. No back-office do PrestaShop, vá a **Módulos → Gestor de módulos** e clique em **Carregar um módulo**.
3. Selecione o ZIP e confirme. O módulo instala-se automaticamente.
4. Depois de instalado, clique em **Configurar**.

Na instalação, o módulo cria automaticamente:

- As 5 tabelas SQL com o prefixo `df_topicclusters_`
- O separador principal **DataFirefly** no menu Melhorar (se ainda não existir)
- O separador filho **Topic Clusters** sob esse separador principal
- As 19 chaves de configuração por omissão

### Primeiro acesso

Uma vez instalado, o módulo fica acessível em **Melhorar → DataFirefly → Topic Clusters**. O painel apresenta o formulário de lançamento de uma nova análise e o histórico das execuções anteriores (vazio na primeira abertura).

## Configuração

Clique no botão **Definições**, no canto superior direito do painel, para aceder à página de configuração. As definições estão agrupadas em cinco secções.

### Geral

| Chave | Por omissão | Descrição |
| --- | --- | --- |
| `DFTC_MODE` | `tfidf` | Modo de clustering: `tfidf` (local), `openai` ou `mistral` |
| `DFTC_K_AUTO` | ativado | Se ativado, calcula automaticamente k = ceil(√(N/2)) limitado a [5, 30] |
| `DFTC_K_MANUAL` | 12 | Valor de k usado se `DFTC_K_AUTO` estiver desativado |
| `DFTC_MAX_ITER` | 60 | Número máximo de iterações do k-means |
| `DFTC_MIN_CLUSTER_SIZE` | 3 | Dimensão mínima de um cluster; abaixo disso, é descartado |

### Extração de texto

Permite escolher que campos do produto entram na análise. A ponderação por campo é fixa (nome × 3, meta × 2, descrição curta × 2, categorias × 2, etiquetas × 2, descrição longa × 1, características × 1).

- `DFTC_INCLUDE_DESCRIPTION` — Incluir a descrição longa (recomendado: ativado)
- `DFTC_INCLUDE_CATEGORIES` — Incluir os nomes das categorias (recomendado: ativado)
- `DFTC_INCLUDE_TAGS` — Incluir as etiquetas do PrestaShop (recomendado: ativado)
- `DFTC_INCLUDE_FEATURES` — Incluir as características do produto (recomendado: desativado, exceto se tiver características muito descritivas)

### Definições TF-IDF

| Chave | Por omissão | Descrição |
| --- | --- | --- |
| `DFTC_MIN_DOC_FREQ` | 2 | Termo ignorado se aparecer em menos de N produtos |
| `DFTC_MAX_DOC_FREQ_RATIO` | 0.50 | Termo ignorado se aparecer em mais de X % do catálogo |
| `DFTC_NGRAM_MAX` | 2 | 1 = unigramas, 2 = unigramas + bigramas |
| `DFTC_TOP_TERMS_COUNT` | 8 | Número de termos apresentados por cluster |

### APIs de embeddings

| Chave | Descrição |
| --- | --- |
| `DFTC_OPENAI_API_KEY` | Bearer token OpenAI (sk-...) |
| `DFTC_OPENAI_MODEL` | Modelo (por omissão `text-embedding-3-small`) |
| `DFTC_MISTRAL_API_KEY` | Chave de API Mistral |
| `DFTC_MISTRAL_MODEL` | Modelo (por omissão `mistral-embed`) |
| `DFTC_BATCH_SIZE` | Número de produtos por chamada à API (por omissão 32) |

### Deteção das pillar pages

- `DFTC_PILLAR_MATCH_THRESHOLD` — Limiar de correspondência (por omissão 0.45). Abaixo desse valor, o cluster é marcado como _pillar gap_. Aumente o limiar para ser mais exigente, baixe-o para ser mais tolerante.

## Os três modos em detalhe

### Modo TF-IDF (recomendado para começar)

O TF-IDF (Term Frequency × Inverse Document Frequency) é um método estatístico clássico em NLP. O módulo constrói um vocabulário a partir de todos os textos dos produtos, filtra os termos demasiado raros ou demasiado frequentes e representa cada produto como um vetor esparso nesse espaço.

**Vantagens:** 100 % local, instantâneo, sem custo e sem dependências externas. Excelente para catálogos lexicalmente homogéneos (um domínio, um vocabulário coerente).

**Limites:** não compreende sinónimos (dois produtos que usem termos diferentes para o mesmo conceito ficam mal agrupados).

**Nota para catálogos em português.** A lista de stopwords do modo TF-IDF local não cobre o português: palavras muito comuns como «para», «com» ou «mais» podem aparecer entre os top-termos de um cluster. Duas soluções: baixar `DFTC_MAX_DOC_FREQ_RATIO` (por exemplo para 0.30), o que elimina os termos presentes em demasiados produtos, ou usar um dos modos de embeddings, que não depende de stopwords.

### Modo OpenAI embeddings

Usa a API OpenAI `text-embedding-3-small` por omissão. Cada produto é representado por um vetor denso de 1536 dimensões que capta a sua semântica.

**Vantagens:** compreende os sinónimos, as variantes lexicais e o contexto. Excelente para catálogos diversificados ou com descrições narrativas.

**Custo indicativo:** cerca de 0,02 USD por milhão de tokens, ou seja, menos de 0,10 USD para um catálogo de 1000 produtos.

**Dica.** O cache de embeddings é automático: se voltar a executar uma análise sobre o mesmo catálogo sem alterar os textos, os vetores são recuperados da tabela `df_topicclusters_embedding_cache` sem nova chamada à API.

### Modo Mistral embeddings

Usa a API Mistral `mistral-embed` por omissão. É um modelo multilingue com bom desempenho, incluindo em português.

**Vantagens:** alojado na Europa (conformidade com o RGPD facilitada), bons resultados nas línguas latinas e tarifário competitivo.

## Lançar uma análise

No painel, o formulário **Lançar uma nova análise** propõe seis parâmetros:

- **Idioma** — o idioma em que os textos dos produtos são extraídos e analisados. Faça uma execução distinta para cada idioma ativo da sua loja.
- **Modo** — TF-IDF, OpenAI ou Mistral (sobrepõe-se à definição por omissão apenas nesta execução).
- **N.º de clusters (k)** — Deixe 0 para o k automático. Caso contrário, force um valor entre 2 e 100.
- **Dimensão mínima** — Clusters mais pequenos são descartados (por omissão 3).
- **Limiar pillar** — Limiar de correspondência abaixo do qual um cluster é marcado como gap (por omissão 0.45).
- **Limite de produtos** — Limita o número de produtos analisados (útil para depuração ou teste rápido). Deixe 0 para analisar todo o catálogo.

Clique em **Lançar a análise**. A execução começa de imediato. Para um catálogo de 1000 produtos:

- Modo TF-IDF: 5 a 15 segundos
- Modo embeddings (primeira execução): 30 segundos a 2 minutos, consoante o batch size
- Modo embeddings (execuções seguintes com cache quente): equivalente ao TF-IDF

**Importante.** O módulo define `set_time_limit(0)` e `memory_limit=1024M` durante a execução. Em alojamentos partilhados muito limitados, estas diretivas podem ser ignoradas. Prefira uma execução noturna ou use o limite de produtos para dividir o trabalho.

## Ler os resultados

Terminada a execução, acede à página de detalhe. Cada cluster é apresentado como um cartão com quatro secções.

### Cabeçalho do cluster

O cabeçalho combina uma etiqueta de estado, um número de cluster e um rótulo gerado. A etiqueta é:

- **PILLAR GAP** (laranja) — Nenhuma pillar page existente cobre este tema. Oportunidade forte.
- **OK** (verde) — Já existe uma página CMS ou categoria a cobrir este tema (o módulo fez a correspondência).

O rótulo é composto pelos 3 principais termos do cluster unidos por `·`. Exemplo: «ténis · pele premium · calçado».

### Estatísticas

- **Produtos** — Número de produtos no cluster
- **Coesão** — Semelhança média dos membros em relação ao centroide (0 a 100 %). Quanto mais alta, mais homogéneo é o cluster.
- **Correspondência** — Pontuação de correspondência com a melhor pillar page existente. Se estiver abaixo do limiar → gap.

### Principais termos

Os termos mais representativos do cluster. No modo TF-IDF, são os termos com maior componente no centroide. No modo embeddings, o módulo calcula um TF interno ao cluster ponderado pelo IDF global, para destacar os termos distintivos.

### Sugestão de pillar page

Presente apenas quando o cluster está marcado como gap. Contém:

- **Título** — Título H1 otimizado para SEO, em português natural
- **Slug** — Seguro para URL, em kebab-case
- **Meta description** — 150 a 160 caracteres
- **Prioridade** — Pontuação combinada: dimensão (0.6) × coesão (0.4)
- **Plano sugerido** — Plano H2 em markdown com as secções habituais (introdução, o que é, como escolher, comparativo, melhores produtos, casos de utilização, erros a evitar, FAQ, CTA)

### Produtos do cluster

Lista dos produtos agrupados com a respetiva pontuação de semelhança ao centroide, ordenados por semelhança decrescente. Clique no ID do produto para abrir a ficha diretamente numa nova janela.

## Fluxo de trabalho recomendado

Eis uma utilização típica do módulo em 4 etapas.

1. **Primeira auditoria** — Execute uma análise TF-IDF no seu idioma principal, com os parâmetros por omissão. Examine os clusters marcados como gap: fazem sentido do ponto de vista editorial?
2. **Triagem** — Para cada gap, use o botão **Ignorar** se o cluster não justificar uma pillar page (por exemplo, um agrupamento acidental de produtos heterogéneos). Os gaps restantes são as suas prioridades.
3. **Redação** — Para cada gap retido, crie uma nova página CMS no PrestaShop com o título, o slug e a meta do rascunho. Use o plano H2 como esqueleto de redação. Clique em **Marcar como feito** depois de publicar.
4. **Nova execução** — Depois de publicar as novas páginas, volte a executar uma análise. Os gaps anteriores devem agora aparecer como OK (o módulo deteta as novas pillar pages).

**Boas práticas de SEO.** Uma pillar page de qualidade tem pelo menos 1500 palavras, integra ligações internas para os produtos do cluster e usa os principais termos de forma natural no conteúdo. O rascunho gerado é um ponto de partida, não um resultado final.

## Exportação

Na página de detalhe de uma execução, dois botões no canto superior direito permitem exportar:

- **CSV** — Tabela com uma linha por cluster e as colunas: id_cluster, label, n_members, coesão, pillar_gap, match_score, suggested_title, suggested_slug, suggested_meta, priority_score, target_keywords. Codificação UTF-8 com BOM (compatível com o Excel).
- **JSON** — Exportação completa, com a lista de produtos por cluster e o plano markdown integral. Ideal para automatização ou integração externa.

## Arquitetura técnica

### Base de dados

O módulo cria 5 tabelas com o prefixo `df_topicclusters_`:

- `run` — Metadados de cada execução (modo, idioma, estado, duração, contadores)
- `cluster` — Clusters individuais (rótulo, principais termos em JSON, coesão, flag pillar_gap, match_score)
- `cluster_product` — Pertença produto → cluster com a pontuação de semelhança
- `pillar` — Sugestões de pillar pages (título, slug, meta, plano, prioridade, estado)
- `embedding_cache` — Cache dos vetores de embeddings indexado por hash do texto

### PSR-4 e autoload

O namespace raiz é `DataFirefly/TopicClusters/`. O autoload manual é registado através de `spl_autoload_register` no ficheiro principal do módulo, pelo que não é necessária qualquer dependência Composer.

### Controllers e compatibilidade PS 8 / PS 9

O módulo usa um `ModuleAdminController` legacy (e não um controller Symfony) para garantir a compatibilidade com as duas versões principais. As consultas SQL foram escritas para respeitar os esquemas das duas versões, nomeadamente a remoção da coluna `meta_keywords` no PS 9.

## Desempenho e limites

- **Catálogos até 1000 produtos** — Execuções em poucos segundos. Sem preocupações particulares.
- **1000 a 10 000 produtos** — O modo TF-IDF continua rápido (10-60 s). Modo embeddings: contar com 1 a 5 minutos na primeira execução e tempo instantâneo depois, graças ao cache.
- **Mais de 10 000 produtos** — Privilegiar o parâmetro **Limite de produtos** para dividir o trabalho, ou aumentar o `memory_limit` para 2 GB.

A complexidade do k-means é O(n × k × iter × d), em que n é o número de produtos, k o número de clusters, iter o número de iterações (tipicamente 10-30) e d a dimensão dos vetores (variável em TF-IDF, 1536 na OpenAI).

## Resolução de problemas

### Nenhum cluster detetado

Verifique se os seus produtos têm conteúdo textual no idioma analisado (pelo menos um nome e, idealmente, uma descrição). Se `DFTC_MIN_DOC_FREQ` for demasiado alto para o seu catálogo, baixe-o para 1.

### Todos os clusters estão marcados como pillar gap

O limiar `DFTC_PILLAR_MATCH_THRESHOLD` está provavelmente demasiado alto. Experimente 0.30 em vez de 0.45 se a sua loja tiver poucas páginas CMS. Confirme também que as suas páginas CMS e categorias estão ativas.

### Erro «Unknown column meta_keywords»

Este erro ocorre no PrestaShop 9 com uma versão anterior do módulo. Atualize para a versão 1.0.0 ou superior, que retira todas as referências a `meta_keywords` (coluna eliminada no PS 9).

### Erro «Compile Error: Access level to processExport() must be public»

Este erro ocorria numa versão anterior à 1.0.0. O nome do método passou a ser `doExport()`, para evitar a colisão com o `AdminControllerCore`. Atualize o módulo.

### A execução falha com erro de API

Verifique se a chave de API indicada na configuração é válida e tem saldo. Teste com `curl` na linha de comandos para confirmar que o servidor consegue chegar a `api.openai.com` ou a `api.mistral.ai`.

## Evoluções previstas

- Criação direta de páginas CMS a partir do rascunho (com um clique)
- Comparação de execuções (antes/depois da publicação das pillar pages)
- Visualização gráfica da rede semântica entre clusters
- Suporte dos embeddings Cohere e Voyage AI
- Cron automático para execuções periódicas

**Apoio.** Para qualquer questão ou problema, contacte [support@datafirefly.com](mailto:support@datafirefly.com). O seu feedback é precioso para orientar o roadmap.