AI Semantic Search for PrestaShop

This module adds AI-powered semantic search to your PrestaShop store. Instead of matching keywords literally, it understands the meaning of the customer’s query through vector embeddings and surfaces relevant products, even without an exact match.

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 three tables (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log) 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.

The counters show the number of indexable entries (products × languages), vectors already indexed, pending entries and the number of cached query embeddings.

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 catalog updates, 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 or those detached from the store, as well as disabled languages, are automatically cleaned from the index.

Storefront search

Enable Front office autocomplete to attach a semantic suggestions menu to your theme’s search bar.

CSS selector

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. For a custom theme, adjust this selector to your theme’s search field.

Hybrid mode

With hybrid mode enabled (recommended), the module combines the semantic score with a keyword match on the product name. Exact name matches are thus favored, without sacrificing semantic relevance.

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 number of suggestions displayed.

Analyzing searches

Every search is logged (query, language, store, number of results, best score). This data helps you understand what your customers are really looking for and spot no-result queries to enrich your catalog.

Query cache

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

Troubleshooting

• No results appear: check that the index is built (the “Vectors indexed” counter is > 0) and that the API key is valid.
• Autocomplete does not show: check the CSS selector and that autocomplete is enabled. Detailed error messages are recorded in the PrestaShop logs.
• Timeouts during indexing: reduce the batch size and prefer cron indexing.
• Inconsistent results after a model change: run a full index rebuild.