Ранжирование документов

POST/v1/rerank

Требуемое право: text. Упорядочивает документы по релевантности запросу. Синхронный ответ, как у текстовых операций: оценка стоимости и резерв создаются при приёме, итоговая сумма — после ответа. Неизвестные поля и неподдерживаемые формы отклоняются до резервирования. Не более 1 000 документов, весь запрос — до 1 МиБ. Допустимость операции для модели смотрите в каталоге (availability.operations).

Авторизация

Authorizationstringобязательный

Ключ API в заголовке Authorization: Bearer <ключ>. Ключ создаётся в кабинете, подробнее — в разделе Аутентификация.

Заголовки

Idempotency-Keystringдлина 1–200

Рекомендуется для каждого запроса. Один стабильный ключ на логический запрос; при повторе с тем же телом, тем же credential и endpoint возвращается исходный результат (replay:true) без нового списания. Новый ключ создаёт новый запрос. Если заголовок не передан, сервер подставляет случайный ключ, и повтор после сетевой ошибки будет оплачен как новый запрос.

Тело запроса

application/json · обязательное

modelstringобязательныйдлина 1–200

Публичный ID модели ранжирования из каталога.

querystringобязательный

Запрос; не пустой, до 16 КиБ.

documentsstring[]обязательныйэлементов 1–1000

top_ninteger1 … ∞

Сколько лучших документов вернуть; не больше числа документов. По умолчанию — все.

return_documentsbooleanпо умолчанию false

Вернуть текст документа в каждом элементе results.

max_cost_microrubinteger0 … 9007199254740991

Максимальная разрешённая оценка резерва в микрорублях. Если оценка выше, запрос отклоняется с 409 quote_exceeds_limit до резервирования.

Ответы

200Документы упорядочены

application/json

idstringобязательный

modelstringобязательный

resultsobject[]обязательный

Документы от самого релевантного к менее релевантным.

Вложенные поля

indexintegerобязательный0 … ∞

Позиция документа в исходном массиве documents.

relevance_scorenumberобязательный

documentstring

Текст документа; только при return_documents:true.

usageobject

billingobject

Вложенные поля

statusstring

estimated_cost_microrubinteger0 … 9007199254740991

cost_microrubinteger | null

replayboolean

202Исход уточняется; резерв сохраняется

application/json

Обработка или сверка ещё не завершена. Сохраняйте исходный Idempotency-Key и тело. Резерв удерживается. Не создавайте новый запрос взамен этого.

Тип: object

ОшибкаОшибка проверки, прав, лимита или доступности. Код error.code; результат запроса при неизвестном исходе не следует считать отменённым.

application/json

errorobjectобязательный

Вложенные поля

codestringобязательный

messagestringобязательный

request_idstring

typestring

curl --request POST \ --url "https://api.kvantora.ai/v1/rerank" \ --header "Authorization: Bearer $KVANTORA_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "model": "<public_api_id>", "query": "Как вернуть деньги за заказ?", "documents": [ "Условия возврата средств.", "Расписание работы офиса." ], "top_n": 1 }'

import os import requests response = requests.post( "https://api.kvantora.ai/v1/rerank", headers={ "Authorization": f"Bearer {os.environ['KVANTORA_API_KEY']}", }, json={ "model": "<public_api_id>", "query": "Как вернуть деньги за заказ?", "documents": [ "Условия возврата средств.", "Расписание работы офиса.", ], "top_n": 1, }, timeout=120, ) print(response.json())

const response = await fetch('https://api.kvantora.ai/v1/rerank', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KVANTORA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "<public_api_id>", "query": "Как вернуть деньги за заказ?", "documents": [ "Условия возврата средств.", "Расписание работы офиса." ], "top_n": 1 }), }); console.log(await response.json());

{ "id": "<string>", "model": "<public_api_id>", "results": [ { "index": 0, "relevance_score": 0, "document": "<string>" } ], "usage": {}, "billing": { "status": "<string>", "estimated_cost_microrub": 0, "cost_microrub": 0 }, "replay": true }