keystone-bench

环境要求

• 有一定 Python 基础，能用 pip 安装 PyPI 包（README 未指定 Python 版本）
• 重建数据时需要能访问 OpenAI 公开的 HealthBench 数据
• 运行评测需要一个 OpenAI 兼容的 API 端点与密钥（README 示例用 OpenRouter）
• 判分模型必须和待测模型来自不同厂商

安装与启动步骤

1. 1安装评测库

   从 PyPI 安装 keystone-bench 包，同时装好 keystone 命令行工具；建议先建一个虚拟环境，避免依赖冲突。

   pip install keystone-bench

   复制

2. 2本地重建数据集

   拉取 OpenAI 公开的 HealthBench 和标签文件，并在本机重建评测数据：仓库目录下输出到 ./dist，否则写到 ~/.cache/keystone/dist。

   keystone build

   复制

3. 3校验重建结果

   把本机重建的文件和仓库发布的哈希逐文件比对，只要哈希不一致，就先不要开始评测。

   keystone build --check

   复制

4. 4查看数据构成

   列出发布集里每个 family 与 layer 的样本数量，可以据此只选需要的子集。

   keystone pairs

   复制

5. 5估算调用开销

   在产生评测费用之前，先估算需要的调用次数与 token 数量。

   keystone estimate --family all --rubric

   复制

6. 6配置模型密钥

   设置 OpenAI 兼容端点的密钥，README 示例用 OpenRouter；如果换成其他端点，请通过 --base-url 指定地址。

   export OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxx

   复制

7. 7运行基准评测

   先跑全家族 quick 层；待测模型与判分模型须来自不同厂商；结果写入 runs/<family>__<layer>__<model>/。

   keystone run --family all --layer quick --model openrouter/openai/gpt-5.6-terra --judge openrouter/anthropic/claude-sonnet-5

   复制

8. 8对比两次运行

   逐条比较两次运行的结果，查看新版本修复了哪些问题、又引入了哪些退化。

   keystone regress runs/v1 runs/v2

   复制

关键配置

如何确认成功

keystone build --check 逐文件哈希通过；跑完后在 runs/ 对应目录生成 records.jsonl、summary.json 与 REPORT.md。

常见问题

注意事项

• 先执行 keystone estimate 估算调用量，再正式跑评测，因为运行和判分都会产生调用费用。
• quick 层是均衡子集：每个 family 有 40 个 twins，控制组占 25%；层和 family 可按需替换。
• 不要只看合并后的总比率；summary.json 含 composition 与 by_family，REPORT.md 会打印分 family 表格。
• 每个回复会被分类两次（行为分类器 + 动作判分），加 --no-action 可跳过第二次。