Semantic Search для FreeScout
Semantic Search это отдельный модуль FreeScout, который исправляет поиск по нескольким словам и, после добавления вашего собственного AI-ключа, находит разговоры по их теме. Он продаётся создателями ReplyRabbit, но не требует установленного ReplyRabbit.
Ищете обзор?
Обзор
Встроенный поиск FreeScout ищет весь ваш запрос как одну фразу в одном поле. Поиск вроде frank invoice ничего не находит, потому что имя клиента находится в одном месте, а слово "invoice" в другом. Semantic Search заменяет это поведение в два этапа:
- Режим ключевых слов (ключ не нужен): каждое слово в вашем поисковом запросе должно присутствовать где-либо в беседе. Тема, имя клиента, адрес электронной почты и текст сообщения учитываются. Это включено, как только модуль активен.
- Поиск по смыслу (ваш собственный ключ ИИ): каждая беседа получает компактный отпечаток того, о чём она, хранящийся в вашей базе данных FreeScout. Поиск сопоставляется по смыслу и по ключевым словам, и два списка объединяются так, чтобы лучший ответ был первым. Этот режим также обеспечивает работу Похожие разговоры панель на боковой панели беседы.
Страница поиска показывает небольшую Семантический или Ключевое слово метка рядом с количеством результатов, чтобы агенты знали, какой режим ответил.
Синтаксис поиска
Обычные сокращения поисковых систем работают в обоих режимах:
| Вы вводите | Что он делает |
|---|---|
frank invoice | Оба слова должны встречаться где-либо в диалоге. |
"out of stock" | Точная фраза должна присутствовать. |
-refund или -"out of stock" | Обращения, содержащие слово или фразу, исключаются. |
cart OR basket | Достаточно любого из слов. OR должно быть заглавными буквами. |
admin@example.com или example.com | Адрес электронной почты или домен сопоставляется точно. |
Поиск по смыслу добавляет только разговоры, которые явно о том же, что и введённые вами слова. Цитируемые фразы, адреса и -exclusions всё равно применяются к этим результатам, поэтому поиск по адресу электронной почты никогда не заполняется несвязанными беседами.
Строка поиска и фильтры
На странице результатов поиска поле поиска находится прямо рядом с Обращения и Клиенты вкладки, поэтому вы можете изменить поиск, не прокручивая обратно наверх. Выпадающий список сортировки находится справа от Клиенты вкладка.

Нажмите кнопку ползунков рядом с полем поиска, чтобы открыть Фильтры панель. Вам не нужно запоминать сокращение выше: четыре правила из слов сами вписывают его в поле поиска.
| Фильтр | Что он пишет | Что он делает |
|---|---|---|
| Все эти слова | frank invoice | Каждое слово должно присутствовать. |
| Эта точная фраза | "out of stock" | Слова должны встречаться вместе, в этом порядке. |
| Любое из этих слов | cart OR basket | Достаточно одного из слов. |
| Ни одно из этих слов | -refund | Обращения со словом исключаются. |

Стандартные фильтры FreeScout (почтовый ящик, статус, назначено, клиент, даты и другие) находятся в Дополнительно раздел внизу панели. Он свёрнут, чтобы панель оставалась короткой, и открывается сам, когда один из этих фильтров уже используется. Небольшое число на кнопке ползунков показывает, сколько фильтров активно. Нажмите Применить чтобы запустить поиск, или Очистить всё чтобы начать заново.

Начиная с 1.1.3, Клиенты вкладка также рассматривает каждое слово по отдельности. Если ни один клиент не совпадает по всем словам, она перечисляет клиентов, совпадающих по любому из них, сначала самые близкие совпадения, поэтому invoice frank всё равно находит клиента по имени Frank.
Предварительные требования
Перед началом убедитесь, что у вас есть:
- FreeScout 1.8.101 или новее на PHP 8.1 или позже.
- Работающий воркер очереди и планировщик FreeScout (
php artisan queue:workиschedule:runcron). Индексация выполняется на них. - Лицензия Semantic Search из вашего Аккаунт ReplyRabbit. Письмо о покупке содержит лицензионный ключ.
- Необязательно, для поиска по смыслу: API-ключ от OpenAI или Google Gemini, либо базовый URL и имя модели эмбеддингов совместимого сервиса, такого как OpenRouter, Ollama или LM Studio.
Установите модуль
Скачать ZIP
Войдите на app.replyrabbit.app с адресом электронной почты, который вы использовали при оформлении заказа, и откройте Semantic Search карточка на панели. Скачайтеsemantic-search.zip.Скопируйте его в папку Modules
Распакуйтеsemantic-search.zipи скопируйтеSemanticSearchпапку вModulesкаталог вашей установки FreeScout, через SFTP или файловый менеджер вашего хостинга, рядом с другими модулями. В FreeScout нет загрузки сторонних модулей через интерфейс.Активируйте модуль
Активировать Semantic Search из списка модулей. Активация запускает миграции базы данных, которые создают две таблицы индекса.Попробуйте поиск
Ищите имя клиента плюс тему, например имя и "счёт". Результаты теперь совпадают по каждому слову, где бы оно ни появлялось в разговоре, а страница поиска показывает Ключевое слово метка.
Режим ключевых слов работает на этом этапе без дополнительной настройки. Шаги ниже открывают поиск по смыслу и панель похожих переписок.
Введите лицензионный ключ
Откройте страницу настроек
В FreeScout перейдите в Управление, затем Настройки, затем Semantic Search.Вставьте ключ лицензии
В Лицензия раздел, вставьте ключ из письма о покупке и сохраните. Статус показывает Лицензировано со временем последней проверки.
Лицензия привязана к URL сайта установки FreeScout. Если вы переносите FreeScout на новый домен, свяжитесь с hey@replyrabbit.app и мы его сбросим.
Настройте поиск по смыслу
Выберите провайдера
В Провайдер эмбеддингов раздел, выберите OpenAI, Google, или Совместимый с OpenAI. Модель по умолчанию заполнена для OpenAI и Google. Для совместимого сервиса введите базовый URL и имя модели, которое он ожидает.Добавьте ключ и проверьте его
Вставьте API-ключ, если он нужен вашему провайдеру, затем нажмите Проверить эмбеддинги. Тест отправляет одно короткое предложение в конечную точку эмбеддингов и проверяет её ответ. Ключи хранятся в зашифрованном виде, и после сохранения показывается только замаскированный предварительный просмотр.Выберите почтовые ящики для индексации
В Индексация раздел, отметьте почтовые ящики для включения. Включать внутренние заметки включена по умолчанию, потому что агенты часто ищут свои собственные заметки. Установите Дней заполнения насколько далеко назад индексировать (по умолчанию 365 дней).Включите поиск по смыслу
Отметить Поиск по смыслу и сохраните. Если провайдер, модель или base URL изменились, страница сообщит, что беседы будут переиндексированы в фоновом режиме.Запустите первый индекс
Нажмите Индексировать сейчас. Блок состояния показывает прогресс, например "Indexed 1,240 of 8,900 (14%)", время последнего запуска, последнюю ошибку, если она есть, и оценочную оставшуюся стоимость. Индексация выполняется пакетами примерно по 200 бесед каждые пять минут, поэтому большой отдел занимает несколько часов. Поиск продолжает работать всё это время.
Какой провайдер?
Используйте пользовательский эндпоинт эмбеддингов
Введите базовый URL API, например https://embeddings.example.com/v1 или http://10.0.0.25:8001/v1, за которым следует точный ID модели эмбеддингов, обслуживаемой там. Semantic Search добавляет /embeddings к базовому URL. Публичные адреса требуют HTTPS. Частный или loopback HTTP-адрес должен находиться в доверенной сети, доступной для FreeScout.
Если шлюз обслуживает и чат, и эмбеддинги, вы можете ввести один и тот же /v1 base URL здесь и в Пользовательские настройки провайдера ReplyRabbit. Настройте модель эмбеддингов здесь, а модель чата в ReplyRabbit. Если ваши серверы чата и эмбеддингов имеют разные URL, введите каждый URL в свой продукт. Продукты не используют общие токены или настройки.
The Проверить эмбеддинги действие должно возвращать вектор эмбеддинга. Чат-модель, которая только отвечает /chat/completions не может обеспечивать поиск по смыслу. Изменение endpoint или модели запускает новый профиль индекса; изменение только токена сохраняет существующие векторы.


Поддержание актуальности
Когда выпускается новая версия, FreeScout показывает её на Управление, затем Модули, и Обновить сейчас устанавливает его на месте: без SFTP, без повторной загрузки. ZIP, скачанный из вашей панели управления, содержит ссылку для скачивания вашей собственной лицензии, поэтому обновление загружается за той же проверкой лицензии, что и первая загрузка.
Две вещи, которые нужно знать:
- Обновление работает только для копии, скачанной из вашей панели управления, и не следует передавать свою копию: её ссылка обновления содержит ключ скачивания вашей лицензии, поэтому любой, у кого есть ZIP, сможет получать обновления по вашей лицензии. Копия от кого-то другого привязана к его лицензии и обновляется по его ключу.
- Если FreeScout сообщает об ошибке загрузки, скачайте новый ZIP из панели управления и замените папку вручную, как в шагах установки выше. Ваш индекс и настройки сохранятся: они хранятся в базе данных, а не в папке модуля.
Стоимость
Индексация отправляет текст каждой переписки вашему провайдеру один раз, плюс снова, если переписка получает новый ответ. Поиск отправляет только поисковые слова.
| Провайдер | Модель | Цена | Около 100 бесед |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 0.02 USD за миллион токенов | примерно 0.01 USD |
| Google Gemini | gemini-embedding-001 | бесплатный тариф, затем оплата за токены | обычно бесплатно |
| Ollama или LM Studio | любая модель эмбеддингов | нет | нет |
Страница настроек показывает оценку для бесед, ожидающих индексации, чтобы вы могли проверить число перед нажатием Индексировать сейчас. Переиндексация происходит только при смене поставщика или модели или при нажатии Переиндексировать всё.
Панель похожих разговоров
Когда включён поиск по смыслу, Похожие разговоры панель появляется на боковой панели беседы. В ней перечислены другие беседы в том же почтовом ящике на ту же тему, с темой, именем клиента и датой. Агенты видят только те беседы, к которым у них уже есть доступ.
Отключите панель для всех с помощью Похожие разговоры переключатель на странице настроек. Новая беседа показывает "Nothing similar yet", пока она не проиндексирована, что занимает несколько минут.

Командная строка
Две команды помогают при управлении FreeScout по SSH:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status выводит те же цифры покрытия, что и страница настроек. reindex запускает пакет сразу, не дожидаясь планировщика, что полезно для первого индекса на большом столе.
Устранение неполадок
| Симптом | Что проверить |
|---|---|
| Страница поиска показывает Ключевое слово вместо Семантический | Подтвердить Поиск по смыслу отмечен, статус лицензии Лицензировано, и блок состояния не показывает недавних ошибок. Если ключ не сработал, поиск переключается на режим ключевых слов, пока это не будет исправлено. |
| На странице поиска вообще не отображается ни одной метки | Поиск был передан собственному поиску FreeScout. Это происходит для запросов, состоящих только из числа (номера тикетов или заказов), с которыми ядро уже хорошо справляется. |
| Проверить эмбеддинги не удаётся | Убедитесь, что в ключе нет ведущих или завершающих пробелов и он принадлежит нужному провайдеру. Для совместимого сервиса убедитесь, что базовый URL доступен с сервера FreeScout, а имя модели эмбеддингов точно соответствует ожидаемому сервисом. |
| Статус показывает "Пока ничего не проиндексировано" | Убедитесь, что обработчик очереди и cron планировщика запущены. Нажмите Индексировать сейчас и обновите через минуту. На общем хостинге первый пакет может запускаться несколько минут. |
| Индексация останавливается на полпути | Прочитайте последнюю ошибку в блоке статуса. Обычная причина это ограничения частоты запросов и ошибки квоты от провайдера; индексация возобновится при следующем запланированном запуске. |
| Результаты поиска медленные на очень большой службе поддержки | Режим ключевых слов проверяет каждое слово поиска по тексту сообщения, что тяжелее, чем сопоставление одной фразы в ядре. Ограничивайте поиск несколькими словами или уменьшайте число почтовых ящиков, включённых в индексацию. |
| Панель похожих разговоров пуста | Переписка ещё не проиндексирована, или панель отключена в настройках. Новые переписки индексируются в течение нескольких минут. |
Конфиденциальность и обработка данных
Поиск по ключевым словам выполняется полностью внутри вашей базы данных FreeScout и ничего никуда не отправляет. При включённом поиске по смыслу текст каждой индексируемой переписки (тема, сообщения клиента, ответы агентов и внутренние заметки, если они включены) отправляется настроенному вами провайдеру. Публичный эндпоинт использует HTTPS; приватный HTTP-эндпоинт остаётся в настраиваемой вами сети. Ключ необязателен для совместимого эндпоинта. Сохраняется только возвращённый отпечаток.
Единственный контакт с replyrabbit.app это проверка лицензии, которая отправляет лицензионный ключ, URL сайта FreeScout и версию модуля. Никакой текст переписки, поисковые слова или данные клиентов нам не отправляются.
Если текст переписки должен оставаться на ваших собственных серверах, используйте локального провайдера или совместимую конечную точку в вашей доверенной частной сети, либо оставайтесь в режиме ключевых слов. С совместимой публичной конечной точкой текст передаётся по HTTPS. Частные HTTP-конечные точки разрешены только в доверенной сети.
FAQ
Нужен ли ReplyRabbit для использования Semantic Search?
Нет. Semantic Search это отдельный модуль FreeScout от тех же разработчиков. Он устанавливается и работает самостоятельно. ReplyRabbit это лишь место, где вы его покупаете, скачиваете и управляете ключом лицензии.
Работает ли Semantic Search без ключа ИИ?
Да. Режим ключевых слов работает с момента активации модуля, без ключа и без настроек. Каждое слово в вашем запросе должно встречаться где-либо в беседе: в теме, имени клиента, адресе электронной почты или тексте сообщения. Ключ AI добавляет только поиск по смыслу и панель похожих бесед.
Каких провайдеров ИИ я могу использовать?
OpenAI (по умолчанию text-embedding-3-small), Google Gemini (по умолчанию gemini-embedding-001) или любой сервис, совместимый с OpenAI, например OpenRouter, Ollama или LM Studio, где вы сами вводите базовый URL и модель. Z.AI не поддерживается, так как у него нет сервиса эмбеддингов.
Сколько стоит ключ ИИ?
С OpenAI text-embedding-3-small по 0.02 USD за миллион токенов индексация около 100 переписок стоит примерно 0.01 USD. Стол с 10 000 переписок платит около 1 USD за однократную индексацию всего, затем несколько центов в месяц за новую почту. Страница настроек показывает оценку перед запуском первой индексации.
Где хранятся данные поиска?
В двух таблицах внутри вашей существующей базы данных FreeScout. Каждая проиндексированная переписка добавляет около половины килобайта. Отдельный поисковый сервер не нужен, и ничего не хранится на replyrabbit.app.
Работает ли он на PostgreSQL?
Да. Поиск по ключевым словам и поиск по смыслу работают на MySQL, MariaDB и PostgreSQL.
Что произойдёт, если мой ключ перестанет работать или лицензия истечёт?
Поиск самостоятельно возвращается в режим ключевых слов, чтобы агенты продолжали получать результаты. Страница настроек показывает причину. Поиск по ключевым словам никогда не зависит от лицензии или ключа.