WIKI 知识库 v1.1.2：把检索与分片参数调优搬进控制台

预计阅读时间：10 分钟

WIKI 知识库 v1.1.2 的重点变化，是将 KB-20 检索配置和固定长度分片调整做成控制台功能。过去修改 top_k、相似度阈值或切块长度，需要编辑 conf/config.json 并重启服务；现在可以直接在知识库管理页面调整“检索与分片”参数，更适合快速验证不同配置对问答效果的影响。

这类改动看起来只是少改几行配置，实际解决的是知识库调优中的两个高频问题：配置变更反馈慢，以及配置文件和正在运行的进程出现不一致。

从重启服务到在线调参

以前的典型流程大致如下：

修改 conf/config.json
    -> 停止服务
    -> 启动服务
    -> 等待知识库初始化
    -> 发起测试问题
    -> 记录结果

当需要比较多组 top_k、最大检索结果数、相似度下限和分片长度时，重启会让每一轮实验都变得很重。更麻烦的是，配置文件已经改过，但进程可能仍然持有旧配置，排查时很难立即确认当前请求究竟使用了哪一组参数。

v1.1.2 将相关设置集中到知识库管理中的“检索与分片”区域。根据来源摘要，至少覆盖以下类型的配置：

default_k：默认召回数量。
max_search_results：检索结果数量上限。
min_source_...：与来源或相似度下限相关的过滤配置，具体字段名以实际版本界面为准。
固定长度分片参数：控制文档如何被切分为可检索片段。

在线修改的价值不只是操作更方便。它还让“配置修改”和“查询验证”处于同一个控制台工作流中，减少了因为忘记重启、重启失败或多实例配置不一致造成的误判。

检索参数和分片长度要一起看

检索参数决定系统从候选片段中取多少内容，分片参数则决定候选片段本身长什么样。两者分开调，往往会得到片面的结论。

例如：

default_k 太小，可能漏掉回答所需的上下文。
default_k 太大，可能把大量相近但无关的片段交给后续生成模型，增加噪声和上下文消耗。
相似度下限过低，召回范围会变宽，但低相关内容也更容易混入结果。
相似度下限过高，结果更“干净”，但可能漏掉使用不同措辞表达的正确内容。
分片过短，语义边界可能被切断，单个片段缺少完整背景。
分片过长，检索命中后携带的信息更多，但不同主题可能被塞进同一片段，降低定位精度。

因此，建议把一次调优看成一个小型实验，而不是凭感觉不断拖动参数。至少固定一组测试问题，记录每次实验的参数、召回结果和最终回答质量。

一个可改造的调参脚本

下面的命令是一个接口实践示例，用于说明如何把控制台调参流程接入自动化实验。接口路径和字段名需要按照实际部署版本提供的 API 进行调整；如果当前版本只有网页控制台，也可以把相同字段作为手工实验记录。

假设服务提供了读取和更新知识库检索配置的接口：

# 读取当前配置，确认运行中的值
curl -sS http://localhost:8080/api/knowledge-bases/demo/retrieval-config | jq

# 更新一组用于对比实验的参数
curl -sS -X PUT \
  http://localhost:8080/api/knowledge-bases/demo/retrieval-config \
  -H 'Content-Type: application/json' \
  -d '{
    "default_k": 5,
    "max_search_results": 8,
    "min_source_similarity": 0.72,
    "chunk_size": 800
  }' | jq

# 更新后再次读取，避免把旧配置当成新配置使用
curl -sS http://localhost:8080/api/knowledge-bases/demo/retrieval-config | jq

可以用几组有明确差异的参数开始实验：

# 低召回量、较高过滤阈值：观察结果是否更精准
curl -sS -X PUT http://localhost:8080/api/knowledge-bases/demo/retrieval-config \
  -H 'Content-Type: application/json' \
  -d '{"default_k": 3, "max_search_results": 5, "min_source_similarity": 0.80, "chunk_size": 800}'

# 高召回量、较低过滤阈值：观察是否能找回被漏检的内容
curl -sS -X PUT http://localhost:8080/api/knowledge-bases/demo/retrieval-config \
  -H 'Content-Type: application/json' \
  -d '{"default_k": 8, "max_search_results": 12, "min_source_similarity": 0.65, "chunk_size": 800}'

实验记录可以先用一个简单的 CSV：

case_id,default_k,max_search_results,min_source_similarity,chunk_size,answer_quality,notes
faq-001,3,5,0.80,800,4,回答准确且引用集中
faq-001,8,12,0.65,800,3,召回了无关版本说明
faq-002,5,8,0.72,800,4,上下文完整

这里的关键不是某个固定数值，而是每次只改变少量变量，并在查询后确认实际生效的配置。这样才能区分问题究竟来自召回数量、过滤阈值，还是分片方式。

上线前需要确认的边界

在线调参降低了实验成本，但也把配置变更带来的风险暴露得更直接。生产环境使用时，建议确认以下事项：

权限控制：只有知识库管理员或具备配置权限的角色才能修改参数。
变更可追踪：记录修改人、修改时间、旧值、新值和变更原因。
配置作用范围：明确参数是只影响当前知识库、当前租户，还是影响整个服务。
多实例一致性：确认修改结果是否由共享存储或配置中心统一读取，避免不同实例使用不同值。
回滚方式：为上一组稳定参数保留记录，出现回答质量下降时可以快速恢复。
重建边界：检索参数通常可以直接影响查询行为；分片长度可能影响索引内容，是否需要重新切分和重建索引，应以实际实现为准。

特别是固定长度分片调整，不能简单等同于修改一个查询参数。若分片长度改变会产生新的片段和向量，系统可能需要重新处理文档。控制台应清楚提示这一点，运维人员也应把索引重建耗时纳入变更计划。

适合怎样采用 v1.1.2

如果团队经常做知识库问答评测，建议把 v1.1.2 的“检索与分片”配置纳入标准实验流程：准备一组代表性问题，先记录当前参数，再逐组调整 default_k、结果上限、相似度阈值和分片长度，最后用统一标准比较回答准确性、引用相关性和响应成本。

对于小规模知识库，可以直接使用控制台进行人工验证。对于需要持续评测的团队，则应在确认实际 API 和权限模型后，把配置读取、参数更新和测试问题执行接入脚本或 CI 流程。

这次版本更新的核心收益，是让知识库调优从“改文件、重启、猜是否生效”变成可观察、可对比的控制台操作。真正上线前仍要补齐权限、审计、回滚和索引重建提示，才能把便利性转化为稳定的生产流程。