AI Semantic Search

Help shoppers find products by describing what they need. Combine semantic and keyword search, show quick product suggestions and review rescued or unanswered queries. Keep classic Magento search available when the AI path is unavailable.

Magento 2.4.7 – 2.4.9
PHP 8.2 – 8.5
Version 1.0.3

30% OFFAI-Powered

AI Semantic Search overview with real comparison UI using offline demo examples

Examples of natural-language shopping intent with semantic search comparison controls

AI Semantic Search insights with rescued queries and remaining gaps from demo data

AI Semantic Search suggestion review and approval screen using demo records

User guide Ask a question

Save 30%

One-off payment, with 12 months of updates.

12 months of new versions and fixes; the versions released in that time stay yours
Install with Composer, or download a zip from your account
Licence for one production domain, staging and development copies included
30-day money-back guarantee, refund policy

No subscription or automatic renewal. Keep using the versions included in your update period. Update and licence details

Composer package softaware/module-ai-semantic-search

What it does Setup & compatibility Questions & support

AI Semantic Search ~~Regular price $299~~$209

A customer asks for something to carry a laptop, while your catalogue calls the product a commuter backpack. AI Semantic Search adds meaning-based matching alongside Magento keyword search, helping connect that request to the product information you actually maintain.

Meet descriptive requests without losing precise queries

Start with Fallback mode: classic results remain the normal path, with semantic help when results are sparse or the request reads like natural language. Hybrid combines the two rankings more broadly. Off and Semantic-only are available for comparison and experiments.

Magento continues to handle product filters, sorting and pagination. Test exact SKUs and restrictive filters as well as descriptive requests. A visually similar or broadly related item is not a substitute for the correct technical part.

Give the search accurate product context

The indexed representation includes names, categories, descriptions, selected attributes and relevant variant information per store view. Choose activity, material, capacity and other useful facts. Changed content is re-embedded; optional AI keywords can supplement it.

Try requests such as something to carry my laptop, clothes for running in cold weather, what should I wear to yoga class and equipment for working out at home. Our blog includes all 12 suggested test queries. Each match needs catalogue evidence: a bottle should not claim to keep drinks cold without documented insulation.

Improve the journey while learning from it

Optional quick suggestions show relevant product candidates while the shopper types. Status & Index reports coverage and estimated indexing cost, and Compare Search Results places classic, semantic and final results side by side.

Search Insights shows rescued queries, remaining gaps, result counts and clicks, with CSV exports. For recurring zero-result requests, AI can propose a grounded synonym or category redirect. Staff approve before it writes Magento's native search data.

Requirements, costs and recovery

Magento Open Source or Adobe Commerce 2.4.7–2.4.9 with OpenSearch, PHP 8.2–8.5, SoftAware Core and AI Core. Use your own OpenAI or Voyage AI embedding key. OpenSearch k-NN is used where configured, with the documented MySQL fallback for smaller catalogues; Elasticsearch 8 is not plugged into this integration.

Repeated queries use the cache and new queries use provider embeddings. Optional keyword generation and suggestions are separate completion requests. Timeouts, a circuit breaker, rate limits and budgets fall back to classic results when needed.

Query processing involves the configured provider. Recognised email/phone queries are excluded, and insights do not retain customer, session or IP identifiers. Catalogue quality and similarity thresholds still determine relevance.

Read the 12 natural-language search examples and test them against representative products before enabling a broad mode.

See the workflow

Try the admin demo. Storefront examples are available on the Luma demo and Hyvä demo. Demonstration or offline-test data shows the workflow; evaluate AI matching and forecasts with your own representative catalogue.

Catalogue understanding

One searchable product representation per store view
Names, categories, descriptions and configured attributes
Relevant configurable variant values included
Changed text re-embedded instead of rebuilding identical data
Optional AI search keyword enrichment

Customer search

Off, Fallback, Hybrid and Semantic-only modes
Configurable semantic weight and similarity thresholds
Magento filters, sorting and pagination retained
Optional quick product suggestions under the search box
Classic search recovery when provider use fails or is limited

Merchant tools

Status and index coverage by store view
Indexing cost estimate before queuing work
Compare classic, semantic and combined results
Anonymous insights with rescued and zero-result queries
CSV exports for review by period and store view

Search improvement

Grounded synonym and category-redirect proposals
Merchant approval before native Magento search data is written
Discard suggestions that do not fit your catalogue
Actual product data determines whether a match is suitable

Privacy and operating limits

OpenAI or Voyage AI embeddings through AI Core
Cached repeated queries and changed-product indexing
Provider timeout, circuit breaker and rate limits
Shared and optional per-module budgets and usage tracking
Recognised email/phone queries excluded from provider use and insights

Questions before you install

Will it replace Magento keyword search?

Not in the recommended Fallback mode. It adds help when classic search is weak or a query is descriptive. Hybrid combines both rankings; Semantic-only is an optional experimental mode.

Can shoppers still filter and sort results?

Yes. The integration retains the Magento search filters, sort and pagination. Semantic candidates are selected before narrow filtering, so restrictive filters can reduce their number.

What happens if the AI provider is unavailable?

Timeouts, budgets and failure handling return shoppers to classic Magento results. That recovery does not guarantee a particular result quality or zero additional latency.

Can it find a laptop bag or cold-weather running clothes?

Those are useful test intents when the catalogue contains supporting descriptions, dimensions, activity and material data. They are not guaranteed rankings. The product must genuinely support the requirement.

Which search engine and provider do I need?

The supported Magento OpenSearch engine plus an OpenAI or Voyage AI embedding key. Elasticsearch 8 is not integrated. AI Core uses OpenSearch k-NN where available and a documented MySQL fallback for smaller setups.

Compatibility

Requirements and compatibility

Compatibility of AI Semantic Search
Magento	2.4.7 – 2.4.9
PHP	8.2 – 8.5
Latest version	1.0.3
composer.json requires	php ~8.2.0\|\|~8.3.0\|\|~8.4.0\|\|~8.5.0 ext-json * magento/framework ~103.0.7 softaware/module-core ^1.0 softaware/module-ai-core ^1.2 magento/module-backend * magento/module-catalog * magento/module-catalog-inventory * magento/module-catalog-search * magento/module-config * magento/module-configurable-product * magento/module-elasticsearch * magento/module-open-search * magento/module-search * magento/module-store * magento/module-url-rewrite *

Installation

Up and running in minutes

After you buy, create a Composer key in your account. Then, in the root of your Magento project:

01Add the repository and your key (once per project)

composer config repositories.softaware composer https://repo.softawarecommerce.com
composer config --auth http-basic.repo.softawarecommerce.com PUBLIC_KEY PRIVATE_KEY

02Install the module

composer require softaware/module-ai-semantic-search

03Enable it

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

The last three are only needed in production mode.

Prefer a zip? Every version you are entitled to can be downloaded from My modules. More about Composer access

User guide

How to set up and use AI Semantic Search

For version 1.0.3. The same guide comes with the module, in docs/user-guide.md.

1. Before you start

Install and set up AI Providers & Costs (Softaware AI Core): add an OpenAI or Voyage AI API key under Stores > Configuration > Softaware > AI > AI Providers & Costs > Embeddings, and set a monthly budget if you like.
Magento must use OpenSearch (Stores > Configuration > Catalog > Catalog > Catalog Search). If the OpenSearch k-NN plugin is installed, AiCore stores the vectors there automatically; otherwise in MySQL (fine up to about 5,000 products per store view).

2. Switch it on

Softaware > AI Semantic Search > Settings

Enabled = Yes (default scope, or per store view).
Search Mode = Fallback to start. Classic results stay exactly as before; semantic results are added only when classic search finds fewer than 5 products or the query reads like a sentence.
Check Document Attributes: the attributes that describe your products in words (colour, material, activity, style, features). Leave the label empty to use the attribute's label.
Save. Then open Status & Index and click Estimate Cost: it shows how many products will be embedded and what it costs. Click Queue Full Reindex; AiCore's cron job embeds the products every 5 minutes (or run bin/magento softaware:semantic-search:reindex --yes).

Coverage on the Status page reaches 100 % when every searchable product of a store view has a vector.

3. Try it

On Status & Index, Compare Search Results shows three lists for any query: classic search, semantic hits (with similarity) and what shoppers get. Good queries to try on Luma sample data:

bag for a laptop and gym clothes
comfortable shoes for running in summer
rucksack (the catalogue says "backpack")
something warm for winter hiking
waterproof jacket for rain

If unrelated products appear, raise Minimum Similarity (e.g. 0.35). If too few semantic products appear, lower it or Relative Similarity.

4. Choosing a mode

Mode	When
Fallback	Recommended. Keyword searches unchanged, help where classic search fails. AI cost only for those queries.
Hybrid	Catalogues with descriptive products (fashion, gifts, furniture) where meaning matters for most queries.
Semantic only	Experiments; SKU and exact-name searches can get worse.

Semantic Weight (Hybrid and natural-language queries in Fallback): 50 % = classic and semantic rankings count equally; higher favours meaning over exact words.

5. Quick search suggestions

With Show Semantic Product Suggestions = Yes, a "Products you might like" box appears under the search box while shoppers type (after 3 characters and a short pause). Magento's own search term suggestions stay as they are.

6. Search Insights

Softaware > AI Semantic Search > Search Insights (last 7/30/90/365 days, per store view):

Rescued by Semantic Search: classic search found nothing or little; semantic results filled the page.
Still Without Results: nothing found at all: ideas for products, synonyms or redirects.
Top Queries: with classic, semantic and shown result counts and clicks.

Each list has Export CSV. No customer, session or IP data is stored. Queries containing an e-mail address or a phone number are not recorded and never sent to the AI (shoppers get classic results for them).

7. Synonym and redirect suggestions

Softaware > AI Semantic Search > Suggestions → Generate Suggestions. For zero-result queries searched at least twice, the AI proposes a synonym group (e.g. "rucksack, backpack") or a redirect to a category, using the products semantic search found as grounding. Review each one: Approve writes it to Marketing > SEO & Search > Search Synonyms (store view) or Search Terms (redirect); Discard hides it.

8. Safety and costs

One embedding per new query; repeated queries come from the cache (7 days).
If the AI is slow (more than the timeout, default 1.5 s), fails, the budget is used up or a rate limit is hit, shoppers get classic results. After an error the AI is paused for 60 s so an outage never slows every search.
AI search keywords (Indexing) and suggestions are optional completions; all costs are in AI Usage & Costs.

9. Troubleshooting

Symptom	Check
Coverage stays at 0 %	AiCore cron running? API key set? `bin/magento softaware:ai:vectors:status`
Compare shows "AI status: not_configured"	No API key for the embedding provider
"AI status: circuit_open"	An AI error happened in the last minute; see `var/log/system.log`
Results did not change	Search Mode Off for the store view, or Fallback with enough classic results (by design)

Changelog

Release notes

1.0.3

Latest

Settings moved back to the Softaware tab of Stores > Configuration, listed in the collapsible "AI" group (Softaware Core 1.2.0 section groups) instead of a separate "Softaware AI" tab. Requires softaware/module-ai-core ^1.2.

1.0.2

Settings moved to the new "Softaware AI" tab of Stores > Configuration (provided by AI Core 1.1.0), which groups the settings of all SoftAware AI modules. Requires softaware/module-ai-core ^1.1.

1.0.1

1.0.1 (2026-10-10)

Fixed

AI requests leave room for the model's thinking: current Claude models always think and count those tokens in the output limit, so an answer could be cut off ("Allow more output tokens") and the run was lost after it had been paid for. The output limit is only a ceiling; unused tokens are not charged.

1.0.0

1.0.0 (2026-10-10)

Added

AiCore vector profile semantic_search: one text vector per product and store view (name, categories, chosen attributes incl. configurable variants' values, short description, description with HTML removed and a length cap, optional AI search keywords). Re-embedded only when the text changes (AiCore hash).
Hybrid search on the storefront search results page (Luma and Hyvä) through a plugin on Magento's OpenSearch query mapper: modes Off, Fallback, Hybrid (weighted reciprocal rank fusion) and Semantic only per store view. Filters, layered navigation, sorting, pagination and visibility rules keep working.
Guards: AiCore query vector cache (embedQuery() / getCachedQuery()), latency budget (default 1.5 s, no retry, millisecond timeout) with classic fallback, circuit breaker after AI errors, rate limits per shop and per visitor (AiCore RateLimiterInterface, also for the insights beacon), AiCore budget check incl. module limits, no-cache headers for pages where the AI was skipped for a passing reason.
Semantic product suggestions under the quick search box (Luma and Hyvä, vanilla JS, publicly cacheable JSON with product cache tags, so a saved or disabled product leaves the cached answers).
Personal data guard: queries containing an e-mail address or phone number are answered by classic search only, never sent to the AI provider (search, suggestions, synonym suggestions) and never stored in the insights.
Search insights (anonymous): latest classic / semantic / shown result counts per query, searches and clicks per day, rescued queries, queries still without results, CSV export, nightly clean-up.
Synonym and redirect suggestions for zero-result queries (AI, grounded on the semantic neighbours); written to Magento's search synonyms or search term redirects only after approval.
Admin: Status & Index (coverage per store view, backend, model, cost estimate, queue full reindex, compare classic / semantic / blended results), Search Insights, Suggestions, Settings; own ACL resources.
CLI: softaware:semantic-search:status|reindex|query|suggestions.
Built on the shared AiCore APIs only: index status, queue and estimate via VectorIndexStatusInterface, reindex via ProductVectorIndexInterface, AI cost panel on Status & Index, offline responders for keyword and synonym suggestions (AiCore offline test doubles replace the former developer embeddings; old setting migrated).

Support

Help from the developers who wrote it