AI Platform Docs
API

API Platform RAG

Программный интерфейс сервиса Platform RAG — коллекции, приём документов, поиск.

Общая информация

Сервис: Platform RAG Версия API: 1.0.0 Протокол: HTTP/1.1 + JSON Базовый URL: https://rag.{env}.internal Аутентификация: Bearer JWT (act-chain)

Сервис предоставляет четыре поверхности: collections, ingest, query и eval. Все защищённые операции используют actChain — HTTP Bearer токен формата JWT, через который пробрасывается act-цепочка для авторизации уровня документа.

Аутентификация и авторизация

Все эндпоинты, кроме открытыхHealth-check, требуют действительный JWT-токен. Авторизация выполняется через SpiceDB с проверкой:

  • collection#read для операций поиска;
  • collection#write для операций приёма.

При недоступности службы авторизации возвращается ответ 503 (fail-closed).

Ошибки

Код ответаЗначениеТело ошибки
401Нет/просрочен act-chain (fail-closed){ "code": "unauthorized", "message": "...", "trace_id": "..." }
403Нет прав на коллекцию (SpiceDB){ "code": "forbidden", "message": "...", "trace_id": "..." }
404Не найдено{ "code": "not_found", "message": "...", "trace_id": "..." }
400Невалидный документ / пустой ACL в private{ "code": "invalid_document", "message": "...", "trace_id": "..." }
503AuthZ/IdP недоступен — fail-closed{ "code": "authz_unavailable", "message": "...", "trace_id": "..." }

Коллекции

Создать коллекцию

POST /v1/collections

Создаёт новую коллекцию с закреплённым профилем эмбеддинга, моделью ACL и стратегией чанкинга (COL-1/2).

Тело запроса CreateCollectionRequest:

ПолеТипОбязательноеОписание
collection_idstring (UUID)НетИдентификатор коллекции; генерируется сервером, если не указан
namestringДаИмя коллекции
descriptionstringНетОписание коллекции
collection_typestringНетТип: knowledge_base, documents, files. По умолчанию: knowledge_base
parent_idstring (UUID)НетИдентификатор родительской коллекции
visibilitystringНетВидимость: private или public. По умолчанию: private
embedding_profile_idstringДаИдентификатор профиля эмбеддинга из Control Plane
acl_modelstringНетМодель ACL: document или collection. По умолчанию: document
chunkingobjectНетСтратегия чанкинга: { "strategy": "recursive_text", "size": 800, "overlap": 120 }
retrieval_defaultsobjectНетПараметры поиска по умолчанию: { "mode": "hybrid", "top_k": 8 }
empty_acl_policystringНетПолитика пустого ACL: reject или strictest. По умолчанию: reject

Ответ 201 Created — Collection

Получить коллекцию

GET /v1/collections/{collection_id}

Возвращает карточку коллекции (COL-4).

Параметры пути:

ПолеТипОписание
collection_idstring (UUID)Идентификатор коллекции

Ответ 200 OK — Collection

Получить список коллекций

GET /v1/collections

Возвращает список всех коллекций, доступных вызывающему (COL-4).

Ответ 200 OK — массив Collection

Переиндексация коллекции

POST /v1/collections/{collection_id}:reindex

Запускает версионируемую переиндексацию (COL-3). In-place изменение профиля эмбеддинга не допускается. Новая версия индекса создаётся атомарно.

Ответ 202 Accepted — Collection

Схема Collection

ПолеТипОписание
collection_idstring (UUID)Идентификатор коллекции
tenant_idstringИдентификатор рабочего пространства
namestringИмя коллекции
descriptionstringОписание
collection_typestringТип коллекции
parent_idstring (UUID)Родительская коллекция
visibilitystringВидимость: private / public
embedding_profile_idstringПрофиль эмбеддинга
acl_modelstringМодель ACL: document / collection
chunkingobjectСтратегия чанкинга
retrieval_defaultsobjectПараметры поиска по умолчанию
empty_acl_policystringПолитика пустого ACL
statusstringСтатус: created, populating, ready, deleted, error
active_versionintegerАктивная версия индекса
doc_countintegerКоличество документов
chunk_countintegerКоличество чанков
created_atstring (date-time)Дата создания
updated_atstring (date-time)Дата обновления

Приём документов

submit_documents

POST /v1/documents:submit

Приём канонических документов от интеграционных сервисов (ING-1).

Тело запроса SubmitDocumentsRequest:

ПолеТипОбязательноеОписание
documentsarrayДаМассив канонических документов

Каждый документ в массиве соответствует схеме CanonicalDocument:

ПолеТипОбязательноеОписание
opstringНетОперация: upsert или delete. По умолчанию: upsert
collectionstringДаИмя или идентификатор коллекции
tenant_idstringДаИдентификатор рабочего пространства
doc_idstringДаУникальный идентификатор документа в источнике
contentobjectДа (для upsert)Содержимое: { "title": "...", "sections": [...], "tables": [...] }
content_refobjectДа (альтернатива content)Ссылка на документ в object storage: { "uri": "s3://...", "content_hash": "..." }
metadataobjectНетМетаданные: source, url, labels, valid_from, valid_until
aclobjectНетACL: { "groups": [...], "principals": [...], "scope": {...} }
content_hashstringДаХеш содержимого для дедупликации
idempotency_keystringДаКлюч идемпотентности

Важно: Для приватной коллекции пустой acl недопустим. Сервис отклоняет такой документ либо, при явном разрешении, индексирует его с самой строгой видимостью (ING-7).

Ответ 202 Accepted — SubmitDocumentsResponse:

ПолеТипОписание
jobsarrayМассив результатов обработки

Каждый результат:

ПолеТипОписание
doc_idstringИдентификатор документа
job_idstring (UUID)Идентификатор задания
statusstringPENDING — задание принято, DEDUPLICATED — документ уже проиндексирован

ingest_status

GET /v1/jobs/{job_id}

Возвращает статус задания из источника истины (PostgreSQL) (ING-2).

Параметры пути:

ПолеТипОписание
job_idstring (UUID)Идентификатор задания

Ответ 200 OK — IngestJob:

ПолеТипОписание
job_idstring (UUID)Идентификатор задания
collectionstringИмя коллекции
tenant_idstringИдентификатор рабочего пространства
doc_idstringИдентификатор документа
opstringОперация: upsert / delete
content_hashstringХеш содержимого
idempotency_keystringКлюч идемпотентности
statusstringPENDING, RUNNING, DONE, FAILED
payload_uristringСсылка на staging-объект в S3 (null для delete / dedup)
payload_bytesintegerРазмер staging-объекта в байтах
attemptsintegerКоличество попыток обработки
errorstringСообщение об ошибке (null при успехе)
trace_idstringИдентификатор трассировки
created_atstring (date-time)Дата создания
updated_atstring (date-time)Дата обновления
available_atstring (date-time)Время доступности для поиска (null до DONE)

Поиск

Гибридный поиск

POST /v1/query

Возвращает отфильтрованные по ACL результаты гибридного поиска (RET-1/2/3).

Тело запроса QueryRequest:

ПолеТипОбязательноеОписание
collectionstringДаИмя или идентификатор коллекции
textstringДаТекст запроса
modestringНетРежим поиска: hybrid, vector, bm25. По умолчанию: hybrid
top_kintegerНетКоличество результатов. По умолчанию: 8
rerankbooleanНетВключить реранк. По умолчанию: false
rewritebooleanНетВключить переписывание запроса. По умолчанию: false
filtersobjectНетДополнительные фильтры

Ответ 200 OK — QueryResponse:

ПолеТипОписание
itemsarrayМассив цитат
metaobjectМетаданные запроса

Каждая цитата Citation:

ПолеТипОписание
doc_idstringИдентификатор документа-источника
chunk_idstringИдентификатор чанка
source_urlstringURL источника (null если отсутствует)
titlestringЗаголовок документа (null если отсутствует)
contentstringТекст чанка
scorenumberОценочный балл релевантности

Метаданные QueryMeta:

ПолеТипОписание
modestringРежим поиска
top_kintegerЗапрошенное количество результатов
rerankbooleanБыл ли применён реранк
hybrid_weightsobjectВеса гибридного поиска
trace_idstringИдентификатор трассировки

Упаковка контекста

POST /v1/retrieve_and_pack

Возвращает упакованный контекст под заданный бюджет токенов (RET-4).

Тело запроса RetrieveAndPackRequest:

Наследует все поля QueryRequest плюс:

ПолеТипОбязательноеОписание
token_budgetintegerДаМаксимальный бюджет токенов для упакованного контекста

Ответ 200 OK — PackedContext:

ПолеТипОписание
packed_contextstringУпакованный текстовый контекст
token_countintegerКоличество токенов в контексте
modestringРежим: full_document или relevance_search
itemsarrayМассив цитат, вошедших в контекст
metaobjectМетаданные запроса

Канонический документ — JSON Schema

Все документы, передаваемые через submit_documents, должны соответствовать схеме CanonicalDocument:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://platform-rag/contracts/canonical-document.schema.json",
  "title": "CanonicalDocument",
  "type": "object",
  "required": ["collection", "tenant_id", "doc_id", "content_hash", "idempotency_key"],
  "additionalProperties": false,
  "properties": {
    "op": { "type": "string", "enum": ["upsert", "delete"], "default": "upsert" },
    "collection": { "type": "string", "minLength": 1 },
    "tenant_id": { "type": "string", "minLength": 1 },
    "doc_id": { "type": "string", "minLength": 1 },
    "content": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "sections": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["text"],
            "properties": {
              "heading": { "type": "string" },
              "text": { "type": "string" }
            },
            "additionalProperties": false
          }
        },
        "tables": { "type": "array", "items": { "type": "object" } }
      },
      "additionalProperties": true
    },
    "content_ref": {
      "type": "object",
      "description": "Ссылка на уже загруженный канонический JSON в object storage (by-ref submit). Взаимоисключим с тяжёлым inline content на уровне API-лимита.",
      "required": ["uri", "content_hash"],
      "additionalProperties": false,
      "properties": {
        "uri": {
          "type": "string",
          "description": "s3://… или https presigned GET на CanonicalDocument JSON"
        },
        "content_hash": {
          "type": "string",
          "description": "Должен совпадать с корневым content_hash"
        },
        "bytes": { "type": "integer", "minimum": 1 }
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "source": { "type": "string" },
        "url": { "type": "string", "format": "uri" },
        "labels": { "type": "array", "items": { "type": "string" } },
        "valid_from": { "type": "string", "format": "date-time" },
        "valid_until": { "type": "string", "format": "date-time" }
      },
      "additionalProperties": true
    },
    "acl": {
      "type": "object",
      "properties": {
        "groups": { "type": "array", "items": { "type": "string" } },
        "principals": { "type": "array", "items": { "type": "string" } },
        "scope": { "type": "object", "additionalProperties": true }
      },
      "additionalProperties": false
    },
    "content_hash": { "type": "string", "minLength": 1 },
    "idempotency_key": { "type": "string", "minLength": 1 }
  }
}

Примеры запросов

Создание коллекции

POST /v1/collections
{
  "name": "handbook",
  "description": "Корпоративный справочник",
  "embedding_profile_id": "text-default-v1",
  "acl_model": "document",
  "chunking": {
    "strategy": "recursive_text",
    "size": 800,
    "overlap": 120
  },
  "retrieval_defaults": {
    "mode": "hybrid",
    "top_k": 8
  }
}

Поиск

POST /v1/query
{
  "collection": "handbook",
  "text": "Правила оформления отпуска",
  "mode": "hybrid",
  "top_k": 5,
  "rerank": true
}

Упаковка контекста

POST /v1/retrieve_and_pack
{
  "collection": "handbook",
  "text": "Правила оформления отпуска",
  "token_budget": 3000,
  "rerank": true
}

Приём документов

POST /v1/documents:submit
{
  "documents": [
    {
      "op": "upsert",
      "collection": "handbook",
      "tenant_id": "acme",
      "doc_id": "confluence:HR:12345",
      "content": {
        "title": "Отпуск",
        "sections": [
          { "heading": "Правила", "text": "До 28 дней в год." }
        ]
      },
      "metadata": {
        "source": "confluence",
        "url": "https://.../HR/12345",
        "labels": ["policy"]
      },
      "acl": {
        "groups": ["group:hr"],
        "principals": [],
        "scope": { "confluence_space": "HR" }
      },
      "content_hash": "abc123...",
      "idempotency_key": "confluence:12345:rev-88"
    }
  ]
}

Интерфейсы памяти агентов

Предыдущая страница

API Guardrails Runtime

Следующая страница

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

Общая информацияАутентификация и авторизацияОшибкиКоллекцииСоздать коллекциюПолучить коллекциюПолучить список коллекцийПереиндексация коллекцииСхема CollectionПриём документовsubmit_documentsingest_statusПоискГибридный поискУпаковка контекстаКанонический документ — JSON SchemaПримеры запросовСоздание коллекцииПоискУпаковка контекстаПриём документов