User Guide - Magento 2 AI Search

User Guide

Welcome to Magehq Docs

MageHQ AI Search for Magento 2 User Guide

MageHQ AI Search is an AI-powered product discovery extension for Magento 2. It improves the default Magento search experience with semantic search, hybrid ranking, smart autocomplete, typo correction, query expansion, synonyms, smart filters, dynamic facets, merchandising rules, search redirects, analytics, and index management tools.

This guide explains how to install, configure, and use MageHQ AI Search in your Magento 2 store.

1. Requirements

  • Magento Open Source or Adobe Commerce 2.4.6 or later
  • PHP 8.1 or later
  • OpenSearch or Elasticsearch configured for Magento native search fallback
  • MageHQ Core module
  • MageHQ AI Commerce Client module
  • A valid AI provider configuration or MageHQ AI Commerce OS subscription

2. Installation

Step 1: Upload the Module

Upload the module files to the following Magento directory:

app/code/Magehq/AISearch

If your package also includes MageHQ Core or MageHQ AI Commerce Client, upload them as well:

app/code/Magehq/Core
app/code/Magehq/AICommerceClient
app/code/Magehq/AISearch

Step 2: Enable the Module

Run the following commands from your Magento root directory:

php bin/magento module:enable Magehq_AISearch
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

For production mode, also deploy static content:

php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Step 3: Verify Module Status

php bin/magento module:status Magehq_AISearch

The module should appear in the enabled module list.

3. Admin Menu

After installation, go to:

MageHQ > AI Search

The module includes the following admin pages:

  • Dashboard: View search KPIs, top searches, no-result opportunities, slow searches, fallback usage, and embedding coverage.
  • Analytics: Review search queries, corrected queries, result counts, clicks, add-to-cart events, orders, and conversion rates.
  • Synonyms: Manage one-way and two-way synonym rules.
  • Merchandising Rules: Boost, bury, pin, hide, or custom-sort products for specific search queries.
  • Search Redirects: Redirect search keywords to custom URLs, CMS pages, categories, or products.
  • Index Management: Reindex products, check provider status, view queue jobs, retry failed jobs, clear AI Search cache, and rebuild analytics aggregates.
  • Settings: Configure AI Search options.

4. General Configuration

Go to:

Stores > Configuration > MageHQ > AI Search

General Settings

Field Description Recommended Value
Enable Module Enable or disable MageHQ AI Search. Yes
Provider Mode Select how AI provider requests are handled. MageHQ AI Commerce OS / Subscription
Legacy AI Provider Used only when Provider Mode is set to Legacy Custom Provider. OpenAI
Legacy API Key API key for the selected legacy provider. Your provider API key
Legacy API Endpoint Provider API endpoint used in legacy mode. https://api.openai.com/v1
Request Timeout Timeout for non-autocomplete AI requests. 10
Embedding Model Model used to generate product embeddings. text-embedding-3-small
Correction Model Model used for typo correction and query correction. gpt-4o-mini
Batch Size Number of products processed per embedding batch during reindex. 50

If you use MageHQ AI Commerce OS / Subscription mode, provider routing, API keys, quota, and usage tracking are managed by MageHQ AI Commerce Subscription. In this mode, you do not need to enter a legacy API key.

5. Feature Configuration

The Features section controls the main storefront search behavior.

Field Description Recommended Value
AI Only on No Results Runs AI fallback only when native Magento search returns no products. This is useful for performance-focused stores. Yes
Enable Semantic Search Allows the module to understand the meaning behind search queries. Yes
Enable Hybrid Search Combines keyword relevance and semantic relevance. Yes
Enable Autocomplete Displays AI-powered suggestions while shoppers type. Yes
Enable Typo Correction Corrects misspelled search queries. Yes
Enable Query Expansion Expands queries with related terms to improve discovery. Yes
Enable Search Analytics Collects search performance data. Yes
Correction Minimum Query Length Minimum query length before AI correction is used. 4
Correction Timeout Short timeout for AI correction so autocomplete can fall back quickly. 3
Autocomplete Debounce Delay Delay after typing stops before the autocomplete request is sent. 300–350 ms

6. Embedding Configuration

Embeddings are used for semantic search. They help the search engine understand product meaning, not only exact keywords.

Field Description Recommended Value
Minimum Query Length Minimum characters required before AI Search starts processing a query. 2
Maximum Autocomplete Suggestions Maximum number of suggestions shown in autocomplete. 8
Attributes Used for Embeddings Product attributes used to generate semantic vectors. Name, SKU, Short Description, Description, Meta Title, Meta Description, Manufacturer, Price, and other searchable attributes

After changing embedding attributes, run a full AI Search reindex.

7. Ranking Weights

Ranking weights allow merchants to control how search results are ordered. Higher values give more importance to that signal.

Weight Description Suggested Value
Keyword Weight Importance of keyword matching. 1.0
Semantic Weight Importance of AI semantic similarity. 1.0
Popularity Weight Boosts products with stronger search or sales popularity. 0.5
Conversion Weight Boosts products that convert better. 0.5
Stock Weight Boosts in-stock products. 0.25
Rating Weight Boosts higher-rated products. 0.25
Category Weight Boosts category-relevant products. 0.25
Sales Trend Weight Boosts products with stronger recent sales trends. 0.25

8. Smart Filters

Smart Filters extract product filters from natural language queries. For example, when a shopper searches for “red shoes under 100”, the module can detect color, category, and price intent.

Go to:

Stores > Configuration > MageHQ > AI Search > Smart Filters

Recommended settings:

  • Enable Smart Filters: Yes
  • Enable Price Extraction: Yes
  • Enable Brand Extraction: Yes
  • Enable Color Extraction: Yes
  • Enable Size Extraction: Yes
  • Enable Category Intent Extraction: Yes
  • Minimum Confidence Threshold: 0.75

For best results, only select option-based attributes such as color, size, manufacturer, brand, or material in the allowed attributes list.

9. Dynamic Facets

Dynamic facets return result-set-aware filters in REST and GraphQL responses without overriding Magento layered navigation.

Go to:

Stores > Configuration > MageHQ > AI Search > Facets

Recommended settings:

  • Enable Dynamic Facets: Yes, if you use REST or GraphQL search results with custom frontend rendering.
  • Enable AI Facet Selection: Yes, if you want facets to be prioritized based on shopper intent.
  • Maximum Facets: 6
  • Maximum Options Per Facet: 8
  • Show Price Facet: Yes
  • Show Category Facet: Yes

10. Cache and Performance

MageHQ AI Search includes cache options to keep autocomplete and repeated search requests fast.

Go to:

Stores > Configuration > MageHQ > AI Search > Cache

Recommended settings:

  • Cache Lifetime: 3600 seconds
  • Enable Autocomplete Cache: Yes
  • Autocomplete Cache TTL: 300–900 seconds

To clear only AI Search cache, use the admin button in Index Management or run:

php bin/magento magehq:aisearch:clear-cache

To also clear rate limit cache entries:

php bin/magento magehq:aisearch:clear-cache --include-rate-limits

11. Analytics

Search analytics helps merchants understand customer intent and improve product discovery.

Go to:

MageHQ > AI Search > Analytics

The analytics grid includes:

  • Search query
  • Corrected query
  • Result count
  • Product clicks
  • Add-to-cart events
  • Orders
  • Conversion rate
  • Last searched date

Recommended analytics settings:

  • Enable Analytics Collection: Yes
  • Analytics Retention Days: 365
  • Track Product Clicks: Yes
  • Track Add-to-Cart and Purchase Events: Yes
  • Track Autocomplete Events: No for high-traffic stores, unless detailed autocomplete reporting is required.
  • Anonymize Session Identifiers: Yes

12. Security

The module includes public endpoint rate limiting for anonymous autocomplete and API traffic.

Go to:

Stores > Configuration > MageHQ > AI Search > Security

Recommended settings:

  • Enable Public Endpoint Rate Limiting: Yes
  • Rate Limit Requests: 120
  • Rate Limit Window: 60 seconds

If Magento cache is unavailable, rate limiting fails open so storefront search can continue working.

13. Index Management

Before AI Search can return semantic results, product embeddings must be generated.

Go to:

MageHQ > AI Search > Index Management

This page displays:

  • Total products
  • Indexed products
  • Products missing embeddings
  • Pending index jobs
  • Failed index jobs
  • Last full reindex time
  • Last partial reindex time
  • Provider status
  • Vector storage status
  • Average embedding generation time
  • Last error message

Available Admin Actions

  • Reindex All: Reindex all products.
  • Reindex Selected Store: Reindex all products for a specific store ID.
  • Reindex Product IDs: Reindex selected product IDs for a selected store ID.
  • Retry Failed Jobs: Retry failed embedding jobs.
  • Clear AI Search Cache: Clear AI Search cache only.
  • Check Provider: Test whether the configured AI provider is reachable.
  • Rebuild Analytics Aggregates: Rebuild dashboard analytics summaries.

14. CLI Commands

Reindex All Products

php bin/magento magehq:aisearch:reindex

Reindex a Specific Store

php bin/magento magehq:aisearch:reindex --store=1

Reindex a Specific Product

php bin/magento magehq:aisearch:reindex --product-id=123

Reindex Multiple Products

php bin/magento magehq:aisearch:reindex --store=1 --product-ids=123,124

Dry Run Before Reindex

Use dry run to validate the command without generating embeddings or writing vectors.

php bin/magento magehq:aisearch:reindex --store=1 --product-ids=123,124 --dry-run

Test a Search Query

php bin/magento magehq:aisearch:test-query "red summer dress"

Test a Store-Scoped Query

php bin/magento magehq:aisearch:test-query --store=1 "red summer dress"

Check Provider Status

php bin/magento magehq:aisearch:check-provider

Clear AI Search Cache

php bin/magento magehq:aisearch:clear-cache

Sync Synonyms

php bin/magento magehq:aisearch:sync-synonyms

Rebuild Analytics

php bin/magento magehq:aisearch:rebuild-analytics

Clean Old Analytics Data

php bin/magento magehq:aisearch:analytics:cleanup

Clean analytics older than a custom number of days:

php bin/magento magehq:aisearch:analytics:cleanup --days=180

15. Synonyms

Synonyms help shoppers find the same products using different words.

Go to:

MageHQ > AI Search > Synonyms

Create a Synonym

  1. Click Add New Synonym.
  2. Select the store view.
  3. Enter the source term.
  4. Enter target terms.
  5. Select direction.
  6. Enable the synonym.
  7. Click Save.

Synonym Direction

  • One Way: The source term expands to target terms only.
  • Two Way: The source term and target terms can match each other.

Example

Source Term Target Terms Direction
sneaker trainer, running shoe Two Way
mobile phone smartphone, cell phone Two Way
t shirt tee shirt, tee One Way

16. Merchandising Rules

Merchandising rules allow merchants to control search results for business goals.

Go to:

MageHQ > AI Search > Merchandising Rules

Available Actions

  • Boost: Increase product ranking for matched queries.
  • Bury: Lower product ranking for matched queries.
  • Pin: Place selected products in a specific position.
  • Hide: Remove selected products from matched search matched queries.
  • < results.
  • Boost Category: Boost products from selected categories.
  • Boost Brand / Manufacturer: Boost products by brand or manufacturer.
  • Boost In-Stock Products: Prefer in-stock products.
  • Boost Sale Products: Prefer products on sale.
  • Boost New Products: Prefer new products.
  • Boost High-Margin Products: Prefer high-margin products when configured.
  • Apply Custom Sort Override: Apply a custom sort rule.

Create a Merchandising Rule

  1. Click Add New Merchandising Rule.
  2. Enter a rule name.
  3. Enter a query pattern, for example running shoes.
  4. Select query match type: Exact Match, Contains, Starts With, or Regular Expression.
  5. Select the action: Boost, Bury, Pin, Hide, or another available action.
  6. Enter boost value, priority, product IDs, category IDs, or attribute conditions if needed.
  7. Select store view and customer group.
  8. Set start date and end date if the rule is campaign-based.
  9. Enable the rule.
  10. Click Save.

Example Rules

  • Boost Running Shoes: Boost selected running shoes when the query contains “running shoes”.
  • Bury Out of Stock: Lower out-of-stock products in search results.
  • Pin Featured Brand: Pin selected brand products near the top of search results.

17. Search Redirects

Search redirects send shoppers from a specific search query to a custom destination.

Go to:

MageHQ > AI Search > Search Redirects

Target Types

  • Custom URL: Redirect to any custom URL.
  • CMS Page: Redirect to a CMS page.
  • Category: Redirect to a category page.
  • Product: Redirect to a product page.

Create a Search Redirect

  1. Click Add New Redirect.
  2. Enable the redirect.
  3. Enter the query or keyword.
  4. Select match type: Exact, Contains, or Starts With.
  5. Select target type.
  6. Enter the target value.
  7. Select store view and customer group.
  8. Set priority.
  9. Set active from and active to dates if needed.
  10. Click Save.

Example

Query Match Type Target Type Target Value
summer sale Exact Custom URL /summer-sale
nike Contains Category Category ID

18. Storefront Autocomplete

MageHQ AI Search automatically enhances the standard Magento mini search form when autocomplete is enabled.

The autocomplete panel may show:

  • Product suggestions
  • Product images
  • Product prices
  • Stock status
  • Category suggestions
  • Popular search terms
  • Corrected query suggestions
  • View all results link

If the autocomplete panel does not appear, check the following:

  • Enable Autocomplete is set to Yes.
  • The Magento search form uses the standard search_mini_form ID.
  • JavaScript is deployed and browser cache is cleared.
  • AI Search cache has been cleared.
  • No theme JavaScript overrides are blocking the Magento search form.

19. REST API

MageHQ AI Search provides REST endpoints for custom frontend, mobile app, and third-party integrations.

Search

GET /rest/V1/magehq-ai-search/search?q=bag

Alternative alias:

GET /rest/V1/magehq/aisearch/search?q=bag

Autocomplete

GET /rest/V1/magehq-ai-search/autocomplete?q=bag

Alternative alias:

GET /rest/V1/magehq/aisearch/autocomplete?q=bag

Track Product Click

POST /rest/V1/magehq-ai-search/click

Alternative alias:

POST /rest/V1/magehq/aisearch/track-click

Track Conversion

POST /rest/V1/magehq-ai-search/conversion

Alternative alias:

POST /rest/V1/magehq/aisearch/track-conversion

20. GraphQL API

The module also provides GraphQL queries for AI search and autocomplete.

AI Search Query

{
  magehqAiSearch(query: "red dress", pageSize: 10, currentPage: 1) {
    total_count
    corrected_query
    expanded_terms
    products {
      id
      sku
      name
      price
      url
      image
      vector_score
      final_score
    }
    suggestions {
      type
      title
    }
    facets {
      code
      label
      type
      options {
        value
        label
        count
        selected
      }
    }
  }
}

Autocomplete Query

{
  magehqAiAutocomplete(query: "bag") {
    query
    corrected_query
    expanded_terms
    products {
      id
      title
      sku
      price
      image
      url
      rating
      stock_status
      badge
    }
    categories {
      id
      title
      url
    }
    popular_searches {
      title
      num_results
    }
  }
}

21. Cron Jobs

Make sure Magento cron is running. MageHQ AI Search uses cron for queue processing, popular search refresh, analytics cleanup, and analytics statistics rebuild.

The module includes the following scheduled jobs:

  • Embedding queue processing: every 5 minutes
  • Popular search refresh: every hour
  • Analytics cleanup: daily
  • Search statistics rebuild: daily

To verify Magento cron:

php bin/magento cron:run

22. Troubleshooting

Provider Status Shows “Failing”

If the Index Management page shows provider status as failing:

  • Check whether the module is enabled.
  • Verify Provider Mode.
  • If using MageHQ AI Commerce OS, confirm the subscription and AI Commerce Client configuration.
  • If using Legacy Custom Provider, verify API key, provider, endpoint, and model names.
  • Run the provider check command:
php bin/magento magehq:aisearch:check-provider

Indexed Products Shows 0

If products are missing embeddings:

  • Run a full AI Search reindex.
  • Check cron status.
  • Check pending or failed jobs in Index Management.
  • Retry failed jobs.
  • Check the provider status.
php bin/magento magehq:aisearch:reindex

Autocomplete Does Not Show

  • Make sure Enable Autocomplete is set to Yes.
  • Flush Magento cache.
  • Redeploy static content in production mode.
  • Check whether the theme uses the standard Magento mini search form.
  • Check browser console errors.

Search Results Are Not Relevant

  • Reindex product embeddings.
  • Review Attributes Used for Embeddings.
  • Add synonyms for common customer search terms.
  • Adjust ranking weights.
  • Use merchandising rules to boost or bury products.
  • Review analytics and no-result queries.

No-Result Queries Still Appear

  • Add synonyms for related search terms.
  • Enable typo correction.
  • Enable query expansion.
  • Check smart filter configuration.
  • Create search redirects for campaign or brand terms.
  • Review catalog product names, descriptions, and searchable attributes.

Where to Find Logs

MageHQ AI Search logs are written to:

var/log/magehq_ai_search.log

Enable Debug Mode only while troubleshooting. Do not keep debug logging enabled permanently on high-traffic production stores.

23. Best Practices

  • Run a full reindex after installation and after changing embedding attributes.
  • Use AI Commerce OS / Subscription mode for provider routing, quota, and usage tracking.
  • Keep autocomplete debounce between 300 and 350 ms for a responsive storefront experience.
  • Use autocomplete cache on production stores.
  • Keep rate limiting enabled for public endpoints.
  • Use synonyms for common alternative terms, misspellings, and regional words.
  • Use merchandising rules for campaigns, best sellers, featured brands, and out-of-stock control.
  • Review analytics regularly to find no-result opportunities.
  • Keep session anonymization enabled for privacy-friendly analytics.
  • Use CLI test query before debugging storefront rendering.

24. Support

If you need help with installation, configuration, AI provider setup, indexing, or storefront compatibility, please contact MageHQ support.

When contacting support, include:

  • Magento version
  • PHP version
  • Module version
  • Provider mode
  • Screenshot of Index Management
  • Relevant logs from var/log/magehq_ai_search.log
  • Exact search query that caused the issue
Copyright © 2024 MageHQ