fuzhengwei / fuzhengwei/WaLiAPI

KB 混合检索 RRF 融合(默认)+ 可选 LLM listwise 重排

Open
#88 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
128
Forks
39
Avg merge
15h 25m
Merged PRs (30d)
44

Description

### 现状

`hybrid_search_with_details` 对向量/FTS5 两路各取 top_k×2 后按 `vector_weight/keyword_weight` **线性加权**合并——两路分数量纲不同(余弦相似度 ~[0,1],BM25 可为任意小正数),直接加权是已知次优:向量路量纲系统性碾压,关键词路的信号几乎被淹没。RRF(倒数排名融合)只用排名、天然消量纲,零依赖即可落地。

### 方案

- 融合逻辑抽为**纯函数** `fuse_scored` + `FusionMode`:RRF 分数 = Σ 1/(k + rank)(k=60 业界惯用)设为**默认**;weighted 线性加权保留可配回退(`kb.fusion_mode`,默认 rrf,未知值回退 rrf)。
- 四调用点接线:标准问答按设置项;MCP 工具路径用默认 RRF。
- 可选 LLM listwise 重排(`kb.rerank_enabled`,**默认关**):top 候选拼提示词(文件名+摘录)经网关自身渠道打分重排(「用渠道跑渠道」,走 kb-internal 路由组——**重排 token 消耗自动计入请求日志**);回复解析容错(截取 JSON 数组、越界/重复丢弃、缺失按原序补尾——输出恒为全排列);失败静默回退原序。

### 兼容承诺

weighted 模式保留可配,历史行为逐字节保留(测试锁定)。默认切 rrf 的行为变化在此显著声明。

### 测试

量纲悬殊两路构造用例(向量 0.99/0.97 vs 关键词 0.0007/0.0005)断言加权下向量独大、RRF 下双路第一的候选登顶;RRF 分数确定性与明细保留;weighted 历史行为;设置项切换表达式(weighted 可切回、未配置走默认);重排解析容错;knowledge 面 43/43。

### 开放点

1. k=60 常数是否需要可配?
2. MCP 检索工具是否需要透传 fusion_mode 参数(当前用默认 rrf)?

---
对应分支:`feat/capability-c06-r3-rrf-fusion`(无迁移)。

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating hybrid_search_with_details and its four call sites, then trace the kb.fusion_mode and kb.rerank_enabled settings. Review the existing retrieval tests before separating fusion behavior and reranking; done means deterministic RRF details, preserved weighted behavior, tolerant reranking fallback, and all knowledge tests passing.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, sqlite
Domain
backend-api-design, databases, search
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.