# 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… - Página: - Idioma: pt - Atualizado em: 2026-09-09 - Outros idiomas: [fr](https://www.datafirefly.com/documentation/recherche-semantique-ia-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/ai-semantic-search-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/busqueda-semantica-ia-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/ki-semantische-suche-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/ricerca-semantica-ia-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/recherche-semantique-ia-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/recherche-semantique-ia-prestashop/index.md) - Índice: 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.