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

# Quick Checks

Quick Checks 是一組毋須使用 LLM、可組合的微型評分器，適用於常見斷言。凡是使用評分器的地方，都可以將它們加入現有的 `scorers: [...]` 陣列，包括 `runEvals`、即時評分、實驗及 Studio。

它們在內部是標準的 `createScorer()` 實例，因此具備與其他評分器相同的可觀測性、儲存及管線整合能力。

## 使用範例

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

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

console.log(result.scores)
```

## 文字檢查

### `checks.includes(expected, options?)`

如果 Agent 的輸出文字包含預期子字串，評分為 1；否則為 0。

```typescript
checks.includes('sunny')
checks.includes('Sunny', { ignoreCase: false })
```

**expected** (`string`): 要在輸出中搜尋的子字串。

**options.ignoreCase** (`boolean`): 不區分大小寫進行比對。 (Default: `true`)

傳回值：如找到則為 `1`，否則為 `0`。

### `checks.excludes(unwanted, options?)`

如果 Agent 的輸出文字不包含該子字串，評分為 1；否則為 0。

```typescript
checks.excludes('error')
checks.excludes('Error', { ignoreCase: false })
```

**unwanted** (`string`): 不得在輸出中出現的子字串。

**options.ignoreCase** (`boolean`): 不區分大小寫進行比對。 (Default: `true`)

傳回值：如沒有出現則為 `1`，否則為 `0`。

### `checks.equals(expected, options?)`

如果輸出文字經可選的標準化處理後與預期字串完全相同，評分為 1；否則為 0。

```typescript
checks.equals('Hello, world!')
checks.equals('Hello', { ignoreCase: false })
```

**expected** (`string`): 輸出必須完全符合的字串。

**options.ignoreCase** (`boolean`): 不區分大小寫進行比對。 (Default: `true`)

傳回值：如相同則為 `1`，否則為 `0`。

### `checks.matches(pattern, options?)`

如果輸出符合正規表示式，評分為 1。

```typescript
checks.matches(/\d+°[FC]/)
checks.matches(/^hello$/, { exact: true })
```

**pattern** (`RegExp`): 用於測試輸出的正規表示式。

**options.exact** (`boolean`): 錨定模式以比對整個輸出（加入 ^ 及 $）。 (Default: `false`)

傳回值：如符合則為 `1`，否則為 `0`。

### `checks.similarity(expected, options?)`

使用 Dice 系數傳回輸出與預期字串之間的字串相似度分數（0 至 1）。設定 `threshold` 後，則會傳回二元值 1/0。

```typescript
checks.similarity('Sunny, 72°F')
checks.similarity('Sunny, 72°F', { threshold: 0.7 })
```

**expected** (`string`): 用作比較的參考字串。

**options.threshold** (`number`): 傳回 1 所需的最低相似度分數（0 至 1）。省略時會傳回原始相似度分數。

**options.ignoreCase** (`boolean`): 不區分大小寫進行比較。 (Default: `true`)

傳回值：原始相似度分數（0 至 1）；設定 `threshold` 時則為二元值 `1`/`0`。

## Tool 呼叫檢查

### `checks.calledTool(toolName, options?)`

如果 Agent 呼叫指定 Tool 的次數至少達到要求，評分為 1。

```typescript
checks.calledTool('get_weather')
checks.calledTool('search', { times: 2 })
```

**toolName** (`string`): 要尋找的 Tool 名稱。

**options.times** (`number`): Tool 必須被呼叫的最低次數。 (Default: `1`)

傳回值：如呼叫次數至少為 `times` 次則為 `1`，否則為 `0`。

### `checks.didNotCall(toolName)`

如果 Agent 沒有呼叫指定 Tool，評分為 1。

```typescript
checks.didNotCall('delete_user')
```

**toolName** (`string`): 不得出現的 Tool 名稱。

傳回值：如沒有呼叫該 Tool 則為 `1`，否則為 `0`。

### `checks.toolOrder(expectedOrder)`

如果各 Tool 按指定次序被呼叫，評分為 1。此檢查採用寬鬆比對，預期 Tool 之間可以有其他 Tool 呼叫。

```typescript
checks.toolOrder(['search', 'summarize', 'respond'])
```

**expectedOrder** (`string[]`): 預期呼叫次序中的 Tool 名稱。它們必須以子序列形式出現在實際 Tool 呼叫中。

傳回值：如符合預期次序則為 `1`，否則為 `0`。

### `checks.maxToolCalls(max)`

如果 Agent 使用的 Tool 呼叫不多於 `max` 次，評分為 1。

```typescript
checks.maxToolCalls(5)
```

**max** (`number`): 允許的 Tool 呼叫次數上限。

傳回值：如在限制之內則為 `1`，否則為 `0`。

### `checks.usedNoTools()`

如果 Agent 完全沒有呼叫 Tool，評分為 1。

```typescript
checks.usedNoTools()
```

傳回值：如沒有呼叫 Tool 則為 `1`，否則為 `0`。

### `checks.noToolErrors()`

如果所有 Tool 調用都沒有產生錯誤狀態，評分為 1。此檢查可偵測錯誤結果（存在 `result.error`）及未完成的 Tool 呼叫（`state === 'call'`）。

```typescript
checks.noToolErrors()
```

傳回值：如所有 Tool 呼叫均成功則為 `1`，否則為 `0`。

## 將檢查與其他評分器組合

檢查可以在同一個 `scorers` 陣列中，與以 LLM 為基礎及以程式碼為基礎的評分器組合使用：

```typescript
import { checks } from '@mastra/evals/checks'
import { createAnswerRelevancyScorer } 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?' }],
  target: myAgent,
  scorers: [
    // Zero-LLM checks
    checks.includes('Brooklyn'),
    checks.calledTool('get_weather'),
    checks.noToolErrors(),
    // LLM-based scorer
    createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
  ],
})
```

## 相關內容

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