На этой странице
Просмотр и обновление корпуса¶
Проверьте текст и фрагменты¶
В разделе Документы найдите файл по имени, статусу или типу. Для поиска документ должен быть проиндексирован и активен. При работе со сгруппированными копиями действует 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, UUIDcommand_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}]
}
}