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

# 評分器概覽

傳統軟體測試有明確的通過／失敗條件，但 AI 輸出並非確定性結果，即使輸入相同也可能有所不同。**評分器**透過提供可量化的指標來衡量 Agent 品質，協助彌補這項落差。

評分器是自動化測試，會使用模型評分、規則式與統計方法評估 Agent 輸出。評分器會傳回**分數**：以數值（通常介於 0 到 1）量化輸出符合評估條件的程度。這些分數可讓你客觀追蹤效能、比較不同做法，並找出 AI 系統可改進之處。你也能以自己的提示與評分函式自訂評分器。

評分器可在雲端執行並擷取即時結果，也能納入 CI/CD 管線，讓你持續測試與監控 Agent。

> **📹 觀看影片:** 觀看 [Mastra evals overview](https://www.youtube.com/watch?v=12WN6u2DrBk)，了解 Evals 的基本介紹，以及如何思考 Agent 品質。

## 評分器類型

Mastra 提供不同種類的評分器，各自適用於特定用途。常見類型如下：

1. **文字評分器**：評估 Agent 回應的準確性、可靠性與內容理解能力
2. **分類評分器**：衡量依預先定義類別將資料分類的準確性
3. **提示工程評分器**：探討不同指示與輸入格式所造成的影響

## 安裝

若要使用 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-TW/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 類別參考](https://mastra.zisheng.pro/zh-TW/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-TW/docs/observability/tracing/overview)。

## Studio

若要評分 Trace，必須先向 Mastra 執行個體註冊評分器：

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

註冊後，你可以在 Studio 的 **Observability** 區段中互動式評分 Trace。開啟 Studio 以管理評分器、檢閱分數及執行實驗。

- **評分器清單**：瀏覽所有已註冊評分器及其說明，並查看每個評分器所附加的 Agent 與 Workflow 數量。
- **評分結果**：選取評分器，即可查看它所產生的每筆分數分頁清單。點選資料列可開啟詳細資料面板，其中顯示分數值、理由、輸入、輸出，以及判定模型所用的提示。你可以在此面板中將任何結果儲存為資料集項目，供未來實驗使用。
- **Agent 的 Evaluate 分頁**：開啟任何 Agent 的 Evaluate 分頁以管理評分器與資料集，也可在其中執行實驗。實驗結果會顯示各項目的分數、通過／失敗狀態與版本標籤。
- **Trace 評分**：在 Observability 區段中，對任何歷史 Trace 或 span 執行評分器，以評估過往互動。你可以依 Agent 或 Workflow 篩選分數。

## 後續步驟

- 使用 [Quick Checks](https://mastra.zisheng.pro/zh-TW/docs/evals/quick-checks)，快速對文字與 Tool 使用情形執行確定性斷言
- 加入[閘門與判定結果](https://mastra.zisheng.pro/zh-TW/docs/evals/gates-and-verdicts)，強制執行必要要求與品質臨界值
- 測試會在連續對話輪次中展現行為的[多輪對話](https://mastra.zisheng.pro/zh-TW/docs/evals/multi-turn)
- 閱讀[建立自訂評分器](https://mastra.zisheng.pro/zh-TW/docs/evals/custom-scorers)指南，了解如何建立自己的評分器
- 探索[內建評分器](https://mastra.zisheng.pro/zh-TW/docs/evals/built-in-scorers)區段
- 使用 [Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview) 測試評分器
- 📹 [Mastra evals workshop](https://www.youtube.com/watch?v=OHOZ5PgPj5M\&t=3578s)