Источники знаний

Источник знаний – это один вход, из которого AI-агенту разрешено отвечать. Источники живут в разделе База знаний → Источники, а соседняя вкладка Проверка поиска показывает фрагменты, которые агент получит по конкретному вопросу.

Ничего не индексируется само собой. Каждый источник создаётся явно, индексируется по своему расписанию и выбирается для конкретного агента в разделе ИИ-ответы и AI-агент.

Типы источников

  • Статья базы знаний – существующая статья этого бота. Опубликованные статьи становятся публичными источниками, внутренние – источниками только для агента, а черновики не дают искомого содержимого вообще.
  • Сайт – страницы вашего сайта, которые обходит краулер по разрешённым адресам.
  • Файл – загруженный PDF, документ Word, Excel, PowerPoint, текстовый, Markdown- или HTML-файл.
  • Инструкция – короткий текст правила, который вы пишете сами, например условия возврата, которых агент обязан придерживаться.
  • Факт – отдельный сохранённый факт по его идентификатору.

Название источника ограничено 120 символами, а вся конфигурация источника, включая текст инструкции, – 64 КБ.

Доступность и приоритет

У каждого источника одна доступность:

  • Для AI-агента – находит только агент.
  • Для операторов – зарезервировано для операторского поиска.
  • Публичный – может участвовать и в публичных поверхностях, например в центре помощи.

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

Приоритет – от −100 до 100. Это разрешение ничьей: при равных оценках выше встанет фрагмент из более приоритетного источника. Заметно лучшее текстовое совпадение приоритет не перебивает.

Источники-сайты

Сайту нужен хотя бы один разрешённый адрес (голое происхождение вида https://host, до 20 штук) и хотя бы один стартовый адрес внутри них, не более 100 адресов. Адреса по HTTP отклоняются.

Обход не выходит за эти границы:

  • Краулер представляется как MyBotKnowledge/1.0 и перед обходом читает robots.txt каждого origin. Префиксы Disallow пропускаются, Crawl-delay соблюдается до 10 секунд.
  • Переходы делаются только по ссылкам <a href>, которые ведут обратно внутрь разрешённых адресов. Якоря отбрасываются, параметры utm_*, gclid и fbclid удаляются до постановки в очередь, поэтому одна страница не индексируется дважды.
  • Перед каждым запросом хост резолвится заново; loopback, приватные, link-local, multicast и метаданные облака отклоняются. Редиректы проверяются по тем же правилам, их не больше трёх.
  • Запрос обрывается через 15 секунд, тело ответа ограничено 8 МБ, принимаются только HTML, XHTML, простой текст и Markdown.
  • Один источник индексирует не более 100 страниц.

Краулер никогда не авторизуется, не отправляет формы и не загружает скрипты, медиа и вложенные ресурсы. Содержимое за логином индексировать нельзя: опубликуйте его или загрузите файлом.

Поле Обновлять каждые (секунды) относится только к сайтам. Значение – от 60 секунд до 366 дней. Статьи, файлы, инструкции и факты по расписанию не перечитываются: они переиндексируются при изменении или по кнопке Обновить.

Загрузка файлов

Файл должен уже лежать в медиатеке этого бота и весить не больше 8 МБ. Принимаются PDF, DOCX, XLSX, PPTX, text/plain, text/markdown, text/html и XHTML.

Извлечение текста намеренно узкое:

  • Из HTML остаются заголовки, списки и тексты ссылок; скрипты, стили, навигация, шапки, подвалы, боковые блоки и шаблоны вырезаются.
  • PDF читается только как текст, не более 100 страниц. Зашифрованные и битые файлы отклоняются целиком, а не разбираются частично.
  • Из Office-файлов читаются только текстовые части документа. Макросы, встроенные объекты и внешние связи игнорируются и никогда не загружаются. Архив должен укладываться в 500 записей, коэффициент сжатия 100:1, 32 МБ в распакованном виде, 200 000 XML-узлов и 500 000 символов текста.

Старые бинарные .doc, .xls и .ppt отклоняются с кодом unsupported_type. Пересохраните их в DOCX, XLSX или PPTX и загрузите заново.

Индексация и статусы

Источник проходит через состояния, которые видны на его карточке:

  • Ожидает индексации – создан или изменён, ещё не обработан.
  • Индексируется – задачу взял обработчик.
  • Готов – текущее содержимое доступно поиску.
  • Нужно обновить – подошёл срок обновления или изменилось содержимое.
  • Ошибка – последняя попытка закончилась кодом ошибки.
  • Отключён – сохранён, но исключён из любого поиска.

Индексация ступенчатая. Обработчик читает источник, режет текст на пересекающиеся фрагменты (примерно 1 500 символов с перекрытием в 200), запрашивает эмбеддинги пачками по 32 и только потом одной транзакцией заменяет документы и фрагменты источника. Читатель всегда видит либо прежнюю полную версию, либо новую полную, но никогда наполовину пересобранный источник. Если контрольная сумма содержимого не изменилась, пересборка пропускается.

Эмбеддинги считаются через ИИ-интеграцию бота (Интеграции) – по её base URL и ключу, по умолчанию моделью text-embedding-3-small на 1 536 измерений. Без рабочей ИИ-интеграции источник не выйдет из очереди индексации.

В одном источнике не более 100 документов, из одного документа – не более 500 фрагментов. Задачи берутся в аренду на две минуты с продлением, поэтому прерванный обработчик освобождает источник, а не блокирует его. На карточке видны число попыток, обработанные документы и фрагменты и документы с ошибками; кнопка Отменить индексирование останавливает текущий проход.

Что возвращает поиск

Вопрос обрабатывают два независимых поиска:

  1. лексический – по текстовому индексу PostgreSQL;
  2. семантический – по векторному индексу (косинусное расстояние).

Бот, набор доступностей, условие «источник активен» и условие «документ не удалён» входят в оба SQL-запроса – до ранжирования и до ограничения выборки. Затем два рейтинга объединяются методом reciprocal rank fusion, приоритет источника и свежесть индексации (в пределах 30 дней) разрешают ничьи, а соседние фрагменты одного документа схлопываются.

Результат – не более 12 фрагментов по 800 символов. Длина вопроса ограничена 16 000 символами, а агента можно ограничить максимум 100 конкретными источниками.

Агент сохраняет источник, документ и фрагмент каждой полученной выдержки в порядке ранга. Ответ, который ссылается на что-то другое, отбраковывается до отправки, поэтому в ответе не может появиться ссылка на черновик, скрытый, отключённый или удалённый источник.

Проверка поиска

База знаний → Проверка поиска выполняет тот же поиск без обращения к модели. Для каждого попадания видны источник, заголовок, фрагмент, оценка совпадения и причина («Гибридное совпадение»). Скрытые метаданные не возвращаются, а сама проверка ограничена по частоте на аккаунт.

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

Если индексация не удалась

Последняя ошибка сохраняется устойчивым кодом:

  • blocked_address – адрес, редирект или полученный IP вне разрешённых адресов либо ведёт во внутреннюю сеть.
  • robots_denied – путь запрещён в robots.txt.
  • unsupported_type – тип содержимого или формат файла не поддерживается.
  • file_too_large – загрузка или файл больше лимита.
  • expanded_too_large – извлечённый текст, число страниц или содержимое архива выходят за лимиты выше.
  • malformed_file – файл или ответ не удалось разобрать.
  • fetch_timeout – сайт не ответил вовремя.
  • rate_limited – провайдер эмбеддингов ограничил запросы, задача будет повторена.

Устраните причину и нажмите Обновить. В ошибках никогда нет полученного текста, поэтому их можно без опаски пересылать в поддержку.

Удаление, отключение и хранение

Отключить сохраняет настройки, но убирает источник из любого поиска; Включить возвращает его в очередь. Удалить стирает источник вместе с его документами и фрагментами.

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

Изоляция

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

API и MCP

REST API использует права knowledge:read и knowledge:write:

  • GET/POST /api/bots/{botID}/knowledge/sources
  • GET/PATCH/DELETE /api/bots/{botID}/knowledge/sources/{sourceID}
  • POST /api/bots/{botID}/knowledge/sources/{sourceID}/upload
  • POST /api/bots/{botID}/knowledge/sources/{sourceID}/refresh
  • POST /api/bots/{botID}/knowledge/sources/{sourceID}/cancel
  • POST /api/bots/{botID}/knowledge/sources/{sourceID}/disable
  • POST /api/bots/{botID}/knowledge/sources/{sourceID}/enable
  • GET /api/bots/{botID}/knowledge/sources/{sourceID}/index-status
  • GET /api/bots/{botID}/knowledge/sources/{sourceID}/documents
  • POST /api/bots/{botID}/knowledge/retrieval-test

В MCP доступны только инструменты чтения: list_knowledge_sources, get_knowledge_source_status и test_knowledge_retrieval. Инструмента, который меняет источник или скачивает скрытые документы, в MCP нет.

Связанные материалы