Scorer 概览

传统软件测试具有明确的通过/失败条件，而 AI 输出具有非确定性，即使输入相同也可能有所不同。Scorer 通过提供可量化的指标来衡量 Agent 质量，帮助弥合这一差距。

Scorer 是一种自动化测试，使用模型评分、基于规则和统计的方法来评估 Agent 输出。Scorer 会返回分数：通常介于 0 和 1 之间的数值，用于量化输出满足评估标准的程度。这些分数让你能够客观地跟踪性能、比较不同方法，并找出 AI 系统中有待改进的领域。你可以使用自己的提示词和评分函数自定义 Scorer。

Scorer 可以在云端运行并捕获实时结果，也可以纳入 CI/CD Pipeline，以便持续测试和监控 Agent。

📹 观看视频

观看 Mastra Evals 概览，了解 Evals 以及如何思考 Agent 质量。

Scorer 类型

Mastra 提供不同类型的 Scorer，每种类型都有特定用途。常见类型包括：

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

安装

要使用 Mastra 的 Scorer 功能，请安装 @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

实时评估

实时评估可在 Agent 和 Workflow 运行时自动为 AI 输出进行实时评分。Scorer 不再需要手动或批量运行，而是与 AI 系统一起异步运行，从而提供持续的质量监控。

将 Scorer 添加到 Agent

你可以将内置 Scorer 添加到 Agent，自动评估其输出。所有可用选项请参阅完整的内置 Scorer 列表。

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

将 Scorer 添加到 Workflow Step

还可以将 Scorer 添加到单个 Workflow Step，在流程的特定位置评估输出。每个 Scorer 都会接收该 Step 自身的输入和输出，因此你可以衡量每个 Step 的质量，而不仅是为最终答案评分：

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();

有关 Step 级 scorers API，请参阅 Step 类 Reference。

实时评估的工作原理

异步执行：实时评估在后台运行，不会阻塞 Agent 响应或 Workflow 执行。这确保 AI 系统在受到监控的同时保持其性能。

采样控制：sampling.rate 参数（0-1）控制接受评分的输出比例：

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

自动存储：所有评分结果都会自动存储在所配置数据库的 mastra_scorers 表中，以便分析长期性能趋势。

Trace 评估

除实时评估外，还可以使用 Scorer 评估 Agent 交互和 Workflow 的历史 Trace。

这对于分析过去的性能、调试问题或运行批量评估特别有用。

需要配置 Observability

要为 Trace 评分，必须先在 Mastra 实例中配置 Observability 以收集 Trace 数据。设置说明请参阅 Tracing 文档。

Studio

要为 Trace 评分，首先需要在 Mastra 实例中注册 Scorer：

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

注册后，可以在 Studio 的 Observability 部分以交互方式为 Trace 评分。打开 Studio 可以管理 Scorer、查看分数并运行实验。

• Scorer 列表：浏览所有已注册的 Scorer，包括其描述以及所关联的 Agent 和 Workflow 数量。
• 评分结果：选择一个 Scorer，查看其产生的所有分数的分页列表。点击某一行可打开详情面板，其中显示分数值、原因、输入、输出和 Judge 使用的提示词。你可以在该面板中将任一结果保存为 Dataset 项目，用于未来的实验。
• Agent Evaluate 标签页：打开任一 Agent 的 Evaluate 标签页，管理 Scorer 和 Dataset，也可以在其中运行实验。实验结果会显示每个项目的分数、通过/失败状态和版本标签。
• Trace 评分：在 Observability 部分，针对任意历史 Trace 或 Span 运行 Scorer，以评估过去的交互。可按 Agent 或 Workflow 筛选分数。

后续步骤

• 使用 Quick Checks 对文本和 Tool 使用情况进行快速、确定性的断言
• 添加 Gate 和 Verdict，强制执行硬性要求和质量阈值
• 测试行为会随连续轮次显现的多轮对话
• 在创建自定义 Scorer 指南中学习如何创建自己的 Scorer
• 在内置 Scorer 部分探索内置 Scorer
• 使用 Studio 测试 Scorer
• 📹 Mastra Evals Workshop