feat(rag): hybrid multi-path search with RRF fusion

Add configurable hybrid mode on KnowledgeSearchPort that fuses dense unfiltered, dense filtered, and lexical ranks via RRF while preserving dense-compatible threshold scores. Archives Delivery 2 OpenSpec change.
2026-07-27 18:33:31 +08:00
parent ac1f831903
commit 376ad0c241
19 changed files with 661 additions and 8 deletions
@@ -0,0 +1,23 @@
+# Acceptance: rag-hybrid-search-rrf
+
+## Result
+
+Hybrid mode implemented on KnowledgeSearchPort:
+
+- dense unfiltered + dense filtered + lexical rank over union
+- RRF fusion by evidenceKey
+- dense-compatible score preserved for thresholds
+- default mode remains dense
+
+## Verification
+
+```text
+mvn -q "-Dtest=RrfFusionTest,VectorKnowledgeSearchAdapterHybridTest,LookupKnowledgeToolTest" test
+```
+
+Pass.
+
+## Residual
+
+- True Milvus BM25/sparse schema + reindex still follow-up
+- Lexical path only ranks dense-recalled candidates (does not expand pure-term misses outside dense topK)
@@ -0,0 +1,3 @@
+# Brief: rag-hybrid-search-rrf
+
+Delivery 2 after chunk identity. Enable hybrid multi-path + RRF on KnowledgeSearchPort without legacy SDK hybrid API. True BM25 schema rebuild is staged follow-up; this change ships sparse-lite lexical ranking over dense candidate union + filtered/unfiltered dense fusion.
@@ -0,0 +1,19 @@
+# Decisions: rag-hybrid-search-rrf
+
+## Capability
+
+sm-flow + OpenSpec fallback; apply pre-authorized.
+
+## Depends
+
+Delivery 1 archived.
+
+## Grill (compressed, pre-authorized)
+
+- Q: Full BM25 schema now? A: No — sparse-lite + RRF first; schema rebuild follow-up.
+- Q: Default mode? A: dense default; hybrid opt-in.
+- Q: Threshold score? A: keep dense-compatible L2 mapping.
+
+## Design
+
+Hybrid paths: dense unfiltered + dense filtered + lexical rank over union; RRF fuse by evidenceKey.
@@ -0,0 +1,5 @@
+# Evidence
+
+- Delivery 1 identity/port foundation required
+- RRF utility and hybrid adapter unit tests green
+- Lexical sparse-lite intentionally intermediate until BM25 schema