О документе
Документ описывает установку, настройку и эксплуатацию BUSSOL Neuro 2 версии 2.2.3 с ID модуля bussol.neuro2.
Документация составлена по фактической структуре сборки 2.2.3: административным страницам, настройкам AI, ORM-сущностям, обработчикам индексации, фоновым агентам, поисковой аналитике и механизму миграции со старого ID.
| Параметр | Значение |
|---|---|
| Продукт | BUSSOL Neuro 2 |
| Module ID | bussol.neuro2 |
| Версия | 2.2.3 |
| Дата версии | 05.10.2026 |
| Namespace | Bussol\Neuro2 |
| Назначение | Умный поиск, поисковая аналитика, AI-словарь, массовый контент и SEO. |
Примеры настроек в документе ориентированы на стандартный поиск и инфоблоки 1С-Битрикс. На проектах с кастомным поисковым движком, нестандартным cron или особыми правами БД требуется отдельная staging-проверка.
1. Назначение и архитектура решения
BUSSOL Neuro 2 — модуль для 1С-Битрикс, объединяющий три рабочих контура:
- расширение внутреннего поиска за счёт синонимов, транслитераций, опечаток и разговорных вариантов;
- поисковую аналитику с выявлением нулевой и слабой выдачи и проверяемыми AI-рекомендациями;
- массовую генерацию контента и SEO для элементов и разделов инфоблоков.
Рекомендации для поиска не применяются «на веру». Модуль формирует кандидатов из фактических данных каталога, выполняет контрольный поиск и предлагает только вариант, который даёт больше результатов, чем исходная проблемная фраза.
Основные компоненты
| Компонент | Назначение |
|---|---|
| AI-провайдер | GigaChat, DeepSeek или OpenAI-compatible/OpenRouter для генерации контента, словаря и выбора рекомендаций. |
| AI-словарь | Хранит правила типов REPLACE и SYNONYM и добавляет варианты в поисковый индекс Bitrix. |
| Контентная очередь | Профили промптов, предпросмотр, фоновые задания, история и безопасный rollback. |
| Поисковая аналитика | Собирает фразы, считает частоту и фактическое число результатов, классифицирует zero/weak/resolved. |
| Рекомендации | Подбирает канонический источник каталога, измеряет «потенциал», позволяет применить, отклонить или игнорировать. |
2. Возможности версии 2.2.3
- поддержка GigaChat, DeepSeek и OpenAI-compatible/OpenRouter;
- AI-чат для проверки подключения провайдера;
- генерация синонимов, транслитераций, типичных опечаток и разговорных вариантов;
- работа с названиями элементов, разделов, списочными и связанными свойствами, directory/HL-справочниками;
- расширение поискового индекса данными разделов, свойств и тегов;
- массовая генерация PREVIEW_TEXT, DETAIL_TEXT, описаний разделов, SEO Title, Description, Keywords, H1 и строковых свойств;
- системные и пользовательские профили промптов;
- предпросмотр генерации на одном объекте до запуска задания;
- фоновая очередь с паузой, продолжением и отменой;
- история изменений и откат отдельной записи или задания целиком;
- защитный rollback: ручная правка после AI-генерации не затирается;
- аналитика поисковых запросов за 7/30/90/180 дней;
- нулевые, слабые, непроверенные, исправленные и игнорируемые запросы;
- AI/эвристические рекомендации только из проверенных кандидатов каталога;
- статус RESOLVED только после переиндексации и успешного контрольного поиска;
- retention поисковой аналитики и исключение известных роботов;
- одноразовый best-effort перенос данных со старого ID
bussol.neuro.
3. Системные требования и совместимость
| Требование | Комментарий |
|---|---|
| PHP | 8.1 или выше. Установщик останавливает установку на более старой версии. |
| 1С-Битрикс | Нужен установленный модуль main. Для основной работы необходим iblock. |
| Поисковая аналитика | Нужен штатный модуль search. Автоматический сбор рассчитан на поиск, вызывающий событие search:OnSearch. |
| Интернет-доступ | Сервер должен иметь исходящий HTTPS-доступ к выбранному AI-провайдеру. |
| Агенты | Фоновая генерация и обслуживание аналитики используют штатные агенты Bitrix. Для больших каталогов рекомендуется запуск агентов через cron. |
| Права | Меню видно пользователям с правом не ниже R, административные действия требуют права W на модуль. |
Если проект полностью заменяет штатный CSearch внешним поисковым движком и не вызывает OnSearch, автоматический сбор фраз потребует отдельного адаптера.
4. Установка, обновление, миграция и удаление
Чистая установка
- Установите модуль
bussol.neuro2через Marketplace или стандартный механизм установки модулей 1С-Битрикс. - Установщик зарегистрирует модуль, создаст ORM-таблицы, события, административные файлы, JS/CSS и два агента.
- Откройте BUSSOL → BUSSOL Neuro → Нейросети и AI-словарь.
- Настройте AI-провайдера и выполните тестовый запрос.
Переход со старого ID bussol.neuro
Версия 2.2.3 использует новый ID bussol.neuro2, namespace Bussol\Neuro2, отдельные таблицы b_bussol_neuro2_* и отдельные ресурсы.
Не удаляйте bussol.neuro до установки и проверки bussol.neuro2. При первой установке новый модуль пытается перенести настройки/API-ключи, словарь, профили, задания, историю, поисковую аналитику и рекомендации из старых таблиц.
- Сделайте резервную копию БД и каталога старого модуля.
- Установите
bussol.neuro2как отдельный модуль. - Проверьте AI-ключ, массовую генерацию и аналитику.
- Отключите или удалите старый модуль, чтобы его события не работали параллельно.
- Выполните полную переиндексацию поиска.
Удаление
Стандартное удаление снимает события, удаляет таблицы модуля, административные/статические файлы и настройки из Bitrix Option. Перед удалением рабочего модуля сделайте резервную копию нужных данных.
5. Быстрый запуск
| Шаг | Действие |
|---|---|
| 1 | В разделе Нейросети выберите провайдера, укажите ключ и нажмите «Сохранить». |
| 2 | Отправьте короткий тестовый запрос через встроенный AI-чат. |
| 3 | На вкладке Поиск включите модуль и выберите, какие данные добавлять в индекс. |
| 4 | На вкладке AI-словарь выберите инфоблок и источник данных, сформируйте промпт, сгенерируйте и отредактируйте варианты, затем сохраните правила. |
| 5 | После изменения словаря выполните стандартную полную переиндексацию модуля «Поиск». |
| 6 | Откройте AI-контент и SEO, проверьте профиль на одном объекте через предпросмотр и только затем запускайте массовое задание. |
| 7 | В Аналитике поиска выберите контрольный инфоблок, соберите реальные запросы и проверьте zero/weak фразы. |
| 8 | Сгенерируйте рекомендацию, примените её, переиндексируйте поиск и выполните повторную проверку. |
Рабочий контур считается настроенным, когда проходят два сценария: «предпросмотр → массовая генерация → история → rollback» и «нулевой запрос → рекомендация → применение → reindex → RESOLVED».
6. Административный центр и права доступа
После установки в меню BUSSOL появляются три раздела.
| Раздел | Назначение |
|---|---|
| Нейросети и AI-словарь | Настройки поискового индекса, поисковой аналитики, AI-провайдеров, встроенный чат и генератор словаря. |
| AI-контент и SEO | Профили промптов, предпросмотр, массовые задания, история и откат. |
| Аналитика поиска | Dashboard, zero/weak запросы, рекомендации, проверка, применение, отклонение и Ignore. |
Просмотр пункта меню доступен при праве R и выше. Действия, меняющие настройки, контент, словарь или рекомендации, требуют права W.
7. Настройки поискового индекса
Вкладка Поиск управляет тем, какие источники участвуют в расширении индексируемого BODY.
| Настройка | По умолчанию | Назначение |
|---|---|---|
| ENABLE_MODULE | Включено | Включает обработчики BUSSOL Neuro 2. |
| USE_SEARCH_PROPS | Включено | Добавляет в источники значения свойств элемента. Списки разрешаются по VALUE_ENUM, связи — по названиям, directory — по UF_NAME. |
| USE_TAGS | Включено | Учитывает теги индексируемого объекта. |
| USE_SECTION_NAME | Включено | Учитывает названия разделов элемента. |
| USE_SUBSECTION | Включено | Учитывает разделы/подразделы в логике расширения индекса. |
Для каждого источника модуль ищет сохранённые варианты в AI-словаре и добавляет их в поле BODY поискового документа.
Уже существующие документы поискового индекса не меняются мгновенно. Если модуль показывает флаг «Требуется переиндексация», выполните стандартную полную переиндексацию модуля «Поиск».
8. Настройка AI-провайдеров
Общие параметры
| Параметр | По умолчанию | Диапазон/назначение |
|---|---|---|
| AI_MAX_TOKENS | 2048 | Максимальное число токенов ответа. |
| AI_TEMPERATURE | 0.7 | 0–2. Чем ниже значение, тем стабильнее и предсказуемее результат. |
| AI_TIMEOUT | 45 сек. | Допустимый диапазон 5–120 секунд. |
GigaChat
- Укажите Authorization Key GigaChat. Можно вставить сам ключ или значение с префиксом
Basic— префикс будет удалён. - Выберите модель: GigaChat 2 Lite, 2 Pro, 2 Max или 3 Ultra.
- Выберите scope:
GIGACHAT_API_PERS,GIGACHAT_API_B2BилиGIGACHAT_API_CORP.
После сохранения password-поле намеренно отображается пустым. Если ключ сохранён, интерфейс показывает соответствующую подсказку. Пустое повторное сохранение не стирает существующий ключ.
DeepSeek
Укажите API-ключ и выберите deepseek-v4-flash или deepseek-v4-pro.
OpenAI-compatible / OpenRouter
Укажите API-ключ, Base URL и ID модели. По умолчанию Base URL — https://openrouter.ai/api/v1, модель — openrouter/free. Поля HTTP-Referer и X-Title необязательны.
Проверка подключения
После сохранения отправьте тестовое сообщение через встроенный AI-чат. Если ответ получен, тот же провайдер будет использоваться генератором словаря, массовым контентом и AI-выбором рекомендаций.
9. AI-словарь поиска
AI-словарь хранит два типа правил:
REPLACE— опечатки, транслит, разговорные и альтернативные написания;SYNONYM— синонимы и эквивалентные формулировки.
Источники значений
Для выбранного инфоблока доступны:
- названия элементов;
- названия разделов;
- списочные свойства;
- привязки к элементам и разделам;
- строковые свойства типа directory / HL-справочник.
Типовой сценарий
- Выберите инфоблок.
- Выберите источник значений.
- Выберите тип правил и число вариантов на значение (1–20).
- Нажмите «Сформировать промпт» и при необходимости отредактируйте его.
- Запустите генерацию. Значения обрабатываются пакетами.
- Отредактируйте итоговый текст вручную, если требуется.
- Сохраните правила и выполните переиндексацию.
Пример формата правила: iPhone 16 Pro | айфон 16про; iphone16 pro; айфон шестнадцать про
Статистика словаря показывает количество сохранённых правил по типам. Выбранный тип правил можно безопасно очистить из интерфейса.
10. Массовая генерация контента и SEO
Раздел AI-контент и SEO работает через профили и фоновые задания.
Поддерживаемые цели для элементов
- PREVIEW_TEXT;
- DETAIL_TEXT;
- SEO Title;
- SEO Description;
- SEO Keywords;
- H1 / PAGE_TITLE;
- одиночные строковые свойства инфоблока, включая HTML user type.
Поддерживаемые цели для разделов
- DESCRIPTION;
- SEO Title;
- SEO Description;
- SEO Keywords;
- H1 / PAGE_TITLE.
Фильтры задания
Можно выбрать инфоблок, раздел, включение подразделов, только активные объекты, лимит и режим перезаписи заполненных полей.
Сначала выполните предпросмотр на одном объекте: интерфейс покажет текущее значение, сгенерированный текст и фактический промпт. Только после проверки запускайте массовую обработку.
11. Профили промптов и переменные
При установке создаются системные профили: краткое и полное описание товара, SEO Title/Description/H1 товара, описание раздела, SEO Title/Description/H1 раздела.
Системный профиль можно редактировать, но нельзя удалить. Пользовательские профили можно создавать и удалять; если профиль уже использовался в заданиях, вместо физического удаления он деактивируется.
Доступные переменные
| Переменная | Содержимое |
|---|---|
{{NAME}} | Название элемента или раздела. |
{{ID}} | ID объекта. |
{{CODE}} | Символьный код. |
{{CONTEXT}} | Сводный контекст, собранный модулем. |
{{PROPERTIES}} | Подготовленные свойства элемента. |
{{SECTION_PATH}} | Путь по разделам. |
{{PREVIEW_TEXT}}, {{DETAIL_TEXT}} | Существующие тексты элемента. |
{{DESCRIPTION}} | Описание раздела. |
{{TARGET_CURRENT}} | Текущее значение целевого поля. |
Системные профили инструктируют модель воспринимать CONTEXT как данные, а не как команды. Объём длинных текстов и общего контекста ограничивается перед отправкой в AI.
12. Фоновые задания, история и rollback
Статусы и управление
Задание может быть запущено, поставлено на паузу, продолжено или отменено. Интерфейс показывает прогресс, количество успешных, пропущенных и ошибочных объектов.
Очередь обслуживает агент BussolNeuro2ContentAgent();, зарегистрированный с интервалом 60 секунд. Для крупных каталогов рекомендуется стандартная cron-схема выполнения агентов Bitrix.
При повторяющихся ошибках внешнего AI очередь останавливается, чтобы не проходить весь каталог с заведомо неуспешными запросами. После устранения причины задание можно продолжить.
История
Для применённых изменений сохраняются старое и новое значения, объект, поле, профиль, статус и возможная ошибка.
Rollback
- можно откатить отдельную запись истории;
- можно запросить откат всего задания;
- если текущее значение уже отличается от AI-значения, запись получает
ROLLBACK_CONFLICT, а ручная правка не затирается; - успешно откатанные записи получают статус
ROLLED_BACK.
13. Поисковая аналитика
BUSSOL Neuro 2 записывает поисковую фразу при событии search:OnSearch, но не выполняет тяжёлые операции внутри пользовательского запроса.
Что хранится
- фраза и её нормализованная форма;
- SITE_ID;
- общее число повторений;
- дневные счётчики;
- последнее измеренное число результатов;
- дата последней проверки, статус и диагностическая ошибка.
По умолчанию запрос считается слабым, если результат содержит от 1 до 3 позиций. Порог настраивается.
Dashboard
Доступны периоды 7, 30, 90 и 180 дней. Показываются общее число поисков, уникальные запросы, zero/weak показатели и доли, новые и применённые рекомендации.
Фильтры
Проблемные, без результатов, слабые, ещё не проверенные, исправленные, игнорируемые и все.
На обычных hit-агентах модуль проверяет только небольшой объём фраз. Массовая проверка и автоматические AI-рекомендации предназначены для cron-контекста.
14. AI-рекомендации и проверка эффекта
Как формируется рекомендация
- Модуль берёт проблемную фразу.
- Формирует до нескольких десятков кандидатов из реальных данных выбранного каталога: разделы, свойства, directory/HL, элементы и существующий словарь.
- Предварительно ранжирует кандидатов по нормализации, раскладке, транслитерации, токенам и триграммам.
- Для лучших кандидатов выполняет контрольный поиск.
- Кандидат отбрасывается, если не увеличивает число результатов.
- Если AI доступен, он выбирает только
candidate_indexиз уже проверенного списка. При недоступном AI используется эвристически лучший кандидат.
| Показатель | Смысл |
|---|---|
| Сейчас | Фактическое число результатов исходной фразы. |
| Рекомендация | Канонический источник каталога, к которому будет привязана проблемная фраза. |
| Потенциал | Число результатов контрольного поиска по канонической фразе до применения правила. |
| Confidence / причина | Пояснение выбранного кандидата. При AI — оценка модели, при fallback — техническая причина. |
Жизненный цикл
ACTIVE → рекомендация NEW → APPLIED → переиндексация → повторная проверка
├─ результат > weak limit → RESOLVED
└─ результат ≤ weak limit → ACTIVE
Рекомендацию можно отклонить. Запрос можно пометить как IGNORED и позднее вернуть в ACTIVE. Более новая рекомендация может перевести старую необработанную запись в SUPERSEDED.
15. Переиндексация и взаимодействие со штатным поиском
Правила AI-словаря начинают влиять на существующие элементы после штатной переиндексации поискового индекса 1С-Битрикс.
Обработчик search:BeforeIndex добавляет варианты словаря к индексируемому документу. Для инфоблоков источниками могут быть TITLE, теги, разделы и свойства — в зависимости от настроек.
После обновления товара обработчик события каталога вызывает обновление поискового индекса соответствующего элемента.
При изменении индексных настроек, сохранении/очистке словаря или применении поисковой рекомендации модуль выставляет признак необходимости переиндексации. После начала полной штатной переиндексации флаг сбрасывается.
16. Хранилище, приватность и безопасность
Таблицы модуля
| Таблица | Назначение |
|---|---|
b_bussol_neuro2_rule | Синонимы и replacement-правила. |
b_bussol_neuro2_prompt_profile | Профили массовой генерации. |
b_bussol_neuro2_content_job | Фоновые задания. |
b_bussol_neuro2_content_history | История применённых изменений и rollback. |
b_bussol_neuro2_search_query | Уникальные поисковые фразы и текущее состояние. |
b_bussol_neuro2_search_daily | Дневные агрегаты. |
b_bussol_neuro2_search_recommendation | Рекомендации и история их статусов. |
Приватность поисковой аналитики
Модуль не сохраняет IP-адрес, ID пользователя и идентификатор сессии. Записываются фраза, сайт, частота и результативность. Известные роботы можно исключить. Срок хранения — 30–730 дней, по умолчанию 180.
Секреты AI
API-ключи сохраняются как секретные опции модуля и не подставляются обратно в HTML password-поля. Пустое поле не перезаписывает уже сохранённый ключ. Доступ к настройкам требует права W.
Собственного слоя шифрования для значений Bitrix Option модуль не добавляет. Ограничьте доступ к БД и административной части согласно политике проекта.
Sanitization AI-контента
Для текстовых SEO-полей HTML удаляется. Для описаний разрешается ограниченный набор тегов: p, br, ul, ol, li, strong, b, em, i, h2–h4, blockquote. Script/style и произвольные атрибуты удаляются.
17. Диагностика и типовые проблемы
| Симптом | Что проверить |
|---|---|
| «Не указан Authorization Key (Basic) GigaChat» | Откройте настройки GigaChat, вставьте ключ и сохраните. После сохранения поле остаётся пустым — это нормально; должна быть подсказка о сохранённом секрете. |
| GigaChat отвечает ошибкой авторизации | Проверьте, соответствует ли выбранный scope типу выданного ключа: PERS/B2B/CORP. |
| AI-чат работает, массовая очередь не идёт | Проверьте штатные агенты Bitrix, BussolNeuro2ContentAgent();, cron/hit-режим и статус задания. |
| После словаря поиск не изменился | Проверьте флаг «Требуется переиндексация» и выполните полную переиндексацию модуля «Поиск». |
| Аналитика пустая | Убедитесь, что ANALYTICS_ENABLED включён и публичный поиск вызывает штатный OnSearch. Административные поиски и tags: не записываются; роботы могут исключаться. |
| Рекомендация не создаётся | Убедитесь, что запрос проверен, выбран правильный инфоблок и существует канонический кандидат, который фактически даёт больше результатов. |
| Рекомендация применена, но статус не RESOLVED | Это ожидаемо до переиндексации и повторной проверки. RESOLVED выставляется только после фактического улучшения выдачи. |
| Rollback показывает конфликт | Поле было изменено вручную после AI-генерации. Модуль намеренно не перезаписывает более новую редакторскую версию. |
| После смены ID пропали данные | Проверьте, что bussol.neuro2 был установлен до удаления bussol.neuro и импорт успел выполниться. |
18. Чек-лист приёмки и ограничения
Чек-лист перед production
- Создана резервная копия БД и файлов.
- Проверена установка/обновление и, при необходимости, импорт со старого ID.
- AI-ключ сохраняется, тестовый чат возвращает ответ.
- Предпросмотр контента показывает ожидаемый результат.
- Массовое задание завершается; история содержит OLD_VALUE/NEW_VALUE.
- Откат одной записи и задания проверен, включая конфликт ручной правки.
- AI-словарь сохранён; после reindex варианты присутствуют в поисковом BODY.
- Нулевой запрос попадает в аналитику и после проверки имеет 0 результатов.
- Рекомендация показывает больший «потенциал», чем текущая выдача.
- После применения устанавливается NEED_REINDEX.
- После переиндексации и recheck успешный запрос получает RESOLVED.
- При деградации выдачи исправленный запрос снова становится ACTIVE.
- Агенты выполняются через cron на проектах с большим каталогом.
- Пользователь без права W не может выполнять административные действия.
Текущие ограничения
- Модуль улучшает штатный поиск Bitrix, но не является отдельным полнотекстовым/vector-search движком.
- Автоматическая аналитика не охватывает полностью внешние поисковые системы без
OnSearch. - Версия 2.2.3 не связывает поиск с кликами, корзиной, заказами и выручкой.
- «Потенциал» рекомендации — измерение контрольной канонической фразы, а не гарантия точного числа результатов после reindex.
- Качество AI-контента зависит от выбранной модели, входных данных и промпта; перед массовой записью используйте предпросмотр.
Считайте внедрение принятым после двух сквозных тестов: AI-контент → история → rollback и zero-result → рекомендация → apply → reindex → recheck → RESOLVED.