这个功能有什么作用

调整了 top_k、更换了 embedding 或修改了分片参数之后，检索到底是变好了还是变差了？本功能把这件事做成可重复、看得见的流程：

1. 命令行跑评测（python -m src.eval.cli）：用固定内容逐题调用检索，算出 Recall、NDCG、延迟等，结果写入文件 kb_store/eval/latest.json。

2. 控制台指标看板：打开页面时读取上面的文件，把里面的数字展示成 KPI 卡片、历史记录和趋势图，并支持导出 CSV。

前端看板只负责展示，不会在浏览器里重新跑检索，也不会重新计算指标。所以只的先跑完评测再打开看板，两边看到的就才是同一份结果；还没跑过时看板则会提示你先执行评测命令，不会用默认就验收线来冒充实测值。

整体架构如下图

flowchart TB
  subgraph 用户
    U1[命令行 / wiki-eval]
    U2[控制台 · 指标看板]
  end

  subgraph 后端
    E1[src/eval<br/>内容 · 跑分 · 指标]
    E2[kb_store/eval/latest.json]
    E3[src/metrics<br/>KPI 整形]
    E4[GET /api/metrics]
    E1 --> E2
    E2 --> E3 --> E4
  end

  subgraph 前端
    F1[MetricsDashboard.vue]
    F2[/api/stats 运行时统计]
  end

  U1 --> E1
  U2 --> F1
  E4 --> F1
  F2 --> F1

如何使用

1. 准备内容

默认内容 conf/eval/golden-default.jsonl（64 题），UTF-8 JSONL，一行就是一个测试内容：

{"id": "kb-001", "query": "怎么从 v1.0.0 升级到 v1.1.0", "positives": ["升级迁移指南.md"], "tags": ["部署运维"]}

更换成自己的语料时，整体替换内容或设置环境变量 KB_EVAL_DATASET【建议替换内容设置环境变量我没有成功过】。内容需先把对应文档导入到知识库中。

2. 后端跑分

# 校验内容格式，不加载模型
python -m src.eval.cli --validate

# 跑分并刷新 latest.json
python -m src.eval.cli

当然也可使用 wiki-eval。报告会落在 kb_store/eval/目录下，同时生成带时间戳的 report-*.json 文件与固定的 latest.json文件。

3. 前端看板

启动服务后打开控制台 「指标看板」：

• 四项 KPI：Recall@5、Recall@3、NDCG@10、检索 p95，标注达标 / 未达标 / 无数据

• 最近一次评测摘要：内容、题量、跑分时间、核心指标

• 历史列表 + Recall@5 趋势线

• CSV 导出

• 运行时统计（文档数、分片数、模型、内存等，中文标签）

当还未跑分则显示空状态和跑分提示不会用验收线代替实测值。

4. 调接口（可选）

curl -s http://127.0.0.1:8000/api/metrics | python -m json.tool
curl -s "http://127.0.0.1:8000/api/metrics/reports?limit=20"

• 默认验收线：Recall@5 ≥ 0.85、Recall@3 ≥ 0.75、NDCG@10 ≥ 0.70、检索 p95 ≤ 300ms。可在 conf/config.json 覆盖：

{
  "metrics": {
    "targets": {
      "recall@5": 0.85,
      "recall@3": 0.75,
      "ndcg@10": 0.70,
      "latency_p95_ms": 300
    }
  }
}

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

sequenceDiagram
  participant CLI as 跑分 CLI
  participant RN as runner.py
  participant KB as 检索
  participant FS as latest.json
  participant API as /api/metrics
  participant UI as 指标看板

  CLI->>RN: run_evaluation(search_fn)
  loop 每道题
    RN->>KB: search(query, top_k)
    KB-->>RN: 文档名列表
    RN->>RN: metrics.py 算 Recall/NDCG/MRR
  end
  RN->>FS: save_report
  UI->>API: GET /api/metrics
  API->>FS: load_latest + list_reports
  API->>API: dashboard.py 对照验收线
  API-->>UI: kpis + latest + history

后端重点

• 检索通过回调注入run_evaluation(search_fn, cases) 不会绑死 KnowledgeBase，单元测可以给假数据。

• 指标在 metrics.py 用标准库来实现，基于「命中标记序列」算 Recall@k、NDCG@k、MRR 等。

• 单题失败记 0 分写 cases[].error不会中断整轮。

• dashboard.build_dashboard() 读取报告里的 summary 字段，转成 KPI 卡片并按配置判断是否达标。

前端重点

• MetricsDashboard.vue 调用/api/metrics 接口渲染 KPI与历史，Recall@5 趋势用 SVG 折线实现。

• /api/stats 的运行时字段经 STAT_LABELS 显示为中文。

对接知识库跑分、示例代码

from src.eval import load_dataset, make_kb_searcher, run_evaluation, save_report
from src.knowledge_base import KnowledgeBase

kb = KnowledgeBase()
report = run_evaluation(make_kb_searcher(kb), load_dataset())
save_report(report)  # → kb_store/eval/latest.json

自定义检索器（测试与二次开发）

from src.eval import load_dataset, run_evaluation, save_report

def my_search(query: str, top_k: int) -> list[str]:
    return ["升级迁移指南.md"][:top_k]

save_report(run_evaluation(my_search, load_dataset()))

报告内容部分（看板展示的数据就来自这里）

{
  "schema": "kb-eval-report/1",
  "summary": {
    "case_count": 64,
    "recall@5": 0.91,
    "ndcg@10": 0.78,
    "latency_ms": { "p95": 120.0 }
  }
}

接口返回部分重点内容

{
  "ok": true,
  "available": true,
  "kpis": [
    { "key": "recall@5", "value": 0.912, "status": "pass", "target_display": "≥ 0.85" }
  ],
  "latest": { "generated_at": "...", "case_count": 64 },
  "history": []
}

那怎么测试呢、如何实现自动化。

python -m unittest tests.test_eval tests.test_metrics -v

test_eval 覆盖了内容、指标算法、跑分与报告；test_metrics 覆盖了报告读取、KPI 与报告数值一致、接口结构等。

那如何手工走通呢（前后端一条链路）

① 将 docs/ 目录下的内容导入知识库
② python -m src.eval.cli --validate
③ python -m src.eval.cli
④ 启动服务然后打开「指标看板」
⑤ 核对 KPI 与 kb_store/eval/latest.json 的 summary 是否一致
⑥ 再跑第二次评测然后刷新，历史就多了一条、趋势线的变化
⑦ 导出 CSV 格式文档字段与列表是一致的
⑧ 删除 latest.json 文件后刷新页面这时会是空态 + 跑分提示

调试看板整形层

from pathlib import Path
from src.metrics.dashboard import build_dashboard

print(build_dashboard(report_dir=Path("kb_store/eval")))

关于维基框架

维基本地知识库 是一个本地优先的开源知识库系统，融合向量检索、重排与对话式问答，支持多种主流大模型 API，具备高性能本地存储与灵活扩展能力，适合智能问答、知识管理、企业知识中台等场景。MulanPSL2 许可证，欢迎共建！

• 官网：framewiki.com

Gitee：https://gitee.com/cdkjframework/knowledge-base

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