> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

## 你会学到什么

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

## 第一步：选择基准测试

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

```bash theme={null}
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`

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

## 第三步：聚合指标

```bash theme={null}
qit bench eval --input ./results/tau_retail_test.jsonl --json
```

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

## 第四步：检查追踪记录

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

```bash theme={null}
qit bench replay --run ./runs/<run_id>
qit bench export --run ./runs/<run_id> --html ./reports/run.html
```

或者打开整个面板：

```bash theme={null}
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 中，它们只是官方路径上的封装器。

## 下一步

继续阅读 [回放并检查失败运行](/zh/tutorials/replay-and-inspect-failed-runs)。