> ## 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.

# 基准测试与配方（recipe）

> 解释 QitOS 如何拆分框架能力、基准测试适配器与可复现配方基线。

# 基准测试与配方

QitOS 把三层明确分开。

## 1. 框架层

这是可复用的内核（kernel，执行内核）：

* `AgentModule + Engine`
* `DesktopEnv`
* `ActionSpace`
* `EnvironmentAdapter`
* 家族预设
* qita 回放与可视化检查

框架代码应保持与具体基准测试无关。

## 2. 基准测试层

这里放数据集专属适配：

* `qitos.benchmark.desktop`：入门基准测试家族
* `qitos.benchmark.osworld`：真实 OSWorld 适配器路径
* 基准测试专用运行时
* 基准测试专用评估器/评分器
* 基准测试原生任务元数据与产物（artifact，持久化的输出文件）处理

凡是 `test_all.json`、评估器桥接、setup/postconfig、qcow2 启动输入、基准测试原生评分这类内容，都应该放这里。

<Note>
  基准测试层是数据集适配器的**遗留接口**。新代码应直接使用配方（recipe）。基准测试运行器正在简化为调用配方的薄委托层。
</Note>

## 3. 配方层

配方是可复现基线方法的**规范位置**：

* 规范单智能体基线
* 基准测试基线方法
* 多模态入门方法

可用的基准测试配方：

| 配方       | 模块                                      | 说明           |
| -------- | --------------------------------------- | ------------ |
| GAIA     | `qitos.recipes.benchmarks.gaia`         | 搜索与文件工具的多步推理 |
| TauBench | `qitos.recipes.benchmarks.tau_bench`    | 航空/零售客服仿真    |
| CyBench  | `qitos.recipes.benchmarks.cybench`      | 网络安全 CTF 挑战  |
| CyberGym | `qitos.recipes.benchmarks.cybergym`     | 交互式网络安全训练环境  |
| Desktop  | `qitos.recipes.desktop.osworld_starter` | 桌面 UI 自动化    |

每个配方可附带 `qitos/recipes/benchmarks/eval_configs/` 目录下的 `eval_config.yaml` 文件，其中指定推荐默认值（模型、最大步数、最大 token 数、评分器）。

### 使用 eval\_config

```python theme={null}
import yaml
from pathlib import Path
from qitos.harness import resolve_builtin_preset

config_path = Path("qitos/recipes/benchmarks/eval_configs/gaia.yaml")
with open(config_path) as f:
    config = yaml.safe_load(f)

# 使用配置中的默认值
model = config["defaults"]["model"]
max_steps = config["defaults"]["max_steps"]

# 结合家族预设的推荐值
preset = resolve_builtin_preset(model)
```

## 为什么这个拆分重要

这个拆分解决了三个真实问题：

* 基准测试运行器不再依赖示例文件
* 同一个基线可以被示例、文档和基准测试运行器共同复用
* 未来独立 `qitos-recipes` 时，几乎只需要迁移打包边界，不需要重构设计

这也是以研究为先的框架应有的演进方式。

### W\&B 集成

在配方执行时将基准测试指标流式传输到 Weights & Biases：

```python theme={null}
from qitos.tracing import add_trace_processor
from qitos.tracing.wandb_processor import WandbTraceProcessor

processor = WandbTraceProcessor(
    project="qitos-benchmarks",
    tags=["gaia", "eval"],
)
add_trace_processor(processor)
```

完整文档参见 [W\&B 集成](/zh/guides/wandb-integration)。

如果你要新增基准测试家族，下一步请直接看[第三方基准测试接入规范](/zh/guides/third-party-benchmark-integration)。