跳转至

尚无译文的页面会以英语打开,并标注为英语。

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

添加基准测试用例、数据集或套件

已提交的数据集规模较小(数据集规模),因此新增用例是改进套件成本最低的方式。请先阅读文件头部或 _comment:大多数文件都说明了其标准答案(gold)是如何构建的,以及新增的行必须满足哪些条件。

向现有集合添加用例

记忆 QA(bench/datasets/synthetic_memory_qa.json)

向某段对话追加一个问题,或追加一段对话:

{
  "conversation_id": "06-billing",
  "conversation": [{ "role": "user", "content": "Our invoices go out on the 3rd of each month." }],
  "questions": [{ "question": "When do invoices go out?", "gold_keys": ["invoice", "3rd"] }]
}

只要返回的 memory_key 或摘录中包含某个 gold 字符串(忽略大小写,下划线视为空格),即算命中。请选择正确的记忆必然包含、而错误的记忆不太可能包含的 gold 词。保持内容为合成数据:不使用第三方文本,不涉及真实人物。

它会改变基线。 0.80 的门限阈值是基于此文件记录的。请在真实部署上于改动前后各运行一次门限检查,如果数值发生变化,则更新 Makefile 中的 MIN_RECALL。测试:tests/unit/test_bench_quality_gate.py、bench/test_quality.py。

提取与图回归

  • bench/fixtures/extraction_regressions.json 的每一行形如 {id, messages, expected}:expected 是必须出现在某条记忆的 key 或 value 中的短语。
  • graph_regressions.json 的每一行形如 {id, messages, expected_triples: [{subject, relation, object}], as_of}。
  • _note 字段用于说明失败类别,测试框架会忽略它。

tests/unit/test_algorithm_gate_assets.py 会检查每一行都有 messages 以及非空的期望值。请针对真实的提取 LLM 运行 make bench-algorithm-gate,以确认该用例通过。

代码平面 QA(bench/fixtures/code_intel_qa*.jsonl)

每行一个 JSON 对象;以 // 开头的行为注释:

{"id": "co037", "type": "conceptual", "query": "where are part merges scheduled", "gold": {"paths": ["src/Storages/MergeTree/MergeTreeBackgroundExecutor"]}}
{"id": "sd011", "type": "symbol_def", "query": "IColumn::insert", "gold": {"qualified_name": "DB::IColumn::insert", "path_prefix": "src/Columns/"}}
{"id": "ab011", "type": "abstain_probe", "query": "kubernetes ingress annotation for sticky sessions", "gold": {}}

各类型的 gold 格式见 bench/code_intel_qa.py 的 docstring(callers 使用 expected_callers,hub 使用 path_prefix 和 symbols)。路径是不含扩展名的前缀。可选的 lane、facets 和 namespace 用于对该行进行路由和切片。

  • 在 gold 作为门限之前,先对照在线索引验证它:先不设下限运行一次,查看不匹配项,再修正 gold。
  • abstain probe 必须针对仓库中不存在的代码。
  • 保持主文件的类型集合不变。 bench/test_code_intel_qa.py(test_fixture_loads_and_validates)断言 code_intel_qa.jsonl 至少有 30 行,且类型恰好为 symbol_def、callers、conceptual、abstain_probe。hub、history 和 test-set 的行放入各自的 lane 文件。
  • make bench-code-intel-dry 必须仍然通过:在完美的合成检索下,每个 lane 都能达到其上限分数。
  • 挖掘得到的 lane 应重新生成,而不是手工编辑:code_intel_mine_prs.py 和 code_intel_ka_slice.py 会写入文件及其头部计数。

编码 agent 经验教训(bench/fixtures/coding_agent_qa.json)

向 lessons(以 memory_key 为键的记忆行)和 questions(question、取自分类体系的 question_type、gold_keys,以及可选的 fix_reuse)中追加内容。每个 gold key 都必须对应一个真实存在的 lesson key,否则 bench/test_coding_agent_qa.py(test_load_corpus_rejects_dangling_gold_key)会失败。--dry 必须仍然通过。

Op 规划任务(bench/fixtures/op_planning_tasks.jsonl)

每个任务包含 id、class(instruction_type、structure)、prompt、一个 gold 计划(工具、必需参数、字面参数)以及存储 assertions。当某个 gold 工具或参数在 MCP 接口上不再存在时,tests/unit/test_op_planning_bench.py(test_every_gold_tool_and_required_arg_exists_on_the_surface)会失败。其 op 已被废弃的任务应移入 op_planning_tasks_retired.jsonl,而不是直接删除。

Skill-eval 任务

bench/skill_eval/tasks/ 下的任务说明带有 front matter(task、namespace、agent、traps),正文中指明一个 skill-eval-… 命名空间,并在结尾说明该命名空间将被审计。相同的正文也是 integrations/claude-code-plugin/evals/loom-memory/<task>/prompt.md 处的一个 claude plugin eval 用例,除 front matter 外逐字节相同。tests/unit/test_skill_eval.py 会检查这三条规则并固定任务列表,因此新增任务时也要更新该测试。参见 技能评测。

接入新数据集

  1. 不要提交数据集。 将其放在 bench/datasets/ 下,或提供路径参数。如果数据集需要下载,请添加 --fetch 路径,或在文件缺失时打印下载命令,如 longmemeval.py 所做的那样。
  2. 在 harness 的 docstring 中记录来源: 出处、文件名、条目数量以及数据集声明的许可证。在 数据集 中添加一行。
  3. 保留数据集自身的类别作为一列,如果已发布的表格使用了可比较的子集,请标明该子集。
  4. 公开基准测试的名称可以出现在 bench/ 中,但绝不能在 server/ 下的文字说明里作为做出某项选择的理由(见 tests/unit/test_public_copy.py BENCHMARK_NAMES)。
  5. 使用 LOOM_NAMESPACE_BENCH_PREFIXES 中的前缀创建临时命名空间(server/settings/catalog.py;新的 harness 使用 bench-),这样 loom namespaces-gc 和命名空间 GC 就能找到中止的运行所遗留的内容。

编写新的 harness

每个 harness 都遵循以下结构:

规则 做法
独立脚本 使用 argparse,提供 --base-url、--token(默认取 LOOM_API_KEY)、--out;既可以用 PYTHONPATH=$PWD python bench/<name>.py 运行,也可以作为模块运行
共享的 HTTP 策略 通过 bench/_http.py(post_json / apost_json)发送请求:Bearer 令牌、遇到 429 时等待、有限次数的 5xx 重试、错误信息中带有响应体
文档字符串就是手册 说明它测量什么、不测量什么、数据集、成本,以及一条运行命令
纯粹的评分核心 评分函数放在实际运行路径之前,无需服务器即可导入,并带有单元测试(bench/test_<name>.py 或 tests/unit/test_bench_<name>.py)
--dry 或自检模式 在合成输入上运行评分器,不需要服务器,也没有花费
评估读取 先把 bench/_gate.py 中的 measurement_fields("memory.search") / ("memory.ask") 合并到请求体中;提供 --credit
一次性、已登记的命名空间 在第一次写入之前调用 register_bench_namespace + remember_bench_namespace,把工作放在 erase_on_exit 内,并提供 --keep-namespaces 标志(bench/bench_namespaces.py)
固定范围 读取时发送 namespace_scope: "this"
需要评判?使用共享的 gate 用 add_gate_arguments(parser) 添加 --repeats、--gate*、--credit、--judge-calibration;用 gate_from_args 得出结论;固定 reader 和 judge 模型,并在被覆盖时给出警告。tests/unit/test_bench_gate_help_renders.py 说明了为什么帮助文本中单独的 % 会破坏 --help
记录测量所用的工具 在数字旁记录 embedder、LLM、provider,以及来自 /v1/health 的 build_commit(参见 quality.py 的 run_metadata)
将失败与未命中分开报告 统计并打印请求错误;不要把它们按未命中计分
配对比较 通过带聚类键的 paired_bootstrap 计算逐项差值;以下界作为发布依据

然后:

  • 在 bench/README.md 的相应部分添加一条列表项;如果它回答的是常见问题,还要在其“When to run what”表中加一行;
  • 只为有人会例行运行的 gate 添加 Makefile 目标,并把它的下限设为可覆盖的变量;
  • 运行 make format(ruff 会格式化 bench/)、pytest bench -q 以及文案检查:
.venv/bin/python -m pytest tests/unit/test_public_copy.py tests/unit/test_bench_namespaces.py -q

文案检查会扫描 bench/:代码、注释或测试数据中不得出现产品名称、人名、内部主机或命名空间、论文引用或决策记录引用。

相关内容

  • 方法论:门禁和 bootstrap 的计算方式。
  • 运行:命令和输出。
  • 测试:单元测试和集成测试套件。