SiteZilla Image Searcher — AI-пошук товарів за фото для OpenCart

SiteZilla Image Searcher додає в OpenCart 2.3 пошук товарів за зображенням. Покупець може завантажити фотографію, перетягнути файл у модальне вікно, вставити картинку з буфера обміну або передати прямий URL. Модуль надсилає зображення на локальний AI-сервер, отримує список схожих product_id та показує повноцінні картки товарів засобами самого OpenCart.

Що бачить покупець

Біля звичайного пошуку з’являється окрема кнопка пошуку за фото. Вона відкриває адаптивне модальне вікно, ізольоване від стандартного Journal/OpenCart typeahead. Користувач додає зображення одним із доступних способів, бачить попередній перегляд і запускає пошук.

Як формуються результати

AI-сервер повертає масив результатів у форматі {product_id, score} або список product_ids. Модуль нормалізує відповідь, групує дублікати за товаром, сортує позиції за оцінкою схожості та відсіює результати нижче встановленого min_score. Після цього OpenCart сам завантажує назву, ціну, акційну ціну, опис, посилання і мініатюру через стандартну модель каталогу.

Локальний AI-сервер

OpenCart-модуль не генерує embeddings самостійно. Він підключається до окремого HTTP-сервісу, який приймає фотографії, будує вектори ознак і працює з векторною базою. Адреса сервера, API-ключ і timeout задаються в адміністративній частині.

1. OpenCart готує товар

   Формується payload із product_id, головним і додатковими зображеннями, їхніми hash, назвою, model, SKU, категоріями, виробником, статусом, кількістю, мовою та магазином.

2. AI-сервер індексує зображення

   Сервіс отримує POST /index/product, обчислює embeddings і записує точки у Qdrant або іншу vector DB.

3. Покупець надсилає фото

   Модуль викликає POST /search/image та передає limit, min_score, language_id, store_id, status, категорію й ознаку наявності.

4. OpenCart рендерить товари

   Сервер повертає ідентифікатори та score, а магазин добирає актуальні дані товарів із власної бази.

Підтримувані API-методи

Індексація каталогу

Адміністратор може відправити один конкретний товар, попередньо переглянути сформований JSON payload або запустити пакетну обробку каталогу. Стан кожного зображення зберігається локально, тому можна відрізнити нові, проіндексовані, змінені, пропущені, видалені та помилкові записи.

Фільтри індексації

• один або кілька виробників;
• одна або кілька категорій;
• опційне включення підкатегорій;
• пошук за Product ID, model, SKU або назвою;
• тільки активні, тільки вимкнені або всі товари;
• тільки в наявності, тільки відсутні або всі;
• товари з головним, додатковим або будь-яким зображенням;
• за станом локального індексу: not indexed, indexed, error, skipped, deleted або changed;
• розмір пакета від 1 до 100 товарів;
• максимальна кількість товарів за запуск;
• пауза між пакетами для зменшення навантаження.

Попередній перегляд перед запуском

Окремі AJAX-дії дозволяють порахувати майбутню вибірку та показати список товарів до фактичного надсилання на AI-сервер. Це корисно для перевірки категорій, виробників, залишків і текстового фільтра перед великою індексацією.

Адміністративна діагностика

Модуль створює локальні таблиці індексу, журналу та API-викликів. Адміністратор бачить дату, endpoint, HTTP-статус, product_id, відповідь backend і текст помилки. Також доступні перевірка /health, запит /stats, очищення журналу та тестовий пошук.

Налаштування пошуку

Для фронтенду можна визначити кількість результатів, мінімальний score, максимальний розмір файлу, дозволені типи зображень, категорію пошуку та правило «тільки в наявності». URL-пошук, вставка з буфера й drag-and-drop вмикаються незалежно один від одного.

Дизайн і теми

У комплекті передбачено шістнадцять готових кольорових тем: green, pink, rose, coral, peach, apricot, mint, sage, olive, sky, azure, lavender, lilac, berry, graphite та cocoa. Окремо можна задати основний колір, hover, м’який фон і колір тексту кнопки. Підписи кнопки та заголовок модального вікна підтримують мовні значення.

Мови інтерфейсу

У модулі є мовні файли для української, російської та англійської. Кастомний текст кнопки й заголовок вікна зберігаються окремо для кожної мови OpenCart.

Безпека та валідація

• перевірка дозволу modify для адміністративних AJAX-дій;
• валідація розміру завантаження;
• перевірка реального MIME через getimagesize();
• обмеження дозволених форматів;
• перевірка HTTP/HTTPS URL;
• API key для звернення до backend;
• контроль timeout;
• зручний режим debug, який можна вимкнути на production.

Що входить у OpenCart-частину

• контролер і шаблон адміністративної сторінки;
• українська, російська та англійська локалізації;
• frontend-кнопка, модальне вікно і рендер результатів;
• HTTP-клієнт для AI API;
• OCMOD-вставка кнопки біля стандартного або Journal-пошуку;
• створення службових таблиць;
• інструменти індексації, фільтрації та журналювання.

Що потрібно окремо

Для реальної роботи необхідний окремий AI backend, який завантажує модель комп’ютерного зору, генерує embeddings і взаємодіє з Qdrant або іншою vector DB. Його можна розгорнути на окремій Ubuntu VM, у Docker або на виділеному сервері. Ресурси залежать від моделі, розміру каталогу, кількості зображень і потрібної швидкості.

Рекомендована послідовність впровадження

1. Аудит каталогу

   Оцінити кількість товарів і фотографій, формати, дублікати, якість зображень та структуру категорій.

2. Розгортання backend

   Підняти API, модель embeddings і vector DB, додати healthcheck та API key.

3. Тестова індексація

   Відправити 10–50 товарів, перевірити payload, відповіді й якість найближчих сусідів.

4. Підбір threshold

   Налаштувати min_score та limit на реальних фотографіях користувачів.

5. Повна індексація

   Запустити пакетну обробку з безпечним batch size і паузами.

6. Запуск на фронтенді

   Увімкнути кнопку, перевірити мобільний вигляд, аналітику та журнал помилок.

Приклади сценаріїв

Обмеження поточної версії

• якість залежить від обраної embedding-моделі та фотографій каталогу;
• AI backend не входить у звичайний OpenCart runtime і розгортається окремо;
• cron endpoint у поточній базі підтверджує доступ, а повне керування індексацією виконується в адмінці;
• точне видалення й синхронізація потребують узгодженого контракту з backend;
• для великого каталогу потрібні черги, контроль повторів і моніторинг ресурсів.

Поширені запитання