Каталог

Как подключить YML-фид к агенту llmagent, что бот берёт из него, как устроен поиск по товарам и как товары попадают в ответы.

Каталог подключает бота к вашему ассортименту: клиент спрашивает «есть ли у вас …» — бот находит подходящие позиции и отвечает с названием, ценой, наличием и ссылкой на товар. Источник каталога — YML-фид: та же выгрузка, которую сайты готовят для Яндекс Маркета.

Раздел «Каталог» находится в кабинете app.llmagent.kz. Каталог привязан к боту: одна ссылка на фид на бота. Объём базы знаний каталог не расходует — он хранится отдельно.

Как устроен поиск

Порядок шагов выведен из разбора реальной ошибки, и он важнее любой настройки:

Точный артикул. Если в запросе есть код товара, он решает всё.
Раздел задаёт множество. Слова вроде «что есть для сада» сначала превращаются в раздел каталога, и дальше бот ищет внутри него. Это принципиально: у трети товаров раздела слова из названия раздела в названии товара нет — включая самые дорогие позиции.
Фильтры и сортировку считает сам каталог. «Самый дорогой в разделе» берётся сортировкой по всему разделу, а не выбором максимума из десятка найденных по названию.
Название решает порядок внутри отобранного. Ищется по смыслу: «канцелярия» находит «Канцелярские товары», хотя слово в слово они не совпадают.

Если раздел из запроса узнать не удалось, бот не подменяет его тихо всем каталогом — иначе «самый дорогой в Грунтах» превратился бы в уверенный ответ не на тот вопрос.

Когда бот отвечает клиенту, он получает из каталога обычно 10 позиций, а при необходимости — до 20: название, цена, описание, производитель, артикул, категория, наличие, характеристики и ссылка. По умолчанию бот предлагает только товары в наличии — то, что помечено в фиде как отсутствующее, клиенту не показывается. В чатах сотрудников бот обращается к каталогу столько раз, сколько нужно для ответа.

Что происходит после подключения

Каталог начинает работать не весь сразу. Сначала в кабинет попадают сами товары — и тут же работают разделы, фильтр по цене, точный артикул и просмотр раздела. Поиск по смыслу дозревает следом.

Повторная синхронизация неизменившегося фида проходит почти вхолостую: обновляются только те товары, что поменялись, пропавшие снимаются, остальные не трогаются. Наполовину обновлённый каталог не «сломан» — у части товаров новая цена, у части старая, ровно как на витрине магазина в момент выгрузки.

Пока каталог дочитывается в первый раз, поиск по смыслу не работает: на первых процентах готовности он предлагал бы случайные товары. Артикул и фильтры при этом уже работают — они не про смысл.

Обновления, ночные и по кнопке, поиск по смыслу обычно не прерывают. Товары с изменившимся описанием находятся по прежнему, пока не обработается новое. Новые товары по артикулу, разделу и цене находятся сразу, а по смыслу — чуть позже. Если новых товаров в выгрузке больше десятой части каталога, поиск по смыслу на время закрывается, как при первом подключении.

Как подключить

Подготовьте YML-фид и убедитесь, что он доступен по прямой ссылке без авторизации.
В разделе «Каталог», в блоке «Источник», нажмите «Подключить» у строки «Фид товаров YML», вставьте ссылку и подключите каталог. Ссылка сразу проверяется: если фид недоступен, кабинет об этом скажет.
Проверьте результат: в строке с названием раздела появятся число товаров, дата выгрузки из фида и время последнего обновления, а в «Поиске по каталогу» — разделы со счётчиками, поиск и фильтры по бренду, цене и наличию. Щелчок по товару открывает его карточку: цена, наличие, описание, характеристики и ссылка на сайт. Кабинет ищет ровно так же, как бот, — это честный способ проверить, что он найдёт клиенту.

Чтобы сменить ссылку, откройте меню «⋯» у строки фида и выберите «Заменить ссылку». Каталог прочитается заново по новому адресу, и пока новый фид читается, бот о товарах не отвечает. Там же — «Отключить», если каталог больше не нужен.

Что бот берёт из фида

Поле фида	Как используется
`name`	Название; главное поле поиска. Для товаров, описанных в фиде как `vendor.model`, название собирается из `typePrefix` + `vendor` + `model`
`price`	Цена; участвует в фильтрах и сортировке
`description`	Описание: HTML-разметка вычищается
`vendor`, `vendorCode`	Производитель и артикул; точный артикул — самый сильный сигнал
`url`	Ссылка на товар в ответе бота; UTM-метки автоматически убираются
`categoryId` + `<categories>`	Категория и всё дерево родителей — по ним работает отбор по разделу
`available`	Наличие; товары не в наличии бот клиенту не предлагает
`param` (с `unit`)	Характеристики; показываются в карточке товара и участвуют в поиске
`disabled="true"`	Такие товары в каталог не попадают вовсе

Изображения из фида бот не использует — он работает с текстом; в кабинете картинки видны у товаров в поиске и в карточке.

Если с фидом что-то не так

Неудачная синхронизация не портит рабочий каталог: бот продолжает отвечать по последней удачной версии. Кабинет покажет в разделе конкретную причину — не удалось загрузить, каталог пуст и так далее.

Ночное обновление ведёт себя так же. Если фид ночью не прочитался, у раздела «Каталог» в меню кабинета появится красная точка, а в самом разделе — причина. Бот тем временем отвечает по последней удачной версии, а следующей ночью обновление повторится само.

Если в каталоге было хотя бы 20 товаров, а в ночной выгрузке их оказалось меньше половины от прежнего, обновление её не применяет: так выглядит фид, который магазин не успел собрать до конца. Если товаров и правда стало меньше, нажмите «Синхронизировать» — по кнопке каталог принимает выгрузку любого размера.

Пока бот не отвечает клиентам — закончились запросы или истёк тариф, — ночное обновление тоже на паузе. Когда бот снова заработает, нажмите «Синхронизировать» или дождитесь следующей ночи.

Если чтение оборвалось и раздел завис на сообщении «Каталог обрабатывается» или «Каталог обновляется», кабинет сам заменит его на понятную ошибку — вместо того чтобы вечно показывать обработку.

Советы по качеству фида

Название — главное поле. «Смеситель для кухни Vidima Uno, хром» найдётся по десятку формулировок; артикул вместо названия — только по артикулу.
Заполняйте vendorCode. Запрос по артикулу — самый точный сценарий.
Стройте дерево категорий через parentId. На нём держится отбор по разделу — самый важный шаг поиска. Категории-«солянки» без родителей эту связь теряют.
Выносите свойства в param. Размер, цвет, материал, мощность как характеристики ищутся и аккуратно показываются в карточке.
Следите за available. Товары не в наличии бот клиенту не предложит — фид со стёртым наличием равносилен пустому каталогу.