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

# 評分器概覽

傳統軟件測試有明確的通過／不通過條件，但 AI 輸出並非確定不變，即使輸入相同，輸出亦可能有所不同。**評分器**透過提供可量化的指標來衡量 Agent 質素，有助彌補這方面的差距。

評分器是自動化測試，利用模型評分、規則及統計方法來評估 Agent 的輸出。評分器會傳回**評分**，即量化輸出符合評估準則程度的數值（通常介乎 0 至 1）。這些評分讓你能客觀追蹤效能、比較不同方法，並找出 AI 系統中可改善之處。你亦可使用自訂 prompt 和評分函數來自訂評分器。

評分器可在雲端執行，以擷取即時結果，亦可整合至 CI/CD pipeline，讓你持續測試及監察 Agent。

> **📹 觀看:** 觀看 [Mastra evals overview](https://www.youtube.com/watch?v=12WN6u2DrBk)，了解 evals 的基本概念，以及如何分析 Agent 質素。

## 評分器類型

Mastra 提供不同種類的評分器，各有特定用途。以下是部分常見類型：

1. **文字評分器**：評估 Agent 回應的準確度、可靠度及語境理解能力
2. **分類評分器**：衡量按預先定義類別將資料分類的準確度
3. **Prompt Engineering 評分器**：探索不同指令及輸入格式所帶來的影響

## 安裝

要使用 Mastra 的評分器功能，請安裝 `@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 輸出評分。評分器無須以手動或批次方式執行評估，而是與 AI 系統並行非同步執行，持續監察質素。

### 將評分器加入 Agent

你可將內置評分器加入 Agent，以自動評估其輸出。如要查看所有可用選項，請參閱[完整的內置評分器清單](https://mastra.zisheng.pro/zh-HK/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 },
    },
  },
})
```

### 將評分器加入 Workflow 步驟

你亦可將評分器加入個別 Workflow 步驟，以評估流程中特定位置的輸出。每個評分器都會接收該步驟本身的輸入及輸出，讓你衡量每個步驟的質素，而非只為最終答案評分：

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

如要了解步驟層級的 `scorers` API，請參閱 [Step class 參考資料](https://mastra.zisheng.pro/zh-HK/reference/workflows/step)。

### 即時評估的運作方式

**非同步執行**：即時評估會在背景執行，不會阻塞 Agent 回應或 Workflow 執行。這可確保 AI 系統在受監察的同時維持效能。

**抽樣控制**：`sampling.rate` 參數（0–1）控制獲評分的輸出百分比：

- `1.0`：為每項回應評分（100%）
- `0.5`：為一半回應評分（50%）
- `0.1`：為 10% 的回應評分
- `0.0`：停用評分

**自動儲存**：所有評分結果都會自動儲存至已設定資料庫的 `mastra_scorers` 資料表，讓你分析效能隨時間的變化趨勢。

## Trace 評估

除了即時評估外，你亦可使用評分器評估 Agent 互動及 Workflow 的歷史 Trace。

這特別適合用於分析過往效能或偵錯，亦可用來執行批次評估。

> **需要可觀測性:** 要為 Trace 評分，必須先在 Mastra 實例中設定可觀測性，以收集 Trace 資料。設定指示請參閱 [Tracing 文件](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)。

## Studio

要為 Trace 評分，首先需要在 Mastra 實例中註冊評分器：

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

註冊後，你可在 Studio 的 **Observability** 部分以互動方式為 Trace 評分。開啟 Studio 即可管理評分器、檢視評分及執行實驗。

- **評分器清單**：瀏覽所有已註冊評分器、其描述，以及每個評分器所連接的 Agent 和 Workflow 數目。
- **評分結果**：選擇評分器，查看其產生的每項評分分頁清單。按一下資料列即可開啟詳細資料面板，當中顯示評分值、原因、輸入、輸出，以及評審所使用的 prompt。你可在此面板將任何結果儲存為資料集項目，供日後實驗使用。
- **Agent Evaluate 分頁**：在任何 Agent 開啟 Evaluate 分頁，以管理評分器和資料集。你亦可在該處執行實驗。實驗結果會顯示各項目的評分、通過／不通過狀態及版本標籤。
- **Trace 評分**：在 Observability 部分，針對任何歷史 Trace 或 span 執行評分器，以評估過往互動。可按 Agent 或 Workflow 篩選評分。

## 後續步驟

- 使用 [Quick Checks](https://mastra.zisheng.pro/zh-HK/docs/evals/quick-checks)，快速對文字及 Tool 使用情況作出確定性斷言
- 加入 [gate 和 verdict](https://mastra.zisheng.pro/zh-HK/docs/evals/gates-and-verdicts)，強制執行硬性要求及質素門檻
- 測試[多輪對話](https://mastra.zisheng.pro/zh-HK/docs/evals/multi-turn)，了解行為如何在連續多輪互動中逐步呈現
- 在[建立自訂評分器](https://mastra.zisheng.pro/zh-HK/docs/evals/custom-scorers)指南中，了解如何建立自己的評分器
- 在[內置評分器](https://mastra.zisheng.pro/zh-HK/docs/evals/built-in-scorers)部分探索內置評分器
- 使用 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview) 測試評分器
- 📹 [Mastra Evals 工作坊](https://www.youtube.com/watch?v=OHOZ5PgPj5M\&t=3578s)