Rerank API для RAG: точный порядок документов

Rerank API для RAG нужен, когда первичный поиск уже нашёл кандидатов, но их порядок недостаточно точно соответствует вопросу пользователя. Вместо повторной индексации вы отправляете запрос и небольшой набор фрагментов в POST /v1/rerank, получаете оценки релевантности и передаёте модели только лучшие документы. Это уменьшает шум в контексте и делает качество retrieval измеримым.

Где rerank находится в RAG-конвейере

Классический retrieval обычно начинается с быстрого отбора: векторная база, полнотекстовый индекс или их комбинация возвращают десятки кандидатов. Этот слой должен обеспечивать полноту — важный документ желательно не потерять. Но высокая полнота часто означает, что рядом с полезными фрагментами оказываются страницы с похожими словами, устаревшие версии и косвенные упоминания.

Rerank — второй этап. Он получает исходный вопрос и уже найденные тексты, заново оценивает каждую пару «вопрос — документ» и меняет порядок. В LLMTOKENAPI для этого предназначен отдельный endpoint POST /v1/rerank со scope rerank:read. Он принимает от одного до 100 документов, поэтому сначала всё равно нужен быстрый кандидатный поиск.

Разделяйте две задачи:

• embeddings или полнотекстовый поиск отвечают за широкий набор кандидатов;
• rerank отвечает за точный порядок внутри этого набора;
• LLM формирует ответ только по верхним результатам и не должна исправлять слабый retrieval догадками.

Такой конвейер проще тестировать, чем один непрозрачный запрос. Можно отдельно измерить, попал ли эталонный фрагмент в кандидаты, а затем — поднял ли rerank его в верхнюю часть выдачи.

Подготовьте документы без потери контекста

Каждый элемент documents может быть строкой или объектом с полями id, text и metadata. Объект удобнее в production: стабильный id позволяет после сортировки найти исходную запись, а metadata — сохранить URL, версию документа или уровень доступа. Оценивается поле text; метаданные не должны заменять содержательный фрагмент.

Не отправляйте целую книгу одним документом. Полезнее передать самостоятельные фрагменты, в которых есть законченная мысль: пункт договора, раздел инструкции или абзац справочного материала. Слишком короткий кусок теряет условия и исключения, слишком длинный смешивает несколько тем. Практику разбиения и первичного поиска мы подробно разобрали в статье про RAG по документам компании.

Проверяйте права доступа до вызова rerank. Если пользователь не должен видеть документ, этот документ нельзя включать даже как кандидата: второй этап меняет порядок, но не является механизмом авторизации.

Вызовите POST /v1/rerank

Ниже минимальный запрос с объектами документов. Ключ храните только на сервере или в защищённом хранилище автоматизации.

curl https://api.llmtokenapi.ru/v1/rerank \
  -H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "semantic-rerank-v1",
    "query": "Как восстановить доступ после смены телефона?",
    "documents": [
      {"id":"security","text":"Восстановление доступа выполняется через резервный код и подтверждение нового устройства."},
      {"id":"billing","text":"Счёт и закрывающие документы доступны в разделе оплаты."},
      {"id":"profile","text":"Номер телефона можно изменить после проверки текущей сессии."}
    ],
    "topN": 2,
    "returnDocuments": true
  }'

query может содержать до 8000 символов, а массив — до 100 документов. topN ограничивает число возвращаемых результатов. Если returnDocuments оставить включённым, ответ содержит исходный документ рядом с index и relevance_score; при значении false вернутся только индекс и оценка. Также поддерживаются варианты top_n и return_documents для совместимых клиентов.

Ответ уже отсортирован по убыванию релевантности. Индекс указывает на позицию документа во входном массиве, поэтому не используйте его как постоянный идентификатор: для этого передавайте собственное поле id.

Выберите размер кандидатного набора и topN

Универсального числа нет. Маленький кандидатный набор быстрее, но первичный поиск может не включить правильный ответ. Слишком большой повышает объём входного текста и добавляет слабые документы. Начните с реальных вопросов пользователей и подберите два параметра по измерениям: сколько кандидатов отправлять на rerank и сколько лучших фрагментов помещать в контекст модели.

topN не обязательно равен числу фрагментов в prompt. Например, можно запросить десять результатов, затем удалить дубликаты одного URL, проверить свежесть и оставить пять. Это особенно важно, если несколько соседних фрагментов относятся к одной странице и повторяют одну мысль.

Не превращайте relevance_score в универсальную вероятность правильности. Оценка полезна для порядка внутри одного запроса, но порог следует калибровать на собственной выборке. Сравните распределения для ответных и неответных документов, а затем выберите правило отказа.

Соберите безопасный контекст для модели

После rerank сформируйте контекст только из допущенных документов. Сохраняйте рядом идентификатор, URL или название источника, чтобы итоговый ответ мог ссылаться на конкретное основание. Инструкции внутри найденного текста считайте недоверенными данными: они не должны переопределять системные правила агента.

Если верхние результаты слабы или противоречат друг другу, лучше вернуть уточняющий вопрос либо честный отказ, чем заставлять модель заполнять пробелы. Для веб-сценария пригодится архитектура AI-поиска с источниками: там отдельно рассматриваются качество источника и связь цитаты с утверждением.

Измеряйте пользу rerank отдельно

Соберите набор из реальных запросов, допустимых документов и эталонных фрагментов. Для каждого запроса сохраняйте кандидатов до и после пересортировки. Основные метрики — доля случаев, когда правильный документ попал в top-k, средняя позиция эталона и доля ответов, для которых доказательств недостаточно.

Добавьте продуктовые показатели: задержку второго этапа, объём обработанного текста, стоимость успешного ответа и частоту отказов. Сравнивайте минимум два режима на одной и той же выборке: первичный поиск без rerank и тот же поиск с rerank. Иначе улучшение может оказаться следствием другого индекса или изменившихся документов.

Практический чек-лист

1. Получите широкий набор кандидатов через embeddings, полнотекстовый или гибридный поиск.
2. Отфильтруйте документы по правам, версии и допустимым источникам.
3. Передайте вопрос и содержательные фрагменты в /v1/rerank.
4. Используйте стабильные id, ограничьте topN и удалите дубли.
5. Сформируйте контекст модели только из проверенных верхних результатов.
6. Калибруйте порог отказа и top-k на вопросах ваших пользователей.
7. Следите за качеством, задержкой и стоимостью как за отдельными слоями системы.

Актуальные методы, scopes и примеры авторизации доступны в документации LLMTOKENAPI. Такой подход делает rerank не декоративной настройкой, а контролируемым этапом между быстрым поиском и генерацией ответа.