Gates and verdicts

Gates 和 verdicts 为 runEvals 增加了严重性语义。Gates 是必须得到 1.0 分的 scorer，即会阻止运行的硬性要求。Thresholds 是被跟踪指标平均得分的下限和/或上限。Verdict 会将结果汇总为 passed、scored 或 failed。

何时使用 gates 和 verdicts

• 在 CI 中强制执行硬性要求（例如“agent 必须调用正确的工具”）
• 使用最低阈值跟踪质量指标（例如“faithfulness 高于 0.7”）
• 从一次 eval 运行中获得单一的 verdict 信号（passed、scored 或 failed），而无需编写自定义断言逻辑
• 将“必须通过”的 gates 与“最好满足”的跟踪指标区分开

快速开始

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'

Verdict 的计算方式

Verdict 会在处理完所有数据项后根据 gates 和 thresholds 计算：

• failed：至少一个 gate 在所有数据项上的平均值低于 1.0
• scored：所有 gates 都通过，但至少一个带阈值 scorer 未达到其阈值
• passed：所有 gates 都得到 1.0 且所有阈值都已满足

当未提供 gates 或带阈值的 scorer，并且每个已配置的 gate 和 threshold 都返回 notScorable()（没有数值证据）时，verdict 字段会被省略。在这些情况下，runEvals 仍会返回 scores 和 summary。

Gates

Gates 是通过 gates 字段传入的 scorer。它们会在每个数据项上先于常规 scorer 运行。Gate 在其能够评分的数据项上必须平均得到 1.0 分才能通过。gate 返回 notScorable() 的项不计入平均值，抛出错误的 gate 在该项上计为 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 }]

任何 scorer 都可以作为 gate。Quick Checks 是天然的选择，因为它们返回二元的 1/0 得分。完整的参数和返回类型文档请参阅 runEvals() reference。

仅 Gate 运行

当至少提供一个 gate 时，scorers 是可选的。这适用于确定性的 CI 检查，你只关心通过/失败 gates，不需要跟踪任何质量指标。

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 或 gate，两者都不提供的运行会抛出错误。

Thresholds

将 scorer 包装为 { scorer, threshold } 以设置通过/失败边界。阈值会与 scorer 在可评分数据项上的平均得分进行比较。返回 notScorable() 的结果不计入平均值。

threshold 可以是：

• 数字：表示最小值（得分等于或高于该值即通过）：{ scorer, threshold: 0.7 }
• 包含 min 和/或 max 的对象：用于范围检查：{ scorer, threshold: { max: 0.3 } }

对于高分代表坏结果的 scorer（例如幻觉、毒性），请使用 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 } },
// ]

裸 scorer（无阈值）仍会出现在 result.scores 中，但不会影响 verdict。

在 CI 中使用 verdicts

Verdict 为 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：非常适合作为 gates 的零 LLM 微型 scorer
• runEvals() reference：完整 API 文档
• Built-in scorers：基于 LLM 和基于代码的 scorer
• Running evals in CI：CI 集成模式