From 2850ac78ceccd6a8d4e3881b56a5f551ffd6b285 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 2 May 2026 09:35:32 +0000 Subject: [PATCH] feat(retrieval): configurable RRF parameters per tenant MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reciprocal Rank Fusion previously hard-coded k=60 and weights 0.7/0.3. Both are now sourced from RetrievalConfig (RRFK, RRFVectorWeight, RRFKeywordWeight) with the same numbers as defaults via three new GetEffective accessors. fuseOrDeduplicate / fuseWithRRF accept the config; HybridSearch reads it from tenantInfo and forwards. Lets corpus owners tune fusion behavior — large corpora benefit from larger k, keyword-heavy domains from a higher keyword weight, etc. — without changing application code. https://claude.ai/code/session_01XADhx6mtu2ZYW3DE9Lun6k --- .../service/knowledgebase_search.go | 6 +++- .../service/knowledgebase_search_fusion.go | 15 ++++---- internal/types/retrieval_config.go | 36 +++++++++++++++++++ 3 files changed, 49 insertions(+), 8 deletions(-) diff --git a/internal/application/service/knowledgebase_search.go b/internal/application/service/knowledgebase_search.go index 5a3dbf2a..61b63b42 100644 --- a/internal/application/service/knowledgebase_search.go +++ b/internal/application/service/knowledgebase_search.go @@ -152,7 +152,11 @@ func (s *knowledgeBaseService) HybridSearch(ctx context.Context, } logger.Infof(ctx, "Result count before fusion: vector=%d, keyword=%d", len(vectorResults), len(keywordResults)) - deduplicatedChunks := fuseOrDeduplicate(ctx, vectorResults, keywordResults) + var retrievalCfg *types.RetrievalConfig + if tenantInfo != nil { + retrievalCfg = tenantInfo.RetrievalConfig + } + deduplicatedChunks := fuseOrDeduplicate(ctx, vectorResults, keywordResults, retrievalCfg) kb.EnsureDefaults() diff --git a/internal/application/service/knowledgebase_search_fusion.go b/internal/application/service/knowledgebase_search_fusion.go index 22c7adc3..9c13eb8f 100644 --- a/internal/application/service/knowledgebase_search_fusion.go +++ b/internal/application/service/knowledgebase_search_fusion.go @@ -29,7 +29,8 @@ func classifyRetrievalResults(ctx context.Context, retrieveResults []*types.Retr } // fuseOrDeduplicate either fuses vector+keyword results via RRF or deduplicates vector-only results. -func fuseOrDeduplicate(ctx context.Context, vectorResults, keywordResults []*types.IndexWithScore) []*types.IndexWithScore { +// retrievalCfg may be nil — defaults are then used for RRF parameters. +func fuseOrDeduplicate(ctx context.Context, vectorResults, keywordResults []*types.IndexWithScore, retrievalCfg *types.RetrievalConfig) []*types.IndexWithScore { if len(keywordResults) == 0 { // Vector-only: keep original embedding scores (important for FAQ) result := deduplicateByScore(vectorResults) @@ -43,7 +44,7 @@ func fuseOrDeduplicate(ctx context.Context, vectorResults, keywordResults []*typ return result } // Hybrid: use RRF fusion to merge vector + keyword results - result := fuseWithRRF(ctx, vectorResults, keywordResults) + result := fuseWithRRF(ctx, vectorResults, keywordResults, retrievalCfg) logger.Infof(ctx, "Result count after RRF fusion: %d", len(result)) return result } @@ -77,12 +78,12 @@ func deduplicateByScore(results []*types.IndexWithScore) []*types.IndexWithScore } // fuseWithRRF merges vector and keyword retrieval results using Reciprocal Rank Fusion. -// RRF score = vectorWeight/(k+vectorRank) + keywordWeight/(k+keywordRank), with k=60. +// RRF score = vectorWeight/(k+vectorRank) + keywordWeight/(k+keywordRank). +// k, vectorWeight and keywordWeight are sourced from retrievalCfg (with defaults). // The merged results are sorted by RRF score descending. -func fuseWithRRF(ctx context.Context, vectorResults, keywordResults []*types.IndexWithScore) []*types.IndexWithScore { - const rrfK = 60 - const vectorWeight = 0.7 - const keywordWeight = 0.3 +func fuseWithRRF(ctx context.Context, vectorResults, keywordResults []*types.IndexWithScore, retrievalCfg *types.RetrievalConfig) []*types.IndexWithScore { + rrfK := retrievalCfg.GetEffectiveRRFK() + vectorWeight, keywordWeight := retrievalCfg.GetEffectiveRRFWeights() // Build rank maps for each retriever (already sorted by score from retriever) vectorRanks := make(map[string]int, len(vectorResults)) diff --git a/internal/types/retrieval_config.go b/internal/types/retrieval_config.go index 5e9a837c..f62604a1 100644 --- a/internal/types/retrieval_config.go +++ b/internal/types/retrieval_config.go @@ -24,6 +24,17 @@ type RetrievalConfig struct { RerankThreshold float64 `json:"rerank_threshold"` // RerankModelID is the ID of the rerank model to use (required for search) RerankModelID string `json:"rerank_model_id"` + + // RRFK is the smoothing constant of Reciprocal Rank Fusion. Larger values + // flatten the curve, reducing the bias towards top-1 results. + // Default: 60. Sensible range: 30..100 depending on corpus size. + RRFK int `json:"rrf_k,omitempty"` + // RRFVectorWeight is the weight applied to the vector retriever inside RRF. + // RRFVectorWeight + RRFKeywordWeight should usually sum to 1.0 but the math + // works for any positive weights. Default: 0.7. + RRFVectorWeight float64 `json:"rrf_vector_weight,omitempty"` + // RRFKeywordWeight is the keyword counterpart. Default: 0.3. + RRFKeywordWeight float64 `json:"rrf_keyword_weight,omitempty"` } // GetEffectiveEmbeddingTopK returns EmbeddingTopK with a fallback default. @@ -66,6 +77,31 @@ func (c *RetrievalConfig) GetEffectiveRerankThreshold() float64 { return c.RerankThreshold } +// GetEffectiveRRFK returns the RRF smoothing constant with a fallback default. +func (c *RetrievalConfig) GetEffectiveRRFK() int { + if c == nil || c.RRFK <= 0 { + return 60 + } + return c.RRFK +} + +// GetEffectiveRRFWeights returns vector / keyword weights with sensible defaults. +// When neither weight is set explicitly, returns 0.7 / 0.3. +func (c *RetrievalConfig) GetEffectiveRRFWeights() (vector, keyword float64) { + if c == nil || (c.RRFVectorWeight == 0 && c.RRFKeywordWeight == 0) { + return 0.7, 0.3 + } + v := c.RRFVectorWeight + k := c.RRFKeywordWeight + if v <= 0 { + v = 0.7 + } + if k <= 0 { + k = 0.3 + } + return v, k +} + // Value implements the driver.Valuer interface for database serialization func (c RetrievalConfig) Value() (driver.Value, error) { return json.Marshal(c)