Rerank (ранжирование документов)

Rerank — это переупорядочивание списка документов по их релевантности к заданному поисковому запросу. В отличие от поиска, который возвращает документы в исходном порядке, rerank использует модель для оценки, насколько каждый документ соответствует запросу, и возвращает их отсортированными по убыванию релевантности.

Для чего используется Rerank

• RAG (Retrieval-Augmented Generation): второй этап пайплайна — после быстрого поиска (например, по эмбеддингам) rerank уточняет порядок кандидатов перед передачей в LLM
• Семантический поиск: повышение точности выдачи за счёт глубокой оценки релевантности
• Фильтрация шума: отсечение нерелевантных документов из предварительно отобранного множества
• Анализ документов: ранжирование фрагментов текста по соответствию запросу

Эндпоинты

Аутентификация

Authorization: Bearer sk_ваш_api_ключ

POST /v1/rerank

Переранжирование списка документов по релевантности к запросу.

Параметры запроса

Параметр documents

Документы могут быть:

Простой строкой — обычный текст документа:

"Paris is the capital of France."

Структурированным объектом — для мультимодальных моделей, с полями text и/или image. Должно быть указано хотя бы одно из них:

{
  "text": "Описание изображения",
  "image": "https://example.com/image.png"
}

Поле image принимает удалённый URL (http/https) или data-URI в base64 (data:image/...).

Параметр provider

Настройки маршрутизации провайдера для данного запроса. Все параметры необязательные.

Базовый запрос (cURL)

curl https://api.ru-openrouter.ru/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -d '{
    "model": "cohere/rerank-v3.5",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital of France.",
      "Berlin is the capital of Germany."
    ],
    "top_n": 3
  }'

Пример на Python

import requests

response = requests.post(
    "https://api.ru-openrouter.ru/v1/rerank",
    headers={
        "Authorization": "Bearer sk_ваш_api_ключ",
        "Content-Type": "application/json",
    },
    json={
        "model": "cohere/rerank-v3.5",
        "query": "What is the capital of France?",
        "documents": [
            "Paris is the capital of France.",
            "Berlin is the capital of Germany."
        ],
        "top_n": 3,
    }
)

data = response.json()
for result in data["results"]:
    print(f"{result['index']}: {result['document']['text']} (score: {result['relevance_score']})")

Пример на Node.js

const response = await fetch("https://api.ru-openrouter.ru/v1/rerank", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_ваш_api_ключ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "cohere/rerank-v3.5",
    query: "What is the capital of France?",
    documents: [
      "Paris is the capital of France.",
      "Berlin is the capital of Germany."
    ],
    top_n: 3,
  }),
});

const data = await response.json();
console.log(data.results);

Пример на PHP

$ch = curl_init("https://api.ru-openrouter.ru/v1/rerank");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_ваш_api_ключ",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "model" => "cohere/rerank-v3.5",
        "query" => "What is the capital of France?",
        "documents" => [
            "Paris is the capital of France.",
            "Berlin is the capital of Germany."
        ],
        "top_n" => 3,
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));

Пример ответа

{
  "id": "gen-rerank-1782124967-sYTtu1JdgYUQ6uHj4kvL",
  "model": "cohere/rerank-v3.5",
  "results": [
    {
      "document": {
        "text": "Paris is the capital of France."
      },
      "index": 0,
      "relevance_score": 0.98
    },
    {
      "document": {
        "text": "Berlin is the capital of Germany."
      },
      "index": 1,
      "relevance_score": 0.12
    }
  ],
  "usage": {
    "search_units": 1,
    "total_tokens": 150,
    "cost_rub": 0.015
  }
}

Поля ответа

GET /v1/rerank/models

Возвращает список моделей, поддерживающих ранжирование документов (rerank).

curl https://api.ru-openrouter.ru/v1/rerank/models \
  -H "Authorization: Bearer sk_ваш_api_ключ"

Пример ответа

{
  "object": "list",
  "data": [
    {
      "id": "cohere/rerank-v3.5",
      "object": "model",
      "created": 1709012345,
      "owned_by": "cohere",
      "pricing": {
        "prompt": "0.000015000",
        "currency": "RUB",
        "pricing_type": "per_request"
      },
      "description": "Cohere: Rerank v3.5"
    }
  ]
}

Поля ответа

Также список rerank-моделей можно получить через /v1/models?filter=rerank.

Ограничения

Коды ошибок