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

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

Канонический URL: https://llmtokenapi.ru/blog/baza-znaniy-cherez-api
Опубликовано: 2026-09-08T15:20:21.245Z
Автор: Команда LLMTOKENAPI

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

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

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

Для разового поиска по нескольким страницам постоянная база избыточна: используйте Contents или Search API. Если данные должны автоматически обновляться с сайта, подключите Website Knowledge Sync — его отдельная схема описана в статье про [синхронизацию базы знаний](/blog/sinhronizaciya-bazy-znaniy-s-saytom).

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

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

```bash
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`; при сетевом повторе отправляйте тот же ключ:

```bash
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`. Проверяйте общий статус базы:

```bash
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`, включённый по умолчанию:

```bash
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](/blog/rerank-api-dlya-rag).

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

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

```bash
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](https://api.llmtokenapi.ru/openapi.json), а общие ограничения — в [документации](/docs). Хорошая база знаний через API начинается с контролируемого корпуса и проверки поиска. Лишь после этого подключайте генерацию, иначе красивый ответ скроет проблему индексации вместо того, чтобы решить её.