# Pesquisa Visual por Imagem e Shop the Look com IA: guia completo

> 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…

- Página: <https://www.datafirefly.com/pt/documentation/ai-visual-search-shop-the-look/>
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/ai-visual-search-shop-the-look/index.md), [en](https://www.datafirefly.com/en/documentation/ai-visual-search-shop-the-look/index.md), [es](https://www.datafirefly.com/es/documentation/ai-visual-search-shop-the-look/index.md), [de](https://www.datafirefly.com/de/documentation/ai-visual-search-shop-the-look/index.md), [it](https://www.datafirefly.com/it/documentation/ai-visual-search-shop-the-look/index.md), [pl](https://www.datafirefly.com/pl/documentation/ai-visual-search-shop-the-look/index.md), [nl](https://www.datafirefly.com/nl/documentation/ai-visual-search-shop-the-look/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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

1. Descarregue o arquivo `dfvisualsearch.zip` a partir da sua conta DataFirefly.
2. Back-office do PrestaShop → **Módulos** → **Carregar um módulo** → envie o ZIP.
3. 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:

1. 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.
2. O contador indica os produtos indexados _para o fornecedor ativo_.
3. **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.