教程：可复现的基准测试运行

如何通过官方 QitOS 基准测试路径运行 GAIA、Tau-Bench 或 CyBench，并检查产出的产物。

这节课的目标不是先拿一个分数，而是产出一个真正可以回放、差异对比、导出的官方 QitOS 基准测试运行。

​

你会学到什么

• 为什么 qit bench 是基准测试官方入口
• RunSpec 与 ExperimentSpec 如何自动附着到运行上
• 一次基准测试运行结束后应该留下哪些文件
• 如何用 qita 继续做回放、导出、对比

​

第一步：选择基准测试

如果只是先熟悉流程，可以从 Tau-Bench 开始：

qit bench run \
  --benchmark tau-bench \
  --split test \
  --subset retail \
  --limit 2 \
  --output ./results/tau_retail_test.jsonl \
  --model-name "Qwen/Qwen3-8B"

如果你希望接入真实执行逻辑，而不是默认的空策略，可以通过 --runner 指向基准测试封装器或自定义运行器回调。

​

第二步：理解统一结果结构

输出文件中的每一行都遵循 BenchmarkRunResult。你应该能看到：

• task_id
• benchmark
• split
• prediction
• success
• stop_reason
• steps
• latency_seconds
• token_usage
• cost
• trace_run_dir
• run_spec_ref

这也是跨基准测试统一聚合的基础。

​

第三步：聚合指标

qit bench eval --input ./results/tau_retail_test.jsonl --json

这会基于统一结果行输出标准摘要，而不是让每个基准测试各自定义一套报告接口。

​

第四步：检查追踪记录

如果运行同时生成了追踪记录目录，就继续用 qita：

qit bench replay --run ./runs/<run_id>
qit bench export --run ./runs/<run_id> --html ./reports/run.html

或者打开整个面板：

qita board --logdir ./runs

​

第五步：确认它是不是官方运行

打开 manifest.json 或 qita 的运行概览，确认这些字段存在：

• run_spec
• experiment_spec
• official_run
• git_sha
• package_version
• prompt_protocol
• parser_name
• tool_manifest

如果缺失这些字段，追踪记录依然可能有用，但还没有达到官方运行契约。

​

什么时候还应该使用示例

当你需要：

• 基准测试特定的智能体构造方式
• 一篇论文风格的参考实现
• 官方运行器之上的薄包装演示

可以继续使用 examples/benchmarks。但不要把它们理解成另一套基准测试框架；在 v0.3 中，它们只是官方路径上的封装器。

​

下一步

继续阅读 回放并检查失败运行。