WIKI 知识库 v1.1.3 正式发布

该功能的作用

以前检索主要靠「向量语义 + 重排」：同义词、口语化提问能找着，但专有名词、型号、原文原句这类字面命中容易漏。当前版把关键词通道补上，做成一条完整链路：

1. BM25 字面召回与向量 ANN并行取候选。
2. 用 RRF（倒数排名融合）合成一份候选列表，再交给原来的 Rerank。
3. 任一通道失败或关掉时自动降级到另一路，问答不至于整段挂掉。
4. 开关与 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

检索问答右侧 知识来源 主标签形如：

#1 · 1.00 · 一般、向量 0.52 · 重排、0.78 · 合成 0.66

字段

名次

本批结果中的排序

相对分

第 1 名最高分值为 1.00 其余按合成分相对峰值比例

较强 / 一般 / 较弱

按合成分档位不是正确率

向量 / 重排 / 合成

分项绝对值便于核对虚高

若回答是「根据当前知识库无法确定」：

• 气泡改为「检索候选 N 条（不足以回答）」
• 侧栏提示：仅是候选，不是已证实依据，并默认收起

同一套参数下用评测集跑分、指标看板看结果，才能验证混合是否真的抬召回：

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（三栏填满剩余高度）└─ 中间栏：工具栏（固定）消息列表（内部滚动）输入框（固定在栏底）

配置片段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": "……"}

python -m unittest tests.test_hybrid_retrieval tests.test_source_score_display -v

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

许可证：MulanPSL-2.0（木兰宽松许可证，第2版）