База знаний AI-чата

Около 4 мин

База знаний AI-чата (RAG)

База знаний позволяет загрузить справочные документы вашего сервиса (статьи хелпа, регламенты, инструкции), и AI-чат будет отвечать пользователям, опираясь на их содержимое, а не выдумывая. Технически это RAG — Retrieval-Augmented Generation.

Только при включённом AI-модуле

База знаний — часть AI-модуля. Раздел доступен, если AI-модуль входит в вашу лицензию и включён. Если лицензия активна, но AI-модуль не подключён, вкладка «База знаний» в админке показывается только для ознакомления — настройки видны, но изменять их нельзя (отмечены замком). Чтобы пользоваться — подключите AI-модуль.

Как это работает

При загрузке документа:

Документ режется на небольшие фрагменты (чанки) с нахлёстом.
Каждый фрагмент превращается в вектор (эмбеддинг) — локальной моделью прямо на сервере, без обращения к внешним сервисам (текст документов никуда не уходит).
Векторы и оригинал сохраняются в базе (Postgres + расширение pgvector).

Нужно расширение pgvector

Векторный движок (на нём же — быстрый универсальный поиск платформы) требует расширение pgvector в PostgreSQL — без него бэкенд не запустится. Это базовое требование, а не часть AI-модуля. Стандартный образ postgres pgvector не содержит: используйте pgvector/pgvector:pg17 или установите pgvector в свою сборку/DBaaS. Подробнее — «Требования к PostgreSQL».

Когда пользователь пишет в чат:

По его вопросу система ищет наиболее подходящие фрагменты — гибридно: и по смыслу (векторный поиск), и по точным словам (полнотекстовый поиск). Векторный ловит синонимы, словесный — точные термины, коды, аббревиатуры.
Подходящие фрагменты подкладываются модели как справочный материал.
Модель формирует ответ по ним и, при необходимости, ссылается на источник.

Справка ≠ действие

Если пользователь просит выполнить действие («создай роль X»), чат выполняет его через инструменты, а не пересказывает инструкцию. База знаний используется для ответов на вопросы («как создать роль?»), а не вместо действий.

Параметры и значения по умолчанию

Параметры задаются в админке и применяются без перезапуска.

Параметр	По умолчанию	Что делает	Нужна переиндексация?
Размер чанка	320	На сколько токенов резать документ при индексации. Меньше — точнее, но обрывистее; больше — размывает смысл.	да
Нахлёст чанков	48	Перекрытие соседних фрагментов (≈10–15 %) — сохраняет смысл на стыках.	да
Порог релевантности	0.84	Минимальная близость фрагмента, чтобы попасть в ответ чата. Ниже порога — в ответ не идёт.	нет
Фрагментов в ответ (topK)	4	Сколько фрагментов подкладывать модели. Обычно 3–5.	нет
Гибридный поиск	вкл	Совмещать смысловой и словесный поиск. Рекомендуется оставить включённым.	нет

Размер чанка измеряется в условных токенах

Размер чанка считается во внутренних токенах индексатора, а не в токенах модели эмбеддингов. На русском они расходятся: значение 320 ≈ 230–275 токенов модели при её лимите 512 — то есть с запасом. Безопасный потолок — около 600. Не поднимайте размер чанка к 512 «потому что модель держит 512» — это разные единицы, иначе часть текста будет обрезана при индексации.

Что и где менять

Всё — в админке (нужны права полного доступа):

Администрирование → вкладка «База знаний» — основной экран:
- Загрузка / обновление документов (.md, .txt). Кнопка-«глаз» — просмотр оригинала, кнопка обновления — заменить файл, корзина — удалить (с подтверждением).
- «Проверить поиск» — вводите запрос и смотрите, какие фрагменты и с какой близостью поднимаются, ещё до ответа модели. Бейдж «по словам» означает точное словесное совпадение. Главный инструмент отладки.
- Параметры — размер чанка, нахлёст, порог, topK, гибрид + кнопка «Переиндексировать».
Администрирование → «Настройки приложения» — те же параметры доступны и здесь (раздел AI), как обычные настройки.

Когда нажимать «Переиндексировать»

После изменения размера чанка или нахлёста нужно переиндексировать — система заново разрежет и пересчитает все документы (из сохранённых оригиналов). Порог, topK и гибрид применяются сразу, без переиндексации.

Наполнение по API (программно)

Кроме ручной загрузки через админку, базу знаний можно наполнять программно — например, синхронизировать её со своей вики, хелпдеском или CMS внешним пайплайном (n8n, скрипт, CI). Документы доставляются батчами; обновление и удаление — идемпотентные.

Требуется AI-модуль

Ручка работает только при включённом AI-модуле (как и вся база знаний).

Аутентификация. Заголовок X-Api-Key — ключ интеграции команды (тот же механизм, что и у остального публичного API). Писать в базу знаний может только команда с полным доступом.

Базовый путь: /api/v1/integration/kb-documents

Загрузка / обновление — `POST /batch`

Тело — набор документов одного источника. sourceSystem — ваш код источника (любая строка до 64 символов, кроме зарезервированного manual), externalId — идентификатор документа в вашей системе. Пара (sourceSystem, externalId) — ключ идемпотентности: повторная заливка того же документа обновит его, а не создаст дубль.

curl -X POST https://<ваш-сервер>/api/v1/integration/kb-documents/batch \
  -H "X-Api-Key: <ключ-команды>" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceSystem": "my-wiki",
    "items": [
      {
        "externalId": "article-42",
        "title": "Как создать роль",
        "content": "# Создание роли\n\nЧтобы создать роль, откройте…",
        "moreUrl": "https://wiki.example.com/articles/42"
      },
      { "externalId": "article-7", "deleted": true }
    ]
  }'

Поле	Обязательно	Назначение
`sourceSystem`	да	Код источника (на весь батч). До 64 символов, кроме `manual`.
`items[].externalId`	да	Идентификатор документа в источнике. До 256 символов.
`items[].title`	для upsert	Заголовок (если пуст — подставится `externalId`).
`items[].content`	для upsert	Текст (Markdown / plain), UTF-8.
`items[].moreUrl`	нет	Ссылка «подробнее» — чат покажет её пользователю рядом с ответом.
`items[].deleted`	нет	`true` → снять документ с публикации (нужен только `externalId`).

Ответ — счётчики created / updated / tombstoned / skipped и список errors по конкретным элементам: один кривой документ не валит весь батч. Неизменившиеся документы пропускаются (skipped) — повторная заливка того же контента ничего не пересчитывает.

До 500 документов в запросе

Лейте крупными батчами (200–300 — нормально). На очень больших объёмах режьте на пачки по ≤500.

Полная синхронизация — `POST /prune`

Чтобы из базы ушли документы, удалённые в источнике, в конце прогона пришлите полный список актуальных externalId этого источника. Всё, чего в нём нет, снимется (тумбстоун).

curl -X POST https://<ваш-сервер>/api/v1/integration/kb-documents/prune \
  -H "X-Api-Key: <ключ-команды>" \
  -H "Content-Type: application/json" \
  -d '{ "sourceSystem": "my-wiki", "keepExternalIds": ["article-42", "article-7"] }'

Защита от случайного сноса

Если keepExternalIds пуст, а в источнике есть живые документы, запрос отклоняется — чтобы упавший пайплайн (приславший пустой список) не снёс весь источник. Чтобы намеренно очистить источник, передайте "force": true.

Индексация — фоновая

Ручка принимает документы и отвечает сразу; векторизация идёт фоном (обычно в пределах нескольких минут). Поэтому только что залитый документ появляется в поиске чата с небольшой задержкой — это нормально. Жать «Переиндексировать» при этом не нужно: новые и изменённые документы индексируются автоматически.

Как подобрать параметры

Тюнить «на глаз» бесполезно — используйте «Проверить поиск»:

Соберите 10–15 типичных вопросов пользователей.
Прогоняйте их, меняя один параметр за раз.
Смотрите: попадает ли нужная статья в топ и выше ли её близость, чем у нерелевантной.
Сменили размер чанка/нахлёст — нажмите «Переиндексировать».

Наибольший эффект дают качество исходных статей и размер чанка, а не подкрутка порога. Чистые, структурированные статьи под конкретные вопросы работают лучше всего.

Модель эмбеддингов

Используется компактная многоязычная модель (multilingual-e5-small), которая работает локально на сервере. Она поставляется вместе с системой — отдельная настройка не требуется. Данные документов при индексации и поиске не покидают сервер.