Базы знаний
Создание базы знаний, загрузка файлов, привязка к агенту и проверка поиском.
База знаний принадлежит команде. Когда агент отвечает на сообщение, колыбель
ищет в привязанных к нему базах и подставляет найденные фрагменты в промпт
как источники с номерами [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, как выше.