評分器概覽

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

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

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

📹 觀看

觀看 Mastra evals overview，了解 evals 的基本概念，以及如何分析 Agent 質素。

評分器類型

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

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

安裝

要使用 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 class 參考資料。

即時評估的運作方式

非同步執行：即時評估會在背景執行，不會阻塞 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 數目。
• 評分結果：選擇評分器，查看其產生的每項評分分頁清單。按一下資料列即可開啟詳細資料面板，當中顯示評分值、原因、輸入、輸出，以及評審所使用的 prompt。你可在此面板將任何結果儲存為資料集項目，供日後實驗使用。
• Agent Evaluate 分頁：在任何 Agent 開啟 Evaluate 分頁，以管理評分器和資料集。你亦可在該處執行實驗。實驗結果會顯示各項目的評分、通過／不通過狀態及版本標籤。
• Trace 評分：在 Observability 部分，針對任何歷史 Trace 或 span 執行評分器，以評估過往互動。可按 Agent 或 Workflow 篩選評分。

後續步驟

• 使用 Quick Checks，快速對文字及 Tool 使用情況作出確定性斷言
• 加入 gate 和 verdict，強制執行硬性要求及質素門檻
• 測試多輪對話，了解行為如何在連續多輪互動中逐步呈現
• 在建立自訂評分器指南中，了解如何建立自己的評分器
• 在內置評分器部分探索內置評分器
• 使用 Studio 測試評分器
• 📹 Mastra Evals 工作坊