企业官网建设流程全解析

如何在 Mastra evals 中设置 gates 与分数阈值得到 passed、scored 或 failed 判定

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

如果你的 Agent 评测目前只有零散的分数，缺少一个"这次运行到底算不算通过"的信号，Mastra 的 gates and verdicts 机制可以解决这个问题：在runEvals中声明必须得满分的 gates（硬性要求）和带分数阈值的 tracked scorers（质量指标），一次评测结束后直接从result.verdict拿到passed、scored或failed三种判定之一，不需要自己写断言逻辑。本文适用场景是用runEvals（来自@mastra/core/evals）对 Agent 做批量评测，并在 CI 或本地脚本中依据判定结果决定流水线是否失败。

准备条件

按照 Evals 概览 的安装说明，安装@mastra/evals包：

npm install @mastra/evals@latest

runEvals本身从@mastra/core/evals导入，Quick Checks（checks）从@mastra/evals/checks导入。此外你还需要一个可评测的 target（Agent 或 Workflow）和一组评测数据。

gates、阈值与 verdict 的判定规则

先明确三者含义，后面的配置都围绕它们展开：

• Gates：通过gates字段传入的 scorer，会在每条数据上先于普通 scorers 执行。一个 gate 必须在所有数据项上平均分达到 1.0 才算通过。任何 scorer 都可以作为 gate，返回二值 1/0 分数的 Quick Checks 是天然的选择。
• Thresholds：把 scorer 包成{ scorer, threshold }即为带阈值的 tracked metric。阈值与 scorer 在所有数据项上的平均分比较：
  • 数字：表示最低分（达到或超过即通过），如{ scorer, threshold: 0.7 }；
  • 含min和/或max的对象：区间检查，如{ scorer, threshold: { max: 0.3 } }。max适用于"分数高反而是坏事"的 scorer（如幻觉、毒性）；min/max必须都在 0 和 1 之间。
• Verdict 判定规则（在所有数据项处理完后计算）：
  • failed：至少一个 gate 在数据项上的平均分低于 1.0；
  • scored：所有 gate 通过，但至少一个 threshold scorer 未达到阈值；
  • passed：所有 gate 得 1.0 且所有阈值都达标。

一个重要的边界：当既没有 gates 也没有带阈值的 scorer 时，verdict字段会被省略，runEvals的行为与之前完全一致。

配置 gates 与阈值：一个完整示例

下面示例来自主文档 Gates and verdicts，其中weatherAgent是你的评测目标，faithfulnessScorer是你自己的 scorer 实例（文档示例中从../scorers导入，替换为你项目中对应的实例即可）：

// 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'

示例逐段说明：

• gates: [checks.calledTool('get_weather'), checks.noToolErrors()]表达两条硬性要求：agent 必须调用get_weather工具、工具调用不能有错误。任一 gate 平均低于 1.0 即整体failed。
• { scorer: faithfulnessScorer, threshold: 0.7 }是数字阈值（最低分 0.7）。未达阈值只会让判定变成scored，不会直接failed。
• checks.includes('Brooklyn')是裸 scorer（不带阈值），分数会出现在result.scores中，但不影响 verdict。

阈值还支持区间形式，文档给出的三种写法：

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 } }, ]

只跑 gate 的确定性 CI 检查

如果只做确定性的通过/失败检查、不追踪质量指标，提供至少一个 gate 时scorers是可选的：

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

注意一个硬性约束：必须至少提供一个 scorer 或 gate，两者都没有的runEvals调用会抛出错误。

读取结果：verdict、gateResults 与 thresholdResults

runEvals返回对象中与判定相关的字段（详见 runEvals 参考文档）：

• verdict：'passed' | 'scored' | 'failed'，仅当提供了 gates 或带阈值的 scorer 时存在；
• gateResults：每个 gate 跨全部数据项的平均结果，每条含id、passed（boolean）、score（0–1）。文档示例：[{ id: 'check-called-tool', passed: true, score: 1 }]；
• thresholdResults：每个带阈值 scorer 的平均结果，每条含id、passed、averageScore、threshold。

在 CI 中用 verdict 作为单一信号，并按文档给出的模式区分处理两种未通过情形：

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), ) }

也就是说：gate 失败会打印未通过的 gate 并以退出码 1 终止流水线；阈值未达标只打印警告，不终止。这个"hard fail 与 soft warn"的分层由 gates 和 thresholds 的语义天然保证。

验证与限制

• 验证方式：运行runEvals后检查result.verdict，并用result.gateResults/result.thresholdResults中的passed字段定位具体是哪个 gate 或哪个 scorer 未达标。
• 未配置 gates 与阈值 scorer 的调用没有verdict字段，不要在这种调用上读取result.verdict。
• gate 的判定依据是"跨所有数据项的平均分达到 1.0"，所以二值型 check 只要有一条数据项不满足，平均分就会低于 1.0，整体判定为failed。
• 若希望把 Quick Checks 的分数持久化到存储，需要把 check 注册到 Mastra 实例（配合storage），详见 Score persistence 一节；不注册只影响持久化，不影响本次评测的判定结果。

进一步阅读

• Gates and verdicts 文档：本文所有规则的原始出处；
• runEvals 参考：完整参数与返回类型，包括多轮turns场景下逐轮 gates/scorers 如何折叠进整体 verdict；
• Quick Checks：所有可用的零 LLM 断言（includes、calledTool、toolOrder、maxToolCalls等）；
• Running scorers in CI：把runEvals放进 Vitest/Jest/Mocha 的 CI 集成模式。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra