> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Scorer 概览

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

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

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

> **📹 观看视频:** 观看 [Mastra Evals 概览](https://www.youtube.com/watch?v=12WN6u2DrBk)，了解 Evals 以及如何思考 Agent 质量。

## Scorer 类型

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

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

## 安装

要使用 Mastra 的 Scorer 功能，请安装 `@mastra/evals` 软件包。

**npm**:

```bash
npm install @mastra/evals@latest
```

**pnpm**:

```bash
pnpm add @mastra/evals@latest
```

**Yarn**:

```bash
yarn add @mastra/evals@latest
```

**Bun**:

```bash
bun add @mastra/evals@latest
```

## 实时评估

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

### 将 Scorer 添加到 Agent

你可以将内置 Scorer 添加到 Agent，自动评估其输出。所有可用选项请参阅[完整的内置 Scorer 列表](https://mastra.zisheng.pro/docs/evals/built-in-scorers)。

```typescript
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 的质量，而不仅是为最终答案评分：

```typescript
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](https://mastra.zisheng.pro/reference/workflows/step)。

### 实时评估的工作原理

**异步执行**：实时评估在后台运行，不会阻塞 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 文档](https://mastra.zisheng.pro/docs/observability/tracing/overview)。

## Studio

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

```typescript
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](https://mastra.zisheng.pro/docs/evals/quick-checks) 对文本和 Tool 使用情况进行快速、确定性的断言
- 添加 [Gate 和 Verdict](https://mastra.zisheng.pro/docs/evals/gates-and-verdicts)，强制执行硬性要求和质量阈值
- 测试行为会随连续轮次显现的[多轮对话](https://mastra.zisheng.pro/docs/evals/multi-turn)
- 在[创建自定义 Scorer](https://mastra.zisheng.pro/docs/evals/custom-scorers) 指南中学习如何创建自己的 Scorer
- 在[内置 Scorer](https://mastra.zisheng.pro/docs/evals/built-in-scorers) 部分探索内置 Scorer
- 使用 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 测试 Scorer
- 📹 [Mastra Evals Workshop](https://www.youtube.com/watch?v=OHOZ5PgPj5M\&t=3578s)