AI Visual Search by Image & Shop the Look — Complete guide
Install, configure and use image-based product search and Shop the Look AI for PrestaShop 8 and 9.
This module adds image-based product search to your shop: the customer drops in a photo and gets the visually closest items in your catalog, ranked by similarity score. Shop the Look detects every item in a full scene and surfaces the matching products. The engine is provider-agnostic: you choose the AI provider (Voyage, Cohere, OpenAI or Mistral) and use your own key. This guide covers installation, configuration, catalog indexing and how the search works.
Installation
- Download the
dfvisualsearch.ziparchive from your DataFirefly account. - PrestaShop back office → Modules → Upload a module → send the ZIP.
- The module creates its index table, registers its hooks and adds a dedicated admin tab.
Compatible with PrestaShop 1.7.6 to 9.x, on PHP 7.4 to 8.3. No core override, no Composer dependency.
General configuration
Go to Modules → Visual Search & Shop the Look AI → Configure.
Choose the provider
Select the engine from the list, then enter the matching API key. You pay the AI as you go with the provider, with no subscription added by the module.
- Voyage and Cohere: direct multimodal image embeddings.
- OpenAI and Mistral: vision analysis then embedding, and additionally unlock Shop the Look.
- API key: stored server-side, never exposed to the front office. Each provider has its own configurable model and vector dimension.
After saving the provider and key, use the Test provider button in the index panel to validate the connection before indexing.
Behavior
- Number of results: how many products to show for an image search.
- Minimum similarity (0–1): 0 shows everything ranked by relevance; raise it (e.g. 0.2 to 0.4) to drop weak matches. Tune per provider.
- Enable Shop the Look and products per detected item.
- Similar products on the product page and their count.
- Inject the camera button in the header, or place it manually in your theme with the
displayDfVisualSearchButtonhook. - Maximum upload size and automatic re-indexing when a product is saved.
Index the catalog
In the Catalog index panel of the configuration:
- Click Index / re-index catalog: the module processes products in batches, with a progress bar, with no risk of server timeout.
- The counter shows products indexed for the active provider.
- Clear index removes the vectors for the current shop.
Indexing turns each product’s cover image into a vector stored in the database. Once indexed, a product is only re-encoded if its image changes.
The cosine-similarity search runs server-side and stays smooth up to about 10,000 products, with no external vector database to host.
How the search works
Each image is turned into a normalized vector (embedding). The customer’s photo is encoded by the same provider, then compared against the index using cosine similarity — which, on normalized vectors, reduces to a plain dot product. Products are then ranked by descending score and filtered by the configured minimum threshold.
- Voyage and Cohere encode the image directly.
- OpenAI and Mistral describe the image with a vision model, then embed that description: indexing and querying therefore live in the same vector space.
Shop the Look
From a scene photo, Shop the Look identifies every visible item and runs a per-item search, presenting the results in distinct groups.
Multi-item detection requires a vision provider (OpenAI or Mistral). With Voyage or Cohere, Shop the Look gracefully falls back to a whole-image “full look” similarity.
Visually similar products
On the product page, a “visually similar products” block appears automatically. It reuses the vector already computed when the product was indexed: no extra request is sent to the AI, so the recommendation adds no recurring cost.
Customer-facing display
The camera button opens a modal where the customer drags and drops a photo or selects one. A preview appears, then the results show as product cards with their similarity score as a percentage. If Shop the Look is enabled, the customer can tick the option to get results grouped by detected item.
Choosing a provider
Every provider handles image search. The choice depends on your needs:
- Voyage / Cohere: direct multimodal embeddings, simple and fast, without Shop the Look.
- OpenAI / Mistral: vision analysis that unlocks Shop the Look’s multi-item detection.
Each provider produces a different vector space and dimension. After changing the active provider, re-index the catalog. Vectors from other providers are kept but ignored at search time; the back office shows the number of products indexed for the current provider.
Compatibility and technical notes
- PrestaShop 1.7.6 to 9.x, multistore and multilingual; each shop keeps its own index.
- Legacy admin controller (no Symfony controller) for PS8/PS9 compatibility.
- Hooks used:
displayHeader,displayTop,displayDfVisualSearchButton,displayFooterProduct,actionProductSave,actionProductDelete. - Vectors stored normalized in the database, encoded for robust storage; search by dot product.
- A per-session anti-abuse throttle protects your AI quota.
- AJAX search endpoint via the module link; JSON response.
FAQ and troubleshooting
The search button does not appear. Check that a provider is configured and its key is valid (Test provider button), then that header injection is enabled or the hook is placed in your theme.
The search returns no results. Make sure the catalog has been indexed for the active provider, and lower the minimum similarity if it is too high for the provider’s vector space.
Shop the Look returns a single group. The active provider does not support detection (Voyage or Cohere). Switch to OpenAI or Mistral for multi-item detection, then re-index.
I changed provider and the results are inconsistent. Run a full re-index: the vectors must be recomputed in the new provider’s space.