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

# 实验（Experiment）：评谁、怎么跑

> Experiment 是可签入的运行配置：同一批评估用例对着哪个 agent、哪个模型、开哪些 flags、跑几次。评估用例与 experiment 分开的原因——晚绑定，让同一份评估用例换着对象跑。

**experiment** 对着哪个 agent、用哪个模型、开哪些 flags、跑几次。用于做 AB 测试、模型对比、feature 对比——`flags` 就是 A/B 测试里的 feature flag，一个 experiment 是一组 flag 取值。

## 一个 experiment 里有什么

experiment 是 `experiments/` 下可签入的 TypeScript 文件，核心就几个字段：

```ts theme={null}
// experiments/concise.ts
export default defineExperiment({
  description: "简洁 prompt 变体",
  agent: webAgent({ baseUrl: "https://staging.example.com" }),  // 已配置好的 agent 实例
  model: "gpt-5.4",                    // 经 ctx.model 透传给 Adapter
  flags: { promptVariant: "concise" },  // 经 ctx.flags 透传;eval 里是 t.flags
  runs: 3,                             // 每条 eval 跑几次(对抗随机性)
});
```

* `agent`：评谁。放的是已经配置好的实例——被测系统的 URL、鉴权传给 Adapter 工厂，不进 experiment 的其它字段。
* `model` / `flags`：透传语义。[NiceEval](https://niceeval.com/) 不解释它们的含义，原样经 `ctx` 递给 Adapter，由 Adapter 随请求转发、应用按需切换——这正是 [Tier](/docs/zh/explanation/tier) 里模型对比（Tier 1）和 feature A/B（Tier 3）的通道。
* `runs`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[写实验](/docs/zh/tutorials/write-experiment)。

Experiment 还有一对实验级 Hook `setup` / `teardown`：整个实验只跑一次，在你自己的机器上执行，用来起停所有 Attempt 共享的服务（比如一条到内网服务的隧道、一个实验专用的 mock server）——`setup` 在本实验第一个 Attempt 派发前执行，`teardown` 在全部 Attempt 收尾后执行（中断也执行），当且仅当 `setup` 的时点已经走到才触发。要按实验在 Sandbox 里准备环境（装二进制、预热、跨 attempt 存取状态），则挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`。两者的边界与写法见[写实验 · 启动 Experiment 共享服务](/docs/zh/tutorials/write-experiment#启动-experiment-共享服务)与[Sandbox provider · 生命周期](/docs/zh/tutorials/sandbox-providers#生命周期)。

同一实验里的评估用例需要不同预制环境时，评估用例只声明 provider-neutral 的 `environment` profile；sandbox spec 的 `environments` 表再把 profile 映射到 Docker image、E2B template 或 Vercel Sandbox snapshot。这样任务需求留在评估用例，provider 产物留在 spec，一个实验仍覆盖全部评估用例、对比不拆分。写法见[写实验 · 让不同评估用例使用不同预制环境](/docs/zh/tutorials/write-experiment#让不同评估用例使用不同预制环境)。

## 矩阵对比

要比较的每个变体写一个 experiment 文件：两个模型就是两个文件，只差 `model` 一行；prompt A/B 就是只差一个参数。同一批 eval 在多个 experiment 下各跑一遍，pass rate、成本、延迟就有了可比的横截面——`niceeval view` 里叠着看。适合比什么、结果怎么读，见[实验矩阵](/docs/zh/tutorials/experiments)。

## 相关阅读

* [写实验](/docs/zh/tutorials/write-experiment) — `defineExperiment` 的完整字段：runs、预算、并发与 sandbox。
* [实验矩阵](/docs/zh/tutorials/experiments) — 跨 agent / model / flags 的对比怎么组织、怎么读结果。
* [评估](/docs/zh/explanation/evals) — 另一半：评估用例是什么、生命周期与 verdict。
* [Tier](/docs/zh/explanation/tier) — `model` / `flags` 各在哪一档生效。