Гайд · TNWS AI
Как переранжировать найденные документы через llama.cpp /v1/rerank
Запускаем reranker GGUF, подаём список кандидатов и проверяем порядок и связь результата с исходными документами.
Задача и применимость
Поисковый вопрос: «как переранжировать документы llama.cpp rerank pooling rank». Улучшить порядок уже отобранных фрагментов для вопроса, не утверждая, что reranker найдёт недостающий документ. llama.cpp server с отдельной моделью reranker; документация для /reranking требует --embedding и --pooling rank. Параметр --reranking включает маршрут в актуальном README на 20 сентября 2026 года. Проверяйте доступность на своей сборке.
Пример рассчитан на уже имеющийся файл модели, полученный законным способом по условиям его лицензии. Здесь не утверждается, что любая GGUF-модель одинаково понимает русский язык или имеет один и тот же чат-шаблон. Фактический номер сборки узнавайте локально через llama-server --version и повторяйте контрольный опыт после обновления бинарника.
Что подтверждено документацией
Документированные имена маршрута: /reranking, /rerank, /v1/rerank, /v1/reranking. Поля запроса query и documents; пример документации использует top_n. Сортировка оценивает только переданные строки, не выполняет поиск по внешней базе и не предоставляет контроль доступа.
Порядок действий
- Сначала получите разрешённые пользователю фрагменты из поискового индекса.
- Сохраните стабильный массив пар doc_id и content на момент вызова.
- Запустите отдельный сервер с моделью reranker и pooling rank.
- Передайте query, documents и top_n на /v1/rerank.
- Свяжите результат с исходными doc_id, затем измерьте качество top-1 на размеченном наборе.
Локальный запуск для описанного сценария (замените путь к файлу на ваш):
./build/bin/llama-server -m /models/your-reranker.gguf --embedding --pooling rank --reranking --host 127.0.0.1 --port 8080
Готовый шаблон запроса и проверки
import json, urllib.request
docs = [
("R7", "Возврат покупки возможен в течение 14 дней."),
("D9", "Доставка производится в рабочие дни."),
("P2", "Оплата принимается банковской картой.")]
body = {"query": "Сколько дней дают на возврат?", "top_n": 3,
"documents": [text for _, text in docs]}
req = urllib.request.Request("http://127.0.0.1:8080/v1/rerank",
data=json.dumps(body, ensure_ascii=False).encode("utf-8"),
headers={"Content-Type": "application/json"}, method="POST")
with urllib.request.urlopen(req, timeout=90) as reply:
result = json.load(reply)
print(result)
assert docs[0][0] == "R7" # Проверьте форму ответа перед сопоставлением.
Входные данные и ожидаемый результат
Вход: вопрос о сроке возврата и три кандидата R7/D9/P2. Ожидаемый смысл первого результата — R7, если выбранная reranker-модель понимает русский язык. Форма ответа и оценка конкретной сборки сначала выводятся целиком; код не делает необоснованного предположения об имени поля score.
Почему важна именно эта проверка
Reranker не заменяет начальный поиск. Если релевантный документ о 14 днях не попал в docs, любой порядок оставшихся кандидатов будет ошибочным. Поэтому измеряйте два этапа отдельно: recall у retrieval и качество выбора top-1 после переранжирования. Особенно осторожно работайте с правами доступа: документы другого клиента нельзя передавать reranker с надеждой отфильтровать их после оценки. Проверка tenant и visibility должна произойти до сборки списка документов.
Работа с реальными данными
Запуск обычной embedding-модели вместо reranker может дать численный ответ либо ошибку, но не корректное соответствие цели. Документация явно требует pooling rank и подходящую модель; убедитесь в назначении конкретного GGUF у автора весов. Для теста сначала попробуйте три контрастных коротких документа и один явно соответствующий вопрос, потом реальные сложные перефразирования. В демонстрационном списке индекс служит ссылкой на исходный массив. Если отсортировать docs отдельно после формирования запроса, индексы потеряют смысл.
Проверка после изменения модели или нагрузки
top_n ограничивает число возвращаемых кандидатов, но не создаёт новые документы. Замеряйте задержку rerank на характерном размере первого этапа и сравнивайте выигрыш в точности с дополнительной стоимостью вычисления. Для русского текста не заявляйте универсального успеха, пока не проверен языковой профиль модели. Сохраняйте вопрос, ID контрольных документов и ожидаемый ID, но для production-логов убирайте приватное содержимое. Если ответ API не соответствует ожидаемой структуре, не угадывайте поля: изучите сырую структуру в своей версии и допишите явный валидатор.
Если retrieval даёт длинные фрагменты, заранее определите, какую часть документа передавать reranker. Отрезание конца может уничтожить ответ о сроке возврата, а отправка всего файла увеличит задержку. Для диагностики сохраните выбранные короткие версии всех трёх текстов и проверьте, что R7 действительно содержит «14 дней» на момент вызова. После обновления источника повторите индексирование и тест; старое содержимое с тем же doc_id иначе даст ложное впечатление, что модель ухудшилась.
Критерии приёмки
- В кандидаты попадают только разрешённые документы.
- Контрольный R7 найден и возвращён выше нерелевантных, либо качество помечено недостаточным.
- Позиция в ответе однозначно восстанавливает исходный doc_id.
Частые ошибки и чего не делать
- Не рассчитывать, что reranker добавит отсутствующий источник.
- Не передавать запрещённые документы до фильтра доступа.
- Не использовать embedding GGUF вместо модели для rerank.
Краткие ответы на вопросы
Нужна ли специальная модель?
Да, reranker с pooling rank.
Ищет ли /v1/rerank новые документы?
Нет, оценивает переданные.
Какие адреса поддерживаются?
README перечисляет /reranking и алиасы /rerank, /v1/rerank, /v1/reranking.
Официальные источники
Частые вопросы
Нужна ли специальная модель?
Да, reranker с pooling rank.
Ищет ли /v1/rerank новые документы?
Нет, оценивает переданные.
Какие адреса поддерживаются?
README перечисляет /reranking и алиасы /rerank, /v1/rerank, /v1/reranking.
Читайте также
Как ограничить генерацию llama.cpp через n_predict и проверить причину остановки
Используем native /completion и поля остановки, чтобы отличить заданный лимит от нормального конца ответа.
Как получить embeddings через llama.cpp /v1/embeddings и проверить pooling
Запускаем специализированную embedding-модель, кодируем две строки и проверяем размерность и числовой формат.
Как получить JSON по схеме через response_format в llama.cpp server
Задаём объектную JSON Schema в chat endpoint, разбираем строку content и валидируем обязательные поля отдельно.
Комментарии
Пока тихо. Скажите первое слово