# vLLM Rerank API: локальная переоценка найденных фрагментов RAG

Источник: https://modelium.tech/zhurnal/vllm-rerank-api/

vLLM предоставляет /v1/rerank для совместимой scoring-модели: передайте запрос и уже найденные фрагменты, получите список с оценками релевантности и исходными индексами. Для русских тестовых текстов можно начать с BAAI/bge-reranker-v2-m3, но качество и совместимость именно вашего стенда нужно проверить. Reranker не ищет документы в хранилище и не генерирует ответ.

На 5 октября 2026 года исходные документы vLLM на коммите `138810056093301f4881050fcf2b1786939da387` описывают Scoring и Rerank API. Здесь показано, как поставить локальную модель **после** извлечения кандидатов и отличить реальное изменение порядка от красивой оценки. Это проверка документации и исходников, а не выполненный Modelium запуск модели. [s1](#src-s1) [s3](#src-s3)

## Когда нужен reranking, а не ещё один поиск?

Для RAG сначала получите кандидатов из индекса с помощью embedding- или гибридного поиска, затем дайте запрос и тексты кандидатов отдельной scoring-модели. vLLM вычисляет оценку пар «запрос–фрагмент», возвращает упорядоченный список, но не хранит индекс и не создаёт ответ с цитатами. У модельных семейств бывают разные scoring-задачи: для обычного cross-encoder это классификация пары, для bi-encoder — сопоставление embeddings; произвольная chat-модель без scoring-задачи здесь не подходит. [s1](#src-s1) [s2](#src-s2)

Практический маршрут: **поиск документов → подходящий reranker → совместимое железо → сервер vLLM → список **`**results**`** → сравнение с размеченным ожиданием**. В первом тесте используйте вымышленные русские фрагменты, а не закрытые документы. На одинаковых запросах сохраните исходную выдачу индекса до обращения к reranker; без неё нельзя сказать, повысилось ли качество или только поменялся порядок. [s1](#src-s1) [s7](#src-s7)

## Как подготовить модель и локальный сервер?

В списке совместимых моделей vLLM прямо указана `BAAI/bge-reranker-v2-m3` для архитектуры `XLMRobertaForSequenceClassification`; закреплённый HF API подтверждает эту архитектуру и наличие `model.safetensors`. Автор описывает модель как multilingual, однако эффективность на **вашей** русской выборке не доказана. В карточке стоит метка `apache-2.0`: читайте сам текст лицензии и условия остальных компонентов прежде чем делать вывод о коммерческом стеке. Размер файла весов не является минимальной RAM или VRAM. [s1](#src-s1) [s7](#src-s7) [s8](#src-s8)

Для воспроизводимости фиксируйте HF ревизию `953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e` и сверяйте версию собственного vLLM с цитируемым коммитом документации. Установите vLLM по инструкции для **вашего** GPU и ОС; наличие документации не гарантирует запуск на CPU или любом драйвере. На подготовленном совместимом стенде команда `vllm serve BAAI/bge-reranker-v2-m3 --revision 953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e --runner pooling --host 127.0.0.1 --port 8000` задаёт pooling и локальную привязку; `--runner pooling` обычно определяется автоматически, но явный флаг помогает зафиксировать режим. По имени HF модель может загружаться через сеть: для закрытого контура сначала обеспечьте кеш и отдельно проверьте сетевые обращения. Modelium эту команду не запускал. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3) [s8](#src-s8)

Не открывайте vLLM прямо в сеть. По документации `--api-key` защищает префикс `/v1`, но маршрут `/rerank` того же сервера остаётся незащищённым: поэтому для внешних клиентов нужны отдельные сетевые правила или прокси с проверенным списком разрешённых путей. Привязка к loopback — только первый барьер на этом хосте, не доказательство отсутствия исходящих соединений. [s4](#src-s4) [s6](#src-s6)

## Как отправить запрос и проверить исходный порядок?

После загрузки выполните `curl -fsS http://127.0.0.1:8000/v1/models` и сверьте модель в ответе; список моделей ещё не доказывает работу scoring. Для пробного POST на `http://127.0.0.1:8000/v1/rerank` передайте JSON `{"model":"BAAI/bge-reranker-v2-m3","query":"Где указан ИНН поставщика?","documents":["Сроки отпуска сотрудников указаны в графике.","В счёте указан ИНН поставщика и дата.","Команда подготовила акт приёмки."],"top_n":3}` с `Content-Type: application/json`. Например, сохраните JSON в локальный файл `rerank-request.json` и вызовите `curl -fsS -X POST http://127.0.0.1:8000/v1/rerank -H 'Content-Type: application/json' --data-binary @rerank-request.json`. Такой вызов следует формату официального примера; сервер и модель у Modelium не запускались. [s1](#src-s1) [s5](#src-s5) [s6](#src-s6)

В ответе по документации ожидается массив `results` с `index`, `document.text` и `relevance_score`. `index` — индекс в исходном массиве `documents`, а **позиция элемента в **`**results**` — новая позиция после reranking. `top_n` необязателен: без него обычно возвращаются все фрагменты. Для тестового вопроса заранее пометьте фрагмент с ИНН как ожидаемо релевантный (`index=1`), затем сравните реальный список индексов с исходным `[0,1,2]`. Не выдавайте ожидаемый `index=1` на первом месте за уже полученный результат. [s1](#src-s1)

Отдельный `/score` принимает `queries` и `documents`, возвращает оценки для пар в исходной связке; не путайте его JSON `data` с отсортированным `results` у `/v1/rerank`. При ошибке «model does not support Rerank» проверьте, что загрузили именно scoring-модель и что выбранная версия vLLM распознала pooling-задачу. Модель Qwen3 Reranker не подставляйте в ту же команду вслепую: vLLM документирует для исходной Qwen/Qwen3-Reranker-0.6B отдельные `--hf_overrides`. [s1](#src-s1) [s2](#src-s2) [s6](#src-s6)

## Как оценить пользу на собственных вопросах?

Для каждого размеченного вопроса сохраняйте выдачу первого этапа (ID документа, текст, порядок), результат `index` после rerank, ожидаемый релевантный ID и версию модели. Пересчитайте позиции документа до/после **только среди тех же кандидатов**; если нужного фрагмента нет в первом этапе, reranker не сможет его добавить. Для пилота измеряйте recall@k: `число вопросов, где нужный документ среди top-k / число размеченных вопросов` при одинаковых вопросах и одинаковом наборе кандидатов. Это предложенная процедура сравнения, не опубликованный показатель качества BAAI и не измерение Modelium. [s1](#src-s1) [s7](#src-s7)

Не интерпретируйте `relevance_score` как вероятность правильности ответа или универсальный порог для разных моделей. Авторская карточка предлагает сигмоиду для отображения собственного score в диапазон 0–1, но этот диапазон **не доказывает** калибровку на вашей выборке. Если порядок не меняется или ухудшается, проверьте состав кандидатов, длину фрагментов, язык, обрезку контекста, выбранную scoring-модель и свои метки; затем повторите на тех же вопросах, а не подбирайте оценку на одном примере. [s1](#src-s1) [s7](#src-s7)

## Когда остановиться и куда двигаться дальше?

При нехватке памяти не выводите требования из размера весов: сначала соберите логи загрузки, GPU/CPU, параметры batching и длины фрагментов, затем сократите тестовый набор или выберите другой совместимый runtime. Если вам нужен только embedding-этап, откройте [vLLM Embeddings API](/zhurnal/vllm-embeddings-api/); если модельная альтернатива — [Qwen3 Reranker](/zhurnal/qwen3-reranker/). Для оценки полноценного поискового тракта и ответов с цитатами основной следующий шаг — [протокол проверки RAG](/zhurnal/ocenka-kachestva-rag/). [s1](#src-s1) [s2](#src-s2)

По окончании теста остановите процесс vLLM через Ctrl+C, сохраните конфигурацию и обезличенные результаты в журнале эксперимента. Документация описывает серверный инференс, но Modelium не проводил собственный прогон, не публикует чисел скорости или качества и не обещает, что тестовая команда пройдёт на любом железе. [s3](#src-s3)

## Источники

1. [vLLM: Scoring Usages и Cohere Rerank API](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/docs/models/pooling_models/scoring.md) — получено 2026-10-05
2. [vLLM: pooling runner и задачи](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/docs/models/pooling_models/README.md) — получено 2026-10-05
3. [vLLM: online serving, различия OpenAI и Cohere API](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/docs/serving/online_serving/README.md) — получено 2026-10-05
4. [vLLM: Security, API key limitations](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/docs/usage/security.md) — получено 2026-10-05
5. [vLLM: пример запроса rerank API](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/examples/pooling/score/rerank_api_online.py) — получено 2026-10-05
6. [vLLM: исходный код маршрутов rerank](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/vllm/entrypoints/pooling/scoring/api_router.py) — получено 2026-10-05
7. [BAAI/bge-reranker-v2-m3: карточка автора](https://huggingface.co/BAAI/bge-reranker-v2-m3/blob/953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e/README.md) — получено 2026-10-05
8. [BAAI/bge-reranker-v2-m3: HF API, метаданные ревизии](https://huggingface.co/api/models/BAAI/bge-reranker-v2-m3/revision/953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e) — получено 2026-10-05