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