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

# 实验矩阵：用运行矩阵比较 agents 和 models

> 使用 NiceEval experiments 让同一批评估用例横跨多个 agents、models 和 flags，比较 pass rate、成本和延迟。

Experiment 用于比较多组运行配置。典型比较包括 Claude Code 与 Codex 在同一批 Coding Agent 任务上的通过率、prompt 改动前后的成本，以及不同模型的延迟与质量。

## 基本形状

**一个实验文件 = 一个配置**（一个 agent × 一个 model）。路径只生成 experiment id 和支持前缀选择：

```text theme={null}
experiments/
  models/openai/gpt-5.4.ts
  models/deepseek/v4-pro.ts
```

```ts theme={null}
// experiments/models/openai/gpt-5.4.ts
import { defineExperiment } from "niceeval";
import { webAgent } from "../../adapter/adapter.ts";

export default defineExperiment({
  description: "gpt-5.4: 对比模型",
  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
  model: "gpt-5.4",   // 单个字符串;另一个模型就复制一份文件改这一行
  runs: 2,
  earlyExit: true,
});
```

```bash theme={null}
npx niceeval exp models
```

另一个模型写另一个文件。默认 `show` / `view` 直接比较当前结果范围里的 experiments，不需要额外分组字段。

多层目录只负责 id 和批量选择：

某一格结果反常、需要单独复现时，用该配置的完整 id（`目录路径/文件名`）精确只跑这一格，不用先批量运行同目录配置：

```bash theme={null}
npx niceeval exp models/openai/gpt-5.4   # 精确 id
npx niceeval exp models/openai           # 这一层目录下全部 experiment
```

目录里如果还有 `gpt-5.4-mini.ts` 这类共享前缀的变体，可以用文件名前缀选择：

```bash theme={null}
npx niceeval exp models/openai/gpt
```

`defineExperiment` 的字段配置与 `flags` 传递方式见[写实验](/docs/zh/tutorials/write-experiment)。

## 可比较的运行维度

* 不同 Adapters。
* 不同模型（Tier 1 接入即可：应用接口暴露模型选择，`model` 经 `ctx.model` 透传）。
* 不同 prompts 或 feature flags（要求 Tier 3 接入：变体在应用内部，需要应用把它暴露成 experiment 可选的 flag，经 `flags` → `ctx.flags` 透传）。
* 不同 sandbox provider。
* 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` Hook 里，一个变体一个 experiment 文件，见 [Sandbox provider · 生命周期](/docs/zh/tutorials/sandbox-providers#生命周期)。
* 同一任务的 pass\@N。

Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/docs/zh/explanation/tier)。

## 查看结果

Experiment 输出通常按 `(agent, model, eval)` 维度展示：

```text theme={null}
api-validation   claude-code+zod-skill   pass@3 = 3/3 (100%)   mean 34s
api-validation   claude-code             pass@3 = 1/3 (33%)    mean 41s
```

除了 pass rate，还应该看平均耗时、token、成本和失败类型。

```bash theme={null}
npx niceeval show --exp models
npx niceeval view
```

每个 experiment 用自己的 `evals` 选择评估用例。函数形式会遍历所有已发现的评估用例：

```ts theme={null}
evals: (eval) =>
  eval.id.startsWith("coding/") &&
  eval.tags.includes("coding") &&
  eval.environment !== "gpu"
```

`eval.id` 是文件路径推导出的项目内 ID，不是绝对路径，可以直接用 `startsWith` / `includes` 判断。在[评估用例](/docs/zh/tutorials/authoring#tags-与-environment)里的两个例子中，`coding/fix-button` 会被选中，`research/gpu-literature` 不会。实验快照记录解析后的 `selectedEvalIds`；报告直接读取它。

## 设计 experiment 的建议

* 保持评估用例集合稳定，避免比较时混入新变量。
* 每个 cell 跑多个 attempts，尤其是非确定性 coding agent。
* 把预算和并发写清楚。
* 对“失败原因”做归类，不只看总分。

## 与普通运行的关系

`npx niceeval exp <路径或 id>` 按文件身份运行；每个文件的 `evals` 决定它覆盖哪些评估用例，结果以 `selectedEvalIds` 落盘。