Я додав BM25 до свого RAG-сервісу — і vector search перестав губити точні запити

📌 Реалізація HybridSearchService: два пошуки + RRF

Мій HybridSearchService робить три речі в методі search():

1. Векторний пошук — той самий vectorStore.similaritySearch() через pgvector, cosine similarity
2. BM25 пошук — SQL запит з оператором @@ по колонці content_tsv
3. RRF злиття — об'єднання обох списків результатів за формулою 1/(k + rank)

BM25 пошук: SQL запит

Для BM25 я використовую plainto_tsquery() — вона автоматично розбиває запит користувача на слова і шукає їх через AND. Результати ранжуються через ts_rank() — вбудовану функцію PostgreSQL, яка рахує BM25-подібний score.

SELECT id, content, metadata FROM vector_store
WHERE content_tsv @@ plainto_tsquery(CAST(:tsconfig AS regconfig), :question)
ORDER BY ts_rank(content_tsv, plainto_tsquery(CAST(:tsconfig AS regconfig), :question)) DESC
LIMIT :topK

⚠️ Підводний камінь: CAST до regconfig

Моя перша спроба без CAST видала BadSqlGrammarException. PostgreSQL не може автоматично привести строковий параметр ? (який приходить як String через JdbcClient) до типу regconfig. Потрібен явний каст: CAST(:tsconfig AS regconfig). Ця ж помилка виникла і при заповненні content_tsv під час індексації — довелося фіксити в двох місцях.

RRF (Reciprocal Rank Fusion): як працює злиття

RRF був запропонований Cormack, Clarke та Buettcher у 2009 році (SIGIR '09) і з тих пір став стандартом для hybrid search. Формула:

score(d) = Σ 1 / (k + rank)

де rank — позиція документа у кожному окремому рейтингу, а k — константа згладжування (я використовую стандартне значення 60).

Що робить k: він контролює, наскільки сильно "перше місце" відрізняється від "п'ятого місця".

• k=60 (стандарт): 1-ше місце = 1/61 = 0.0164, 5-те = 1/65 = 0.0154. Різниця маленька — усі результати "майже рівні"
• k=1 (маленький): 1-ше = 1/2 = 0.5, 5-те = 1/6 = 0.167. Різниця тройна — топові результати домінують
• k=200 (великий): різниці майже немає — важливо лише чи потрапив чанк у результати

Чому саме 60? Це значення з оригінальної наукової статті. Його використовують Elasticsearch, Qdrant, Weaviate.

Приклад з реальними даними

Запит: "Наказ №142 про звільнення"

Vector search повертає (за cosine similarity — по сенсу "звільнення"):

1. Чанк про процедуру звільнення (rank 1)
2. Чанк про трудовий договір (rank 2)
3. Чанк "Наказ №142" (rank 5)

BM25 повертає (за точним збігом слів "Наказ №142"):

1. Чанк "Наказ №142" (rank 1)
2. Чанк "Наказ №155" (rank 2)

RRF score для чанка "Наказ №142":

vector rank=5: 1/(60+5) = 0.0154
BM25 rank=1:   1/(60+1) = 0.0164
total:                     0.0318 ← найвищий серед усіх

Чанк "Наказ №142" виграє — він високо в обох рейтингах. Без hybrid search він був би на 5-й позиції і міг не потрапити у контекст LLM.

Заповнення tsvector при індексації нових документів

Нові документи проходять через PgVectorIndexingService. Після vectorStore.add(documents) (який зберігає embeddings) я додав UPDATE, що заповнює content_tsv:

private void updateTsVector(Long docId) {
    jdbcClient.sql(
        "UPDATE vector_store SET content_tsv = to_tsvector(CAST(:tsconfig AS regconfig), content) " +
        "WHERE metadata->>'doc_id' = :docId AND content_tsv IS NULL"
    )
    .param("tsconfig", tsConfig)  // @Value("${app.search.tsconfig:simple}")
    .param("docId", String.valueOf(docId))
    .update();
}

Чому без тригера: я розглядав варіант з PostgreSQL тригером, але тригер — це SQL, він не знає про Spring @Value. Якщо клієнт змінить мову (наприклад, з simple на german для німецького клієнта) — довелося б пересоздавати тригер через міграцію. З Java-кодом усе управляється з application.properties.

📌 Конфігурація: vector vs hybrid через проперті

Я не видалив старий PgVectorSearchService. Замість цього зробив переключення через @ConditionalOnProperty:

# application.properties
app.search.mode=hybrid       # або "vector" для чистого vector search
app.search.tsconfig=simple   # мова для tsvector: simple, russian, german, english...
app.search.rrf-k=60          # константа згладжування RRF

@ConditionalOnProperty(name = "app.search.mode", havingValue = "vector", matchIfMissing = true)
public class PgVectorSearchService implements SearchService { ... }

@ConditionalOnProperty(name = "app.search.mode", havingValue = "hybrid")
public class HybridSearchService implements SearchService { ... }

Навіщо два режими

Мій сервіс обслуговує різних бізнес-клієнтів, і не для всіх hybrid search оптимальний:

• Hybrid search дає більше навантаження на базу — два запити замість одного (vector + BM25), плюс додатковий GIN індекс споживає RAM. Для деяких клієнтів з невеликою базою документів і простими запитами це надлишково
• Fallback — якщо BM25 частина зламається або tsvector не заповнений для якихось чанків, можна миттєво повернутися на чистий vector search через одну проперті
• A/B тестування — можна порівнювати якість відповідей між режимами на одних і тих самих запитах

По дефолту matchIfMissing = true на PgVectorSearchService — якщо проперті не задана, працює як раніше. Нічого не ламається.

Конфігурація під клієнта

Для українського клієнта:

app.search.mode=hybrid
app.search.tsconfig=simple

Для німецького клієнта:

app.search.mode=hybrid
app.search.tsconfig=german

Для клієнта з маленькою базою, де hybrid надлишковий:

app.search.mode=vector

Мова для tsvector і tsquery повинна збігатися — інакше пошук не працюватиме коректно. PostgreSQL з коробки підтримує: simple, english, german, french, spanish, russian, italian, dutch, turkish та інші.

⚠️ Підводні камені, які я зустрів

1. BadSqlGrammarException при plainto_tsquery

Проблема: перший запуск BM25 пошуку видав bad SQL grammar. PostgreSQL не міг привести строковий параметр ? до типу regconfig.

Рішення: явний каст CAST(:tsconfig AS regconfig) у двох місцях — у WHERE та ORDER BY частинах SQL.

2. Та ж помилка при індексації нових документів

Проблема: виправив HybridSearchService, але при завантаженні нового документа — та ж BadSqlGrammarException у PgVectorIndexingService.updateTsVector().

Рішення: додати CAST і там. Урок — якщо to_tsvector() використовується з параметром через JdbcClient, CAST потрібен завжди.

3. @RequiredArgsConstructor не працює з @Value

Проблема: Lombok @RequiredArgsConstructor генерує конструктор тільки для final полів. Поле з @Value — не final, тому не потрапляє в конструктор.

Рішення: замінив @RequiredArgsConstructor на явний конструктор у класах, де є і final залежності, і @Value конфігурація.

4. content_tsv = NULL для існуючих документів

Проблема: після міграції нова колонка content_tsv була NULL для всіх існуючих чанків. BM25 повертав 0 результатів.

Рішення: одноразовий UPDATE: UPDATE vector_store SET content_tsv = to_tsvector('simple', content) WHERE content_tsv IS NULL;

5. Similarity threshold для українського тексту

Дефолтний threshold cosine similarity для vector search занадто високий для українського тексту з nomic-embed-text. Я знизив його до 0.1 — інакше vector search повертав мало результатів. Детально про вибір embedding-моделі та threshold — у статті про embedding-моделі.

📊 Результати: vector=5, bm25=2, merged=5

Логи з мого сервісу після впровадження hybrid search:

Stream query: 'Скільки часу займає повернення коштів?', sessionId=3
HybridSearchService: Hybrid search results: 5 chunks (vector=5, bm25=1, merged=5)

Stream query: 'Скільки часу займає розробка лендінгу?', sessionId=null
HybridSearchService: Hybrid search results: 5 chunks (vector=5, bm25=2, merged=5)

Stream query: 'напиши про Локальний деплой Як це працює?', sessionId=3
HybridSearchService: Hybrid search results: 5 chunks (vector=5, bm25=0, merged=5)

Що ми бачимо:

• "повернення коштів" — BM25 знайшов 1 чанк з точним збігом слів, vector знайшов 5 по сенсу. Чанк, що потрапив в обидва рейтинги, отримав найвищий RRF score і опинився першим
• "розробка лендінгу" — BM25 знайшов 2 чанки. Hybrid дав 5 результатів — чанки з обох рейтингів, відсортовані по RRF score
• "Локальний деплой" — BM25 знайшов 0. Це нормально: запит "напиши про Локальний деплой Як це працює" — семантичний, без точних термінів з документів. Vector search впорався сам

Головний висновок: hybrid search не погіршує результати, коли BM25 не знаходить нічого — він просто повертає vector results. Але коли BM25 знаходить — якість фінального рейтингу зростає, бо RRF підсилює чанки, які з'являються в обох пошуках.

Про чанкінг документів — як я розбиваю PDF, DOCX і CSV на чанки для індексації, включаючи семантичний FAQ-чанкінг — читайте у статті про Chunking Strategies. А про вибір Ollama-моделей, які працюють локально на 8 ГБ RAM — у статті про Ollama на 8 ГБ.

❓ Часті питання (FAQ)

Чи потрібен hybrid search, якщо база документів маленька (< 100 документів)?

Не обов'язково. На маленькій базі vector search зазвичай достатній — є менше "шуму" і релевантні чанки потрапляють у топ. Hybrid виправданий, коли документи містять точні терміни, коди або ціни, які vector search "розмиває". Тому я і зробив переключення через app.search.mode — для маленьких клієнтів залишаю vector.

Чому tsvector, а не Elasticsearch для BM25?

PostgreSQL у мене вже є — він зберігає і документи, і вектори (pgvector). Додавати Elasticsearch як окремий сервіс — це DevOps overhead, моніторинг, синхронізація даних. Вбудований tsvector з GIN індексом вирішує задачу BM25 пошуку без додаткової інфраструктури. Для масштабу 10K+ документів з високим QPS варто розглянути Elasticsearch або Qdrant з нативним hybrid.

Як hybrid search впливає на latency?

Мінімально. BM25 і vector search виконуються послідовно (поки не паралельно), але BM25 по GIN індексу — мілісекунди. RRF злиття — мікросекунди (обрахунок рангів). Основний час — embedding запиту через nomic-embed-text і vector search через pgvector. Hybrid додає ~5-15ms до загального часу пошуку.

Чи можна використовувати конфіг russian замість simple для української?

Можна — стемінг частково працює (мови схожі). Але є ризик неправильного стемінгу для деяких українських слів. simple надійніше: він просто токенізує без стемінгу. Для "розуміння" слів у мене є vector search — BM25 потрібен тільки для точних збігів.

Що робити, якщо BM25 завжди повертає 0 результатів?

Перевірте три речі: (1) чи заповнена колонка content_tsv — виконайте SELECT count(*) FROM vector_store WHERE content_tsv IS NOT NULL; (2) чи збігається tsconfig у to_tsvector() і plainto_tsquery(); (3) чи є точні збіги слів запиту в тексті чанків. Якщо запити переважно семантичні — BM25 повертає 0, і це нормальна поведінка.

✅ Висновки

• 🔹 Vector search сам по собі не достатній: він "розмиває" точні терміни, ціни, номери документів. BM25 закриває ці пробіли
• 🔹 Hybrid search (BM25 + vector + RRF): два паралельних пошуки, злиття через формулу 1/(k + rank). Чанк, що високо в обох рейтингах, виграє
• 🔹 pgvector + tsvector: не потрібен Elasticsearch — PostgreSQL з GIN індексом достатній для BM25 поруч з vector search
• 🔹 Конфігурація під клієнта: app.search.mode=hybrid/vector, app.search.tsconfig=simple/german/english — усе через проперті, без перекомпіляції
• 🔹 Підводні камені: CAST(:tsconfig AS regconfig) обов'язковий для JdbcClient, content_tsv потрібно заповнити для існуючих чанків, similarity threshold для українського тексту — 0.1
• 🔹 Hybrid не погіршує: коли BM25 не знаходить нічого — результати = vector search. Коли знаходить — якість зростає

Моя головна думка: hybrid search — це найпростіший і найефективніший крок для підвищення якості RAG-системи після базового vector search. Якщо ваші документи містять терміни, ціни, коди — ефект помітний одразу. А якщо ні — hybrid просто працює як vector search, нічого не ламаючи.

📖 Джерела

• Cormack, Clarke, Buettcher — Reciprocal Rank Fusion (SIGIR '09)
• Robertson, Walker — BM25: Foundations and Review
• Elasticsearch — Reciprocal Rank Fusion
• Qdrant — Hybrid Search and Universal Query API
• PostgreSQL — Full Text Search Documentation
• PostgreSQL — GIN Index
• pgvector — Open-source vector similarity search for Postgres

📚 Пов'язані статті

• Hybrid Search та Reranking: як підняти якість RAG на 15–40% без зміни моделі
• Chunking Strategies в RAG 2026: як правильно розбивати дані для production
• Embedding-моделі для RAG у 2026: як обрати, порівняння провайдерів
• Ollama на 8 ГБ RAM: які моделі працюють у 2026