该功能的作用
以前检索主要靠「向量语义 + 重排」：同义词、口语化提问能找着，但专有名词、型号、原文原句这类字面命中容易漏。当前版把关键词通道补上，做成一条完整链路：
BM25 字面召回与向量 ANN并行取候选。
用 RRF（倒数排名融合）合成一份候选列表，再交给原来的 Rerank。
任一通道失败或关掉时自动降级到另一路，问答不至于整段挂掉。
开关与rrf_k挂在「知识库管理 → 检索与分片」，保存即热更新，方便对比实验。
社区版默认开启混合检索；关掉hybrid_enabled即可回到「仅向量 + 重排」。另外本版顺带修了两处容易误解的体验：
知识来源分数：主标签改为「名次 + 本批相对分 + 档位」，并拆开展示向量 / 重排绝对值；模型答「无法确定」时，侧栏降级为「检索候选」并默认收起。
聊天页高度：整页不再被消息撑高；消息区内部滚动，输入框始终留在可视区域底部。
混合检索整体架构
|
名称 |
文件路径 |
说明 |
|---|---|---|
|
稀疏索引 |
src/kb/bm25_index.py |
纯标准库 Okapi BM25；中英简单切词 |
|
融合 |
src/kb/hybrid.py |
多路 RRF |
|
检索主路径 |
src/knowledge_base.py |
双通道 + 降级 + 重排；回传向量/重排分项 |
|
可配置项 |
src/kb/retrieval_settings.py |
hybrid_enabled / rrf_k 校验与热更新 |
|
来源组装 |
src/api/http_server.py |
相对排序分、档位、分项分数 |
|
页面 |
KbManagement.vue / RetrievalQa.vue |
混合开关；来源展示与聊天布局 |
那如何使用呢？
1. 默认即可使用
升级到 v1.1.3 后，配置默认：
|
参数 |
默认值 |
说明 |
|---|---|---|
|
hybrid_enabled |
true |
开启 BM25∪向量 |
|
rrf_k |
60 |
RRF 常数；越大排名差越平滑 |
导入或重建分片时会同步重建内存 BM25 索引，无需单独操作。
2. 面板参数调整
控制台「知识库管理 → 检索与分片」：
打开 / 关闭混合检索 hybrid_enabled
调整RRF 常数 rrf_k（关闭混合时该项禁用）
# 读当前生效值（含 hybrid）curl -s http://127.0.0.1:8000/api/kb/settings | python -m json.tool# 临时关掉混合只走向量+重排curl -s -X PUT http://127.0.0.1:8000/api/kb/settings -H "Content-Type: application/json" -d "{\"hybrid_enabled\":false}" | python -m json.tool
3. 看懂「知识来源」分数
检索问答右侧 知识来源 主标签形如：
#1 · 1.00 · 一般、向量 0.52 · 重排、0.78 · 合成 0.66
|
字段 |
说明 |
|---|---|
|
名次 |
本批结果中的排序 |
|
相对分 |
第 1 名最高分值为 1.00 其余按合成分相对峰值比例 |
|
较强 / 一般 / 较弱 |
按合成分档位不是正确率 |
|
向量 / 重排 / 合成 |
分项绝对值便于核对虚高 |
若回答是「根据当前知识库无法确定」：
气泡改为「检索候选 N 条（不足以回答）」
侧栏提示：仅是候选，不是已证实依据，并默认收起
4. 和评测一起用
同一套参数下用评测集跑分、指标看板看结果，才能验证混合是否真的抬召回：
python -m src.eval.clipython -m src.eval.cli --top-k 10
建议进行对比hybrid_enabled=true对比false，看 Recall@5 / NDCG@10 与检索 p95。
是如何实现的
1. 检索数据流
检索数据流日志关键词如Hybrid recall: channel=hybrid_rrf|vector_only|bm25_only ...方便排查走了哪条路。
2. 分数怎么来的
合成分 ≈ 0.35 × 向量分 + 0.65 × 重排分（默认权重）相对分 = 合成分 / 本批最高合成分
所以当问对了文档却只有 0.66很常见，因为那是合成分不是错误率。界面主标签改用相对分后，排第一的文档最高会显示1.00，同时仍可在下方看到真实向量/重排序值。
3. 聊天页高度
视口 100dvh└─ 顶栏 + 主内容区（问答页禁止整页滚动）└─ qa-layout（三栏填满剩余高度）└─ 中间栏：工具栏（固定）消息列表（内部滚动）输入框（固定在栏底）
4. 示例
配置片段conf/config.json思路
{"search": {"hybrid_enabled": true,"default_k": 5,"min_source_similarity": 0.6},"retrieval": {"rrf_k": 60,"embed_weight": 0.35,"rerank_weight": 0.65}}
接口返回的来源项（节选）
{"filename": "升级迁移指南.md","rank": 1,"relative_similarity": 1.0,"similarity": 0.66,"embed_similarity": 0.52,"rerank_similarity": 0.78,"score_label": "一般","preview_text": "……"}
那有如何测试呢？
1. 自动化验收
python -m unittest tests.test_hybrid_retrieval tests.test_source_score_display -v
2. 手动验收
2.1 首先需要确认 hybrid_enabled=true导入含专有名词的文档2.2 用「原文原句 / 型号」提问应能命中（相对纯向量更稳一些）2.3 关掉 hybrid 再问同一次对比召回的差异2.4 问知识库中没有的内容，答案「无法确定」，右侧栏则收起来并提示「检索候选」2.5 多轮对话只有消息区上下滚动，底部输入框始终固定低部2.6 跑评测门控（混合召回路径）如下
python -m src.eval.cli --dataset conf/eval/golden-default.jsonl --hybrid on --no-rerank --warmup 3 --top-k 10 --min-recall5 0.85 --min-recall3 0.75 --min-ndcg10 0.70 --max-latency-p95 300
版本升级说明
从 v1.1.2 升级拉代码 / 装包后重启服务即可。
旧配置中没有hybrid_enabled时默认按 true 处理。
pyproject.toml/ 前端package.json版本均为 1.1.3。
社区发版可参考scripts/release/plan-v1.1.3.json（如果有）。
关于维基框架
维基本地知识库是一个本地优先的开源知识库系统，融合向量检索、重排与对话式问答，支持多种主流大模型 API，具备高性能本地存储与灵活扩展能力，适合智能问答、知识管理、企业知识中台等场景。MulanPSL2 许可证，欢迎共建！
官网：framewiki.com
Gitee：https://gitee.com/cdkjframework/knowledge-base
:page_facing_up: 许可证：MulanPSL-2.0（木兰宽松许可证，第2版）