LLMTOKENAPI
ВойтиНачать

База знаний через API: загрузка, поиск и ответы

Пошаговая работа с базой знаний через API: создание, идемпотентная загрузка файлов, статус индексации, семантический поиск, ответы и цитаты.

8 сентября 2026 г.4 мин чтенияОбновлено 8 сентября 2026 г.
Документы проходят индексацию, собираются в многослойную базу и превращаются в ответ с выбранными доказательствами

База знаний через API превращает набор документов в постоянный поисковый слой: приложение загружает файлы, ждёт индексацию, находит релевантные фрагменты и получает ответ с цитатами. В LLMTOKENAPI этот цикл собран вокруг /v1/knowledge-bases; данные разных организаций изолированы, а исходный контент хранится в зашифрованном виде.

Когда нужна управляемая база знаний

Собственная связка парсера, embeddings, векторной базы и генерации даёт полный контроль, но требует обслуживать форматы, очереди, повторные загрузки, права доступа и удаление. Управляемый API полезен, когда продукту важнее быстро получить воспроизводимый RAG-контур и измерять качество ответа, чем поддерживать каждый инфраструктурный компонент.

Для разового поиска по нескольким страницам постоянная база избыточна: используйте Contents или Search API. Если данные должны автоматически обновляться с сайта, подключите Website Knowledge Sync — его отдельная схема описана в статье про синхронизацию базы знаний.

Создайте базу отдельным запросом

Ключу нужны knowledge:write для создания и загрузки, а также knowledge:read для статуса, поиска и ответа. Начните с понятного имени и необязательного описания:

curl https://api.llmtokenapi.ru/v1/knowledge-bases \
  -H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Документация продукта",
    "description": "Публичные руководства и внутренние регламенты поддержки"
  }'

Сохраните id из ответа как BASE_ID. Не используйте имя как технический идентификатор: оно описывает бизнес-контекст, а UUID служит ссылкой для файлов, поиска и удаления. Список баз читается через GET /v1/knowledge-bases.

Загрузите файл идемпотентно

Файл передаётся как multipart/form-data в поле file. Для каждого логического добавления нужен Idempotency-Key; при сетевом повторе отправляйте тот же ключ:

curl https://api.llmtokenapi.ru/v1/knowledge-bases/BASE_ID/files \
  -H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
  -H "Idempotency-Key: support-handbook-v3" \
  -F "file=@support-handbook.pdf"

Один файл может занимать до 100 МБ и до 1 000 страниц. Поддерживаются PDF, DOCX, PPTX, XLSX, TXT, Markdown, HTML, CSV и распространённые растровые изображения. TypeScript SDK умеет ограниченно параллелить пакет до 100 файлов, но каждому элементу всё равно назначается отдельное задание и идемпотентный ключ.

Перед обработкой содержимое проходит проверку и разбор. Повторная отправка файла с тем же хешем в ту же базу не должна создавать вторую копию. Это полезная страховка, но не заменяет версионирование на стороне приложения: храните источник, дату и бизнес-версию документа рядом с его идентификатором.

Дождитесь готовности индекса

Загрузка создаёт асинхронное ingest-задание. Не отправляйте пользовательский вопрос сразу после 202 Accepted. Проверяйте общий статус базы:

curl https://api.llmtokenapi.ru/v1/knowledge-bases/BASE_ID/status \
  -H "Authorization: Bearer $LLMTOKENAPI_API_KEY"

Статус показывает число готовых, обрабатываемых и проблемных файлов. По уже готовой части можно искать, пока остальные документы ещё индексируются. В интерфейсе показывайте эту неполноту явно: «готово 18 из 20» полезнее, чем молча отвечать по частичному корпусу.

Список объектов доступен через GET /v1/knowledge-bases/BASE_ID/files. Для сбоя сохраните идентификатор задания и публичный код ошибки; не повторяйте загрузку с новым ключом, пока не выяснено состояние старого запуска.

Сначала проверьте семантический поиск

До генерации ответов убедитесь, что retrieval находит нужные фрагменты. Метод /search принимает вопрос, topK от 1 до 50 и флаг rerank, включённый по умолчанию:

curl https://api.llmtokenapi.ru/v1/knowledge-bases/BASE_ID/search \
  -H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Каков срок ответа поддержки на критический инцидент?",
    "topK": 8,
    "rerank": true
  }'

Проверяйте не только первый результат. Целевой фрагмент должен находиться среди верхних кандидатов, содержать достаточный контекст и ссылаться на ожидаемый файл. Если retrieval слабый, генеративная модель не исправит отсутствующее доказательство. Практика измерения порядка документов разобрана в руководстве по Rerank API для RAG.

Получите ответ с цитатами

Когда поиск стабилен, используйте /answer. Параметр model: "auto" оставляет выбор подходящего публичного маршрута сервису, а maxOutputTokens ограничивает длину результата:

curl https://api.llmtokenapi.ru/v1/knowledge-bases/BASE_ID/answer \
  -H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Каков срок ответа поддержки на критический инцидент?",
    "topK": 8,
    "rerank": true,
    "model": "auto",
    "maxOutputTokens": 1200
  }'

Ответ должен рассматриваться вместе с citations. Ссылка доказывает происхождение фрагмента, но не гарантирует, что документ актуален или правило применимо к конкретному клиенту. Для юридических, медицинских и финансовых решений добавляйте проверку человеком и дату действия источника.

Разделите доступ и жизненный цикл данных

Не используйте один ключ для загрузчика и пользовательского чат-интерфейса. Процесс импорта получает knowledge:write, а runtime ответа — только knowledge:read. База привязана к организации; идентификатор другого tenant не должен открывать его файлы.

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

Измерьте качество на собственных вопросах

Составьте набор из 30–100 реальных вопросов: простые факты, сравнения, вопросы без ответа и конфликтующие версии. Для каждого отметьте правильный файл, ожидаемый смысл и допустимый отказ. Измеряйте recall retrieval, корректность цитаты, полноту ответа, задержку и стоимость.

Актуальные схемы запросов доступны в OpenAPI LLMTOKENAPI, а общие ограничения — в документации. Хорошая база знаний через API начинается с контролируемого корпуса и проверки поиска. Лишь после этого подключайте генерацию, иначе красивый ответ скроет проблему индексации вместо того, чтобы решить её.