Ранжирование (Rerank)

Rerank — это процесс переупорядочивания набора документов по степени их релевантности к заданному запросу. Используется для улучшения качества поиска и RAG-систем.

Эндпоинт /v1/rerank позволяет передать поисковый запрос и список документов, после чего модель вернёт их ранжированными по релевантности.

Базовое использование

Python

import requests

response = requests.post(
    "https://api.aitunnel.ru/v1/rerank",
    headers={
        "Authorization": "Bearer sk-aitunnel-xxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "rerank-4-pro",
        "query": "Что такое искусственный интеллект?",
        "documents": [
            "Искусственный интеллект — область компьютерных наук.",
            "Машинное обучение является подразделом ИИ.",
            "Нейронные сети — основа современного глубокого обучения.",
            "Python — популярный язык программирования.",
        ],
        "top_n": 3,
    },
)

data = response.json()
for result in data["results"]:
    print(f"Индекс: {result['index']}, Релевантность: {result['relevance_score']:.4f}")
    print(f"  Документ: {result['document']['text']}")

TypeScript

const response = await fetch("https://api.aitunnel.ru/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-aitunnel-xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "rerank-4-pro",
    query: "Что такое искусственный интеллект?",
    documents: [
      "Искусственный интеллект — область компьютерных наук.",
      "Машинное обучение является подразделом ИИ.",
      "Нейронные сети — основа современного глубокого обучения.",
      "Python — популярный язык программирования.",
    ],
    top_n: 3,
  }),
});

const data = await response.json();
for (const result of data.results) {
  console.log(`Индекс: ${result.index}, Релевантность: ${result.relevance_score.toFixed(4)}`);
  console.log(`  Документ: ${result.document.text}`);
}

cURL

curl https://api.aitunnel.ru/v1/rerank \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-4-pro",
    "query": "Что такое искусственный интеллект?",
    "documents": [
      "Искусственный интеллект — область компьютерных наук.",
      "Машинное обучение является подразделом ИИ.",
      "Нейронные сети — основа современного глубокого обучения.",
      "Python — популярный язык программирования."
    ],
    "top_n": 3
  }'

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

Параметр	Тип	Обязательный	Описание
model	string	Да	Идентификатор модели
query	string	Да	Поисковый запрос
documents	string[]	Да	Массив документов для ранжирования
top_n	number	Нет	Вернуть только N наиболее релевантных документов
return_documents	boolean	Нет	Включить текст документов в ответ (по умолчанию true)
rank_fields	string[]	Нет	Поля JSON-документов, по которым производится ранжирование

Формат ответа

{
  "id": "...",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9871,
      "document": {
        "text": "Искусственный интеллект — область компьютерных наук."
      }
    },
    {
      "index": 1,
      "relevance_score": 0.8234,
      "document": {
        "text": "Машинное обучение является подразделом ИИ."
      }
    }
  ],
  "usage": {
    "cost_rub": 0.24,
    "balance": 950.5
  }
}

Поле index соответствует позиции документа в исходном массиве documents. relevance_score — число от 0 до 1, чем выше — тем релевантнее.

Использование в RAG-системах

Rerank применяется как второй этап после семантического или ключевого поиска — для финального отбора наиболее релевантных фрагментов перед передачей в LLM.

import requests
from openai import OpenAI

client = OpenAI(
    api_key="sk-aitunnel-xxx",
    base_url="https://api.aitunnel.ru/v1/",
)

# 1. Предположим, что первичный поиск вернул кандидатов
candidates = [
    "Париж — столица Франции и крупнейший её город.",
    "Эйфелева башня построена в 1889 году.",
    "Лондон является столицей Великобритании.",
    "Франция — страна в Западной Европе.",
    "Берлин — столица Германии.",
]

# 2. Переранжируем с помощью rerank
rerank_res = requests.post(
    "https://api.aitunnel.ru/v1/rerank",
    headers={"Authorization": "Bearer sk-aitunnel-xxx", "Content-Type": "application/json"},
    json={
        "model": "rerank-4-pro",
        "query": "Какой город является столицей Франции?",
        "documents": candidates,
        "top_n": 2,
    },
).json()

top_docs = [candidates[r["index"]] for r in rerank_res["results"]]

# 3. Передаём топ-2 документа в LLM
context = "\n".join(top_docs)
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": f"Отвечай только на основе контекста:\n{context}"},
        {"role": "user", "content": "Какой город является столицей Франции?"},
    ],
)
print(response.choices[0].message.content)

Лучшие практики

1. Выбор модели: rerank-4-pro — наилучшее качество; rerank-4-fast — оптимальный баланс скорости и качества; rerank-v3.5 — самый экономичный вариант
2. Размер top_n: Передавайте в LLM 3–5 наиболее релевантных документов, а не все результаты поиска
3. Размер документов: Разбивайте длинные тексты на фрагменты по 200–500 слов перед передачей на ранжирование
4. Двухэтапный поиск: Используйте быстрый векторный поиск для отбора 20–100 кандидатов, а rerank — для финального ранжирования топ-3–10