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 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
• 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
• 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.

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.

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.

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.