Pesquisa Visual por Imagem e Shop the Look com IA: guia completo
Instalar, configurar e utilizar a pesquisa de produtos por imagem e o Shop the Look com IA no PrestaShop 8 e 9.
Este módulo acrescenta a pesquisa de produtos por imagem à sua loja: o cliente arrasta uma fotografia e obtém os artigos do seu catálogo visualmente mais próximos, ordenados por pontuação de semelhança. O modo Shop the Look deteta cada artigo de uma cena completa e propõe os produtos correspondentes. O motor é agnóstico: escolhe o fornecedor de IA (Voyage, Cohere, OpenAI ou Mistral) e usa a sua própria chave. Este guia cobre a instalação, a configuração, a indexação do catálogo e o funcionamento da pesquisa.
Instalação
- Descarregue o arquivo
dfvisualsearch.zipa partir da sua conta DataFirefly. - Back-office do PrestaShop → Módulos → Carregar um módulo → envie o ZIP.
- O módulo cria a sua tabela de índice, regista os seus hooks e acrescenta um separador de administração dedicado.
Compatível com PrestaShop 1.7.6 a 9.x, em PHP 7.4 a 8.3. Sem overrides do núcleo e sem dependências Composer.
Configuração geral
Vá a Módulos → Pesquisa Visual e Shop the Look com IA → Configurar.
Escolher o fornecedor
Selecione o motor na lista e indique a chave de API correspondente. Paga a IA ao consumo junto do fornecedor, sem qualquer subscrição acrescentada pelo módulo.
- Voyage e Cohere: embeddings multimodais diretos da imagem.
- OpenAI e Mistral: análise de visão seguida de embedding, que desbloqueiam ainda o Shop the Look.
- Chave de API: guardada do lado do servidor, nunca exposta ao front-office. Cada fornecedor tem o seu próprio modelo e a sua dimensão de vetor configuráveis.
Depois de gravar o fornecedor e a chave, use o botão Testar o fornecedor no painel de índice para validar a ligação antes de indexar.
Comportamento
- Número de resultados: quantos produtos mostrar numa pesquisa por imagem.
- Semelhança mínima (0-1): 0 mostra tudo, ordenado por relevância; aumente (por exemplo, 0,2 a 0,4) para afastar as correspondências fracas. Deve ser calibrado consoante o fornecedor.
- Ativar o Shop the Look e produtos por artigo detetado.
- Produtos semelhantes na ficha de produto e o respetivo número.
- Injetar o botão de câmara no cabeçalho, ou colocá-lo manualmente no seu tema através do hook
displayDfVisualSearchButton. - Tamanho máximo de carregamento e reindexação automática ao gravar um produto.
Indexar o catálogo
No painel Índice do catálogo da configuração:
- Clique em Indexar / reindexar o catálogo: o módulo trata os produtos por lotes, com barra de progresso, sem risco de tempo esgotado no servidor.
- O contador indica os produtos indexados para o fornecedor ativo.
- Limpar o índice elimina os vetores da loja atual.
A indexação transforma a imagem de capa de cada produto num vetor guardado na base de dados. Uma vez indexado, um produto só volta a ser codificado se a sua imagem mudar.
A pesquisa por semelhança de cosseno corre do lado do servidor e mantém-se fluida até cerca de 10 000 produtos, sem necessidade de alojar uma base de dados vetorial externa.
Como funciona a pesquisa
Cada imagem é convertida num vetor (embedding) normalizado. A fotografia enviada pelo cliente é codificada pelo mesmo fornecedor e depois comparada com o índice por semelhança de cosseno, que, sobre vetores normalizados, se reduz a um simples produto escalar. Os produtos são em seguida ordenados por pontuação decrescente e filtrados pelo limiar mínimo configurado.
- Os fornecedores Voyage e Cohere codificam a imagem diretamente.
- Os fornecedores OpenAI e Mistral descrevem a imagem com um modelo de visão e codificam depois essa descrição: a indexação e a consulta passam assim a viver no mesmo espaço vetorial.
Com os fornecedores de visão, o passo intermédio é uma descrição textual da imagem, gerada em regra em inglês. A comparação faz-se entre descrições, pelo que o idioma da sua loja não afeta a qualidade dos resultados: o cliente português obtém as mesmas correspondências, sem ter de escrever fosse o que fosse.
Shop the Look
A partir de uma fotografia de cena, o Shop the Look identifica cada artigo visível e lança uma pesquisa por artigo, apresentando os resultados em grupos distintos.
A deteção de vários artigos exige um fornecedor de visão (OpenAI ou Mistral). Com o Voyage ou o Cohere, o Shop the Look passa de forma limpa para uma semelhança de «visual completo» da imagem inteira.
Produtos visualmente semelhantes
Na ficha de produto, aparece automaticamente um bloco de «produtos visualmente semelhantes». Reutiliza o vetor já calculado na indexação do produto: não é enviado qualquer pedido adicional à IA, pelo que a recomendação não acrescenta custos recorrentes.
Apresentação do lado do cliente
O botão de câmara abre uma janela onde o cliente arrasta uma fotografia ou a seleciona. É mostrada uma pré-visualização e, em seguida, os resultados aparecem em cartões de produto com a respetiva pontuação de semelhança em percentagem. Se o Shop the Look estiver ativo, o cliente pode assinalar a opção para obter os resultados agrupados por artigo detetado.
Numa loja portuguesa, os textos da janela de pesquisa visual são apresentados no idioma de recurso enquanto não os traduzir em Internacional > Traduções. Como se trata de um elemento visto pelo cliente, faça essa tradução antes de ativar o botão no cabeçalho.
As fotografias enviadas pelos visitantes são transmitidas ao fornecedor de IA escolhido para serem analisadas. Mencione-o na sua política de privacidade e prefira um fornecedor com tratamento na Europa (a Mistral, por exemplo) se quiser evitar transferências para fora da UE. Uma fotografia pode conter dados pessoais, nomeadamente se mostrar pessoas: a finalidade e o destinatário devem constar do seu registo de atividades de tratamento, sob supervisão da CNPD.
Escolher um fornecedor
Todos os fornecedores asseguram a pesquisa por imagem. A escolha depende das suas necessidades:
- Voyage / Cohere: embeddings multimodais diretos, simples e rápidos, sem Shop the Look.
- OpenAI / Mistral: análise de visão que desbloqueia a deteção de vários artigos do Shop the Look.
Cada fornecedor produz um espaço vetorial e uma dimensão diferentes. Depois de mudar de fornecedor ativo, volte a lançar a indexação do catálogo. Os vetores dos outros fornecedores são conservados mas ignorados na pesquisa; o back-office indica o número de produtos indexados para o fornecedor atual.
Compatibilidade e notas técnicas
- PrestaShop 1.7.6 a 9.x, multiloja e multi-idioma; cada loja mantém o seu próprio índice.
- Controlador de administração legacy (sem controlador Symfony), para compatibilidade com PS8 e PS9.
- Hooks utilizados:
displayHeader,displayTop,displayDfVisualSearchButton,displayFooterProduct,actionProductSave,actionProductDelete. - Vetores guardados normalizados na base de dados, codificados para um armazenamento robusto; pesquisa por produto escalar.
- Uma limitação anti-abuso por sessão protege a sua quota de IA.
- Endpoint de pesquisa em AJAX através da ligação do módulo; resposta em formato JSON.
Perguntas frequentes e resolução de problemas
O botão de pesquisa não aparece. Confirme que existe um fornecedor configurado e que a sua chave é válida (botão Testar o fornecedor) e, depois, que a injeção no cabeçalho está ativa ou que o hook está bem colocado no seu tema.
A pesquisa não devolve resultados. Certifique-se de que o catálogo foi indexado para o fornecedor ativo e baixe a semelhança mínima se estiver demasiado alta para o espaço vetorial do fornecedor.
O Shop the Look devolve um único grupo. O fornecedor ativo não faz deteção (Voyage ou Cohere). Passe para a OpenAI ou a Mistral para a deteção de vários artigos e reindexe.
Mudei de fornecedor e os resultados estão incoerentes. Volte a lançar uma indexação completa: os vetores têm de ser recalculados no espaço do novo fornecedor.