feat(retrieval): configurable RRF parameters per tenant

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
This commit is contained in:
Claude
2026-05-02 09:35:32 +00:00
committed by lyingbug
parent 0dc32cb0c4
commit 2850ac78ce
3 changed files with 49 additions and 8 deletions
@@ -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()
@@ -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))
+36
View File
@@ -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)