Quick Checks

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

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

使用範例

src/evals/weather-checks.ts

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。

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

expected:

string

要在輸出中搜尋的子字串。

options.ignoreCase?:

boolean

= true

不區分大小寫進行比對。

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

checks.excludes(unwanted, options?)

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

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

unwanted:

string

不得在輸出中出現的子字串。

options.ignoreCase?:

boolean

= true

不區分大小寫進行比對。

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

checks.equals(expected, options?)

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

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

expected:

string

輸出必須完全符合的字串。

options.ignoreCase?:

boolean

= true

不區分大小寫進行比對。

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

checks.matches(pattern, options?)

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

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

pattern:

RegExp

用於測試輸出的正規表示式。

options.exact?:

boolean

= false

錨定模式以比對整個輸出（加入 ^ 及 $）。

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

checks.similarity(expected, options?)

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

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

expected:

string

用作比較的參考字串。

options.threshold?:

number

傳回 1 所需的最低相似度分數（0 至 1）。省略時會傳回原始相似度分數。

options.ignoreCase?:

boolean

= true

不區分大小寫進行比較。

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

Tool 呼叫檢查

checks.calledTool(toolName, options?)

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

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

toolName:

string

要尋找的 Tool 名稱。

options.times?:

number

= 1

Tool 必須被呼叫的最低次數。

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

checks.didNotCall(toolName)

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

checks.didNotCall('delete_user')

toolName:

string

不得出現的 Tool 名稱。

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

checks.toolOrder(expectedOrder)

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

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

expectedOrder:

string[]

預期呼叫次序中的 Tool 名稱。它們必須以子序列形式出現在實際 Tool 呼叫中。

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

checks.maxToolCalls(max)

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

checks.maxToolCalls(5)

max:

number

允許的 Tool 呼叫次數上限。

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

checks.usedNoTools()

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

checks.usedNoTools()

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

checks.noToolErrors()

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

checks.noToolErrors()

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

將檢查與其他評分器組合

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

src/evals/combined-eval.ts

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 概覽
• 內置評分器
• createScorer() 參考
• runEvals() 參考
• 自訂評分器