dfaimetagen: gerador por IA de meta titles, descrições e ALT

Apresentação

O dfaimetagen gera em massa os seus meta titles, meta descriptions e etiquetas ALT de imagens através de IA (Anthropic Claude, OpenAI GPT ou Mistral) no PrestaShop 8 e 9. O módulo cobre 6 tipos de entidades (produtos, categorias, páginas CMS, fabricantes, fornecedores, imagens de produtos), aplica padrões CTR comprovados, produz variantes A/B, controla os comprimentos SERP e rejeita os duplicados através da similaridade de Jaccard.

Pré-requisitos

• PrestaShop 8.0 a 9.x
• PHP 8.1, 8.2, 8.3 ou 8.4
• Extensões PHP: curl, json, iconv
• MySQL 5.7+ ou MariaDB 10.3+
• Uma chave API junto de pelo menos um fornecedor: Anthropic, OpenAI ou Mistral

Instalação

1. Descarregue o ficheiro dfaimetagen.zip a partir da sua conta de cliente.
2. No back-office PrestaShop, vá a Módulos > Gestor de módulos > Adicionar um novo módulo.
3. Carregue o ZIP e clique em Instalar.
4. O módulo cria 6 tabelas na base de dados (prefixo df_aimeta_), instala 11 padrões CTR por defeito e gera um token CRON aleatório.
5. Aparece um novo separador AI Meta Generator sob o menu Catálogo.

Configuração do fornecedor de IA

1. Vá a Catálogo > AI Meta Generator > Parâmetros.
2. Selecione o seu fornecedor ativo: Anthropic, OpenAI ou Mistral. Os três produzem português europeu correto se o idioma for indicado no prompt, o que o módulo faz automaticamente através do token {LANG_NAME}; nos primeiros testes, verifique que os textos não saem em português do Brasil e ajuste o system prompt se necessário (ver « Templates de prompts avançados »).
3. Cole a sua chave API no campo correspondente.
4. Clique no botão Testar ao lado do campo para verificar a conectividade: deve receber a resposta « OK ».
5. Os modelos por defeito são claude-sonnet-4-5, gpt-4o-mini e mistral-large-latest. Pode alterá-los se preferir outro modelo do mesmo fornecedor.

Definições de geração

Ainda em Parâmetros, pode ajustar:

• Limites de comprimento: por defeito alinhados com as recomendações Google SERP: meta title 35–60 caracteres, meta description 120–158, ALT 25–125. Se a IA ultrapassar, o texto é truncado de forma limpa numa fronteira de palavra.
• Variantes A/B por item: de 1 a 5 alternativas geradas por entidade e por idioma.
• Limiar antiduplicação: percentagem de similaridade de Jaccard acima da qual uma variante é rejeitada (85 % por defeito). A comparação ignora os acentos.
• Tamanho do lote: número de itens processados por tick AJAX ou CRON (10 por defeito, até 100).
• Timeout HTTP: tempo máximo de espera por uma resposta do fornecedor (60 s por defeito).
• Sobrescrever / Ignorar os não vazios: comportamento por defeito perante as meta já preenchidas.

Lançar uma geração em massa

1. Vá a Catálogo > AI Meta Generator > Bulk Generation.
2. Entidade: produtos, categorias, páginas CMS, fabricantes, fornecedores ou imagens de produtos.
3. Campo: meta title, meta description ou ALT de imagem (os ALT aplicam-se às imagens de produtos).
4. Padrão CTR: escolha um padrão preciso ou deixe Auto para usar o padrão por defeito do campo.
5. Idiomas: seleção múltipla: a geração é multiplicada (itens × idiomas).
6. Âmbito: todas as entidades, por lista de IDs, ou por filtro de categoria / fabricante.
7. Limite: fixe 10 ou 20 para um teste, 0 para processar tudo.
8. Clique em Criar o job.

Acompanhar e executar os jobs

A página Jobs lista todos os jobs com a sua progressão, as suas estatísticas (bem-sucedidos / falhados / ignorados) e o seu estado. Três modos de execução:

• Executar até terminar (página de detalhe do job): processa os lotes em ciclo via AJAX com barra de progresso em direto. Mantenha o separador aberto.
• Executar um lote: processa um único lote e depois recarrega a página.
• CRON: processamento em segundo plano, recomendado para os grandes catálogos (ver abaixo).

Um job pode ser cancelado a meio, relançado desde o início ou eliminado. O histórico completo de cada geração (estado, tokens de entrada/saída, eventual erro) é conservado no separador Histórico do detalhe do job.

Configurar o CRON

1. Em Parâmetros, secção CRON, copie o URL apresentado. Tem a forma:
   https://a-sua-loja.pt/modules/dfaimetagen/cron.php?token=O_SEU_TOKEN
2. Adicione-o ao crontab do seu servidor, por exemplo a cada 5 minutos:
   */5 * * * * curl -s "https://a-sua-loja.pt/modules/dfaimetagen/cron.php?token=O_SEU_TOKEN" >/dev/null
3. Cada passagem processa até 5 lotes do job pendente mais antigo. Parâmetros opcionais: &batch=20 (tamanho do lote) e &loops=10 (número de lotes por passagem).

Variantes A/B e ativação

Cada geração produz o número de variantes configurado (1 a 5). A primeira variante válida é escrita na entidade e marcada Ativa. As outras ficam em reserva na página de detalhe do job:

• Clique em Ativar ao lado de uma variante para a escrever imediatamente na entidade.
• As outras variantes do mesmo trio (entidade, campo, idioma) são automaticamente desativadas.
• O contador de caracteres de cada variante permite verificar a conformidade SERP de relance.

Padrões CTR

Os 11 padrões pré-instalados cobrem três famílias:

• Meta titles: benefício + ano, lista numerada, parênteses retos USP, gancho em forma de pergunta, palavras de impacto.
• Meta descriptions: empilhamento de benefícios, prova social, problema-solução, CTA direto.
• ALT de imagens: descritivo, contextual.

Para criar os seus próprios padrões, vá a Catálogo > AI Meta Generator > Patterns. O template aceita tokens dinâmicos:

• {NAME}, {BRAND}, {CATEGORY}, {PRICE}, {YEAR}, {NUMBER}, {LANG_NAME}: preenchidos automaticamente pelo módulo;
• {BENEFIT}, {USP}, {CONTEXT}: preenchidos pela IA no momento da geração.

Os padrões marcados « sistema » são fornecidos com o módulo e preservados nas atualizações.

Templates de prompts avançados

Para um controlo total do comportamento da IA, crie templates em Catálogo > AI Meta Generator > Prompt Templates. Cada template visa um trio (entidade, campo, idioma, ou todos os idiomas) e define:

• o system prompt: papel, tom, restrições globais (por exemplo « escreve em português europeu, nunca em português do Brasil »);
• o user prompt: com os tokens {NAME}, {BRAND}, {CATEGORY}, {DESCRIPTION}, {PRICE}, {PATTERN}, {LANG_NAME}, {MIN_LENGTH}, {MAX_LENGTH}, {AB_VARIANTS}, {EXISTING}.

Marque um template « por defeito » para que se aplique automaticamente ao seu trio.

Antiduplicação

Antes de conservar uma variante, o módulo compara-a com as variantes já guardadas:

1. Hash exato (sha1 da versão normalizada): rejeição imediata em caso de duplicado perfeito.
2. Similaridade de Jaccard nos conjuntos de palavras normalizadas (minúsculas, sem acentos): rejeição se a similaridade ultrapassar o limiar configurado.

Uma variante rejeitada é automaticamente regenerada pela IA (dentro do limite de tentativas do lote).

Painel

A página Dashboard agrega: número de jobs (total, pendentes, terminados), variantes geradas e ativas, gerações bem-sucedidas / falhadas, tokens consumidos (entrada + saída), últimos jobs e últimas gerações. Use-a para vigiar o orçamento de IA e detetar os erros de fornecedor.

Multiloja

O módulo lê e escreve os valores tendo em conta o contexto de loja quando a tabela *_lang em causa tem uma coluna id_shop. Selecione a loja de destino no formulário de geração em massa se a sua instalação for multiloja.

Resolução de problemas

• « FAIL » no teste de conectividade: verifique a chave API, o saldo de créditos do fornecedor e que o seu servidor autoriza ligações HTTPS de saída (cURL) para api.anthropic.com, api.openai.com ou api.mistral.ai.
• Job bloqueado em « running »: relance um lote manualmente a partir da página de detalhe, ou espere pela próxima passagem CRON. Um job pode sempre ser cancelado e depois relançado.
• Variantes vazias ou truncadas: aumente o timeout HTTP nos Parâmetros, ou escolha um modelo mais rápido.
• 403 no URL CRON: o token do URL já não corresponde (talvez tenha sido regenerado). Copie de novo o URL a partir dos Parâmetros.
• Nada é gerado para certas entidades: se « Ignorar os não vazios » estiver ativo, as entidades já preenchidas são saltadas voluntariamente. Marque « Sobrescrever » para forçar.

Desinstalação

A desinstalação elimina as 6 tabelas do módulo e as suas chaves de configuração. As meta geradas e já escritas nos seus produtos, categorias e imagens são conservadas: fazem parte do seu catálogo.