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"))) 关于维基框架 维基本地知识库 是一个本地优先的开源知识库系统，融合向量检索、重排与对话式问答，支持多种主流大模型 API，具备高性能本地存储与灵活扩展能力，适合智能问答、知识管理、企业知识中台等场景。MulanPSL2 许可证，欢迎共建！ 官网：framewiki.com Gitee：https://gitee.com/cdkjframework/knowledge-base 📄 许可证：MulanPSL-2.0（木兰宽松许可证，第 2 版）