|
|
这个功能有什么作用呢？
以前调 top_k、相似度阈值、切块长度都要改 conf/config.json 然后再重启服务，要做对比实验就很慢，也容易「改了配置但进程还在用旧值」。KB-20 检索配置（含固定长度分片调整）将该功能做成控制台里的功能：
1.知识库管理 「检索与分片」：直接改 default_k、max_search_results、min_source_similarity、chunk_size、chunk_overlap。 2.保存即热更新：检索参数修改后即可生效 /api/query（未显式传 k 时走新的 default_k），不用在重启服务了。 3.分片参数对新导入生效：新上传 / 文本写入按新块长切分；不过已有文档则需要点「重建分片」才会按新规则重切。 4.当前生效值可读：GET /api/kb/settings 返回进程里真正在用的数据，避免「文件写了、内存没改就」的错觉。
不过社区版仍只提供固定长度切分；语义 / 递归分片是商业专属本页不会出现语义策略下拉。
整体架构如下图
- ┌──────────── 用户 ────────────┐│ 知识库管理 · 检索与分片 ││ 检索问答 /api/query ││ 新导入 / 重建分片 │└──────────────┬───────────────┘ │ GET/PUT ▼┌──────────── 后端 ────────────┐│ /api/kb/settings ││ → retrieval_settings.py ││ ├→ conf/config.json ││ └→ 运行时 kb.default_k ││ / chunk_* / _search │└──────────────────────────────┘
层次
路径
说明
校验 / 落盘辅助
src/kb/retrieval_settings.py
范围校验、写 config 字典、热更新运行时属性
API
handlers/kb.py
+ KnowledgeBaseApi
GET/PUT /api/kb/settings
查询默认 k
handlers/query.py
请求未带 k 时用 api.default_search_k()
页面
frontend/src/views/kb/KbManagement.vue
「检索与分片」表单
前端 API
frontend/src/api/kb.ts getKbSettings
/ updateKbSettings
怎么用使用？
1、 打开面板
启动服务后进入控制台「知识库管理」→「检索与分片」即可看到当前生效值。建议参数（也是当前本版默认配置）：
参数
默认
说明
default_k
5
问答未指定 k 时的召回数；检索问答页挂载时会同步该值
max_search_results
10
召回上限，须 ≥ default_k
min_source_similarity
0.0
0
= 关闭硬阈值，减少长尾被误杀
chunk_size
800
固定长度块大小（字符）
chunk_overlap
120
相邻块重叠
修改完配置后耍要刷新「检索问答」页即可，工具栏召回数会跟新的 default_k 对齐（仍可临时手动调）。
2、 改检索参数
将 default_k 参数调整到 8 后点击「保存并生效」按钮，再去检索问答提问（先不带 k 调 /api/query）召回参数会立刻改变。
- # 读当前生效值curl -s http:[i]//127.0.0.1:8000/api/kb/settings | python -m json.tool[/i]# 热更新（示例）curl -s -X PUT http:[i]//127.0.0.1:8000/api/kb/settings \[/i] -H "Content-Type: application/json" \ -d "{"default_k":8,"max_search_results":12,"min_source_similarity":0,"chunk_size":800,"chunk_overlap":120}" \ | python -m json.tool
接口
说明
GET /api/kb/settings
当前生效参数 + 使用说明 notes
PUT /api/kb/settings
校验后写配置文件并热更新进程
3. 改分片参数（新导入 / 重建）
改 chunk_size / chunk_overlap 后：
-新导入的文档按新规则切； -旧文档的不会自动重新分片需在左侧选中文档后点「重建分片」。
4. 和评测 / 看板一起用
同一套参数下用 KB-10 跑分用 KB-11 看板看结果，对比实验才可复现。python -m src.eval.cli省略 --top-k时会跟当前知识库 default_k（并至少覆盖指标所需的 k），报告 config 会带上 default_k、chunk_size、chunk_overlap、top_k_source 等方便对账。
- python -m src.eval.cli [i]# top_k 跟 KB-20[/i]python -m src.eval.cli --top-k 10 [i]# 显式覆盖[/i]
- KbManagement │ PUT /api/kb/settings ▼retrieval_settings.normalize_settings │ ├─→ 写 conf/config.json（search / chunking） └─→ 热更新 KnowledgeBase 运行时 （default_k / chunk_* / _search_cfg） │ ▼ /api/query search(k=default_k)
后端的重点有如下四点
•
校验集中在 normalize_settings 越界、max < default_k、overlap ≥ size 都会直接返回400。
•
写文件用现有 _config_write_path()，只会修改 search.* 与 knowledge_base.chunking.*，不会动密钥等其它部分。
• _search_cfg
与 kb.* 会同步更新避免「若只改了其中一个」。
•
社区切分仍会走固定长度，语义分片只会在商业版本支持 business/chunking。
前端重点有如下两点
•
在中间栏新增 Tab「检索与分片」el-input-number 编辑五项等参数。
•
在分片策略展示为只读「固定长度（社区）」。
重点代码示例
读 / 写设置（Python）
- from src.kb.retrieval_settings import normalize_settings, snapshot_from_runtime[i]# 假定 api 已启动[/i]snap = api.get_retrieval_settings()updated = api.update_retrieval_settings({"default_k": 8, "max_search_results": 12})assert updated["default_k"] == 8
响应的配置片段
- { "ok": true, "settings": { "default_k": 8, "max_search_results": 12, "min_source_similarity": 0.0, "chunk_size": 800, "chunk_overlap": 120, "chunking_strategy": "fixed", "notes": { "search": "检索参数保存后立即生效，无需重启服务。", "chunk": "分片参数仅对新导入或「重建分片」生效；旧文档不会自动重切。" } }}
- # 单元：校验、热更新、路径识别python -m unittest tests.test_kb_settings -v# 静态路由仍把 /api/kb/settings 当 API（不 SPA fallback）python -m unittest tests.test_p6_static_ui -v
如何手动验收方式如下三点：
1.
打开「检索与分片」改 default_k 保存 不用重启服务，直接问答召回条数变化。
2.
修改小 chunk_size 后新导入一段长文 → 分片数变多，旧文档需要重建分片。
3. min_source_similarity
设为 0 与设为 0.55 各跑一轮评测，在对比 Recall 是否按预期变化。
关于维基框架
维基本地知识库是一个本地优先的开源知识库系统，融合向量检索、重排与对话式问答，支持多种主流大模型 API，具备高性能本地存储与灵活扩展能力，适合智能问答、知识管理、企业知识中台等场景。MulanPSL2 许可证，欢迎共建！
官网：framewiki.com
Gitee：https://gitee.com/cdkjframework/knowledge-base
:page_facing_up: 许可证：MulanPSL-2.0（木兰宽松许可证，第2版）
原文链接 |
|
发表于 
