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

Просмотр и обновление корпуса

Проверьте текст и фрагменты

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

Общий префикс REST-эндпоинтов — /api/v1/spaces/{space_id}.

  • GET /documents возвращает статус и число фрагментов. name ищет подстроку без учёта регистра. Фильтры — status и content_type. Для постраничного просмотра задайте page и page_size.

  • GET /documents/{document_id} возвращает сведения о файле. extracted_char_count считает кодовые точки Unicode до чанкинга, включая пробелы. null означает неизвестное значение, ноль — пустой результат извлечения.

  • GET /documents/{document_id}/download скачивает исходник.

  • GET /chunks?document_id={document_id} перечисляет фрагменты в порядке нарезки. Фильтр по тексту — q. Используйте GET /chunks/{chunk_id} для чтения текста, метаданных и доступного контекста, а GET /chunks/sizes для проверки длин фрагментов.

Сведения о документе · Список фрагментов · Просмотр фрагмента

Посмотрите карту эмбеддингов

Откройте Данные → Карта эмбеддингов. Точка обозначает фрагмент, цвет — документ. Нажмите точку, чтобы прочитать текст. Карта приближённо передаёт расстояния, проецируя плотные векторы на плоскость методом главных компонент (PCA).

Введите запрос и нажмите Подсветить, чтобы увидеть совпадения текущего пайплайна. Показать на карте из карточки источника запускает новый поиск только по тексту вопроса. Точную цитату проверяйте в карточке. Очистите запрос, чтобы убрать подсветку.

Если карты ещё нет, владелец может нажать Построить карту. Страница опрашивает статус. Воркер использует экспортированные векторы или заново вычисляет эмбеддинги доступных листовых фрагментов и сохраняет позиции. Повторное вычисление может вызвать платные запросы и даёт приближённые векторы при позднем чанкинге. Если карта хранит позиции, включите новые фрагменты через POST /chunk-map/build.

  • GET /chunk-map требует права чтения (область ключа read). status принимает значения absent, building или ready. Готовая карта возвращает points с полями chunk_id, document_id, x и y. Для получения matched_chunk_ids передайте query и при необходимости top_k (по умолчанию 5, диапазон 1–20). Ограничения запроса. Поиск может вызвать настроенные модели. При 409 из-за отсутствия нужной LLM повторите запрос без query. Если карта без запроса возвращает 409 из-за недоступных векторов, перестройте её.

  • POST /chunk-map/build требует права записи (область write) и пустого тела. Возвращает 202 Accepted с document_count и estimated_seconds, которое может быть null. Повтор во время построения возвращает enqueued: false. Опросите эндпоинт чтения для получения результата.

  • POST /chunk-map/give-up требует тех же прав и пустого тела. Используйте его после подтверждения потери сообщения. Он снимает заявку до начала работы воркера и возвращает released и status.

Чтение карты · Запуск построения · Снятие заявки · Экспорт и повторное вычисление векторов

Замените, переиндексируйте или удалите документ

  • Исправить метаданные. Отправьте PATCH /documents/{document_id} с телом {"metadata": {...}}. Добавьте все поля, которые нужно сохранить. Запрос заменяет объект метаданных без новой нарезки и пересчёта эмбеддингов.

  • Заменить исходник в управляемом хранилище. Прочитайте accepted_revision_id и intent_version через GET /documents/{document_id}. Отправьте файл как multipart на POST /documents/{document_id}/original с параметрами intent=replace, UUID command_id, логическим use_llm, expected_intent_version и expected_revision_id при наличии принятой версии. Устаревшие ожидаемые версии отклоняются. Для повторяемого создания укажите свободный UUID, intent=create и пропустите обе ожидаемые версии. При неизвестном результате повторите запрос с теми же данными и UUID команды.

  • Переиндексировать, деактивировать или активировать в управляемом хранилище. Откройте действия файла в разделе Документы. Через REST отправьте POST /documents/{document_id}/{reindex|deactivate|activate} с {"command_id":"<UUID>"}. Переиндексация обновляет нарезку и индексы. Деактивация убирает документ из поиска и сохраняет исходник. Активация публикует фрагменты для поиска.

  • Удалить документ. Отправьте DELETE /documents/{document_id}. 204 No Content означает, что запрос принят. Документ скрывается сразу, а физическое удаление идёт в фоне. Заголовок X-Document-Operation-Id содержит идентификатор операции. В подключённом хранилище можно удалить только записи ContextBase. См. Подключения и хранилища.

Проверяйте GET /document-operations/{operation_id} в состояниях awaiting_original, queued, running и publishing. Остановитесь на succeeded, failed или cancelled. При ошибке проверьте операцию и документ перед повтором. Пока готовится замена, поиск может использовать предыдущую принятую версию.

Замена исходника и проверка версии · Статус фоновой операции

Выберите и зарегистрируйте модель эмбеддингов

Привяжите модель эмбеддингов при создании пространства. Размерность индекса и векторов модели должна совпасть. Для подключённой коллекции подберите модель и настройки запроса под записанные векторы. Для перехода на другую размерность или способ получения векторов создайте новое пространство с нужной моделью и загрузите корпус заново.

GET /api/v1/embedding-models перечисляет доступные модели. GET /api/v1/embedding-models/catalog описывает параметры регистрации. Локальные модели запускает сама установка. Для OpenAI-совместимого сервиса укажите ID модели, размерность и базовый URL перед /embeddings. При регистрации сервис получит пробный запрос. Если задано params.dimensions, значение должно совпасть с dim. Ключ API храните как секрет.

Чтобы обновить зарегистрированную вами модель, отправьте PUT /api/v1/embedding-models/{id}. Пока модель привязана к пространству, можно менять только api_key, embed_batch_size, max_concurrent_requests, max_retries, max_tokens_per_request, price_per_million_tokens и timeout. Существующие векторы остаются пригодны для поиска. При изменении остальных параметров 409 Conflict перечислит привязанные пространства.

Перед массовой загрузкой проверьте отчёт проверки и Подключения и хранилища. Индекс HNSW в pgvector поддерживает до 2 000 измерений для используемого типа векторов. Предел размерности HNSW. Подберите embed_batch_size под пропускную способность и память.

Каталог моделей · Проверка модели · Пакеты индексации

Примените новую конфигурацию

Установите jq и используйте ключ API владельца с областью manage. Прочитайте весь config через GET /api/v1/spaces/{space_id}, замените чанкер и проверьте полный JSON. В примере размер фрагмента — 384 токена, перекрытие — 48.

space="${BASE_URL}/api/v1/spaces/${SPACE_ID}"
curl --fail-with-body -sS -H "X-API-Key: ${CONTEXTBASE_API_KEY}" "$space" |
  jq '.config | .chunk = {"node":"fixed","params":{"chunk_size":384,"chunk_overlap":48}}' > proposed-pipeline.json
curl --fail-with-body -sS -H "X-API-Key: ${CONTEXTBASE_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @proposed-pipeline.json \
  "$space/config/validate"

Проверка возвращает ошибки, объём перестройки и оценку затрат. Изучите отчёт и отправьте тот же полный JSON на PUT /config по адресу пространства.

  • Изменения на пути запроса могут примениться сразу.

  • Для управляемого хранилища опрашивайте GET /config/status. Проверьте rebuilding, stale, rebuild_failed и счётчики обработанных и неудачных документов. После завершения проверьте поиск. В зависимости от изменения задача обновляет представления или заново нарезает корпус.

  • Для подключённого хранилища следите за проходом по внешним данным по статусу индекса хранилища.

POST /config/reindex запускает повторную нарезку подходящего корпуса по сохранённым настройкам. POST /config/recheck проверяет ресурсы без применения изменений.

Применение конфигурации · Статус перестройки

Фильтруйте по метаданным

Как владелец пространства, отправьте PUT /metadata-schema с полной схемой. Каждый элемент fields содержит name, field_type и необязательное indexed (по умолчанию true). Типы — string, string_list, number и boolean. Для года используйте число, а для строковых дат — единый формат ISO.

При записи документа проверяются все объявленные поля, в том числе неиндексируемые. Фильтровать можно только по объявленным индексируемым полям. Остальные поля можно хранить в метаданных. После 202 Accepted дождитесь фонового обновления, если изменился состав индекса. Ранее принятые документы повторно не валидируются. При правке метаданных документа исходник и нарезка сохраняются.

В поддерживаемых режимах metadata_filter отбирает кандидатов до ранжирования. Соединяйте conditions и подгруппы через all или any. Операторы зависят от типа поля. Используйте eq для равенства, one_of для вхождения в набор значений и contains для элемента списка. Режимы без поддержки фильтра отклоняют такой запрос.

Объявите year как число и отправьте запрос поиска.

{
  "query": "Когда надо подать заявку на командировку?",
  "metadata_filter": {
    "join": "all",
    "conditions": [{"field": "year", "operator": "eq", "value": 2026}]
  }
}

Схема метаданных · Группы фильтров

ContextBase0.1.0

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