# Auditoria Semântica: documentação
> Instalação Pré-requisitos PrestaShop 8.0 a 9.x PHP 7.4 no mínimo (8.x recomendado) MySQL 5.7+ ou MariaDB 10.3+ Uma chave de API da OpenAI ou da Mistral (opcional: está incluído um…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfsemanticaudit/index.md), [en](https://www.datafirefly.com/en/documentation/dfsemanticaudit/index.md), [es](https://www.datafirefly.com/es/documentation/dfsemanticaudit/index.md), [de](https://www.datafirefly.com/de/documentation/dfsemanticaudit/index.md), [it](https://www.datafirefly.com/it/documentation/dfsemanticaudit/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsemanticaudit/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsemanticaudit/index.md)
- Índice:
## Instalação
### Pré-requisitos
- PrestaShop 8.0 a 9.x
- PHP 7.4 no mínimo (8.x recomendado)
- MySQL 5.7+ ou MariaDB 10.3+
- Uma chave de API da OpenAI ou da Mistral (opcional: está incluído um modo local sem API)
### Instalar o módulo
1. Descomprima o ficheiro `dfsemanticaudit.zip` descarregado a partir da sua conta de cliente.
2. Carregue a pasta `dfsemanticaudit/` para `/modules/` do seu PrestaShop por FTP, ou utilize a instalação por ZIP em **Módulos → Gestor de módulos → Carregar um módulo**.
3. Clique em **Instalar**.
### Ativar o módulo
O módulo cria automaticamente quatro tabelas SQL (`ps_dfsa_content`, `ps_dfsa_audit`, `ps_dfsa_cluster`, `ps_dfsa_assignment`), bem como um separador de administração acessível a partir do menu da esquerda.
## Configuração
Antes da primeira auditoria, vá a **Módulos → DataFirefly → Auditoria Semântica → Configuração**.
### Escolha do fornecedor de embeddings
Estão disponíveis três fornecedores. A escolha determina a qualidade dos grupos obtidos.
### OpenAI (recomendado)
O fornecedor predefinido. Utiliza o modelo `text-embedding-3-small` (1536 dimensões). Qualidade máxima e custo marginal: cerca de 0,02 € por 1000 produtos na primeira indexação.
- **Chave de API**: crie-a em [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
- **Modelo**: deixe `text-embedding-3-small` por predefinição. O `text-embedding-3-large` (3072 dim.) dá uma qualidade ligeiramente superior, mas custa 6× mais.
### Mistral
Alternativa europeia alojada em França. Utiliza `mistral-embed` (1024 dimensões). Tarifário comparável ao da OpenAI.
- **Chave de API**: crie-a em [console.mistral.ai](https://console.mistral.ai/)
- **Modelo**: `mistral-embed`
### TF-IDF local
Funciona inteiramente no seu servidor, sem chamadas de API e sem custo recorrente. Utiliza os princípios clássicos do tratamento estatístico da linguagem (TF-IDF normalizado), com uma dimensão de 384.
- Qualidade suficiente para catálogos com menos de 500 produtos.
- Suporta FR, EN, ES, DE e IT (stopwords integrados).
- Não exige qualquer chave de API.
**Numa loja portuguesa** — A lista de stopwords do modo local não inclui o português. Num catálogo em português, prefira a OpenAI ou a Mistral, cujos modelos de embeddings tratam a língua sem configuração adicional.
**Dica** — Pode mudar de fornecedor a qualquer momento. Na auditoria seguinte, todos os conteúdos são reprocessados automaticamente.
### Parâmetros da auditoria
- **k (número de grupos)**: 8 por predefinição. Intervalo de 2 a 50.
- **Limiar de fora de tema**: distância de cosseno a partir da qual um conteúdo é assinalado. 0,55 por predefinição. Intervalo de 0,1 a 1,5.
### Reindexação automática
Ativada por predefinição. O módulo regista hooks na criação, alteração e eliminação de produtos, categorias e páginas CMS. Em cada mudança, o conteúdo é marcado para reprocessamento na execução seguinte, sem qualquer esforço manual.
## Lançar a primeira auditoria
Três etapas a executar por ordem a partir do **painel**.
### Etapa 1: reindexar o conteúdo
Clique em **Reindexar o conteúdo**. O módulo percorre os seus produtos, categorias ativas, páginas CMS e fabricantes, calcula um hash `SHA1` do título + extrato e marca para tratamento apenas os conteúdos novos ou alterados.
Para 1000 conteúdos, esta etapa demora alguns segundos.
### Etapa 2: gerar os embeddings
Clique em **Gerar os embeddings**. O módulo envia os conteúdos marcados como «dirty» ao fornecedor selecionado, em lotes de 50 (OpenAI/Mistral) ou numa passagem local (TF-IDF). Uma barra de progresso acompanha o avanço.
Para 1000 conteúdos:
- OpenAI: cerca de 30 segundos
- Mistral: cerca de 40 segundos
- TF-IDF local: menos de 1 segundo
### Etapa 3: lançar a auditoria
Clique em **Lançar a auditoria**. O agrupamento k-means por cosseno reúne os conteúdos em `k` grupos (inicialização k-means++, 50 iterações no máximo), etiqueta cada grupo com os seus termos principais (TF×IDF), calcula a distância de cada conteúdo ao seu centroide e identifica os casos atípicos.
Esta etapa demora menos de um segundo, mesmo para 5000 conteúdos.
## Compreender o relatório
### Painel
Quatro indicadores principais no topo:
- **Conteúdos indexados** — total de produtos, categorias, páginas CMS e fabricantes processados.
- **Páginas fora de tema** — número absoluto, taxa em percentagem e distribuição por tipo.
- **Grupos temáticos** — número de grupos temáticos identificados.
- **Distância mediana** — distância de cosseno mediana ao centroide. Abaixo de 0,40 = catálogo muito coerente. Acima de 0,60 = catálogo disperso.
### Grupos
Vista **Grupos**: lista detalhada ordenada por dimensão, com etiqueta automática (5 principais termos TF×IDF), pontuação de coesão (0 = disperso, 1 = idêntico) e dimensão (número de conteúdos).
Um grupo com uma **coesão inferior a 0,40** é demasiado heterogéneo: é muitas vezes sinal de que o assunto deveria ser dividido em dois subtemas, ou de que o `k` é demasiado baixo.
### Mapa semântico 2D
Projeção de todos os conteúdos num plano através da técnica **Johnson-Lindenstrauss** (uma projeção aleatória que preserva aproximadamente as distâncias).
Cada ponto é um conteúdo e cada cor um grupo. As cruzes marcam os centroides. Os pontos com **contorno vermelho** estão fora de tema. A legenda à direita permite ocultar ou mostrar cada grupo individualmente, clicando nele.
**Leitura rápida** — Se vir pontos de uma cor perdidos muito longe do seu centroide, são candidatos prioritários a mudança.
### Páginas fora de tema
Vista **Páginas fora de tema**: tabela ordenável dos conteúdos cuja distância de cosseno ao centroide ultrapassa o limiar configurado. Em cada linha:
- Tipo, título, URL público e ligação direta para a ficha de edição
- Grupo atual (com a sua cor)
- Distância ao centroide (quanto mais elevada, mais afastado está o conteúdo)
- Grupo sugerido (quando pertinente)
- Δ Ganho: redução da distância se o conteúdo fosse deslocado
### Páginas irrecuperáveis
No fundo da vista Fora de tema, uma secção especial lista os conteúdos afastados **de todos os grupos**. O módulo não encontrou para eles qualquer destino viável.
Três ações a considerar:
1. **Eliminar** se a página não tiver tráfego de SEO nem conversão.
2. **Noindex** para preservar o orçamento de rastreio sem perder o histórico.
3. **Reescrever** para alinhar o conteúdo com um grupo existente.
### Sugestões de reestruturação
Vista **Sugestões**: equivalente a Páginas fora de tema, mas centrada na ação. Todas as mudanças propostas são listadas com o ganho de coerência esperado. Ordene por ganho decrescente para tratar primeiro os casos com mais impacto.
O módulo **nunca** altera a sua estrutura automaticamente. As alterações mantêm-se sob o seu controlo, através do back-office normal do PrestaShop.
## Exportação CSV
Em cada vista do relatório, um botão **Exportar CSV** permite descarregar os dados em bruto. Útil para:
- Partilhar o relatório com um consultor de SEO externo
- Tratar os dados no Excel ou no Sheets
- Arquivar o estado de uma auditoria antes de alterar a estrutura
## Automatização por cron
O módulo expõe um URL assinado, apresentado na página de configuração. Despoleta em modo headless o encadeamento completo **indexação → embeddings → auditoria**.
Exemplo de tarefa cron semanal (todas as segundas-feiras às 3 h):
```
0 3 * * 1 wget -q -O /dev/null "https://a-sua-loja.com/modules/dfsemanticaudit/cron.php?token=O_SEU_TOKEN"
```
O token deriva da `_COOKIE_KEY_` do seu PrestaShop e só muda com uma reinstalação. Guarde-o com cuidado.
## Custos de API
Estimativa para um catálogo médio (1000 produtos):
- **OpenAI text-embedding-3-small**: cerca de 0,02 € da primeira vez, depois quase nulo (só os conteúdos alterados são reprocessados)
- **OpenAI text-embedding-3-large**: cerca de 0,13 € da primeira vez
- **Mistral mistral-embed**: cerca de 0,10 € da primeira vez
- **TF-IDF local**: 0 €
## Multilingue e multiloja
O módulo é nativamente multilingue e multiloja. Cada auditoria é executada sobre um par **idioma × loja** específico, utilizando o idioma de contexto do back-office.
Para auditar a sua loja em português e depois em inglês, mude de idioma na barra superior do PrestaShop e lance uma nova auditoria.
**Nota** — O módulo respeita o idioma de origem de cada conteúdo, sem qualquer tentativa de tradução automática. Os grupos obtidos serão diferentes em cada idioma, o que é normal.
## Resolução de problemas
### A etapa «Gerar os embeddings» falha com um erro 401
A sua chave de API é inválida ou está expirada. Verifique-a na página de configuração e volte a configurá-la se for necessário.
### A etapa «Gerar os embeddings» falha com um erro 429
Atingiu o limite de débito do seu fornecedor. Aguarde alguns minutos e volte a lançar: o módulo retoma onde tinha parado, graças ao tratamento por lotes.
### Nenhum grupo parece pertinente
Três pistas:
1. Aumente o número de grupos (k). Se o seu catálogo tem 10 temáticas distintas mas k=4, o agrupamento não conseguirá separá-las.
2. Passe do modo TF-IDF local para a OpenAI ou a Mistral. Em catálogos heterogéneos, a qualidade semântica faz toda a diferença.
3. Verifique se os títulos e as descrições dos seus conteúdos são suficientemente ricos. Um produto com um título de 2 palavras e sem descrição não dará um bom embedding.
### Demasiadas páginas assinaladas como fora de tema
Aumente o limiar de fora de tema (por exemplo, de 0,55 para 0,70). É expectável se o seu catálogo cobrir legitimamente várias temáticas amplas.
### Nenhuma página assinalada como fora de tema, mas o catálogo parece incoerente
Baixe o limiar (por exemplo, de 0,55 para 0,40) para apertar a deteção.
## FAQ
### É obrigatório ter uma chave de API?
Não. O modo TF-IDF local funciona sem ligação externa. É ligeiramente menos preciso do que a OpenAI ou a Mistral, mas chega para começar ou para um catálogo homogéneo.
### O módulo altera automaticamente a minha estrutura?
Não. O módulo limita-se a **recomendar**. Todas as mudanças de conteúdo ficam a seu cargo, através do back-office normal do PrestaShop.
### Como escolher o número de grupos (k)?
Regra empírica: `k` ≈ número de categorias principais de primeiro nível. Por predefinição, k=8 funciona bem entre 100 e 5000 produtos. Se estiver na dúvida, lance 2 ou 3 auditorias com valores de k diferentes para comparar: as auditorias anteriores ficam no histórico.
### Os meus vetores são enviados para um servidor de terceiros?
Com a OpenAI ou a Mistral: sim, os títulos e extratos dos seus conteúdos são enviados para a respetiva API de embeddings. Com o modo TF-IDF local: não, nenhum dado sai do seu servidor.
### Durante quanto tempo são conservadas as auditorias?
Indefinidamente, até serem eliminadas manualmente a partir do painel. Pode consultar o histórico completo para medir a evolução da sua coerência semântica ao longo do tempo.
### O módulo funciona em multiloja?
Sim. Cada loja do multistore pode ter as suas próprias auditorias independentes.