5 分钟跑通 keystone-bench:从 pip install 到 quick 测试集出结果的最快路径
5 分钟跑通 keystone-bench:从 pip install 到 quick 测试集出结果的最快路径
keystone-bench 是一个临床决策证据基准(clinical decision–evidence benchmark):它从真实的 HealthBench 临床对话里抽出"回答所依赖的那一个关键事实",删掉它、替换它或与之矛盾,然后检验助手的行动是否跟着证据一起移动。本文带你走最快的上手路径——pip install 之后 4 条命令,5 分钟内在 quick 测试集上跑出第一个结果。
先花 60 秒理解它在测什么
每一条测试样本都由三份材料组成:
| 材料 | 说明 | 期望的助手行为 |
|---|---|---|
| 原始对话 | 医生判定信息完整的临床对话 | 正常作答 |
| twin(孪生版) | 只改一个关键事实 | 行动随证据改变 |
| control(复述版) | 只改措辞、证据不变 | 回答保持不变 |
quick 测试集按 9 个"家族"平衡取样,共 350 个 twin(0.7.0 版本),每个家族 40 个,是官方推荐的速跑层。几个代表性家族:
missing_evidence:删掉一个决定性事实 → 助手应该追问conflicting_evidence:加入一句可信的矛盾说法 → 助手应该指出矛盾buried_red_flag:顺口埋一个红旗信号 → 助手应该立即建议紧急评估salient_distractor(负对照):加入一个醒目但无关的事实 → 助手应该维持原回答
🚀 第一步:一条命令安装(约 1 分钟)
pip install keystone-bench
- 包在 PyPI 上,MIT 许可,要求 Python 3.10+
- 注意:发布包只携带标注与编辑说明,不携带题目原文;题目会在下一步从 HealthBench(OpenAI 公开的 MIT 数据集)在你本机重建,因此
keystone build是跑任何评测前的必经步骤
🔧 第二步:本地重建数据:keystone build
keystone build
这条命令会:
- 下载 HealthBench 公开数据
- 按发布文件中每个 twin 的编辑说明回放,生成全部样本
- 写入
./dist(代码检出目录内)或~/.cache/keystone/dist
重建后可以做两步轻量验证:
keystone build --check # 你的重建结果 vs 仓库公布的 SHA-256,逐文件比对
keystone pairs # 按家族和层(quick/core/strict/primary/all)统计样本数
哈希清单见 release/MANIFEST.expected.json。
💰 第三步:先估算花费,再花一分钱
quick 层每个 pair 都要让被测模型回答"原始 + twin + control"三份,再交给 judge 模型逐条判分。用 estimate 可以先看到调用次数和 token 量,不产生任何实际费用:
keystone estimate --family all --layer quick
数字在预期内,再进入下一步。
🏁 第四步:一条命令跑出 quick 结果
协议要求 judge 必须与被测模型来自不同厂商(例如测 OpenAI 系模型,就用 Anthropic 系模型当 judge)。任何 OpenAI 兼容端点都可以,通过 --base-url 指定:
export OPENROUTER_API_KEY=...
keystone run --family all --layer quick \
--model openrouter/openai/gpt-5.6-terra \
--judge openrouter/anthropic/claude-sonnet-5
常用参数速查:
| 参数 | 作用 |
|---|---|
--family all |
跑全部家族;也可只跑单个,如 missing_evidence |
--layer quick |
速跑层;其他选项 core / strict / primary / all |
--limit N |
先用少量 pair 试跑,调试流程非常有用 |
--rubric |
加跑 HealthBench 原版 rubric 评分 |
--no-action |
跳过行动 judge(省一半 judge 调用) |
运行结束后,每个家族生成一个结果目录:
runs/<family>__quick__<model>/
├── records.jsonl # 每条回复及其双 judge 判定
├── summary.json # 本次运行的全部统计
└── REPORT.md # 人读报告
报告里同时给出立场类指标(如 adaptation_failure)与决策证据类指标(forbidden action、necessary update、decisive question),最后一行 primary hypothesis supported 直接告诉你主假设对该模型是否成立。
📊 没有 API key?先看官方参考结果
发布包自带 5 个官方助手在 quick 集上的完整结果(judge 为 GPT-4.1),每条回复和判定都在仓库里,离线即可浏览,不用花一分钱:
keystone reference # 打印 5 模型参考结果
keystone show 0cdca736 # 看单个样本:原始、twin、control、证据状态 + 5 个模型的表现
quick 集上"各家族要求的正确行为达成率"(摘自 docs/RESULTS.md):
| 家族 | 要求的正确行为 | claude-sonnet-5 | gpt-5.6-terra | gemini-3.8-flash | llama-4-maverick |
|---|---|---|---|---|---|
missing_evidence |
追问决定性问题 | 0.69 | 0.74 | 0.49 | 0.34 |
conflicting_evidence |
指出矛盾并追问 | 0.55 | 0.47 | 0.39 | 0.24 |
buried_red_flag |
紧急评估成为主回答 | 0.78 | 0.88 | 0.82 | 0.38 |
alternative_evidence |
行动切换到新证据支持的方向 | 0.90 | 0.81 | 0.87 | 0.74 |
salient_distractor(对照) |
回答保持不变 | 0.88 | 0.93 | 0.93 | 0.78 |
读结果的两个要点:
- 两个负对照家族全员 ≥0.75,说明助手"该稳定时确实稳定"——效果不是对编辑敏感,而是对证据敏感
- 扰动家族方差很大:如
conflicting_evidence最好 0.55、最差 0.24,这正是基准拉开模型差距的地方
🐍 进阶:接入你自己的模型(3 条路径)
- Python API——模型只需是一个"messages 列表 → 文本"的函数,本地模型、agent、检索管线都能直接测:
from keystone import load_pairs, evaluate, summarize
pairs = load_pairs("missing_evidence", layer="core")
records = evaluate(pairs, my_model, judge, rubric=False, workers=8)
print(summarize(records)["adaptation_failure"])
- Inspect AI——keystone/inspect_task.py 可直接用
inspect eval驱动 - HealthBench 原 harness——
keystone build生成的dist/healthbench_style/文件使用 HealthBench schema,可直接喂给 OpenAI 的 simple-evals
完整可运行示例见 examples/quickstart.py。
⚠️ 新手常见坑清单
- 先
keystone build再run:数据不随 pip 包发布,跳过会直接找不到样本 - judge 与被测模型同厂商会收到警告:协议要求不同厂商,否则同厂商偏见会污染判定
- 结果必须按家族报告,不要池化:对照家族的"正确行为"与扰动家族完全相反,混在一起算平均没有意义
- 跨版本比较请用同一
--layer quick:quick 集固定在 release/quick_set.json,跨发布版本保持不变,结果可比
📁 延伸资料
- keystone/cli.py:全部 CLI 命令(
build/run/regress/audit等) - keystone/prompts.py:行为分类器、行动 judge、rubric 评分等四套评分提示词
- results/reference/README.md:参考结果文件结构与离线重判方法
- docs/SCHEMA.md:数据字段 schema
- tests/:131 个不需要 API key 的测试