# AI Semantic Search for PrestaShop

> This module adds AI-powered semantic search to your PrestaShop store: autocomplete, search results page, "You may also like" block on the product page and analytics dashboard all share the same…

- Page: <https://www.datafirefly.com/en/documentation/ai-semantic-search-prestashop/>
- Language: en
- Last updated: 2026-10-11
- Other languages: [fr](https://www.datafirefly.com/documentation/recherche-semantique-ia-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), [pt](https://www.datafirefly.com/pt/documentation/recherche-semantique-ia-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/recherche-semantique-ia-prestashop/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

This module adds AI-powered semantic search to your PrestaShop store: autocomplete, search results page, "You may also like" block on the product page and analytics dashboard all share the same meaning-based ranking, computed with vector embeddings.

## Requirements

- PrestaShop 8.0 to 9.x
- PHP 7.4 to 8.3 with the cURL extension enabled
- An API key from an embedding provider: OpenAI, Mistral AI, or any OpenAI-compatible gateway

## Installation

1. In the back office, open **Modules > Module Manager**.
2. Click **Upload a module** and upload the ZIP file.
3. Once installed, click **Configure**.

The module creates four tables (`dfvectorsearch_index`, `dfvectorsearch_qcache`, `dfvectorsearch_log`, `dfvectorsearch_similar`) and a hidden tab for its AJAX calls. Nothing is visible on the storefront until the index is built.

## Configuring the embedding provider

In the **Settings** tab, choose your provider and enter your API key.

### OpenAI

Select the **OpenAI** provider and enter your key. The recommended model is `text-embedding-3-small` (good quality/price ratio). For maximum precision on a demanding catalog, you can use `text-embedding-3-large`.

### Mistral AI (European hosting)

Select **Mistral AI** for data processing in Europe, GDPR-compliant. The model to use is `mistral-embed`.

### OpenAI-compatible gateway

Select **Custom** to use your own gateway (internal proxy, Azure OpenAI, etc.). Then enter the API base URL, for example `https://my-gateway.example.com/v1`.

The API key is masked after saving. Leave the masked value untouched to keep the existing key; enter a new key only if you want to replace it.

### Dimensions

The **Dimensions** field lets you reduce the vector size to speed up search on very large catalogs. Leave it at `0` to use the model's default size. OpenAI text-embedding-3 models support reduced dimensions (for example 512).

Changing the provider, model or number of dimensions makes the whole index stale: on save, the index is automatically flagged for a full rebuild and the query cache is cleared. Run indexing again afterward.

## Building the index

After saving the API key, go to the **Embedding index** box at the top of the configuration page.

1. Click **Index now**. The module processes products in batches with a progress bar, language by language and store by store.
2. Leave the page open until the status shows _Index up to date_.

### Batch size

The **Indexing batch size** setting controls how many products are processed per call (5 to 100). Lower it if your server hits timeouts.

### Scheduled indexing (cron)

To keep the index automatically in sync with the catalog, copy the **Cron indexing URL** shown in the configuration and call it regularly (for example every 15 minutes) from your hosting's task scheduler.

The URL contains a security token. Each call works for about twenty seconds then stops cleanly, to stay compatible with PHP execution time limits.

## How re-indexing works

Each time a product is added, updated or deleted, the corresponding entry is flagged for re-indexing. The module computes a checksum of the product text: if only the price or stock changed, the text stays identical and **no new API call is triggered**. Disabled products and disabled languages are automatically cleaned from the index.

## Storefront search

### Autocomplete

Enable **Front office autocomplete** to attach a semantic suggestions menu to your theme's search bar. The **Search input CSS selector** field tells the module which field to attach to. The default value `#search_widget input[type="text"]` works with classic-based themes.

### Disabling the theme autocomplete

The **Disable the theme autocomplete** setting (enabled by default) removes the native search suggestions (ps_searchbar and lookalikes) to avoid a double dropdown. The module unregisters the native script and hides any dropdown injected by a custom theme.

### Hybrid mode

With **hybrid mode** enabled (recommended), the semantic ranking comes first and the missing native keyword results are appended after. You never get fewer results than the original search.

### Threshold and result count

The **minimum similarity score** (between 0 and 0.99; recommended: 0.30) discards results that are too distant. The **maximum results** field limits the suggestions shown in the autocomplete.

## The search results page

The **Take over the search results page** setting (enabled by default) makes the module provide the search page ranking through the `productSearchProvider` hook, PrestaShop's official mechanism used by faceted navigation. Concretely:

- the autocomplete and the page show the same products, in the same order;
- the theme's pagination and sorting keep working (the "relevance" sort keeps the semantic order; price, name and date are re-applied within the ranking);
- if the embedding API is unavailable, the module silently falls back to native results and logs the incident: the search page never breaks.

The module only triggers on a text search. Categories, tag pages and other listings keep their native mechanisms.

## Similar products (You may also like)

The **Similar products block** (enabled by default) shows on each product page a "You may also like" section computed by semantic proximity between the vectors already stored in your database. No API call is made: the block even works without an API key as long as the index exists.

- **Number of similar products**: 2 to 12 (default 6).
- **Similar products minimum score**: a dedicated threshold, independent from the search one (recommended: 0.45). Below it, the product does not appear, even if that means fewer cards. Changing it automatically clears the similar products cache.
- An affinity bonus favors products sharing the default category and the brand.
- Results are cached for 24 hours per product and invalidated automatically on re-indexing.
- The rendering uses your theme's native miniatures: flags, wishlist, quick view and hover styles included.

On a small demo catalog where every product shares the same marketing copy, similarities are naturally looser. Raise the threshold to 0.55-0.60 to keep only close matches.

## Statistics and analytics

The configuration page shows a dashboard computed over the last 30 days: number of searches, zero-result rate, average results per search, daily volume histogram, top 20 queries (count, average results, best score) and top 20 zero-result queries.

Zero-result queries are a goldmine: they tell you exactly what your customers search for without finding it, and therefore what to add to your catalog or your synonyms.

- The **Export CSV** button downloads the full log (semicolon separator) with each search's source: autocomplete or results page.
- The log is automatically pruned after 365 days.

## Query cache

Customer query embeddings are cached for 30 days. Repeated searches are instant and are not re-billed by the provider. The **Clear query cache** button lets you reset it at any time.

## Updating the module

If you update the module by replacing its files (outside the Module Manager), open the configuration page once: the module then automatically registers missing hooks, creates missing tables and columns, and sets new defaults. Front CSS and JS files embed a cache-buster, so no browser cache clearing is needed.

## Troubleshooting

- **No results appear**: check that the index is built (the "Vectors indexed" counter is > 0) and that the API key is valid.
- **Two dropdowns show up**: check that **Disable the theme autocomplete** is enabled, then clear the PrestaShop cache once.
- **Autocomplete and results page differ**: open the module configuration page once (the results page hook gets registered automatically), and check that **Take over the search results page** is enabled.
- **The You may also like block is empty**: the index must be built for the current language and store; otherwise lower the similar products minimum score.
- **Timeouts during indexing**: reduce the batch size and prefer cron indexing.
- **Inconsistent results after a model change**: run a full index rebuild.