调整 top_k、更换 embedding 模型，或者修改文档分片参数后，检索效果究竟变好了还是变差了？WIKI 知识库 v1.1.1 把这个问题变成了一套可重复、可观察的评测流程：用固定内容和固定题目运行检索，计算 Recall、NDCG、延迟等指标，并将结果保存下来供控制台看板查看。
从“感觉更准”变成可比较的数据
检索系统的调优通常会同时影响多个维度：
top_k变大，可能提高召回覆盖率，也可能带来更高延迟；- 更换 embedding 模型，可能改善语义匹配，但需要重新验证已有题目；
- 修改分片大小或重叠范围，可能让答案更完整，也可能引入更多噪声。
如果只人工打开几个问题进行测试，很难判断变化来自配置本身，还是来自测试样本、查询顺序和主观感受。v1.1.1 使用固定内容逐题调用检索，让每次实验都能在相近条件下重复执行，并用统一指标记录结果。
命令行评测流程
评测入口是 Python 模块命令：
python -m src.eval.cli
运行前，请确认项目依赖已经安装，并准备好评测所需的固定知识内容和题目。命令执行后，结果写入：
kb_store/eval/latest.json
一个适合本地调参的基本流程如下：
# 1. 调整检索配置，例如 top_k、embedding 或分片参数
# 2. 重新构建或更新知识库
# 3. 运行固定评测集
python -m src.eval.cli
# 4. 查看本次生成的结果文件
python -m json.tool kb_store/eval/latest.json
可以把每次配置修改和评测结果放在同一个变更记录中。例如：
实验 A：top_k=5，默认 embedding，原分片参数
实验 B：top_k=10，默认 embedding，原分片参数
实验 C：top_k=10，新 embedding，调整后的分片参数
然后比较每次生成的 Recall、NDCG 和延迟，而不是只看某一个问题是否“感觉更相关”。
如何理解这些指标
Recall 适合观察相关内容有没有被召回。它能回答“正确文档是否出现在候选结果中”，适合评估检索覆盖范围。
NDCG 不仅关注是否召回，还关注相关结果出现的位置。相关文档排在更靠前的位置，通常会得到更好的排序评价，因此它能帮助发现“召回了，但排得不够好”的问题。
延迟则反映一次评测请求需要等待多久。一个配置可能让 Recall 上升，却同时显著增加响应时间；这时就不能只根据准确性指标做决定。
这些指标不应该孤立解读。实际选择配置时，可以建立简单的判断表：
| 变化 | 可能结论 |
|---|---|
| Recall 上升，NDCG 上升，延迟基本稳定 | 值得优先考虑 |
| Recall 上升，但延迟明显增加 | 需要结合产品响应时间要求权衡 |
| Recall 稳定，NDCG 下降 | 可能是排序质量或分片策略变差 |
| 所有指标都下降 | 回滚配置并检查索引、embedding 或评测数据 |
用结果文件做自动化检查
如果要把评测接入脚本或 CI，可以在命令执行后读取 latest.json。下面的示例假设结果文件中包含名为 metrics 的对象；实际字段以项目生成的 JSON 结构为准：
import json
from pathlib import Path
result_path = Path("kb_store/eval/latest.json")
data = json.loads(result_path.read_text(encoding="utf-8"))
print("评测结果：")
print(json.dumps(data, ensure_ascii=False, indent=2))
metrics = data.get("metrics", {})
recall = metrics.get("recall")
ndcg = metrics.get("ndcg")
latency = metrics.get("latency")
if recall is not None:
print(f"Recall: {recall}")
if ndcg is not None:
print(f"NDCG: {ndcg}")
if latency is not None:
print(f"Latency: {latency}")
如果结果文件的字段结构不同，可以先运行 python -m json.tool 查看实际 JSON，再调整字段路径。这样做的价值在于：人工看板适合快速观察趋势，脚本则适合执行阈值检查和回归测试。
控制台看板让趋势更容易被发现
除了命令行评测，v1.1.1 还提供控制台指标看板。运行评测后打开控制台页面，可以集中查看评测指标和结果趋势，减少在终端与结果文件之间来回切换的成本。
看板最适合回答这些问题：
- 最近一次配置变更是否让整体 Recall 下降？
- 新 embedding 是否改善了排序质量？
top_k增大带来的收益是否值得额外延迟？- 某次分片调整是否只改善了部分题目？
看板不能替代评测集本身。如果固定题目覆盖不足，指标仍然可能无法代表真实用户查询。因此，评测内容应持续补充典型问题、边界问题和容易混淆的问题，并在修改评测集时保留版本记录。
落地时的检查清单
采用这套流程时，可以按下面的顺序执行：
- 固定一批知识内容和评测题目，避免每次实验输入不同。
- 一次只改变一组主要变量，例如只调整
top_k。 - 运行
python -m src.eval.cli，确认结果确实写入kb_store/eval/latest.json。 - 同时观察 Recall、NDCG 和延迟，不要只追求单项最高分。
- 在控制台看板中查看整体趋势，并针对异常题目回看具体检索结果。
- 将表现稳定的配置和评测结果一起记录，方便回滚和复现。
v1.1.1 的重点不是提供一个“永远正确”的参数，而是建立一条可重复的反馈回路：改配置、跑固定评测、查看指标、分析变化，再决定是否保留。对于需要持续调优的知识库，这比依赖零散人工体验更可靠，也更适合团队协作。