閘門與判定結果

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

何時使用閘門與判定結果

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

快速入門

src/evals/weather-eval.ts

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 才算通過。

src/evals/tool-gate.ts

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() 參考文件，了解完整的參數及傳回類型文件。

僅使用閘門的執行

只要提供至少一個閘門，scorers 便是選填項目。這適合用於確定性的 CI 檢查：你只關心閘門通過與否，而無需追蹤任何品質指標。

src/evals/gate-only.ts

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 }。

src/evals/threshold-example.ts

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 管線提供單一訊號：

src/evals/ci-check.ts

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：適合用作閘門、無需 LLM 的微型評分器
• runEvals() 參考文件：完整 API 文件
• 內置評分器：以 LLM 及程式碼為基礎的評分器
• 在 CI 中執行 Evals：CI 整合模式