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

# 閘門與判定結果

閘門與判定結果為 `runEvals` 加入嚴重程度語義。閘門是必須取得 1.0 分的評分器，屬於會阻止執行通過的硬性要求。閾值是所追蹤指標可接受的最低分數。判定結果會將執行結果總結為 `passed`、`scored` 或 `failed`。

## 何時使用閘門與判定結果

- 在 CI 中強制執行硬性要求（例如「Agent 必須調用正確的 Tool」）
- 使用最低閾值追蹤品質指標（例如「忠實度高於 0.7」）
- 無需編寫自訂斷言邏輯，即可從一次 eval 執行取得單一判定訊號（`passed`、`scored` 或 `failed`）
- 將「必須通過」的閘門與「最好達到」的追蹤指標分開

## 快速入門

```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'
```

## 判定結果的運作方式

處理所有資料項目後，系統會根據閘門及閾值計算判定結果：

- `failed`：至少一個閘門在所有資料項目中的平均分低於 1.0
- `scored`：所有閘門均已通過，但至少一個設有閾值的評分器未達其閾值
- `passed`：所有閘門均取得 1.0 分，且所有閾值均已達到

如果沒有提供閘門或設有閾值的評分器，判定結果欄位便會省略，而 `runEvals` 的行為會與以往完全相同。

## 閘門

閘門是透過 `gates` 欄位傳入的評分器。對於每個資料項目，閘門會在一般評分器之前執行。閘門在所有資料項目中的平均分必須為 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 }]
```

任何評分器都可用作閘門。Quick Checks 會傳回二元的 1/0 分數，因此非常適合此用途。請參閱 [runEvals() 參考文件](https://mastra.zisheng.pro/zh-HK/reference/evals/run-evals)，了解完整的參數及傳回類型文件。

### 僅使用閘門的執行

只要提供至少一個閘門，`scorers` 便是選填項目。這適合用於確定性的 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, threshold }` 中，即可設定通過／失敗的界限。系統會將閾值與評分器在所有資料項目中的平均分作比較。

`threshold` 可以是：

- **數字**：表示最低值（分數等於或高於此值即為通過）：`{ scorer, threshold: 0.7 }`
- **包含 `min` 及／或 `max` 的物件**：用於按範圍進行檢查：`{ scorer, threshold: { max: 0.3 } }`

如果評分器的高分代表不理想（例如幻覺或毒性），請使用 `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 } },
// ]
```

未設閾值的獨立評分器仍會顯示在 `result.scores` 中，但不會影響判定結果。

## 在 CI 中使用判定結果

判定結果可為 CI 管線提供單一訊號：

```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/zh-HK/docs/evals/quick-checks)：適合用作閘門、無需 LLM 的微型評分器
- [runEvals() 參考文件](https://mastra.zisheng.pro/zh-HK/reference/evals/run-evals)：完整 API 文件
- [內置評分器](https://mastra.zisheng.pro/zh-HK/docs/evals/built-in-scorers)：以 LLM 及程式碼為基礎的評分器
- [在 CI 中執行 Evals](https://mastra.zisheng.pro/zh-HK/docs/evals/running-in-ci)：CI 整合模式