> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Gate 与 Verdict

Gate 与 Verdict 让 `runEvals` 能区分评估条件的严重程度。Gate 是必须获得 1.0 分的 Scorer，代表一旦未满足就会让运行失败的硬性要求。阈值是所跟踪指标可接受的最低分数。Verdict 会将结果汇总为 `passed`、`scored` 或 `failed`。

## 何时使用 Gate 与 Verdict

- 在 CI 中强制执行硬性要求（例如“Agent 必须调用正确的 Tool”）
- 使用最低阈值跟踪质量指标（例如“faithfulness 高于 0.7”）
- 无需编写自定义断言逻辑，即可从 Evals 运行中获取单一 Verdict 信号（`passed`、`scored` 或 `failed`）
- 将“必须通过”的 Gate 与“最好达到”的跟踪指标分开

## Quickstart

```typescript
import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'
import { weatherAgent } from '../agents'
import { faithfulnessScorer } from '../scorers'

const result = await runEvals({
  data: [{ input: 'What is the weather in Brooklyn?' }],
  target: weatherAgent,

  // Gates: must all score 1.0 or the run fails
  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],

  // Scorers: tracked with optional thresholds
  scorers: [
    { scorer: faithfulnessScorer, threshold: 0.7 },
    checks.includes('Brooklyn'), // no threshold = tracked only
  ],
})

console.log(result.verdict) // 'passed' | 'scored' | 'failed'
```

## Verdict 的工作原理

处理完所有数据项目后，会根据 Gate 和阈值计算 Verdict：

- `failed`：至少有一个 Gate 在所有数据项目上的平均分低于 1.0
- `scored`：所有 Gate 均已通过，但至少有一个带阈值的 Scorer 未达到阈值
- `passed`：所有 Gate 均获得 1.0 分，并且所有阈值均已达到

如果未提供 Gate 或带阈值的 Scorer，Verdict 字段将省略，`runEvals` 的行为与之前完全相同。

## Gate

Gate 是通过 `gates` 字段传入的 Scorer。它们会在每个数据项目的常规 Scorer 之前运行。要通过 Gate，其在所有数据项目上的平均分必须达到 1.0。

```typescript
import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'

const result = await runEvals({
  data: [{ input: 'What is the weather?' }],
  target: weatherAgent,
  gates: [checks.calledTool('get_weather')],
  scorers: [qualityScorer],
})

// result.gateResults: [{ id: 'check-called-tool', passed: true, score: 1 }]
```

任何 Scorer 都可用作 Gate。Quick Checks 很适合此场景，因为它们返回二元的 1/0 分数。有关完整的参数和返回类型文档，请访问 [runEvals() Reference](https://mastra.zisheng.pro/reference/evals/run-evals)。

### 仅使用 Gate 的运行

如果至少提供了一个 Gate，`scorers` 就是可选的。这适用于只关心通过/失败 Gate、无需跟踪任何质量指标的确定性 CI 检查。

```typescript
import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'

const result = await runEvals({
  data: [{ input: 'What is the weather in Brooklyn?' }],
  target: weatherAgent,
  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
})
```

必须提供至少一个 Scorer 或 Gate；两者均未提供时，运行会抛出错误。

## 阈值

将 Scorer 包装在 `{ scorer, threshold }` 中，可以设置通过/失败边界。阈值会与该 Scorer 在所有数据项目上的平均分进行比较。

`threshold` 可以是：

- **数值**：表示下限（分数达到或超过该值即通过）：`{ scorer, threshold: 0.7 }`
- **包含 `min` 和/或 `max` 的对象**：用于基于范围的检查：`{ scorer, threshold: { max: 0.3 } }`

对于高分代表不良结果的 Scorer（例如幻觉、毒性），请使用 `max`。当分数应处于特定范围内时，请使用 `{ min, max }`。

```typescript
import { runEvals } from '@mastra/core/evals'

const result = await runEvals({
  data: [{ input: 'Explain quantum computing' }],
  target: myAgent,
  scorers: [
    { scorer: faithfulnessScorer, threshold: 0.7 }, // min threshold (number shorthand)
    { scorer: hallucinationScorer, threshold: { max: 0.3 } }, // max threshold — high score = bad
    { scorer: verbosityScorer, threshold: { min: 0.3, max: 0.8 } }, // range threshold
    toneScorer, // bare scorer, no threshold — tracked only
  ],
})

// result.thresholdResults:
// [
//   { id: 'faithfulness', passed: true, averageScore: 0.85, threshold: 0.7 },
//   { id: 'hallucination', passed: true, averageScore: 0.1, threshold: { max: 0.3 } },
//   { id: 'verbosity', passed: false, averageScore: 0.9, threshold: { min: 0.3, max: 0.8 } },
// ]
```

不带阈值的裸 Scorer 仍会出现在 `result.scores` 中，但不会影响 Verdict。

## 在 CI 中使用 Verdict

Verdict 为 CI Pipeline 提供一个信号：

```typescript
import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'

const result = await runEvals({
  data: testDataset,
  target: myAgent,
  gates: [checks.calledTool('search'), checks.noToolErrors()],
  scorers: [{ scorer: faithfulnessScorer, threshold: 0.7 }],
})

if (result.verdict === 'failed') {
  console.error(
    'Gate failures:',
    result.gateResults?.filter(g => !g.passed),
  )
  process.exit(1)
}

if (result.verdict === 'scored') {
  console.warn(
    'Threshold misses:',
    result.thresholdResults?.filter(t => !t.passed),
  )
}
```

## 相关内容

- [Quick Checks](https://mastra.zisheng.pro/docs/evals/quick-checks)：无需 LLM 且非常适合用作 Gate 的微型 Scorer
- [runEvals() Reference](https://mastra.zisheng.pro/reference/evals/run-evals)：完整 API 文档
- [内置 Scorer](https://mastra.zisheng.pro/docs/evals/built-in-scorers)：基于 LLM 和代码的 Scorer
- [在 CI 中运行 Evals](https://mastra.zisheng.pro/docs/evals/running-in-ci)：CI 集成模式