На этой странице

Подключите ContextBase к приложению

1. Выдайте приложению доступ к пространству

В разделе Доступ и ключи создайте ключ типа Обычный для пространства с проиндексированной памяткой Next Product Lab из Установка и быстрый старт. Выберите Чтение, задайте срок действия и сохраните полный ключ в хранилище секретов. В списке ключей видны его префикс и статус.

Задайте переменные в локальном терминале или на сервере приложения.

  • CONTEXTBASE_BASE_URL — http://localhost:13000 для локального запуска или HTTPS-адрес вашей установки.

  • CONTEXTBASE_SPACE_ID — UUID из адреса пространства или ответа GET /api/v1/spaces/ с выданным ключом.

  • CONTEXTBASE_API_KEY — полный ключ для заголовка X-API-Key. Храните ключ на серверной стороне приложения.

2. Найдите фрагменты с подтверждением

curl --fail-with-body "$CONTEXTBASE_BASE_URL/api/v1/spaces/$CONTEXTBASE_SPACE_ID/search" \
  -H "X-API-Key: $CONTEXTBASE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"За сколько рабочих дней до демонстрации нужно подготовить черновик заметок к выпуску?","top_k":5}'

Найдите абзац о заметках к выпуску в sources[].text. В памятке указан срок не позднее чем за два рабочих дня до демонстрации.

Найденные фрагменты

Вызовите POST /search и выведите sources[] в порядке ранжирования. Чтобы обойтись без LLM, выберите преобразования запроса и реранкеры, которым она не нужна.

Ответ с цитатами

Вызовите POST /query или POST /query/stream. Выведите answer и sources[] отдельными блоками. Из потока возьмите их в завершающем событии done.

Параметры поиска

  • top_k для search, query и query/stream принимает от 1 до 20. Значение по умолчанию — 5.

  • metadata_filter ограничивает поиск по полям пространства. Сверьте ограничения для выбранного режима.

  • rrf_k меняет константу объединения в search, если пайплайн это поддерживает. Фактическое значение смотрите в retrieval_receipt.

3. Получите ответ и выведите цитаты

Настройте модель и включите генератор в пространстве.

curl --fail-with-body "$CONTEXTBASE_BASE_URL/api/v1/spaces/$CONTEXTBASE_SPACE_ID/query" \
  -H "X-API-Key: $CONTEXTBASE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"За сколько рабочих дней до демонстрации нужно подготовить черновик заметок к выпуску?","top_k":5}'

Проверьте, что цитаты подтверждают срок в два рабочих дня. Формулировка ответа может различаться. При outcome со значением blocked пайплайн удержал ответ.

Используйте для цитат поля источника.

  • text — найденная выдержка. В parent_text может прийти более широкий контекст. В graph_context — сводки и связи графа.

  • locator — проверенное место в документе, когда оно известно. В нём есть document_id, название документа, путь раздела и позиции в символах Юникода. Начало start входит в диапазон, конец end исключён. Страница и метка необязательны. У родительского фрагмента может быть свой parent_locator.

  • bibliography — доступное описание канонического документа. Покажите URL владельца как справочную ссылку. Скачивайте сохранённый оригинал через API документов с авторизацией.

Открывайте канонический чанк через GET /api/v1/spaces/{space_id}/chunks/{chunk_id}. У выдержки из подключённого хранилища может не быть канонического чанка. В этом случае покажите полученный текст. Передавайте ID целиком. После изменения документа он может перестать открываться.

Обратная связь

При наличии query_id по нему можно найти запись запроса. Автор запроса может оценить сохранённый ответ через веб-сессию или ключ с правом read в пространстве. Отправьте оценку через PUT /api/v1/spaces/{space_id}/queries/{query_id}/feedback.

4. Покажите ход генерации

POST /api/v1/spaces/{space_id}/query/stream принимает тело query и возвращает Server-Sent Events. Читайте ответ на POST через SDK или curl -N. Обработайте ошибки HTTP до чтения событий.

Событие

Действие в приложении

stage

Покажите этап по полям stage, label_key, icon и phase.

check

Свяжите проверки по node_id, attempt_id и phase. Используйте вердикт и действие, когда они приходят.

token

Добавьте delta к предварительному тексту. В некоторых режимах, например в графе агентов, приходит готовый ответ без токенов.

done

Замените предварительный текст полями answer и sources. Проверьте outcome на блокировку ответа.

error

Завершите показ прогресса. Выведите detail и обработайте reason. Этим событием заканчивается поток при сбое.

См. код формирования событий и примеры SDK.

Если запрос не сработал

  • 401 — проверьте полный X-API-Key, срок действия и установку.

  • 404 — проверьте UUID и доступ ключа. Пространство без доступа тоже может вернуть 404.

  • 409 — по reason проверьте готовность индекса, модель генератора и совместимость фильтра с режимом запроса.

  • 502 — по detail определите, какой провайдер, хранилище или другой внешний сервис нужно проверить.

Выпуск ключей по API

Вызовите POST /api/v1/auth/api-keys/ с авторизованной пользовательской сессией.

{
  "name": "Демо-приложение Next Product Lab",
  "purpose": "generic",
  "scopes": [{"space": "SPACE_UUID", "level": "read"}]
}

Выдайте write для загрузки документов, manage для изменения пайплайна и запуска оценки от имени владельца в операциях, принимающих ключи. Действуют и уровень ключа, и текущая роль его владельца. Для выпуска ключей нужна пользовательская сессия. Участниками и настройками установки управляйте в веб-интерфейсе. См. Пространства и доступ.

ContextBase0.1.0

Поиск в документации