seekdb 检索评测助手

把“搜索看起来更好了”转成可复现的证据。对同一组查询和文档标注，比较全文检索、向量检索或混合检索的排序质量，找出需要回看的查询，并生成 JSON 和 Markdown 报告。

输入与适用范围

需要 Python 3.9+，只使用标准库；脚本离线运行，不连接数据库或模型服务。
输入是用户提供的 JSONL 相关性标注 qrels.jsonl 和一个或多个按排名排列的运行结果。字段见 references/data-format.md。
每个结果必须来自实际检索。缺少标注时，先帮助整理待标注样本；可以展示包内合成示例，但不能把示例得分称为用户系统的性能。
若用户需要在 seekdb 中执行检索，先读取其数据库版本、表结构、索引和现有查询，再依据该版本文档编写 SQL。本技能不假设任何版本通用的全文或向量 SQL 语法。

工作步骤

确认比较目标、k、查询集与标注覆盖。默认 k=10。保留完全相同的文档 ID、过滤条件、语料快照和相关性口径；不同实验若改变了 embedding、分词或过滤条件，应在结论中说明。
将标注和有序结果转成约定格式，不根据待比较系统的结果伪造相关性。每个查询对应一个记录；即使无命中，也保留 doc_ids: []。
从技能目录运行以下命令。实际工作使用用户授权的文件路径，将输出写入工作目录。

python3 scripts/evaluate.py \
  --qrels /path/to/qrels.jsonl \
  --run baseline=/path/to/fulltext.jsonl \
  --run candidate=/path/to/hybrid.jsonl \
  --k 10 \
  --output-json /path/to/report.json \
  --output-md /path/to/report.md

--run 可重复，第一项作为比较基线。脚本会拒绝重复查询、重复文档 ID、未知查询和非法数值。先按错误信息修复输入，再重新评测；不要为了让分数好看而删除失败查询。

优先检查报告中的覆盖率、缺失查询、未标注文档数量和无正例查询，再解释均值。对退步最多的查询回看前 k 个结果与标注，区分：漏召回、排序变化、过滤范围变化、标注不足。
给出有边界的建议：哪种方案在这组标注上改善了什么，哪些查询退步，下一步需要补哪些实验。均值增加不等于统计显著，也不证明生成答案更准确。需要显著性推断时，另行设计与查询采样方式匹配的统计分析。

指标与缺失值口径

| 指标 | 本技能的定义 | | --- | --- | | Precision@k | 前 k 个结果中相关文档数 / k；不足 k 条的空位视为未命中 | | Recall@k | 前 k 个结果中相关文档数 / 该查询全部已标注正例数 | | MRR@k | 每个查询第一个相关结果排名的倒数，再对查询取均值；前 k 条无正例为 0 | | nDCG@k | DCG 使用 (2^grade - 1) / log2(rank + 1)；IDCG 由该查询全部标注按 grade 降序取前 k 条得到 | | p50 / p95 | 有限且非负的可用 latency_ms 样本，使用 nearest-rank 百分位 |

grade 为 0–4 的整数，grade > 0 为相关；未标注文档按 0 计算，并在报告显式计数。这是在不完整标注下的评测约定，不等于认定它们确实无关。
以 qrels 中的全部查询作为固定评测集合。运行中缺少的查询按空结果计算，不会悄悄取两个运行的交集。
全部标注均为 0 的查询没有可用正例，四个质量指标记为 null，不纳入质量宏平均；单独报告数量。若全部查询都无正例，不作排序质量优劣结论。
延迟缺失记为不可用，绝不补成 0。报告延迟样本数；缺少相同硬件、并发、预热与测量范围时，不将其解释为公平的系统性能比较。
所有质量宏平均都对相同的“含已标注正例查询”取算术平均。比较表中的差值为 candidate − baseline。

立即试用

以下是人工构造的微型教学数据，不是 seekdb 性能测试：

python3 scripts/evaluate.py \
  --qrels assets/example/qrels.jsonl \
  --run fulltext=assets/example/fulltext.jsonl \
  --run hybrid=assets/example/hybrid.jsonl \
  --k 3 --output-json /tmp/retrieval-report.json \
  --output-md /tmp/retrieval-report.md
python3 -m unittest discover -s scripts -p 'test_*.py' -v

这个例子包含一个混合检索的缺失查询，故不会只靠删掉失败查询就获得虚假的提升。

交付

给用户报告链接和最关键的比较结果：标注版本与 k、有效查询数、四个质量指标、延迟覆盖、退步查询及数据局限。引用实际脚本输出，不编造测试、吞吐或线上收益。JSON 保留逐查询结果，便于下一轮回归复查。