Skip to main content
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 channeldocument.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