Pesquisa Semântica IA para PrestaShop

Este módulo acrescenta uma pesquisa semântica por inteligência artificial à sua loja PrestaShop: a sugestão automática, a página de resultados de pesquisa, o bloco «Também vai gostar» na ficha de produto e o painel de estatísticas partilham a mesma ordenação por significado, calculada por embeddings vetoriais.

Pré-requisitos

• PrestaShop 8.0 a 9.x
• PHP 7.4 a 8.3 com a extensão cURL ativa
• Uma chave de API num fornecedor de embeddings: OpenAI, Mistral AI ou qualquer gateway compatível com a OpenAI

Instalação

1. No back-office, abra Módulos > Gestor de módulos.
2. Clique em Carregar um módulo e envie o ficheiro ZIP.
3. Depois de instalado, clique em Configurar.

O módulo cria quatro tabelas (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log, dfvectorsearch_similar) e um separador oculto para as suas chamadas AJAX. Nada é visível do lado do cliente enquanto o índice não estiver construído.

Configuração do fornecedor de embeddings

No separador Definições, escolha o seu fornecedor e indique a sua chave de API.

OpenAI

Selecione o fornecedor OpenAI e introduza a sua chave. O modelo recomendado é o text-embedding-3-small (boa relação entre qualidade e preço). Para precisão máxima num catálogo exigente, pode usar o text-embedding-3-large.

Mistral AI (alojamento europeu)

Selecione Mistral AI para um tratamento dos dados na Europa, em conformidade com o RGPD. O modelo a usar é o mistral-embed.

Gateway compatível com a OpenAI

Selecione Custom para usar o seu próprio gateway (proxy interno, Azure OpenAI, entre outros). Indique então o URL de base da API, por exemplo https://o-meu-gateway.exemplo.com/v1.

A chave de API fica oculta depois de gravada. Deixe o valor oculto como está para conservar a chave existente; introduza uma chave nova apenas se a quiser substituir.

Os modelos de embeddings da OpenAI e da Mistral são multilingues e lidam bem com o português: uma pesquisa por «casaco impermeável» encontra fichas que falam de «blusão à prova de água», o que a pesquisa nativa por palavras-chave não faz. O índice é construído idioma a idioma, pelo que a versão portuguesa do catálogo tem de estar traduzida e indexada para que a pesquisa semântica funcione em /pt/.

Dimensões

O campo Dimensões permite reduzir o tamanho dos vetores para acelerar a pesquisa em catálogos muito grandes. Deixe 0 para usar o tamanho predefinido do modelo. Os modelos text-embedding-3 da OpenAI aceitam dimensões reduzidas (por exemplo, 512).

Mudar de fornecedor, de modelo ou de número de dimensões torna todo o índice obsoleto: ao gravar, o índice é automaticamente marcado para reconstrução completa e a cache das consultas é limpa. Volte depois a lançar uma indexação.

Construir o índice

Depois de gravar a chave de API, vá ao painel Índice de embeddings, no topo da página de configuração.

1. Clique em Indexar agora. O módulo trata os produtos por lotes, com barra de progresso, idioma a idioma e loja a loja.
2. Deixe a página aberta até o estado indicar Índice atualizado.

Dimensão dos lotes

A definição Dimensão do lote de indexação controla o número de produtos tratados por chamada (5 a 100). Reduza-a se o seu servidor tiver problemas de tempo esgotado.

Indexação agendada (cron)

Para manter o índice sincronizado automaticamente com o catálogo, copie o URL de indexação por cron apresentado na configuração e chame-o com regularidade (por exemplo, a cada 15 minutos) a partir do agendador do seu alojamento.

O URL contém um token de segurança. Cada chamada trabalha cerca de vinte segundos e para depois de forma limpa, para se manter compatível com os limites de tempo de execução do PHP.

Como funciona a reindexação

A cada adição, alteração ou eliminação de produto, a entrada correspondente é marcada para reindexação. O módulo calcula uma impressão (checksum) do texto do produto: se só o preço ou o stock mudou, o texto mantém-se igual e não é feita qualquer nova chamada à API. Os produtos desativados e os idiomas desativados são automaticamente removidos do índice.

Pesquisa do lado do cliente

Sugestão automática

Ative a Sugestão automática no front-office para associar um menu de sugestões semânticas à barra de pesquisa do seu tema. O campo Seletor CSS do campo de pesquisa indica ao módulo a que campo se deve ligar. O valor predefinido #search_widget input[type="text"] funciona com os temas baseados no classic.

Desativar a sugestão automática do tema

A definição Desativar a sugestão automática do tema (ativa por predefinição) elimina as sugestões de pesquisa nativas (ps_searchbar e equivalentes) para evitar um duplo menu pendente. O módulo cancela o registo do script nativo e oculta qualquer menu injetado por um tema personalizado.

Modo híbrido

Com o modo híbrido ativo (recomendado), a ordenação semântica é colocada à cabeça e os resultados por palavra-chave nativos em falta são acrescentados a seguir. Nunca obtém menos resultados do que na pesquisa de origem.

Limiar e número de resultados

A pontuação mínima de semelhança (entre 0 e 0,99; recomendado: 0,30) afasta os resultados demasiado distantes. O número máximo de resultados limita as sugestões apresentadas na sugestão automática.

A página de resultados de pesquisa

A definição Assumir o controlo da página de resultados (ativa por predefinição) faz com que a ordenação da página de pesquisa seja fornecida pelo módulo, através do hook productSearchProvider, o mecanismo oficial do PrestaShop usado pela navegação por facetas. Na prática:

• a sugestão automática e a página apresentam os mesmos produtos, pela mesma ordem;
• a paginação e as ordenações do tema continuam a funcionar (a ordenação por «relevância» mantém a ordem semântica, enquanto preço, nome e data são recalculados na ordenação);
• se a API de embeddings estiver indisponível, o módulo passa em silêncio para os resultados nativos e regista o incidente: a página de pesquisa nunca se parte.

O módulo só entra em ação numa pesquisa por texto. As categorias, as páginas de etiquetas e as restantes listagens mantêm os seus mecanismos nativos.

Produtos semelhantes (Também vai gostar)

O Bloco de produtos semelhantes (ativo por predefinição) apresenta em cada ficha de produto um «Também vai gostar» calculado por proximidade semântica entre os vetores já guardados na base de dados. Não é feita qualquer chamada à API: o bloco funciona mesmo sem chave de API, desde que o índice exista.

• Número de produtos semelhantes: de 2 a 12 (6 por predefinição).
• Pontuação mínima dos produtos semelhantes: limiar dedicado, independente do da pesquisa (recomendado: 0,45). Abaixo dele, o produto não aparece, mesmo que isso signifique mostrar menos cartões. Alterá-lo limpa automaticamente a cache dos semelhantes.
• Um bónus de afinidade favorece os produtos da mesma categoria predefinida e da mesma marca.
• Os resultados ficam em cache 24 horas por produto e são invalidados automaticamente na reindexação.
• A apresentação usa as miniaturas nativas do seu tema, incluindo emblemas, lista de desejos, pré-visualização rápida e estilos ao passar o rato.

Num catálogo pequeno de demonstração, em que todas as fichas partilham o mesmo texto de marketing, as semelhanças são naturalmente mais frouxas. Suba o limiar para 0,55-0,60 para manter apenas as correspondências próximas.

Estatísticas e análises

A página de configuração mostra um painel calculado sobre os últimos 30 dias: número de pesquisas, taxa de pesquisas sem resultados, resultados médios por pesquisa, histograma do volume por dia, as 20 principais consultas (ocorrências, resultados médios, melhor pontuação) e as 20 principais consultas sem resultados.

As consultas sem resultados são uma mina de ouro: indicam com precisão o que os seus clientes procuram sem encontrar e, por isso, o que acrescentar ao catálogo ou aos sinónimos.

• O botão Exportar em CSV descarrega o registo completo (separador ponto e vírgula) com a origem de cada pesquisa: sugestão automática ou página de resultados.
• O registo é eliminado automaticamente ao fim de 365 dias.

O ficheiro exportado usa o ponto e vírgula como separador, que é também o formato que o Excel e o LibreOffice configurados em português abrem diretamente, sem passar pelo assistente de importação.

Cache das consultas

Os embeddings das consultas dos clientes ficam em cache 30 dias. As pesquisas repetidas são instantâneas e não voltam a ser cobradas pelo fornecedor. O botão Limpar a cache das consultas permite reiniciá-la a qualquer momento.

Atualização do módulo

Se atualizar o módulo substituindo os seus ficheiros (fora do Gestor de módulos), abra uma vez a página de configuração: o módulo regista então automaticamente os hooks em falta, cria as tabelas e colunas em falta e aplica as novas definições predefinidas. Os ficheiros CSS e JS do front-office integram um mecanismo de invalidação de cache, pelo que não é necessário limpar a cache do navegador.

Resolução de problemas

• Não aparece qualquer resultado: confirme que o índice está construído (contador «Vetores indexados» superior a 0) e que a chave de API é válida.
• Aparecem dois menus pendentes: confirme que a opção Desativar a sugestão automática do tema está ativa e limpe uma vez a cache do PrestaShop.
• A sugestão automática e a página de resultados divergem: abra uma vez a página de configuração do módulo (registo automático do hook da página de resultados) e confirme que Assumir o controlo da página de resultados está ativo.
• O bloco Também vai gostar está vazio: o índice tem de estar construído para o idioma e a loja atuais; caso contrário, baixe a pontuação mínima dos produtos semelhantes.
• Tempos esgotados durante a indexação: reduza a dimensão dos lotes e privilegie a indexação por cron.
• Resultados incoerentes depois de mudar de modelo: volte a lançar uma reconstrução completa do índice.