Создание и заполнение базы знаний

Принцип — сначала опирайтесь на данные, затем проверяйте. База знаний — это источник, которому необходимо следовать, а не подсказка. Определите её охват в instructions и всегда убеждайтесь, что реальный вопрос возвращает результаты до того, как вы начнёте на него полагаться — пустой поиск означает, что агент ответит «не охватывается». Подробнее в Принципах проектирования.

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

1. Создайте её

create_knowledge_base(
  name="Company policy",
  description="Mortgage policy and rates, effective 2026 — not car or personal loans",  # routes questions here
  instructions="Authoritative current mortgage policy; overrides any industry norm. "
               "Covers home mortgages only; for car or personal loans, say so and hand off.",  # for the model
)

Имя нормализуется в url-safe slug при создании — "Company policy" вернётся как company-policy. Используйте это возвращённое имя для всего остального: add_knowledge_text(kb_name=…), search_knowledge_base(kb_name=…) и прикрепления его к агенту. Ввод исходного имени с пробелами позже просто выдаст ошибку 404.

2. Напишите description — именно он определяет маршрутизацию вопросов к этой базе

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

Таким образом, база с размытым или пустым описанием будет искаться, когда не нужно, и — что хуже — пропущена, когда нужно. Ни один из этих сбоев не объявляет о себе явно: первый проявляется как медленный ответ с нерелевантными цитатами, второй — как «У меня нет ничего по этому вопросу».

Напишите одну строку, используя слова, которые использовал бы посетитель, называя предмет:

✅ "Country-by-country medical device registration requirements"
✅ "Regulatory change news by country and authority, 2022–2026 — what changed and when"
✅ "Selpercatinib — for lung and thyroid cancer"
 
❌ "Knowledge base"                ← routes nothing
❌ "Imported from the website"     ← says where it came from, not what is in it
❌ "Sandbox test, safe to delete"  ← says why it exists, not what is in it

Важно быть отличимым от ваших других баз, а не быть длинным. У арендатора с девятью базами — восемь препаратов и профиль компании, по одной строке на каждую, ни одна длиннее дюжины слов — маршрутизирует 10 из 10 вопросов правильно, потому что «для рака лёгких и щитовидной железы» и «для гломерулонефрита по типу IgA» не могут быть перепутаны. Измерено, а не предположено.

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

Эта строка также отображается в списке консоли, но это второстепенная задача.

3. Напишите instructions, исходя из ожидаемого использования — при создании, а не «позже»

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

Выведите его из того, как БЗ будет фактически использоваться — одна строка на вопрос:

Примеры инструкций базы знаний, по типу БЗ:

# Website-content KB (products, services, team, blog)
instructions="Company website content: products, services, team and blog posts. Authoritative
for what we offer and who we are. Marketing copy is not a contractual promise — for prices,
terms or eligibility prefer the policy KB; if only this KB answers, attribute it to the website."
 
# Policy / regulation KB
instructions="Current company policy, effective 2026; overrides industry norms and prior
knowledge. Covers home mortgages only — for car or personal loans, say so and hand off.
Any quoted rate or fee must state its effective date."
 
# Product-docs KB
instructions="Official product documentation for the current release. State the version when a
feature is version-dependent. If the docs don't cover something, say so — never fill the gap
from general knowledge."

4. Добавьте контент

add_knowledge_text(kb_name="Company policy", title="2026 late-fee rule",
                   content="From 1 July 2026 the daily late fee is 0.019% …")

Бинарные файлы (pdf/docx) и целые папки (zip) проходят через add_knowledge_file — подпапки обходятся, и каждый md/txt/pdf/html/docx импортируется по его пути внутри архива.

4b. Напишите предложение, которое вы хотите, чтобы было найдено

Извлечение соответствует значению, и само по себе значение почти ничего не весит. Это единственная вещь с самым высоким рычагом воздействия, которую вы контролируете, и её легко сделать неправильно, потому что ошибок нет — поиск всё равно что-то вернёт, просто не то.

В реальном каталоге клиентов была такая строка в 1 480 из 1 500 записей:

Reading level: 1 · Age: 5 · Words: 1951

И «какие книги подходят для ребёнка, только начинающего читать самостоятельно» вернули книгу о музыкальных вундеркиндах. Факт был в тексте, но был недостижим: 1 не имеет никакого сходства с начинающим читателем, так как одно слово имеет сходство с другим.

Добавление одного предложения рядом со значением исправило это — измерено на той же записи:

Reading level: 1 · Age: 5
Suitable for around age 5, for children just starting to read on their own.

(Меньше — значит ближе. На этой модели два не связанных фрагмента находятся вокруг 0.61, поэтому последняя строка переходит от «едва лучше случайности» к реальному совпадению — и выигрыш сохраняется для всех языков.)

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

Что не стоит вашего времени

Экспорты часто повторяют себя — summary и description с идентичным текстом. Это выглядит расточительно, и интуиция, что это «тратит» вектор, ошибочна: мы измерили это, и удаление дублирования изменило извлечение на +0.002 расстояния на 60 записей — то есть ничего. Векторное вложение — это направление, а не бюджет; повторение одного и того же в основном указывает в том же направлении дважды.

Оставьте как есть. Потратьте усилия на предложение выше.

4c. Если документы имеют общий заголовок, создайте структурированный индекс

Векторный поиск не может считать, фильтровать по числу или группировать. «Сколько у вас есть», «какие из них менее 200 слов», «сколько на категорию» не отвечаются плохо — они структурно не отвечаются, и агент либо откажется, либо отчитается по тем нескольким записям, которые ему случайно попались.

build_knowledge_index(name="books", roles=["identity", "link", "image"])

Стоит вызывать только тогда, когда документы имеют машиночитаемый заголовок — таблицу метаданных, YAML front matter, строки Field: value. Экспорты продуктов, каталоги, буклеты и списки курсов обычно подходят; проза не подходит, и вызов откажется, вместо того чтобы строить таблицу, значения которой все разные. Отказ — это правильный результат, а не ошибка, которую нужно обходить.

roles называет поля, которые должны быть извлечены точно и никогда не перефразированы:

Спросите пользователя, какие это поля; не выводите их. Какой из трёх URL является тем самым, который нужно отправить клиенту, — это бизнес-факт, который данные не указывают. Если заявленная роль не может быть найдена, она возвращается в roles.unresolved с именами кандидатов — покажите их пользователю, а не выбирайте одну.

Читайте dropped и сообщайте пользователю

{"built": true, "documents": 4523,
 "columns": ["title", "age", "word_count", "genre", "read_url", "cover_url"],
 "dropped": [["isbn", "not_found", "no anchor 'ISBN: ' in the sample"]]}

Удалённый столбец невидим везде остальном: последующие ответы просто обходят его, так что этот отчёт — единственное место, где он когда-либо упоминается. То же самое для get_knowledge_index, чьи предупреждения регулярно выявляют проблемы с данными, о которых клиент не знал — в одном реальном каталоге у десятой части записей количество страниц было 0, что является не короткой книгой, а отсутствующим значением, записанным как ноль, и это снизило бы каждый средний показатель, построенный на нём.

Сообщите об этом своими словами клиента. Ничего другого в платформе не сделает.

Изменение позже

patch_knowledge_index(name="books", request="also track the author", apply=false)

Запустите с apply=false сначала, покажите пользователю, что изменится, пакетно выполните несколько правок, затем примените один раз. Применение снова читает поля из сохранённого текста; оно не пере-вкладывает ничего, поэтому это дёшево.

Запрос чего-то, чего нет в документах, возвращает запись refused с причиной — передайте её пользователю дословно, а не изобретайте обходной путь.

5. ★ Проверьте извлечение — не пропускайте ★

search_knowledge_base(kb_name="Company policy", query="how is the late fee calculated")
#   hits  → the agent can answer this
#   empty → the agent will treat it as "not covered" and say so

6. Подключите её

update_agent(name="Support", add_knowledge_bases=["company-policy"])   # incremental — keeps existing mounts

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

Сообщите об этом — не останавливайтесь на «импортировано». Скажите пользователю, сколько чанков попало, и дайте им кликабельную ссылку, чтобы открыть базу знаний и её звёздную карту знаний (3D-представление того, что было поглощено): https://console.agent4.io/#/knowledge-bases/Company%20policy — затем подтвердите, что она прикреплена к агенту.