第24章 评估（Evals）

# Evals 传统软件测试有明确的通过/失败标准，而 AI 输出是非确定性的——相同输入可能产生不同结果。Scorer（评分器）通过提供可量化的指标来衡量 Agent 质量，弥合了这一差距。 Scorer 是自动化测试，通过模型评分、基于规则和统计方法来评估 Agent 输出。Scorer 返回分数：通常是 0 到 1 之间的数值，量化输出满足评估标准的程度。借助这些分数，你可以客观追踪性能、对比不同方案，并发现 AI 系统中需要改进的地方。Scorer 支持自定义提示词和评分函数。 Scorer 可以在云端运行，实时捕获结果，也可以集成到 CI/CD 流水线中，对 Agent 进行长期测试和监控。 📹 观看 Mastra evals 概览，了解 evals 的基本概念以及如何评估 Agent 质量。 ## Scorer 的类型 Mastra 提供多种 Scorer，各有侧重。常见类型包括： 文本类 Scorer：评估 Agent 回答的准确性、可靠性和上下文理解能力 分类 Scorer：衡量基于预定义类别对数据进行分类的准确度 提示词工程 Scorer：探索不同指令和输入格式的影响 ## 安装 要使用 Mastra 的 Scorer 功能，请安装 @mastra/evals 包。 npmpnpmYarnBunnpm install @mastra/evals@latest
pnpm add @mastra/evals@latest
yarn add @mastra/evals@latest
bun add @mastra/evals@latest
## 实时评估 实时评估可以在 Agent 和工作流运行时自动对 AI 输出进行实时打分。无需手动或批量运行评估，Scorer 会随 AI 系统异步运行，实现持续的质量监控。 ## 为 Agent 添加 Scorer 你可以为 Agent 添加内置 Scorer，自动评估其输出。完整可用选项请查看内置 Scorer 列表。 src/mastra/agents/evaluated-agent.tsimport { Agent } from '@mastra/core/agent'
import { createAnswerRelevancyScorer, createToxicityScorer } from '@mastra/evals/scorers/prebuilt'

export const evaluatedAgent = new Agent({
id: 'evaluated-agent',
scorers: {
relevancy: {
为 workflow 步骤添加 scorer（为 workflow 步骤添加 scorer 的直链） 你也可以给单个 workflow 步骤添加 scorer，在流程的特定环节评估输出。每个 scorer 接收该步骤自身的输入和输出，这样就能逐步衡量质量，而不是只给最终答案打分： src/mastra/workflows/content-generation.tsimport { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'
import { customStepScorer } from '../scorers/custom-step-scorer'

const contentStep = createStep({
id: 'content-step',
inputSchema: z.object({ topic: z.string() }),
outputSchema: z.object({ content: z.string() }),
scorers: {
customStepScorer: {
scorer: customStepScorer(),
sampling: {
type: 'ratio',
rate: 1, // 对每次步骤执行都打分
},
},
},
execute: async ({ inputData }) => {
return { content: await generateContent(inputData.topic) }
},
})

export const contentWorkflow = createWorkflow({
id: 'content-workflow',
inputSchema: z.object({ topic: z.string() }),
outputSchema: z.object({ content: z.string() }),
})
.then(contentStep)
.commit()
步骤级 scorer 的 API 参见 Step 类文档。 在线评估的工作原理Direct link to 在线评估的工作原理 异步执行：在线评估在后台运行，不会阻塞 agent 响应或 workflow 执行。评估进行监控的同时，你的 AI 系统保持正常响应。 采样控制：sampling.rate 参数（0-1）决定对多大比例的输出打分： 1.0：对所有响应打分（100%） 0.5：对一半响应打分（50%） 0.1：对 10% 的响应打分 0.0：关闭打分 采样对每条 trace 是确定性的：决策由 trace ID 推导得出，而非随机抽取。实际效果是： 相同采样率的 scorer 会对相同的 trace 打分，因此在共享流量上，它们的分数具有可比性。 同一条 trace 重复执行会得到相同的采样决策，采样覆盖范围可复现。 当 run 没有 trace（未配置可观测性）时，决策改由 run ID 推导。如果 trace 采样拒绝了该 trace，scorer 会完全跳过这个 run，这样就不会为从未存储的 trace 生成分数。 资格过滤：可选的 filter 参数通过基于 run 上下文的声明式谓词来限制 scorer 的适用范围。由于过滤发生在采样之前，sampling.rate 只作用于符合条件的 run： src/mastra/agents/evaluated-agent.tsexport const myAgent = new Agent({
// ...
scorers: {
relevancy: {
scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
filter: {
op: 'eq',
left: { path: 'requestContext.plan' },
right: { literal: 'enterprise' },
},
sampling: { type: 'ratio', rate: 0.1 },
},
},
})
这样会为企业版流量打 10% 的分，其余流量则不打分。如果想以不同比例为不同流量分段打分，可以用互补的过滤器把同一个 scorer 绑定两次。 过滤器条件可以引用 requestContext.*、entity.*、entityType、source、threadId、resourceId 和 projectId。支持的运算包括比较（eq、ne、lt、lte、gt、gte）、成员判断（in、notIn）、存在性（exists、notExists）、真值判断（truthy、falsy）以及布尔组合（and、or、not）。如果过滤器引用了未知字段，agent 构建时就会直接报错，而不是在运行时静默跳过打分。过滤器就是普通的 JSON，因此不受 durable agent 状态序列化的影响。 资格过滤器决定 scorer 是否运行；如果想在 scorer 运行后筛选它能看到哪些消息，请使用 filterRun()。过滤器看不到 run 的输入或输出。当资格取决于 run 中发生的事情时（比如是否调用了某个特定工具），请在 scorer 步骤中返回 notScorable()：剩余步骤会被跳过，也不会存储分数。 自动存储：所有打分结果会自动存入所配置数据库中的 mastra_scorers 表，方便你随时间推移分析性能趋势。

Score persistence

只有当 Mastra 实例配置了 storage，且 scorer 注册在该实例上时，分数才会持久化。正是通过注册，Mastra 才能在写入分数前通过 getScorerById() 解析 scorer 的元数据（name、description、type）。 挂载到 agent 或 workflow step 上的 scorer 会自动注册。而直接传给 runEvals() 的 scorer（包括 Quick Checks），则需要在 Mastra 类上配置 scorers 选项： src/mastra/index.tsimport { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'
import { checks } from '@mastra/evals/checks'
import { createAnswerRelevancyScorer } from '@mastra/evals/scorers/prebuilt'
import { myAgent } from './agents/my-agent'

export const mastra = new Mastra({
agents: { myAgent },
storage: new LibSQLStore({ url: 'file:./mastra.db' }),
scorers: {
calledTool: checks.calledTool('get_weather'),
includes: checks.includes('Brooklyn'),
relevancy: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
},
})
这个查找只比对 scorer 的 ID，所以注册的实例可以使用与评估时不同的配置。checks.calledTool() 的每个实例都用同一个 ID：check-called-tool，因此注册一次就能覆盖你评估的所有工具名。 参数仍然会影响随分数一起存储的描述信息，而这份描述来自注册时的实例，不是评估时用的那个。checks.calledTool('') 是可以接受的，分数也能正常持久化，但存储的记录会显示调用的是 ""，所以建议传入一个有代表性的值。 不注册也不会影响评分结果，只是每次保存都会报一条 Scorer with id not found 的警告，分数也永远无法写入存储。 追踪评估 除了实时评估，你还可以用 scorer 来评估智能体交互和工作流的历史追踪数据。 这对分析过往表现、排查问题或执行批量评估特别有用。 需要可观测性支持 要评估追踪数据，必须先在 Mastra 实例中配置可观测性以收集追踪数据。设置步骤请参阅 Tracing 文档。 Studio 要评估追踪数据，首先需要把你的 scorer 注册到 Mastra 实例中： const mastra = new Mastra({
scorers: {
answerRelevancy: myAnswerRelevancyScorer,
responseQuality: myResponseQualityScorer,
},
})

注册之后，你可以在 Studio 的 Observability 区块中以交互方式对 trace 进行评分。打开 Studio 即可管理 scorer、查看评分结果，还能运行实验。

Scorer 列表：浏览所有已注册的 scorer 及其描述，以及每个 scorer 关联的 agent 和 workflow 数量。

评分结果：选择某个 scorer，可分页查看它产出的所有评分。点击某一行可打开详情面板，其中显示评分值、原因、输入、输出以及 judge 所用的 prompt。在该面板中，还可以将任意结果保存为数据集条目，供后续实验使用。

Agent Evaluate 标签页：打开任意 agent 的 Evaluate 标签页，即可管理 scorer 和数据集，也可以在那里运行实验。实验结果会展示每条数据的评分，并附带通过/失败状态和版本标签。

Trace 评分：在 Observability 区块中，可以对任意历史 trace 或 span 运行 scorer，评估过去的交互。评分结果可按 agent 或 workflow 筛选。

后续步骤

使用 Quick Checks 对文本和工具调用进行快速、确定性的断言

添加 gates 和 verdicts 来强制执行硬性要求和质量阈值

测试多轮对话中跨连续轮次呈现的行为

在 Creating Custom Scorers 指南中学习如何创建自己的 scorer

在 Built-in Scorers 部分探索内置 scorer

使用 Studio 测试 scorer

📹 Mastra evals workshop