Evals

传统软件测试有明确的通过/失败条件，而 AI 输出是非确定性的，相同输入也可能产生不同结果。Scorers 通过提供可量化的指标来衡量 Agent 质量，从而弥合这一差距。

Scorers 是自动化测试，使用模型评分、基于规则和统计方法评估 Agent 输出。Scorers 返回 scores：即数值（通常在 0 到 1 之间），用于量化输出满足评估标准的程度。这些分数让你能够客观跟踪性能、比较不同方法，并找出 AI 系统中需要改进的地方。Scorers 可以通过你自己的 prompts 和评分函数进行定制。

Scorers 可以在云端运行以捕获实时结果，也可以集成到 CI/CD 流水线中，用于长期测试和监控 agents。

📹 观看

观看 Mastra evals 概览，了解 evals 以及如何衡量 Agent 质量。

Scorer 类型

Mastra 提供多种类型的 scorers，各有特定用途。常见类型包括：

1. 文本 Scorers：评估 Agent 响应的准确性、可靠性和上下文理解能力
2. 分类 Scorers：衡量基于预定义类别对数据进行分类的准确性
3. 提示词工程 Scorers：探索不同指令和输入格式的影响

安装

要使用 Mastra 的 scorers 功能，请安装 @mastra/evals 包。

npm

npm install @mastra/evals@latest

pnpm

pnpm add @mastra/evals@latest

Yarn

yarn add @mastra/evals@latest

Bun

bun add @mastra/evals@latest

实时评估

实时评估让你可以在 agents 和 workflows 运行时，自动实时评分 AI 输出。Scorers 与 AI 系统异步并行运行，无需手动或批量执行评估，从而提供持续的质量监控。

为 agents 添加 scorers

你可以为 agents 添加内置 scorers，自动评估其输出。所有可用选项参见内置 scorers 完整列表。

src/mastra/agents/evaluated-agent.ts

import { Agent } from '@mastra/core/agent'
import { createAnswerRelevancyScorer, createToxicityScorer } from '@mastra/evals/scorers/prebuilt'

export const evaluatedAgent = new Agent({
  id: 'evaluated-agent',
  scorers: {
    relevancy: {
      scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
      sampling: { type: 'ratio', rate: 0.5 },
    },
    safety: {
      scorer: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
      sampling: { type: 'ratio', rate: 1 },
    },
  },
})

为 workflow 步骤添加 scorers

你也可以为单个 workflow 步骤添加 scorers，在流程的特定节点评估输出。每个 scorer 接收该步骤自身的输入和输出，因此可以衡量每一步的质量，而不只是对最终答案评分：

src/mastra/workflows/content-generation.ts

import { 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, // Score every step execution
      },
    },
  },
  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()

步骤级 scorers API 参见 Step 类参考。

实时评估如何工作

异步执行：实时评估在后台运行，不会阻塞 Agent 响应或 workflow 执行。AI 系统保持响应，同时实时评估对其进行监控。

采样控制：sampling.rate 参数（0-1）控制对多大比例的输出进行评分：

• 1.0：对每个响应评分（100%）
• 0.5：对所有响应中的一半评分（50%）
• 0.1：对 10% 的响应评分
• 0.0：禁用评分

采样对每个 trace 是确定性的：决定由 trace ID 推导，而非随机抽取。实际效果：

• 以相同 rate 配置的 scorers 会评分相同的 traces，因此它们的分数在共享流量上具有可比性。
• 重新运行同一个 trace 会产生相同的采样决定，因此采样覆盖率可复现。

当运行没有 trace 时（未配置可观测性），决定改由 run ID 推导。如果 trace 采样拒绝了该 trace，scorers 会完全跳过该运行，因此从未存储的 traces 不会产生分数。

资格过滤器：可选的 filter 参数使用对运行上下文的声明式谓词来限制 scorer 的适用范围。由于过滤发生在采样之前，sampling.rate 仅作用于匹配的运行：

src/mastra/agents/evaluated-agent.ts

export 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% 的企业套餐流量，其余流量不评分。若要以不同 rate 评分不同细分群体，可绑定同一个 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，因此不受持久化 Agent 状态序列化的影响。

资格过滤器决定scorer 是否运行；若要在 scorer 运行后过滤它能看到的哪些消息，请使用 filterRun()。过滤器无法看到运行的输入或输出。当资格取决于运行中发生了什么（例如是否调用了某个特定工具）时，请改为在 scorer 步骤中返回 notScorable()：剩余步骤会被跳过，且不会存储分数。

自动存储：所有评分结果会自动存储在你配置数据库的 mastra_scorers 表中，让你可以分析随时间变化的性能趋势。

分数持久化

当 Mastra 实例配置了 storage，且 scorer 已在该实例上注册时，分数才会被持久化。注册使 Mastra 能够在写入分数之前，通过 getScorerById() 解析 scorer 的元数据（名称、描述、类型）。

附加到 Agent 或 workflow 步骤的 scorers 会自行注册。直接传给 runEvals() 的 scorers（包括 Quick Checks）需要在 Mastra 类上配置 scorers 选项：

src/mastra/index.ts

import { 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。因此注册一个实例即可覆盖你评估的所有工具名称。

参数仍然会影响随每个分数存储的 description，该描述来自已注册的实例，而不是你用于评估的实例。checks.calledTool('') 会被接受并能正常持久化分数，但会存储 Checks that "" was called，因此请传入有代表性的值。

跳过注册不会改变评分结果，但每次保存都会失败并出现 Scorer with id <id> not found 警告，分数永远不会进入存储。

Trace 评估

除实时评估外，你还可以使用 scorers 评估 Agent 交互和 workflows 中的历史 traces。

这尤其适用于分析过去的性能或调试问题，也可用于运行批量评估。

需要可观测性

要评分 traces，必须先在 Mastra 实例中配置可观测性以收集 trace 数据。设置说明参见链路追踪文档。

Studio

要评分 traces，首先需要将 scorers 注册到 Mastra 实例：

const mastra = new Mastra({
  scorers: {
    answerRelevancy: myAnswerRelevancyScorer,
    responseQuality: myResponseQualityScorer,
  },
})

注册后，你可以在 Studio 的 Observability 区域中以交互方式评分 traces。打开 Studio 管理 scorers、查看分数并运行实验。

• Scorers 列表：浏览所有已注册的 scorers 及其描述，以及每个 scorer 关联的 agents 和 workflows 数量。
• 评分结果：选择某个 scorer，查看它产生的所有分数的分页列表。点击某行打开详情面板，其中显示分数值、原因、输入、输出以及 judge 使用的 prompts。在此面板中，可将任意结果保存为 dataset item，供未来实验使用。
• Agent 的 Evaluate 标签页：在任意 Agent 上打开 Evaluate 标签页，管理 scorers 和 datasets。你也可以在那里运行实验。实验结果会显示逐项分数、通过/失败状态和版本标签。
• Trace 评分：在 Observability 区域中，对任意历史 trace 或 span 运行 scorer，以评估过去的交互。可按 Agent 或 workflow 过滤分数。

后续步骤

• 使用 Quick Checks 对文本和工具使用情况进行快速、确定性的断言
• 添加门禁与判定，强制执行硬性要求和质量阈值
• 测试多轮对话，观察行为如何在连续轮次中涌现
• 在创建自定义 Scorers指南中学习如何编写自己的 scorers
• 在内置 Scorers章节中探索内置 scorers
• 使用 Studio 测试 scorers
• 📹 Mastra evals 研讨会