評分器概覽

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

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

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

📹 觀看影片

觀看 Mastra evals overview，了解 Evals 的基本介紹，以及如何思考 Agent 品質。

評分器類型

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

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

安裝

若要使用 Mastra 的評分器功能，請安裝 @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 輸出。評分器不必手動或批次執行，而會與 AI 系統並行非同步執行，提供持續的品質監控。

將評分器加入 Agent

你可以將內建評分器加入 Agent，自動評估其輸出。請參閱完整的內建評分器清單，了解所有可用選項。

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 步驟

你也可以將評分器加入個別 Workflow 步驟，在流程中的特定位置評估輸出。每個評分器都會接收該步驟本身的輸入與輸出，因此能衡量每個步驟的品質，而不只評分最終答案：

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：停用評分

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

Trace 評估

除了即時評估，你也能使用評分器評估 Agent 互動與 Workflow 的歷史 Trace。

這特別適合用來分析過往效能、偵錯問題或執行批次評估。

需要可觀測性設定

若要評分 Trace，必須先在 Mastra 執行個體中設定可觀測性，以收集 Trace 資料。設定方式請參閱 Tracing 文件。

Studio

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

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，快速對文字與 Tool 使用情形執行確定性斷言
• 加入閘門與判定結果，強制執行必要要求與品質臨界值
• 測試會在連續對話輪次中展現行為的多輪對話
• 閱讀建立自訂評分器指南，了解如何建立自己的評分器
• 探索內建評分器區段
• 使用 Studio 測試評分器
• 📹 Mastra evals workshop