Настройка

Базы знаний

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

База знаний принадлежит команде. Когда агент отвечает на сообщение, колыбель ищет в привязанных к нему базах и подставляет найденные фрагменты в промпт как источники с номерами [1], [2]. Агент без привязанной базы источников не получает.

1. Установите embedding-модель

Поиск работает по векторам, а векторы считает embedding-модель колыбели. База запоминает модель, которой она построена, в момент создания: берётся модель команды из блока «Модели команды», иначе подходящая установленная.

cradle models pull qwen3-embedding-0.6b-q8
cradle models list

В таблице есть модель с ролью embedding (Ключи и модели).

Если нет. Загрузка и поиск отвечают No embedding model installed on this server. — модели с ролью embedding нет. Сообщение «Расширение pgvector недоступно — RAG недоступен» значит, что база данных сервера без расширения vector: у встроенной базы оно есть, во внешнем Postgres его нужно разрешить (сервер создаёт его при запуске).

2. Создайте базу

В консоли: страница команды → вкладка База знаний → Новая база. Введите название (например «Поставщик X — каталог кабелей»), при желании описание («Описание (опционально)»). Селектор «Где хранятся файлы» выбирает хранилище оригиналов; оставьте «Хранилище колыбели по умолчанию», если не нужно другое (S3 добавляется в карточке колыбели в блоке «Хранилища»; после первого документа хранилище базы менять нельзя). Нажмите Создать.

То же вызовом API (скоуп kb:write, команда — по ключу):

curl -s -X POST http://127.0.0.1:31416/api/v1/admin/kb \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Catalog","description":"price lists"}'

Как проверить. В ответе "ok":true и id; база появилась в списке «Базы знаний (N)»; cradle kb list показывает её.

Если нет. name is required (1..120 chars) — пустое или слишком длинное название; file store not found — выбранного хранилища нет.

3. Загрузите документы

Выберите базу и используйте один из способов:

  • Загрузить файлы или перетащите файлы в окно: MD, TXT, PDF, DOCX, XLSX, CSV (также .markdown, .log, .xls); один файл — до 100 МБ;
  • Добавить текст → «Заголовок», «Текст» → Залить;
  • Добавить URL → «URL» → Загрузить и индексировать: одна страница или файл (HTML, PDF, DOCX, XLSX).

Кнопка Обход сайта в веб-консоли не работает: обход (crawlSite) не отдаётся по HTTP. Нужные страницы добавляйте по одной через Добавить URL.

Файл можно загрузить и вызовом API (скоуп kb:write):

curl -s -X POST http://127.0.0.1:31416/api/v1/admin/kb/<kbId>/documents/file \
  -H "Authorization: Bearer $KEY" -F "file=@price-list.pdf"

Как проверить. В блоке «Документы» у файла указаны число знаков и «чанков».

Если нет.

  • unsupported file type ".ext" — формат не поддерживается.
  • file exceeds 100 MB — файл больше лимита.
  • no text could be extracted from the file — из файла не достался текст (например, скан без текстового слоя); у URL то же называется extracted text is empty.
  • cannot read the file: … — файл повреждён или не читается парсером.
  • store_unavailable — хранилище файлов базы не отвечает.
  • No embedding model installed on this server. — шаг 1.

4. Привяжите базу к агентам

Кликните агента на канвасе команды → блок Knowledge Bases → отметьте базы → Save. Привяжите базу тем агентам, которые отвечают: в базовой команде это Team Lead (когда он отвечает сам) и Исполнитель (когда лид поручает ему сообщение). Режим Grounding mode у агента — Off (источники не подставляются), Soft (по умолчанию) или Strict (каждый факт должен подтверждаться источником, иначе ответ-отказ и тикет оператору).

Как проверить. Задайте агенту вопрос по содержимому документа через канал (Каналы): в ответе есть ссылки [1], а в тикете, если он создан, — блок источников.

Если нет. Ответ без ссылок — база не привязана к агенту, режим Off или в базе нет подходящего фрагмента (проверьте шагом 5).

5. Проверьте поиск

В консоли на странице базы есть блок «Тестовый поиск»: введите «Поисковый запрос», нажмите Найти; у каждого результата указана «дистанция» (чем она меньше, тем ближе фрагмент). Тот же поиск по API (скоуп kb:read):

curl -s -X POST http://127.0.0.1:31416/api/v1/admin/kb/search \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query":"cable price","kbIds":["<kbId>"],"topK":5}'

В ответе {"ok":true,"hits":[…]}; у каждого результата content, documentTitle, sourceUri, distance.

Как проверить. Нужный фрагмент среди первых результатов.

Если нет. «Ничего не найдено» — в базе нет документов или поиск идёт не по той базе. Если у базы есть предупреждение «Индекс построен моделью X; модель команды — Y», база ищет той моделью, которой построена; подробности — в RAG.

Команды cradle kb create, cradle kb add и cradle kb search в версии 0.9.2 отвечают not implemented (код выхода 2). Работает cradle kb list; создание, загрузка и поиск — в консоли или по API, как выше.