5 分钟跑通 keystone-bench:从 pip install 到 quick 测试集出结果的最快路径

原创2026-10-25 11:40:491,603 阅读

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

这条命令会:

  1. 下载 HealthBench 公开数据
  2. 按发布文件中每个 twin 的编辑说明回放,生成全部样本
  3. 写入 ./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

读结果的两个要点:

  1. 两个负对照家族全员 ≥0.75,说明助手"该稳定时确实稳定"——效果不是对编辑敏感,而是对证据敏感
  2. 扰动家族方差很大:如 conflicting_evidence 最好 0.55、最差 0.24,这正是基准拉开模型差距的地方

🐍 进阶:接入你自己的模型(3 条路径)

  1. 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"])
  1. Inspect AI——keystone/inspect_task.py 可直接用 inspect eval 驱动
  2. 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-bench