1. Назначение и модель работы

bussol.smartsearchultra — поисковый модуль для интернет-магазина на 1С-Битрикс. Он объединяет быстрый полнотекстовый поиск, обработку опечаток и словоформ, управляемую релевантность, semantic embeddings, natural-language фильтры, голосовой ввод, поиск по изображению, аналитику и полноценную страницу результатов.

2. Что нового в версии 3.3.7

Текущая версия определяется файлом install/version.php: 3.3.7, дата сборки 20.10.2026.

3. Системные требования, установка и обновление

Фактические зависимости сборки 3.3.7

Новая установка

1. Разместите каталог модуля как /local/modules/bussol.smartsearchultra/ (либо в используемом проектом каталоге /bitrix/modules/).
2. Установите модуль через административную часть Битрикс. Установщик создаст таблицы, зарегистрирует события и агент очистки аналитики, скопирует компоненты и theme-ресурсы.
3. Откройте Bussol → Интеллектуальный поиск → Настройки и настройте каждый SITE_ID отдельно.
4. Выберите инфоблоки, поля и свойства. При больших каталогах проверьте FULLTEXT во вкладке «AI и индексы».
5. Если используются semantic/image embeddings — выберите AI-провайдера и модель до полной переиндексации.
6. Запустите полную переиндексацию и только после неё проверяйте морфологию, natural-language facets и embeddings.
7. Разместите bussol:smartsearch в нужном шаблоне сайта; при необходимости создайте отдельную /search/ со bussol:smartsearch.results.

Обновление 3.3.6 → 3.3.7

Замените файлы модуля и очистите кеш Битрикс при необходимости. Версия 3.3.7 меняет только copyright-заголовки, поэтому миграция БД и переиндексация не требуются.

Переход со старого ID bussol.smartsearch

1. Сделайте резервную копию БД и старого каталога.
2. Удаляя старый модуль, выберите сохранение данных, чтобы не удалять таблицы b_bussol_smartsearch_*.
3. Не держите активными одновременно bussol.smartsearch и bussol.smartsearchultra.
4. Установите новый каталог bussol.smartsearchultra. Обычные b_option-настройки будут перенесены, если новые значения ещё не созданы.
5. Проверьте сайты, AI-настройки и индексы; очистите кеш Битрикс и браузера.

4. Меню, права и многосайтовые настройки

Модуль добавляет собственный пункт в левую административную панель в разделе Bussol. Пункт виден пользователям с правом модуля не ниже R; сама страница настроек 3.3.7 дополнительно проверяет IsAdmin().

5. Быстрый компонент `bussol:smartsearch`

Компонент предназначен для поисковой строки в шапке или контентной области сайта. Он выполняет AJAX-поиск с debounce 350 мс, показывает dropdown-выдачу и умеет работать с областью поиска (scope).

<?php
$APPLICATION->IncludeComponent(
    'bussol:smartsearch',
    '',
    [
        'SITE_ID' => SITE_ID,
        'PLACEHOLDER' => 'Что найти?',
        'SHOW_SCOPE' => 'Y',
        'CACHE_TIME' => 3600,
    ]
);

Поведение интерфейса

• При вводе текста появляется собственная кнопка-крестик. Клик очищает поле, статус и текущую выдачу; уже отправленный запрос инвалидируется, поэтому поздний AJAX-ответ не открывает список снова.
• При пустом поле и фокусе загружаются «История поиска» и «Часто ищут», если аналитика включена.
• Клик по найденному товару записывает CTR-событие; для state-changing click-action используется Bitrix sessid.
• Если включена полноценная страница результатов, кнопка «Найти» перенаправляет на настроенный URL с параметрами q и scope.
• Цвет фона кнопки, текста и border строки задаются отдельно для каждого сайта через CSS-переменные компонента.

6. Полноценная страница результатов

Компонент bussol:smartsearch.results предназначен для отдельной страницы результатов. Он принимает строку поиска из q, поддерживает пагинацию и серверную сортировку, а клики с карточек также участвуют в CTR/conversion analytics.

<?php
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php';
$APPLICATION->SetTitle('Поиск');

$APPLICATION->IncludeComponent(
    'bussol:smartsearch.results',
    '',
    [
        'SITE_ID' => SITE_ID,
        'PER_PAGE' => 24,
        'SHOW_SORT' => 'Y',
        'CACHE_TIME' => 0,
    ]
);

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/footer.php';

7. Синонимы, rewrite, морфология и стоп-слова

Синонимы

Одна группа задаётся на строку. Связи двунаправленные: любой термин группы расширяет запрос остальными вариантами.

смартфон = телефон, мобильник
ноутбук = laptop, лэптоп
телевизор = tv, телек

Ручные правила X → Y

Rewrite применяется к точному нормализованному запросу до основного поиска. Используйте правила для маркетинговых названий, жаргона и частых ошибочных форм.

айфон 16 => iphone 16
самсунг а55 => samsung galaxy a55

Морфология и стоп-слова

• При включённой морфологии модуль пытается использовать stemming() модуля «Поиск» Bitrix; если модуль/функция недоступны, применяется встроенный fallback.
• Пользовательские стоп-слова можно разделять пробелом, запятой, точкой с запятой или новой строкой.
• После изменения морфологии или стоп-слов нужна полная переиндексация, потому что SEARCH_STEMS строится в индексе.
• Опция «Исправлять опечатки и раскладку» действует независимо от пользовательских словарей и помогает сформировать дополнительные варианты запроса.

8. Поиск естественным языком

Natural-language parser работает локально и не требует AI. Он отделяет текстовую часть запроса от коммерческих ограничений и facet-значений.

смартфон samsung до 50000 в наличии
ноутбук lenovo от 70000 до 120000
красное платье размер 46

Для свойств используется таблица b_bussol_smartsearch_facet_value. В facet index попадают свойства из основной настройки «Символьные коды свойств» и из отдельного списка «Свойства бренда». Значения бренда по умолчанию: BRAND, BRAND_REF, MANUFACTURER.

9. Управление релевантностью и коммерческое ранжирование

Вес отдельных полей

Вес 0 отключает дополнительный весовой сигнал поля. Допустимый диапазон в конфигурации — 0…50.

Ручные приоритеты

Для инфоблоков, разделов и отдельных элементов используется формат ID=баллы; разрешены положительные и отрицательные значения.

# приоритет инфоблоков
7=500
12=150

# приоритет разделов
25=400
88=-200

# приоритет товаров
1024=1000
2048=500

Коммерческие сигналы

10. FULLTEXT, Hybrid Semantic Search и ANN

FULLTEXT для больших каталогов

FULLTEXT используется как быстрый этап candidate retrieval, а не как финальная релевантность. Индекс создаётся по SEARCH_TEXT, SEARCH_LATIN, SEARCH_STEMS; найденные кандидаты затем проходят обычный SmartSearch scoring.

Hybrid semantic text search

При включении для каждого товара строится TEXT_VECTOR. Пользовательский запрос получает embedding с ролью query; lexical/FULLTEXT и semantic кандидаты объединяются, после чего cosine similarity преобразуется в дополнительный ranking score.

ANN/vector index

ANN реализован локально через Random Hyperplane LSH и хранит buckets в MySQL, поэтому не требует MySQL VECTOR, pgvector или отдельной vector DB. ANN сначала отбирает небольшое множество кандидатов, затем similarity считается точно.

11. AI-провайдеры и модели

Во вкладке «AI и индексы» выбирается провайдер, после чего интерфейс подставляет endpoint и список моделей. API key вводится отдельно; начиная с security release 3.3.6 сохранённый ключ не выводится обратно в HTML формы.

Unified JSON contract

{
  "task": "embedding",
  "input_type": "text",
  "model": "your-model",
  "input": "поисковый запрос"
}

Для изображения используются input_type: "image", base64-поле image и mime_type. Модуль понимает ответы с embedding, vector или data[0].embedding.

12. Поиск по изображениям

Visual search включён по умолчанию на чистой установке и имеет два уровня. Первый работает полностью локально; второй включается отдельно и использует AI embeddings.

Hybrid image ranking

Если выбран OpenAI, image embedding слой недоступен в текущем ProviderCatalog, поэтому visual search продолжает работать по pHash. Для единой text+image модели используйте Jina, Cohere либо совместимый Custom endpoint.

13. Голосовой ввод и браузеры

Компонент не содержит собственного сервера распознавания речи: он проверяет window.SpeechRecognition || window.webkitSpeechRecognition. Если объект доступен, создаётся recognition с языком из настройки (по умолчанию ru-RU) и максимум тремя альтернативами.

14. Аналитика, CTR, conversions, self-learning и A/B

Аналитический слой не участвует в обязательном поисковом пути: при ошибке записи статистики результат поиска всё равно возвращается пользователю.

Безопасность visitor identity

После исправлений 3.3.6 visitor ID формируется на сервере, подписывается HMAC-SHA256 и хранится в HttpOnly/SameSite cookie. Client-side visitorId больше не используется как доверенная security identity для истории и click ownership.

Рекомендуемый запуск self-learning

1. Сначала соберите базовую статистику показов, кликов и заказов.
2. Настройте детерминированную релевантность и убедитесь, что нулевые запросы не вызваны отсутствующим индексом.
3. Включите A/B и направьте, например, 50% трафика в вариант LEARNED.
4. Сравнивайте CTR, conversion rate и выручку CONTROL vs LEARNED.
5. Увеличивайте learning weight только после статистически осмысленного объёма событий.

15. CSV импорт/экспорт и диагностика релевантности

CSV

Административная форма поддерживает импорт и экспорт с разделителем ;. Доступны режимы Заменить текущие и Добавить к текущим.

Диагностика релевантности

Action diagnose предназначен только для администратора. В настройках можно указать запрос и ID элемента. Если ID = 0, интерфейс показывает первые 50 результатов.

• Эффективный запрос после rewrite/NLP.
• Число кандидатов и источник candidate retrieval.
• Итоговый score.
• Вклад текста, морфологии, semantic similarity, отдельных полей и business ranking.
• Natural-language constraints и ANN hits, когда они применимы.

16. Архитектура, хранение данных и API

Основные таблицы

Префикс таблиц намеренно остался b_bussol_smartsearch_* после смены module ID — это сохраняет индекс и аналитику при миграции с bussol.smartsearch.

События и обслуживание

Engine actions

Публичные имена компонентов

Несмотря на новый module ID, публичные вызовы остаются bussol:smartsearch и bussol:smartsearch.results, поэтому шаблоны сайта не нужно переименовывать при переходе на Ultra.

17. Безопасность и диагностика

Диагностика типовых проблем

18. Чек-лист запуска

• Сделана резервная копия БД и каталога модуля перед установкой/обновлением.
• В Bitrix зарегистрирован именно module ID bussol.smartsearchultra; старый bussol.smartsearch не активен одновременно.
• Для каждого SITE_ID выбраны нужные инфоблоки, поля и свойства.
• Проверены синонимы, rewrite, стоп-слова и natural-language свойства.
• На большом каталоге проверен/создан FULLTEXT; candidate limit соответствует размеру каталога.
• Если нужны embeddings, выбран AI provider/model, задан API key и выполнена полная переиндексация.
• Если нужен visual search, проверен GD, заполнены IMAGE_HASH; для AI image search заполнены IMAGE_VECTOR и ANN.
• Быстрый компонент установлен в шаблон; кнопка очистки, scope, suggestions и переход на страницу результатов работают.
• На /search/ проверены пагинация и все сортировки.
• Голосовой ввод протестирован в целевых браузерах; отсутствие Web Speech API не блокирует обычный поиск.
• Аналитика собирает запросы, impressions и clicks; zero-results используются для улучшения словарей.
• Conversion analytics проверена тестовым заказом, если установлен sale.
• Self-learning включается только после накопления событий; для первого запуска рекомендуется A/B CONTROL vs LEARNED.
• Проверен security-journal текущего архива; для 3.3.7 статус — ready_for_submission, открытых находок 0.
• После всех изменений очищен кеш Битрикс и браузера и выполнен контрольный набор поисковых сценариев.