PS PrestaShop PrestaShop Intermédio

Thin Content Detector: documentação

Deteção automática de conteúdo pobre, duplicados e texto repetido no seu catálogo PrestaShop, com sugestões de enriquecimento por IA. Instalação, configuração dos limiares, fornecedores de IA, análise por cron e resolução de problemas.

Atualizado Versão do módulo 1.0.0

O DataFirefly Thin Content Detector analisa automaticamente os seus produtos, categorias e páginas CMS em todos os idiomas ativos da loja. Deteta três padrões tóxicos para o SEO (conteúdo demasiado pobre, descrições duplicadas e páginas dominadas por texto repetido) e gera sugestões de enriquecimento por IA prontas a colar. Este guia cobre a instalação, a configuração, a utilização diária, o agendamento por cron e a resolução de problemas.

Visão geral

Desde o Helpful Content Update, o Google despromove ativamente as páginas cujo conteúdo é demasiado curto, demasiado semelhante ao de outras páginas ou demasiado dominado por elementos repetidos. Num catálogo de comércio eletrónico, são tipicamente as fichas copiadas do fornecedor, as categorias com duas frases genéricas ou as variantes que partilham 95 % da descrição. É invisível a olho nu em 500 produtos, mas, somado, é isso que impede o seu site de posicionar.

Os três tipos de deteção

  • Conteúdo pobre: páginas abaixo do limiar de palavras configurável. Três níveis de gravidade conforme a distância ao limiar (crítico abaixo de 25 %, aviso entre 25 e 75 %, nota entre 75 e 100 %).
  • Duplicados: deteção em duas passagens, com hash SHA1 para os duplicados exatos (gravidade 3) e depois semelhança de Jaccard acima do limiar configurável para os quase duplicados (gravidade 2).
  • Rácio modelo / conteúdo: identifica os tokens partilhados com as páginas irmãs (mesma categoria-mãe) e calcula a percentagem de tokens únicos por página. Uma página com 200 palavras mas 90 % de texto repetido é tão tóxica como uma página de 30 palavras.

Instalação

  1. Envie o ZIP do módulo em Módulos > Gestor de módulos > Carregar um módulo.
  2. Clique em Instalar. O módulo cria duas tabelas (ps_dfthincontent_issue e ps_dfthincontent_scan) e um separador de administração em Catálogo.
  3. Aceda ao módulo em Catálogo > Thin Content (DataFirefly).
Compatibilidade. PrestaShop 8.0 a 9.x, PHP 7.4 a 8.3, MySQL 5.6+ ou MariaDB 10.3+. Multiloja suportada nativamente (a chave única dos problemas inclui id_shop). Sem dependências Composer.

Configuração

Clique no botão Configuração na faixa do módulo. Estão disponíveis três painéis.

Limiares de deteção

  • Palavras mínimas por produto: 150 por predefinição. Qualquer produto cuja descrição longa e curta somadas tenham menos de 150 palavras é assinalado.
  • Palavras mínimas por categoria: 100 por predefinição.
  • Palavras mínimas por página CMS: 250 por predefinição.
  • Limiar de semelhança de Jaccard: 85 % por predefinição. Acima disso, duas páginas são consideradas quase duplicadas.
  • Rácio de modelo mínimo: 30 % por predefinição. Abaixo disso, a página é considerada demasiado dominada por texto repetido.
Que limiar escolher? 150 palavras por produto é um bom ponto de partida para a maioria das lojas. Em têxtil ou consumíveis, pode descer para 100. Em eletrónica técnica ou casa, suba para 250. Na semelhança de Jaccard, 85 % apanha os verdadeiros duplicados sem assinalar cada variante legítima; passe a 75 % se tiver muitas variantes muito próximas a diferenciar.
Contagem de palavras em português. Um texto português é, em regra, ligeiramente mais longo do que o equivalente inglês, mas fica próximo do francês. Se traduziu o catálogo a partir do francês, os limiares que usa na versão francesa costumam servir tal e qual. Como a contagem é por idioma, uma ficha bem preenchida em francês e apenas esboçada em português aparece assinalada só na linha portuguesa: é precisamente o que quer ver.

Alvos da análise

  • Analisar os produtos (ativo por predefinição).
  • Analisar as categorias (ativo por predefinição).
  • Analisar as páginas CMS (ativo por predefinição).
  • Nova análise automática ao gravar (inativo por predefinição). Quando está ativo, cada gravação de um produto, de uma categoria ou de uma página CMS aciona um novo teste apenas desse objeto. Vê em tempo real se a sua reescrita chega para ultrapassar os limiares.

Configuração da IA

As sugestões de enriquecimento usam um endpoint compatível com a OpenAI (chat completions). Isso inclui um vasto conjunto de fornecedores:

  • OpenAI: endpoint https://api.openai.com/v1/chat/completions, com o modelo gpt-4o-mini recomendado (cerca de 0,001 € por sugestão).
  • Mistral AI: endpoint https://api.mistral.ai/v1/chat/completions, modelo mistral-small-latest.
  • Groq: endpoint https://api.groq.com/openai/v1/chat/completions, modelo llama-3.3-70b-versatile. Muito rápido.
  • Ollama local: endpoint http://localhost:11434/v1/chat/completions, com qualquer modelo descarregado. Custo zero.
  • Anthropic, através de um proxy compatível com a OpenAI.

Parâmetros a preencher:

  • Endpoint: URL completo para /v1/chat/completions.
  • Modelo: identificador do modelo no fornecedor.
  • Chave API: Bearer token. Guardada de forma cifrada pelo sistema de configuração do PrestaShop.
  • Máximo de tokens: 600 por predefinição. Chega para uma sugestão de enriquecimento normal.
A chave API não é obrigatória. A deteção e o acompanhamento dos problemas funcionam sem IA. Só as sugestões de enriquecimento exigem um endpoint configurado. Pode perfeitamente usar o módulo em modo de auditoria puro.

Utilização: painel

O painel é a página inicial do módulo. Apresenta:

  • Três contadores principais: total de problemas abertos, corrigidos e ignorados.
  • Repartição por tipo de problema: pobre, duplicado, modelo.
  • Repartição por tipo de objeto: produto, categoria, página CMS.
  • Limiares atuais: recordatório dos valores configurados.
  • Últimas 5 análises: data, duração, número de objetos analisados.
  • Botão «Executar uma análise completa»: aciona uma análise síncrona por AJAX. Uma janela mostra o progresso e o resumo no fim.

Executar uma análise

Clique em Executar uma análise completa. A análise percorre todos os idiomas ativos, aplica os três analisadores aos alvos ativos, guarda os problemas detetados em ps_dfthincontent_issue e marca como corrigidos os problemas que já não são detetados (por exemplo, se enriqueceu uma ficha desde a última análise).

Num catálogo grande (acima de 5000 produtos), prefira a análise por cron (ver mais abaixo). A análise síncrona continua utilizável, mas pode ultrapassar o limite de tempo predefinido do PHP. A análise por cron levanta os limites automaticamente, com set_time_limit(0) e memory_limit 512M.

Utilização: lista de problemas

Acessível através de Ver os problemas na faixa. Apresentação paginada (50 por página) com filtros avançados:

  • Estado: aberto, corrigido, ignorado.
  • Tipo de problema: pobre, duplicado, modelo.
  • Tipo de objeto: produto, categoria, CMS.
  • Idioma: filtro por um dos idiomas ativos.
  • Pesquisa livre: pelo nome do objeto.

Cada linha mostra a gravidade (marca vermelha, laranja ou azul), o tipo de problema, o tipo de objeto com ícone, o nome, o idioma, o número de palavras, a métrica pertinente (percentagem de semelhança ou de unicidade) e três botões de ação:

  • Sugestão de IA: abre uma janela com uma sugestão de enriquecimento em HTML, gerada a pedido (ver a secção seguinte).
  • Marcar como corrigido: passa o problema ao estado fixed. Fica no histórico, mas deixa de poluir os contadores.
  • Ignorar: passa o problema ao estado ignored. É útil para páginas propositadamente curtas (por exemplo, uma página CMS «Contacto», curta mas legítima).

Exportação CSV

O botão Exportar CSV descarrega a totalidade dos problemas do filtro atual. A exportação é feita em fluxo (blocos de 500 linhas), para lidar com catálogos grandes sem saturar a memória. Codificação UTF-8 com BOM, para abertura direta no Excel. Delimitador ponto e vírgula, que é também o que o Excel em português espera.

Sugestões de IA

Clique no botão IA em qualquer linha. O módulo envia um pedido ao endpoint configurado com um prompt construído dinamicamente a partir do tipo de problema e do tipo de objeto:

  • Produto pobre: enriquecer com argumentos de venda, materiais, utilização, proveniência e garantias.
  • Categoria pobre: enriquecer com os argumentos da gama, conselhos de compra e comparação das subcategorias.
  • CMS pobre: desenvolvimento editorial, contextualização e exemplos.
  • Duplicado: diferenciar a ficha, focando o que a torna única face aos seus duplicados.
  • Modelo: eliminar o texto repetido e acrescentar elementos únicos dessa página em concreto.

A mensagem de sistema impõe uma resposta em HTML limpo: apenas as etiquetas p, ul, li e h3. Sem markdown e sem etiquetas de raiz. Pode colar o resultado diretamente no campo de descrição do TinyMCE, sem qualquer limpeza.

A sugestão fica guardada na base de dados. Se reabrir a janela mais tarde, é apresentada de imediato, sem nova chamada à API.

Fluxo recomendado. Filtre por gravidade crítica, gere as sugestões uma a uma, copie cada sugestão para a ficha correspondente e grave. Se a nova análise automática estiver ativa, o problema passa a corrigido assim que a gravação ultrapassa os limiares.
Releia sempre a sugestão. A IA escreve no idioma da ficha, mas pode derivar para português do Brasil. Verifique as formas típicas antes de colar («utilizador» e não «usuário», «ecrã» e não «tela», «casa de banho» e não «banheiro») e confirme que nenhuma característica do produto foi inventada: uma descrição enriquecida continua a ser uma alegação comercial, sujeita ao Decreto-Lei n.º 57/2008 sobre práticas comerciais desleais.

Cron: análises agendadas

O módulo expõe um endpoint de cron protegido por token, ideal para análises noturnas:

https://a-sua-loja.pt/modules/dfthincontent/cron.php?token=O_SEU_TOKEN

O token é gerado aleatoriamente na instalação e apresentado no painel de configuração. Mantenha-o confidencial: dá acesso ao acionamento de uma análise completa.

Exemplo de crontab (análise diária às 4h)

0 4 * * * curl -s "https://a-sua-loja.pt/modules/dfthincontent/cron.php?token=O_SEU_TOKEN" > /dev/null 2>&1

Características da análise por cron

  • set_time_limit(0): sem limite de tempo do PHP.
  • memory_limit 512M: definido automaticamente.
  • Resposta em JSON com o número de objetos analisados, o número de problemas detetados e a duração total.
  • Validação por hash_equals, para resistir a ataques por temporização.
Regenerar o token. Se suspeitar de uma fuga do token, desinstale e volte a instalar o módulo, e será gerado um novo. Também pode alterar diretamente o valor DFTHIN_CRON_TOKEN na tabela ps_configuration.

Arquitetura técnica

Estrutura das tabelas

  • ps_dfthincontent_issue: um registo por problema detetado. Chave única: (id_object, object_type, id_lang, id_shop, issue_type). Campos de nota: severity (1 a 3), word_count, content_hash (SHA1), metric_value (percentagem de semelhança ou de unicidade), metric_data (JSON com o detalhe), ai_suggestion, status, object_name e object_url.
  • ps_dfthincontent_scan: histórico das análises. Data de início e de fim, duração, itens analisados por tipo e estado.

Hooks utilizados

  • actionAdminControllerSetMedia: carregamento do CSS e do JS e exposição do URL de AJAX através de Media::addJsDef.
  • actionProductUpdate: nova análise do produto alterado, se a opção estiver ativa.
  • actionObjectCategoryUpdateAfter: o mesmo para as categorias.
  • actionObjectCmsUpdateAfter: o mesmo para as páginas CMS.

Limites de desempenho

A deteção de duplicados é, por natureza, O(n²): cada página é comparada com todas as outras do mesmo tipo, idioma e loja. Para evitar uma explosão em catálogos muito grandes, o módulo aplica duas proteções:

  • Limite de segurança de 1500 itens por grupo (tipo, idioma e loja). Acima disso, a deteção de duplicados é desativada nesse grupo, com um aviso registado.
  • Pré-filtragem por número de palavras: a semelhança de Jaccard só é calculada entre itens cujo número de palavras esteja numa janela de ±50 %. Isto elimina a grande maioria das comparações inúteis.

Resolução de problemas

A análise não arranca

  1. Abra a consola de rede do navegador, clique em Executar uma análise completa e observe o pedido AJAX para action=scanFull.
  2. Se a resposta for HTML em vez de JSON, trata-se de um erro fatal do PHP no servidor: veja os registos do PrestaShop (var/logs/) e do PHP.
  3. Se a resposta for 404, confirme que o controlador AdminDfThinContent está mesmo registado (tabela ps_tab).
  4. Se a resposta for 403, o token CSRF expirou: atualize a página e tente de novo.

As sugestões de IA devolvem um erro

  • Confirme que a chave API está correta e ativa no seu fornecedor.
  • Confirme que o servidor consegue alcançar o URL do endpoint (firewall de saída, DNS).
  • Se usa o Ollama localmente, confirme que o serviço está a correr (ollama serve) e que o modelo foi descarregado (ollama pull llama3.3).
  • Consulte os registos do PrestaShop: o módulo regista aí os erros de cURL e os códigos HTTP diferentes de 200.

O cron devolve 401 ou 403

O token transmitido não corresponde. Obtenha o token correto no painel de configuração e substitua-o no seu crontab. Sem espaços e sem quebras de linha no valor.

São assinalados duplicados legítimos

É o caso típico das variantes muito próximas (tamanhos do mesmo modelo, cores). Há três opções:

  • Marcar os problemas como ignorados, um a um.
  • Subir o limiar de semelhança de Jaccard para 95 % ou mais.
  • Desativar a análise dos produtos e manter apenas as categorias e o CMS, se o seu caso de utilização não exigir a análise dos produtos.

Desinstalação

Desinstale em Módulos > Gestor de módulos > Desinstalar. O módulo elimina de forma limpa as duas tabelas da base de dados, o separador de administração e todas as chaves de configuração. Sem resíduos.

Guarde a exportação CSV antes de desinstalar se quiser conservar o histórico das sugestões de IA geradas. Depois de eliminadas as tabelas, as sugestões perdem-se.

Recursos

Esta página foi útil?

Ainda com dúvidas? Contacte o suporte