📑 У цій статті

  1. Що знадобиться (5-хвилинний чек-лист)
  2. Крок 1: Реєстрація і отримання license key
  3. Крок 2: Завантаження aisearch.ocmod.zip
  4. Крок 3: Установка через OpenCart Installer
  5. Крок 4: Modifications Refresh (важливо!)
  6. Крок 5: Активація модуля + license key
  7. Крок 6: Reindex каталогу
  8. Крок 7: Перевірка на frontend
  9. Troubleshooting типових проблем
  10. FAQ

Установка AI Search v1.0.5 на OpenCart 3 або 4 займає реально 5 хвилин активного часу плюс 30-90 хвилин фонової reindex (магазин при цьому не падає). Не потрібно знань програмування — все через стандартний OpenCart Installer. Поетапно, з реальними скріншотами адмінки.

Що знадобиться

5 хв
активної роботи
OC 3+
або OpenCart 4
FTP/SSH
не потрібно
$0
для до 200 SKU
  • Доступ адміністратора до вашого OpenCart-магазину (admin URL + логін)
  • Версія OpenCart 3.0.x або 4.0.x
  • ~5 хвилин активної роботи (більшість часу — фоновий reindex)
  • Жодного знання PHP, FTP, SSH чи коду

Крок 1: Реєстрація і отримання license key

  1. Перейдіть на ai-search.cc/register
  2. Зареєструйтесь через Google (один клік) або email + пароль
  3. Виберіть тариф: Free (до 200 SKU безкоштовно) для тестування, або платний для production
  4. У кабінеті: Licenses → побачите ваш license key (формат: XXXXXXXX-XXXXXXXX-XXXXXXXX, наприклад VMILJRPH-G1T5F7PM-IO4MMSUD)
🔑
License key прив'язаний до домену. Якщо ви тестуєте на dev-магазині (dev.shop.com) і хочете перенести на production (shop.com) — у кабінеті можна вільно змінити домен у налаштуваннях ліцензії.

Крок 2: Завантаження aisearch.ocmod.zip

  1. У кабінеті: Downloads
  2. Кнопка "Download aisearch.ocmod.zip" — завантажує zip-архів (~450 КБ)
  3. Файл називається aisearch.ocmod.zip — НЕ розпаковуйте! OpenCart-installer працює з zip-архівом

Крок 3: Установка через OpenCart Installer

  1. В адмінці OpenCart: Extensions → Installer
  2. Натисніть кнопку Upload (синя кнопка вгорі справа)
  3. Виберіть завантажений aisearch.ocmod.zip
  4. Дочекайтесь "Success: You have modified extensions!" (зазвичай 5-15 секунд)
⚠️
Якщо отримуєте "Permission Denied": у деяких хостингах не вистачає прав запису. Перейдіть в System → Users → User Groups → Administrator → ввімкніть Access permission для extension/installer. Збережіть і спробуйте знову.

Крок 4: Modifications Refresh

Цей крок ключовий — без нього модуль не активуються event hooks.

  1. В адмінці: Extensions → Modifications
  2. Натисніть кнопку Refresh (помаранчева, вгорі справа)
  3. Дочекайтесь "Success: You have modified modifications!"
❌
Найчастіша помилка: "встановив модуль — фільтри не з'являються". У 99% випадків — забули Refresh modifications. Без цього кроку OpenCart не активує наші event hooks.

Крок 5: Активація модуля + license key

  1. В адмінці: Extensions → Extensions → Modules
  2. Знайдіть AI Search у списку, натисніть зелену кнопку Install (плюсик)
  3. Після встановлення натисніть синю кнопку Edit (олівець)
  4. В адмін-панелі модуля:
    • License Key: вставте з кабінету (Ctrl+V)
    • Status: Enabled
    • Default Language: виберіть основну мову (UA / RU / EN)
    • Active Stores: вкажіть магазини якщо у вас multistore
  5. Кнопка Save

Крок 5.1: Активація AI Filters (опціонально)

AI Filters — фасетні фільтри — поставляються разом з основним модулем. Активуються через окрему вкладку у головному модулі:

AI Search Filters → General — налаштування орієнтації та AJAX режиму
Filters → General: вибір орієнтації (горизонтальна / вертикальна) та AJAX-режиму
  1. В адмінці AI Search відкрийте вкладку Filters → General
  2. Status: Enabled → оберіть Orientation (Vertical column_left для більшості тем) → AJAX mode: ON
  3. Перейдіть на під-вкладку Filters to show щоб налаштувати які групи фільтрів показувати
AI Search Filters → Filters to show — категорії, бренди, OC Filter Groups, атрибути, ціна, наявність
Filters to show: Categories, Brands, OC Filter Groups, Attributes, Price range, Stock availability — drag-to-reorder

Крок 6: Reindex каталогу

Без reindex модуль працює як стандартний LIKE-fallback. Щоб увімкнути semantic-пошук — індексуємо товари (детальніше про процес — у Documentation):

AI Search Indexer tab — Products progress bar 100%, what to index, languages selector
Indexer tab: Products progress bar, вибір мов, налаштування полів для індексації (важливо для якості пошуку)
  1. В адмінці перейдіть у Extensions → Extensions → Modules → AI Search → Edit → Indexer tab
  2. Оберіть Index Languages (порожньо = всі активні мови) та What to Index (Name, Description, Categories — обов'язково)
  3. Натисніть кнопку Re-index (Farm Queue)
  4. Залиште сторінку відкритою або поверніться через 30-90 хвилин (залежить від каталогу)
✅
Магазин не падає під час reindex. Embedding-обчислення на наших GPU-серверах. Ваш shop-сервер тільки шле текст товарів і отримує вектори. Покупці продовжують користуватись магазином зі стандартним LIKE-fallback — як тільки reindex завершиться, search-handler автоматично перемкнеться на AI.

Час reindex залежить від розміру каталогу:

  • 200-1000 SKU: ~2-5 хвилин
  • 1000-5000 SKU: ~10-30 хвилин
  • 5000-30 000 SKU: ~30-90 хвилин
  • 30 000-100 000 SKU: ~2-3 години (Pro/Enterprise тариф)

Крок 7: Перевірка на frontend

  1. Відкрийте свій frontend у новій вкладці
  2. В пошуку вашого магазину спробуйте 3 типи запитів:
    • Морфологія: ввести у множині те що проіндексоване в однині (наприклад "чашки" замість "Чашка")
    • Опечатка: "тарилка" замість "тарілка"
    • Синонім: "стілець" замість "крісло"
  3. Очікуваний результат: всі 3 типи повертають релевантні товари. Якщо стандартний LIKE-пошук на цих запитах давав "0 результатів", AI Search має знайти товари.

Troubleshooting типових проблем

❓
"License key invalid" при активації
Перевірте: 1) ліцензія активна у кабінеті (не expired); 2) домен ліцензії співпадає з URL магазину (з або без www, з http або https); 3) ви скопіювали key цілком, без зайвих пробілів.
❓
Reindex зависає на 0%
Перевірте: 1) GPU-сервер AI Search доступний (інколи бувають короткі перерви) — статус на Documentation; 2) admin-сесія не завершилась за час reindex — у такому випадку запустіть знову, прогрес зберігається; 3) логи у storage/logs/ покажуть чи є HTTP-помилки до API.
❓
Пошук на frontend все одно показує LIKE-результати
Очистіть OpenCart cache: Dashboard → Storage → Clear cache (Twig + Modification). Якщо ви на Redis — також FLUSHALL.
❓
"Class not found" або інші PHP-помилки після установки
У 99% випадків — поточний крок 4 (Modifications Refresh) не виконано. Поверніться до кроку 4.
❓
Multistore: модуль не активується для додаткового магазину
У AI Search → Settings → Active Stores явно вкажіть всі магазини (multi-select). Без цього модуль працює тільки для default-store.

FAQ

Чи можна встановити AI Search без правок теми?

Так. Модуль працює через event hooks — жодних змін у twig чи інших файлах теми не потрібно. Перевірено на тисячах OpenCart-тем.

Чи потрібно вимикати стандартний пошук?

Ні. AI Search замінює backend-логіку пошуку через event hooks. Стандартна форма пошуку у header вашої теми продовжує працювати — просто результати приходять з нашого ядра.

Скільки RAM потрібно на shop-сервері для AI Search?

Не більше ніж для стандартного OpenCart. Embedding-обчислення на наших GPU, не у вас. Shop-сервер тільки шле/отримує API-запити.

А якщо я хочу повернутися на стандартний пошук?

В адмінці AI Search → Settings → Status: Disabled. Все. Або повна деінсталяція через Modules → Uninstall.

Чи можна одночасно мати AI Search і інший search-модуль?

Технічно так, але вони можуть конфліктувати на event hooks. Рекомендуємо вимкнути конкуруючий модуль перед активацією AI Search.

Як оновити модуль до нової версії?

В кабінеті ai-search.cc → Downloads → завантажте свіжий zip → Installer → Upload (поверх старого). Modifications → Refresh. Готово.