Перейти к основному содержанию
POST
Rerank documents: bge-reranker-v2-m3
Используйте playground справа, чтобы напрямую вызвать endpoint: поместите Bearer sk-your-api-key в Authorization, затем нажмите кнопку отправки — тело примера уже заполнено.
Возможности модели, тарификация, измеренные данные и три подводных камня приведены в overview. Сведения о размерности Recall, разбиении на чанки и пороговой стратегии приведены в RAG tuning in practice.

Справочник параметров

Нераспознанные параметры (max_chunks_per_doc, rank_fields, truncate, …) молча игнорируются, а не отклоняются.

Примечания к ответу

  • index — исходная позиция документа в массиве documents, который вы отправили. Используйте её, чтобы найти объект своего документа; не сопоставляйте по возвращённому text.
  • relevance_score — диапазон 0–1. Сопоставимо только внутри одного запроса. Не сопоставимо между запросами, а в кросс-языковых случаях систематически ниже. См. обсуждение порога в обзоре.
  • results всегда отсортирован по relevance_score по убыванию; значения index полные и уникальные.
  • Считывайте usage из prompt_tokens (query учитывается один раз + все документы) и total_tokens (query учитывается для каждой пары); input_tokens / output_tokens на этом канале всегда 0. Этот раунд не смог подтвердить по тарификации, какое поле является платным — считайте счёт из консоли авторитетным.

Коды ошибок

Сначала подозревайте имя модели при 503. Если тело запроса не удается разобрать (например Content-Type: text/plain), шлюз вообще не читает поле model и возвращает тот же 503 с пустым именем модели — это выглядит как недоступность канала, но ею не является.
Неверный path не приводит к 404. И /rerank, и /v2/rerank (значение по умолчанию в Cohere v2 SDK) возвращают HTTP 200 с HTML домашней страницы сайта, что на стороне клиента выглядит как ответ, который невозможно разобрать. https://api.apiyi.com/v1/rerank — это единственный допустимый path.

Заметки по отладке

При очень малом числе кандидатов разница в оценках экстремальна (0.97 для первого, 0.12 для второго) и ничего не говорит о том, где проходит граница решения модели. Используйте 10–20 документов, включая 2–3 намеренных отвлекающих варианта — тематически близких, но не отвечающих на вопрос. Это показывает диапазон оценок на вашем корпусе, а именно на него должен опираться любой порог.
Китайский запрос к английским документам может оценивать правильные ответы всего в 0.003–0.3, но порядок верный. Это свойственно модели, а не сломанному вызову. Оценивайте по порядку, а не по абсолютному значению.
Даже один кандидат дает около 2 с на P50 — это фиксированные накладные расходы шлюза и upstream. Переход от 1 к 100 кандидатам увеличивает P50 лишь с 2.0 с до 3.8 с. Поэтому не сокращайте набор кандидатов ради снижения задержки; выигрыш намного меньше, чем ожидается.
Upstream TPM составляет всего 20,000. Итерации с 100 кандидатами сжигают весь минутный бюджет примерно за 15 вызовов и начинают возвращать 429. Вместо этого отлаживайте с 10–20 кандидатами — этого достаточно, чтобы увидеть распределение оценок, не прерываясь из-за квоты. См. раздел о квоте в настройке RAG.

Авторизации

Authorization
string
header
обязательно

Add the Authorization: Bearer YOUR_API_KEY request header

Тело

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

Always bge-reranker-v2-m3 (case-sensitive; a wrong name returns 503)

Пример:

"bge-reranker-v2-m3"

query
string
обязательно

The search query. An empty string returns 400

documents
string[]
обязательно

Candidate documents. Plain string array only — passing Cohere-style [{"text": "..."}] objects returns 400. Cannot be empty. Keep to 100 or fewer.

top_n
integer

Return the top N results. Omitting it, or passing 0 or a negative number, returns all. Must be an integer — a string returns 400. Does not affect usage: every candidate is scored regardless.

Пример:

2

return_documents
boolean

Whether to echo the document text in results. Note: this parameter currently has no effect on this channel — document.text is always echoed. If response size matters, map results back by index yourself rather than relying on this flag to trim the payload.

Пример:

true

Ответ

Rerank succeeded

results
object[]

Sorted by relevance_score, descending

usage
object

Token usage. This model consumes input tokens only