Semantic search

Optional embeddings and vector search understand intent beyond literal keywords, with OpenAI, Cohere or a self-hosted endpoint. It is off by default and falls back to keyword search whenever it is not switched on.

What it does

By default, product search is keyword based. A shopper who types "something warm for winter" only matches products whose text contains those words. Semantic search adds a second leg: it converts the query into a vector with an embeddings provider, scans a vector index built from your catalogue, and fuses the two ranked lists. The result is that "something warm for winter" can find the fleece even when the listing never uses the word warm.

The two legs run together as a hybrid. Keyword matching keeps exact terms precise, while the vector leg adds meaning, so you get the strengths of both rather than replacing one with the other.

Turning it on

Open WooCommerce, Fahad AI and enable the Semantic Search setting. Then build the index once so there are vectors to scan. After that, the index updates as products change.

1. Tick Enable semantic search.
2. Choose an embeddings provider and add its key.
3. Click Build / rebuild index.

Choosing an embeddings provider

The embeddings provider is separate from your chat provider, so you can mix and match. Three options are supported:

• OpenAI (default). Uses text-embedding-3-small at 512 dimensions out of the box. You can reuse your existing chat OpenAI key or set a dedicated embeddings key.
• Cohere, which is stronger for non-Latin scripts such as Urdu. It defaults to the embed-multilingual-v3.0 model.
• OpenAI-compatible endpoint, which works with any service that exposes an /embeddings endpoint: Moonshot, Together, or a self-hosted server. Set the base URL and key to reuse a key you already have.

For the self-hosted or compatible route, point the base URL at your endpoint:

Embeddings provider:  OpenAI-compatible
Embeddings base URL:  https://your-host.example/v1
Embeddings key:       sk-...your-endpoint-key...

Only product text, such as titles, descriptions and attributes, is sent to the provider to build the index. Prices, stock and customer data are never sent. Review the chosen provider's privacy policy before enabling.

Where vectors are stored

The plugin picks the best vector store for your host automatically, and you can override it for large catalogues. There are three tiers:

• Built-in postmeta store. The default. Vectors live in WordPress post meta and the scan runs in PHP. No extra infrastructure, and it works on a typical MySQL host.
• Native MariaDB vectors. When MariaDB 11.7 or newer is detected, the index uses the database's native vector search instead of the PHP scan. This is auto-detected, so most stores get it without changing anything.
• External Qdrant. For very large catalogues that outgrow the database backends, point the index at a managed or self-hosted Qdrant server by setting its URL, collection and key. Only vectors and product IDs are stored there: no product text and no customer data.

Index health

The settings screen reports the state of the index so you are never guessing whether it is current. It shows:

• The number of products indexed.
• When the index was last built.
• A failure count when embedding requests have errored.
• A clear rebuild needed prompt when you change the embedding model, since a model change means the existing vectors no longer match.

Embedding requests retry transient errors, such as rate limits and timeouts, with backoff, and repeated identical searches reuse a cached query embedding for a few minutes to keep costs down.

If something is not configured

Semantic search degrades cleanly. With no embeddings provider, an empty index, or the feature switched off, the retriever returns nothing extra and plain keyword search runs as usual. You can enable it, test it, and turn it back off at any time without breaking search.