# Open WebUI: локальный reranking для поиска по документам

Источник: https://modelium.tech/zhurnal/open-webui-reranking/

Локальный reranking в Open WebUI пересортировывает уже найденные фрагменты документа по соответствию вопросу; сам по себе он не добавляет в поиск отсутствующие документы. Для него нужны загруженная база знаний, локальная embedding-модель и отдельный reranker; в рассматриваемом коде Open WebUI reranking включён в ветку hybrid search. Сравнивайте фрагменты до и после на одном наборе русских вопросов, сохраняя остальные настройки одинаковыми.

**Срез на 30 сентября 2026 года:** документация Open WebUI закреплена по commit `805f46f`, код — по `v0.11.4` (`8bd8b4f`), карточка BAAI — по ревизии `953dc6f`. Команды и поведение ниже выведены из этих исходников, а не из собственного прогона Modelium. [s1](#src-s1) [s4](#src-s4) [s7](#src-s7)

## Когда нужен второй этап поиска?

RAG сначала ищет подходящие части загруженных документов, затем передаёт их текст модели как контекст. В Open WebUI Knowledge Base можно прикрепить к чату или модели; путь обработки документа зависит от выбранных extraction, embedding и inference-провайдеров. [s2](#src-s2) [s3](#src-s3)

Reranker получает пару «вопрос — найденный фрагмент» и оценивает соответствие, меняя порядок **уже отобранных кандидатов**; карточка BAAI отличает эту задачу от генерации embedding. Поэтому настройка reranker не исправит ошибку извлечения текста из PDF и не найдёт документ, которого вообще нет среди кандидатов. Последний вывод — следствие двухступенчатого конвейера, а не обещание качества. [s5](#src-s5) [s7](#src-s7)

В закреплённой версии API `/query/doc` вызывает `query_doc_with_hybrid_search` и передаёт `RERANKING_FUNCTION` лишь при включённом `ENABLE_RAG_HYBRID_SEARCH`. При выключенном hybrid search маршрут использует обычный `query_doc` без этой функции. Это важно: записать имя reranker в конфигурацию, не включив соответствующую ветку поиска, недостаточно для данного маршрута. Другие пути и будущие релизы проверяйте отдельно. [s4](#src-s4)

## Что подготовить для локального сценария?

Нужны установленный Open WebUI, подключённая **локальная** языковая модель, Knowledge Base с тестовыми документами, модель embeddings, а также отдельная локальная модель для reranking. Настройка одного из этих компонентов не делает остальные локальными автоматически: тип провайдера извлечения, embeddings и генерации проверьте отдельно. [s3](#src-s3) [s1](#src-s1)

Для пробного многоязычного reranker можно рассмотреть `BAAI/bge-reranker-v2-m3`: авторская карточка помечает его как multilingual, а поле лицензии — `apache-2.0`. Это не независимое доказательство качества на русском, не обещание минимального объёма RAM/VRAM и не рекомендация под любую нагрузку. Сверьте условия использования и качество на своих документах. [s7](#src-s7)

В документации `RAG_RERANKING_ENGINE` пустой по умолчанию и означает локальный `Sentence-Transformers CrossEncoder`; значение `external` направляет данные в внешний API и требует полного URL. Код локального загрузчика создаёт `sentence_transformers.CrossEncoder`; сборка Slim не предоставляет этот путь для нового локального reranker. Для закрытого контура не подменяйте локальный путь внешним без проверки передачи данных. [s1](#src-s1) [s4](#src-s4)

## Как настроить воспроизводимое сравнение?

- В отдельном тестовом экземпляре подготовьте несколько документов с заведомо различимыми фактами и записанный набор русских вопросов. Сначала проверьте, что нужный фрагмент вообще появляется среди кандидатов — иначе меняйте извлечение, индексацию или первый этап поиска, а не reranker. Это протокол проверки, а не отчёт о выполненном тесте. [s3](#src-s3) [s5](#src-s5)

- Зафиксируйте неизменные документы, embedding-модель, настройки поиска и набор запросов. В админских настройках Retrieval/RAG настройте гибридный поиск и количество кандидатов, оставив `RAG_RERANKING_MODEL` пустым для контрольного прогона. Ключи документации: `ENABLE_RAG_HYBRID_SEARCH`, `RAG_TOP_K`, `RAG_TOP_K_RERANKER`, `RAG_RELEVANCE_THRESHOLD`. Последний порог лучше оставить `0.0` на первом сравнении, чтобы он не скрывал кандидатов. [s1](#src-s1) [s4](#src-s4)

- В том же экземпляре укажите `RAG_RERANKING_MODEL=BAAI/bge-reranker-v2-m3` и пустой `RAG_RERANKING_ENGINE` — **по документации**, после предварительной загрузки/проверки разрешённого checkpoint. Код admin config загружает модель и создаёт функцию reranking. Если окружение полностью офлайн, предварительно подготовьте файлы embedding и reranker: `OFFLINE_MODE` останавливает автоматические загрузки и обновления, но сам по себе не является сетевой изоляцией. [s1](#src-s1) [s4](#src-s4) [s6](#src-s6) [s7](#src-s7)

- Повторите ровно те же вопросы и запишите ID документа, текст нужного фрагмента, его позицию и задержку на каждом запросе до/после. Сравнивайте сначала **поисковую выдачу**, затем ответы LLM с цитатами: убедительный ответ не доказывает, что исходный фрагмент найден правильно. Исходный retrieval-код отдельно принимает `k` и `k_reranker`, поэтому не меняйте их одновременно с моделью. [s4](#src-s4) [s5](#src-s5)

Для конфигурации via environment (в тестовом инстансе, не как уже выполненная команда) достаточно задать имена переменных и модель:

ENABLE_RAG_HYBRID_SEARCH=trueRAG_RERANKING_ENGINE=RAG_RERANKING_MODEL=BAAI/bge-reranker-v2-m3RAG_RELEVANCE_THRESHOLD=0.0

Эти параметры в документации — persistent ConfigVar: сохранённые значения в БД могут иметь приоритет над последующей правкой окружения, поэтому фактические значения следует сверять в админских настройках. `RAG_TOP_K` и `RAG_TOP_K_RERANKER` по умолчанию равны 3, но для оценки recall часто понадобится больше кандидатов; это размер выборки, а не замер производительности. [s1](#src-s1) [s4](#src-s4)

## Что считать успехом и когда отказаться?

Составьте эталон: какие фрагменты документов действительно отвечают на каждый вопрос. Результат пилота — для каждого запроса нужный отрывок присутствует в финальной выдаче и корректно подтверждает ответ; дополнительно сопоставьте время отклика и долю ложных релевантных фрагментов до/после. Выбор порога приемлемости и ручная разметка остаются за вашей командой; Modelium не проводил этого сравнения. [s5](#src-s5)

Если нужный документ не попал в исходную выборку, reranker его не «восстановит». Если задержка стала неприемлемой или русские реквизиты ранжируются хуже, вернитесь к контрольной конфигурации: очистите `RAG_RERANKING_MODEL`, сохраните прежние `TOP_K`/`TOP_K_RERANKER`, повторите те же запросы. При использовании внешнего reranker содержимое фрагментов и запросов может покинуть локальный контур, в отличие от описанного локального CrossEncoder; это риск архитектуры внешнего API, требующий проверки конкретного провайдера. [s1](#src-s1) [s4](#src-s4) [s5](#src-s5)

**Следующий шаг:** откройте [протокол оценки качества RAG](/zhurnal/ocenka-kachestva-rag/) и сохраните сравнение нужных фрагментов до и после reranking на своих документах. Материал про [гибридный поиск](/zhurnal/gibridnyy-poisk-rag/) объясняет отбор кандидатов; гайд [Open WebUI](/zhurnal/open-webui/) — запуск интерфейса.

## Источники

1. [Open WebUI Docs — env configuration, RAG and reranking](https://github.com/open-webui/docs/blob/805f46f8d9f42e26958ee80f849e0d27a1198db0/docs/reference/env-configuration.mdx) — получено 2026-09-30
2. [Open WebUI Docs — Retrieval Augmented Generation](https://github.com/open-webui/docs/blob/805f46f8d9f42e26958ee80f849e0d27a1198db0/docs/features/chat-conversations/rag/index.md) — получено 2026-09-30
3. [Open WebUI Docs — Knowledge Bases and Document Chat](https://github.com/open-webui/docs/blob/805f46f8d9f42e26958ee80f849e0d27a1198db0/docs/features/workspace/knowledge.mdx) — получено 2026-09-30
4. [Open WebUI v0.11.4 — retrieval API and local reranker loader](https://github.com/open-webui/open-webui/blob/8bd8b4fac5e059578ac0c74b3c18d11139f88b7d/backend/open_webui/routers/retrieval.py) — получено 2026-09-30
5. [Open WebUI v0.11.4 — hybrid retrieval and reranking pipeline](https://github.com/open-webui/open-webui/blob/8bd8b4fac5e059578ac0c74b3c18d11139f88b7d/backend/open_webui/retrieval/utils.py) — получено 2026-09-30
6. [Open WebUI v0.11.4 — RAG runtime defaults and offline mode](https://github.com/open-webui/open-webui/blob/8bd8b4fac5e059578ac0c74b3c18d11139f88b7d/backend/open_webui/config.py) — получено 2026-09-30
7. [BAAI — bge-reranker-v2-m3 model card](https://huggingface.co/BAAI/bge-reranker-v2-m3/blob/953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e/README.md) — получено 2026-09-30