Tudo o que quer saber antes de instalar.
Uma análise detalhada de como o DataFirefly Ligações Internas Semânticas por IA: Embeddings Vetoriais, Semelhança de Cosseno e Inserção Semiautomática com Âncoras Inteligentes para PrestaShop 8 e 9 (Mistral, OpenAI) funciona, porque o construímos assim e o raciocínio por trás das funcionalidades acima.
Porque é que as ligações internas semânticas são superiores às ligações por palavras-chave
Os módulos clássicos de ligações internas funcionam por regras de palavra-chave para URL. Escreve tapete berbere e associa o URL da categoria tapete-berbere. O motor faz depois um find-replace no HTML dos seus artigos, produtos ou páginas. Esta abordagem tem duas limitações importantes. É rígida: só cria uma ligação quando a palavra-chave exata aparece, o que exclui todas as páginas em que o assunto é tratado com outra formulação (tapete marroquino, kilim, tapete tradicional). E é cega ao contexto semântico: o motor não sabe se a página de destino é mesmo relevante para o conteúdo de origem, apenas faz uma correspondência de texto. As ligações semânticas funcionam de outra forma: cada conteúdo é representado por um vetor de várias centenas de dimensões que codifica o seu sentido, seja produto, categoria, página CMS ou artigo. Dois conteúdos são ligados se estiverem próximos nesse espaço vetorial, independentemente das palavras usadas. Assim, o módulo encontra oportunidades que um motor por palavras-chave nunca veria e evita os falsos positivos em que uma palavra-chave aparece num contexto irrelevante.
Embeddings de IA: como funciona na prática
Na primeira indexação, o módulo percorre todas as entidades ativas da sua loja nos tipos ativados (produtos, categorias, páginas CMS). Para cada entidade, o conteúdo textual é extraído e limpo: título, meta_title, meta_description, descrição curta e descrição longa (o HTML é removido de forma limpa). O texto limpo é depois enviado em lote ao fornecedor configurado (Mistral ou OpenAI), que devolve um vetor de embedding por item, uma lista de números de vírgula flutuante que representa a semântica do texto. Esse vetor é guardado na base de dados sob a forma de BLOB float32 em little-endian, com a norma L2 pré-calculada para acelerar os cálculos de semelhança. A semelhança entre dois conteúdos é depois calculada em PHP por produto escalar normalizado (semelhança de cosseno), uma operação extremamente rápida com as normas já calculadas. Num catálogo de 5000 entidades, o cálculo completo de todos os pares num idioma demora apenas alguns segundos.
Porquê dois fornecedores e não apenas um
Cada fornecedor tem o seu ponto forte. O mistral-embed é a opção predefinida recomendada: 1024 dimensões, latência muito baixa, alojamento na Europa (soberania da UE para lojas mais sensíveis) e custo de cerca de 10 cêntimos por milhão de tokens, ou seja menos de um euro para indexar um catálogo de vários milhares de entidades multilingues. O text-embedding-3-small da OpenAI é a alternativa: 1536 dimensões (espaço vetorial mais rico), excelente em idiomas não europeus e um custo de cerca de 2 cêntimos de dólar por milhão de tokens. O módulo unifica os dois fornecedores atrás de uma interface comum: mesmo formato de resposta, mesmo mecanismo de lotes e mesma gestão de erros com o PrestaShopLogger. Pode trocar de fornecedor na lista pendente da configuração e o módulo detetará que as dimensões mudaram, convidando a reindexar com um clique em Reindexar tudo.
O gerador de âncoras, a verdadeira peça central do módulo
É o ponto que faz a diferença face a um módulo de sugestão em bruto. Para cada par de origem e destino acima do limiar de semelhança, o gerador aplica o seguinte algoritmo: extrai o título do destino, divide-o em n-gramas de 2 a 6 palavras, retira as stopwords (francês e inglês) e procura cada um desses n-gramas textualmente no conteúdo de origem. Os n-gramas encontrados são ordenados por comprimento decrescente (os mais longos são mais discriminantes e mais otimizados para SEO) e apresentados na lista pendente do back-office. A âncora predefinida é a mais longa encontrada, o que dá tipicamente uma âncora de 3 ou 4 palavras que inclui as palavras-chave principais do título de destino. Se nenhum n-grama do título de destino aparecer na origem, o módulo propõe o título de destino tal e qual (modo de fallback). Mantém sempre o controlo: lista pendente editável e opção Personalizar para escrever qualquer texto de âncora. Na inserção, o módulo escolhe a primeira ocorrência do texto da âncora no conteúdo de origem que ainda não esteja dentro de uma tag a, code ou pre, pelo que não há risco de partir uma ligação existente nem de voltar a ligar um texto já ligado.
Rollback cirúrgico por marcador único
É a funcionalidade que tranquiliza qualquer comerciante cuidadoso com as suas descrições. Cada ligação inserida recebe um atributo HTML data-dfasl com um identificador único de 36 carateres gerado aleatoriamente na inserção (formato do tipo UUID). O identificador também é guardado na tabela dfasl_inserted_link, com a entidade de origem, o destino, a âncora, a data de inserção e o identificador do colaborador que validou. Para retirar uma ligação, vai ao separador Ligações inseridas e clica em Remover na linha em causa: o módulo aplica uma regex que corresponde exatamente ao padrão da tag a com esse identificador único, retira a tag mantendo o texto da âncora intacto e marca a ligação como removida na base de dados. Nenhuma outra tag da descrição é tocada e nenhuma ligação manual corre perigo. Em 500 ligações inseridas pelo módulo em 200 fichas de produto, pode retirar apenas uma num clique sem mexer nas outras 499.
Worker CLI e estratégia de processamento para catálogos grandes
Num catálogo de algumas dezenas de produtos, tudo pode ser feito no back-office: Reindexar tudo e depois Processar um lote chega. Acima de alguns milhares de entidades, a interface fica lenta e ninguém quer manter o navegador aberto durante horas. O módulo expõe um worker CLI (bin/analyze.php) que se lança na linha de comandos do PHP com quatro opções. --shop para escolher uma loja num ambiente multiloja. --enqueue-all para recolocar na fila todas as entidades ativas antes de processar, útil para uma reindexação completa depois de mudar de fornecedor ou de modelo. --loop para continuar enquanto houver itens por tratar. --max-batches para limitar o número de lotes processados numa execução (segurança contra corridas descontroladas). --sleep para intercalar uma pausa entre lotes (útil para respeitar os limites de pedidos da API). O comando típico para um cron a cada 15 minutos é: php modules/dfaisemanticlinks/bin/analyze.php --loop --max-batches=50 --sleep=1. O worker repõe automaticamente as entradas bloqueadas no estado Em curso há mais de 30 minutos (caso um worker anterior tenha falhado), trata os erros de API marcando os itens em causa com o estado Com erro e a respetiva mensagem, e continua a processar os itens saudáveis do lote.
Reindexação automática e atualidade do índice
Um índice que se dessincroniza do catálogo deixa de ter valor. O módulo garante a atualidade por hooks nativos do PrestaShop. A cada alteração de um produto, de uma categoria ou de uma página CMS (hooks actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter e actionObjectCmsUpdateAfter), a entidade é recolocada na fila com o estado Em espera, em todos os idiomas ativos, e o próximo worker trata dela automaticamente. Na eliminação (hooks actionObjectProductDeleteAfter, actionObjectCategoryDeleteAfter e actionObjectCmsDeleteAfter), os embeddings e as sugestões associadas são removidos em cascata. O módulo inclui ainda um hash do conteúdo (SHA-256 do texto limpo): se uma entidade voltar à fila sem que o conteúdo real tenha mudado (por exemplo porque alguém só mexeu no stock), o lote de indexação deteta o hash inalterado e salta a chamada à API, poupando tokens. A reindexação automática pode ser desligada nas Definições (opção DFASL_AUTO_INDEX), útil para a suspender durante uma importação CSV massiva e retomá-la no fim com um Reindexar tudo.
Multiloja e multilingue nativos
O módulo é nativamente multiloja e multilingue. Os embeddings são delimitados por entidade, idioma e loja: um mesmo produto em duas lojas terá dois embeddings independentes se as descrições diferirem, e um mesmo produto em português e em inglês terá dois embeddings diferentes ainda que a ficha seja a mesma. As sugestões nunca cruzam fronteiras linguísticas: um produto português nunca receberá a sugestão de uma ligação para um produto inglês (o que não faria sentido em SEO). As fronteiras entre lojas são respeitadas da mesma forma. A configuração pode ser diferente por loja (chave de API, limiar de semelhança, tipos indexados, hook de apresentação), útil quando tem uma loja B2B com conteúdo técnico e uma loja B2C com conteúdo para o público geral na mesma infraestrutura.
Casos de utilização típicos
Loja de moda multilingue com um catálogo de 2000 produtos: as ligações semânticas encontram pares de produtos próximos em estilo ou visual (por exemplo duas variações do mesmo corte de vestido) que regras por palavras-chave falhariam sistematicamente. Loja B2B técnica com descrições densas: as ligações semânticas relacionam os produtos que partilham o mesmo caso de uso industrial sem que o vocabulário seja idêntico. Blog de comércio eletrónico: cada artigo pode referenciar automaticamente os produtos, categorias e outros artigos mais relevantes por sentido, com âncoras extraídas textualmente do texto do artigo, o contrário de um find-replace mecânico. Reformulação de catálogo: depois de uma importação massiva ou de uma reorganização, um Reindexar tudo reconstrói a malha em poucos minutos, onde uma estratégia manual levaria semanas de trabalho editorial. Catálogos com vocabulário muito específico (cosmética biológica, equipamento médico, produtos técnicos): o módulo deteta proximidades semânticas que os não especialistas não veriam e permite à equipa de SEO descobrir oportunidades pouco óbvias.
Arquitetura interna e compatibilidade com PrestaShop 8 e 9
O módulo é construído em PHP 8.1+ com tipos estritos, classes readonly e funcionalidades modernas (match, enums). O autoload é PSR-4 no namespace DataFirefly/AiSemanticLinks/ mapeado em src/. Os controladores de administração usam o ModuleAdminController legado (não as grelhas Symfony), uma escolha deliberada para garantir compatibilidade estável entre o PrestaShop 8.0 e o 9.x sem manter duas variantes do código. Um minicontentor de serviços próprio (ServiceContainer) liga os repositórios e os serviços de negócio, o que isola o módulo das diferenças do contentor Symfony entre versões do PrestaShop e evita uma dependência que partiria a cada atualização importante. Cinco tabelas SQL com prefixo dfasl_: embedding (vetores e hashes), queue (fila de trabalho), suggestion (pares propostos), inserted_link (ligações ativas) e job (operações em massa). A desinstalação elimina de forma limpa as 5 tabelas e remove todas as variáveis de configuração DFASL_*. O código-fonte é entregue não cifrado e conforme PSR, para poder fazer override, auditar ou estender como entender.
Ainda não existem avaliações.