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

# 快速檢查

Quick Checks 是可組合的微型評分器，用於「輸出包含 X」或「Agent 呼叫了 Tool Y」等常見斷言。它們無需 LLM、可即時執行，並可像其他評分器一樣加入同一個 `scorers: [...]` 陣列。

## 何時使用 Quick Checks

當你需要快速、確定的斷言時，可使用 Quick Checks：

- 驗證輸出文字包含或不包含指定字串
- 確認 Agent 呼叫了（或沒有呼叫）指定 Tool
- 驗證 Tool 呼叫順序及次數上限
- 以零成本的二元檢查作為 CI pipeline 的閘門
- 與基於 LLM 的評分器配合，進行分層評估

如要進行主觀或語義評估，請改用[基於 LLM 的評分器](https://mastra.zisheng.pro/zh-HK/docs/evals/built-in-scorers)。

## 快速開始

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

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

console.log(result.scores)
// { 'check-includes': 1, 'check-called-tool': 1, 'check-no-tool-errors': 1 }
```

## 可用的檢查

Quick Checks 分為以下類別：

### 文字檢查

這些評分器會評估 Agent 的文字輸出：

| 檢查                       | 功能                        | 分數                          |
| ------------------------ | ------------------------- | --------------------------- |
| `checks.includes(str)`   | 輸出包含子字串                   | 1 或 0                       |
| `checks.excludes(str)`   | 輸出不包含子字串                  | 1 或 0                       |
| `checks.equals(str)`     | 輸出與字串完全相同                 | 1 或 0                       |
| `checks.matches(regex)`  | 輸出符合正規表達式                 | 1 或 0                       |
| `checks.similarity(str)` | 與字串的 Dice coefficient 相似度 | 0-1（如設有 `threshold`，則為二元分數） |

### Tool 呼叫檢查

這些評分器會評估 Agent 執行期間的 Tool 使用情況：

| 檢查                        | 功能                | 分數    |
| ------------------------- | ----------------- | ----- |
| `checks.calledTool(name)` | Tool 至少被呼叫 N 次    | 1 或 0 |
| `checks.didNotCall(name)` | Tool 未被呼叫         | 1 或 0 |
| `checks.toolOrder([...])` | Tool 按預期順序呼叫      | 1 或 0 |
| `checks.maxToolCalls(n)`  | Tool 呼叫總數不超過 N 次  | 1 或 0 |
| `checks.usedNoTools()`    | 完全沒有呼叫 Tool       | 1 或 0 |
| `checks.noToolErrors()`   | 所有 Tool 呼叫均沒有發生錯誤 | 1 或 0 |

## 結合檢查與 LLM 評分器

檢查可在單次 `runEvals` 呼叫中與基於 LLM 的評分器配合使用。使用檢查作為確定性閘門，並以 LLM 評分器進行定性評估：

```typescript
import { checks } from '@mastra/evals/checks'
import { createFaithfulnessScorer } from '@mastra/evals/scorers/prebuilt'
import { runEvals } from '@mastra/core/evals'
import { myAgent } from '../agents'

const result = await runEvals({
  data: [
    {
      input: 'What is the weather in Brooklyn?',
      context: ['Brooklyn weather data: sunny, 72°F'],
    },
  ],
  target: myAgent,
  scorers: [
    // Deterministic checks (instant, free)
    checks.includes('Brooklyn'),
    checks.calledTool('get_weather'),
    checks.excludes('error'),
    checks.noToolErrors(),

    // LLM-based scorer (semantic, costs tokens)
    createFaithfulnessScorer({ model: 'openai/gpt-5-mini' }),
  ],
})
```

## 在即時評分中使用檢查

將檢查附加至 Agent，以持續監察：

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

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: 'Answer weather questions using the get_weather tool.',
  model: 'openai/gpt-5.6-sol',
  tools: { get_weather: weatherTool },
  scorers: {
    noErrors: {
      scorer: checks.noToolErrors(),
      sampling: { type: 'ratio', rate: 1 },
    },
    mentionCity: {
      scorer: checks.includes('Brooklyn'),
      sampling: { type: 'ratio', rate: 0.5 },
    },
  },
})
```

## 檢查的運作方式

每項檢查都是標準的 `createScorer()` 實例，包含一個 `preprocess` 步驟和一個 `generateScore` 步驟。它們與其他評分器一樣，遵循相同的[四步 pipeline](https://mastra.zisheng.pro/zh-HK/docs/evals/custom-scorers)：

1. **preprocess**：從 Agent 執行結果中擷取並標準化相關資料（文字內容、Tool 呼叫）
2. **generateScore**：將預處理結果轉換為分數（通常是二元分數 1 或 0）

由於檢查會略過 `analyze` 和 `generateReason` 步驟，而且不會呼叫 LLM，因此能在數微秒內完成。請參閱 [Quick Checks 參考資料](https://mastra.zisheng.pro/zh-HK/reference/evals/checks)，了解完整 API，包括每項檢查的所有參數和選項。

## 相關內容

- [Quick Checks 參考資料](https://mastra.zisheng.pro/zh-HK/reference/evals/checks)
- [內置評分器](https://mastra.zisheng.pro/zh-HK/docs/evals/built-in-scorers)
- [自訂評分器](https://mastra.zisheng.pro/zh-HK/docs/evals/custom-scorers)
- [`runEvals()` 參考資料](https://mastra.zisheng.pro/zh-HK/reference/evals/run-evals)