这个功能有什么作用呢？

以前调 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 │└──────────────────────────────┘

怎么用使用？

1、 打开面板

启动服务后进入控制台「知识库管理」→「检索与分片」即可看到当前生效值。建议参数（也是当前本版默认配置）：

修改完配置后耍要刷新「检索问答」页即可，工具栏召回数会跟新的 default_k 对齐（仍可临时手动调）。

2、 改检索参数

将 default_k 参数调整到 8 后点击「保存并生效」按钮，再去检索问答提问（先不带 k 调 /api/query）召回参数会立刻改变。

# 读当前生效值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 "{\"default_k\":8,\"max_search_results\":12,\"min_source_similarity\":0,\"chunk_size\":800,\"chunk_overlap\":120}" \  | python -m json.tool

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              # top_k 跟 KB-20python -m src.eval.cli --top-k 10   # 显式覆盖

是怎么实现的，数据流如下图

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# 假定 api 已启动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

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