WIKI 知识库 v1.1.1 正式发布

这个功能有什么作用

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

命令行跑评测 （python -m src.eval.cli）：用固定内容逐题调用检索，算出 Recall、NDCG、延迟等，结果写入文件 kb_store/eval/latest.json。
控制台指标看板：打开页面时读取上面的文件，把里面的数字展示成 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

标题	目录路径	说明
内容	`conf/eval/golden-default.jsonl`	固定配置「问法 → 应命中文档」
跑分	`src/eval/`	调检索、算指标、写报告等等
报告	`kb_store/eval/latest.json`	跑评测后生成的结果文件，看板展示的就是读它
看板 API	`src/metrics/` + `handlers/metrics.py`	读取报告、对照验收线、给出 JSON对象
看板页面	`frontend/src/views/metrics/MetricsDashboard.vue`	KPI 卡片、历史、趋势、CSV等

如何使用

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"

接口	说明
`GET /api/metrics`	KPI + 最近报告 + 历史（看板用这个）
`GET /api/metrics/reports`	仅历史列表

默认验收线：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")))