MastraScorer

MastraScorer 類別是 Mastra 中所有評分器的基礎類別。它提供標準 .run() 方法來評估輸入／輸出配對，並支援依 preprocess → analyze → generateScore → generateReason 執行流程運作的多步驟評分 Workflow。

大部分使用者都應使用 createScorer 建立評分器實例。不建議直接實例化 MastraScorer。

如何取得 MastraScorer 實例

使用 createScorer 工廠函式，它會傳回一個 MastraScorer 實例：

import { createScorer } from '@mastra/core/evals'

const scorer = createScorer({
  name: 'My Custom Scorer',
  description: 'Evaluates responses based on custom criteria',
}).generateScore(({ run, results }) => {
  // scoring logic
  return 0.85
})

// scorer is now a MastraScorer instance

.run() 方法

.run() 方法是執行評分器及評估輸入／輸出配對的主要方式。它會讓資料依序經過你定義的步驟（preprocess → analyze → generateScore → generateReason），並傳回包含分數、理由及中間結果的詳細結果物件。

const result = await scorer.run({
  input: 'What is machine learning?',
  output: 'Machine learning is a subset of artificial intelligence...',
  runId: 'optional-run-id',
  requestContext: {/* optional context */},
})

.run() 輸入

input:

any

要評估的輸入資料。視乎評分器的要求，可以是任何類型。

output:

any

要評估的輸出資料。視乎評分器的要求，可以是任何類型。

runId:

string

此評分執行的可選唯一識別碼。

requestContext:

any

來自受評估 Agent 或 Workflow 步驟的可選請求情境。

groundTruth:

any

在評分期間用作比較的可選預期或參考輸出。使用 runEvals 時會自動傳入。

.run() 傳回值

runId:

string

此評分執行的唯一識別碼。

score:

number

由 generateScore 步驟計算的數值分數。

reason:

string

分數的解釋（如已定義 generateReason 步驟；可選）。

preprocessStepResult:

any

preprocess 步驟的結果（如已定義；可選）。

analyzeStepResult:

any

analyze 步驟的結果（如已定義；可選）。

preprocessPrompt:

string

preprocess 提示（如已定義；可選）。

analyzePrompt:

string

analyze 提示（如已定義；可選）。

generateScorePrompt:

string

產生分數的提示（如已定義；可選）。

generateReasonPrompt:

string

產生理由的提示（如已定義；可選）。

judge:

ScorerJudgeResults

以提示為基礎的評分器步驟之執行詳情（如有；可選）。

Judge 結果

可選的 judge 記錄包含以提示為基礎的評分器步驟所作 judge 模型呼叫的詳情。其已知鍵為 preprocess、analyze、generateScore 及 generateReason。每個鍵都包含一個依序排列的 executions 陣列。

interface ScorerJudgeExecutionBase {
  prompt: string
  judgeModelId: string
  judgeProvider?: string
  attemptCount: number
  modelCallCount: number
  durationMs: number
}

interface ScorerJudgeExecutionSuccess extends ScorerJudgeExecutionBase {
  status: 'success'
  output: JSONValue
  usage: ScorerJudgeUsage
  cost?: {
    amount: number
    unit: string
    source: string
  }
}

interface ScorerJudgeExecutionFailure extends ScorerJudgeExecutionBase {
  status: 'failed'
  output?: JSONValue
  rawOutput?: string
  usage?: ScorerJudgeUsage
  finishReason?: string
  error: {
    name: string
    message: string
    code?: string
  }
}

type ScorerJudgeExecution = ScorerJudgeExecutionSuccess | ScorerJudgeExecutionFailure

interface ScorerJudgeUsage {
  inputTokens?: number
  outputTokens?: number
  totalTokens?: number
  reasoningTokens?: number
  cachedInputTokens?: number
  cacheCreationInputTokens?: number
}

type ScorerJudgeResults = Partial<
  Record<
    'preprocess' | 'analyze' | 'generateScore' | 'generateReason',
    { executions: ScorerJudgeExecution[] }
  >
>

使用步驟鍵存取其 judge 執行詳情：

const execution = result.judge?.generateScore?.executions[0]

console.log(execution?.status)
console.log(execution?.judgeModelId)
console.log(execution?.usage?.totalTokens)
console.log(execution?.durationMs)

status 值描述邏輯提示步驟的執行結果，而非受評估回應的質素。結構化輸出後備機制最終成功時，會建立一筆 attemptCount 大於一的 success 執行記錄。用盡所有嘗試後，則會建立一筆 failed 執行記錄。

成功的執行必須具備已驗證的 output 及標準化的 usage。失敗的執行必須具備 error 摘要，並只包含執行階段收到的證據。只有在輸出已通過驗證，但其後的回呼或編排失敗時，失敗的執行才會包含 output。Mastra 不會剖析 rawOutput 來建立 output。

attemptCount 計算 judge 調用次數，包括結構化輸出後備機制。modelCallCount 計算這些嘗試中已完成的模型步驟數目。durationMs 涵蓋整個提示步驟的執行時間。

函式步驟不會建立 judge 項目。此記錄中的用量屬於評分器的 judge 模型，而非受評估的 Agent 或 Workflow。彙總成功執行時，請按 status 篩選。彙總所有已完成的 Provider 用量時，請包括兩種狀態。可選的 cost 欄位只會出現在直接報告具權威性的成本、來源及單位之成功執行中。

使用 Mastra 指標查詢各次評分器執行的彙總用量、延遲及估算成本。judge 記錄描述單次評分器執行，並不會查詢指標或 Trace。

失敗的執行

評分器階段失敗時，.run() promise 仍會被拒絕。捕捉 ScorerRunError，即可檢查已完成的階段及其產生的任何結果：

import { ScorerRunError } from '@mastra/core/evals'

try {
  const result = await scorer.run({ input, output })
  console.log(result.score)
} catch (error) {
  if (error instanceof ScorerRunError) {
    console.log(error.failedStep)
    console.log(error.completedSteps)
    console.log(error.result?.score)

    const failedExecution = error.result?.judge?.[error.failedStep]?.executions.find(
      execution => execution.status === 'failed',
    )
    console.log(failedExecution?.error)
  }

  throw error
}

ScorerRunError 提供以下屬性：

failedStep:

ScorerStepName

失敗的評分器階段。

completedSteps:

ScorerStepName[]

失敗前已完成的評分器階段，按執行次序排列。

result:

ScorerRunResultSnapshot | undefined

已完成評分器階段的輸出，以及曾嘗試的提示階段之 judge 執行證據。兩者皆無時會省略此屬性。

result 快照包含已完成階段的輸出及 judge 執行證據。例如，如果 generateScore 傳回 0 後 generateReason 失敗，error.result.score 會是 0，generateScore 執行的 status: 'success'，而 generateReason 執行的 status: 'failed'。整次執行仍視為失敗。

提示失敗時，可以建立只包含執行識別資料、輸入及失敗 judge 項目的 error.result。函式階段若在產生評分器欄位前失敗，則不會建立結果。

JSON.stringify(error) 會使用標準 MastraError 序列化，並省略 result，包括成功及失敗的 judge 證據。需要評分器產出內容或原始失敗輸出時，請明確讀取 result。

記憶體內的實驗結果可保留失敗評分器已完成的分數或理由，以及 error、failedStep 和 completedSteps。該評分器仍視為失敗，而復原的分數不會寫入舊有的成功分數儲存空間。

步驟執行流程

呼叫 .run() 時，MastraScorer 會按以下次序執行已定義的步驟：

1. preprocess（可選）：擷取或轉換資料
2. analyze（可選）：處理輸入／輸出及預先處理的資料
3. generateScore（必要）：計算數值分數
4. generateReason（可選）：提供分數的解釋

每個步驟都會接收先前步驟的結果，讓你可以建立複雜的評估管線。

使用範例

const scorer = createScorer({
  name: 'Quality Scorer',
  description: 'Evaluates response quality',
})
  .preprocess(({ run }) => {
    // Extract key information
    return { wordCount: run.output.split(' ').length }
  })
  .analyze(({ run, results }) => {
    // Analyze the response
    const hasSubstance = results.preprocessStepResult.wordCount > 10
    return { hasSubstance }
  })
  .generateScore(({ results }) => {
    // Calculate score
    return results.analyzeStepResult.hasSubstance ? 1.0 : 0.0
  })
  .generateReason(({ score, results }) => {
    // Explain the score
    const wordCount = results.preprocessStepResult.wordCount
    return `Score: ${score}. Response has ${wordCount} words.`
  })

// Use the scorer
const result = await scorer.run({
  input: 'What is machine learning?',
  output: 'Machine learning is a subset of artificial intelligence...',
})

console.log(result.score) // 1.0
console.log(result.reason) // "Score: 1.0. Response has 12 words."

整合

MastraScorer 實例可用於 Agent 及 Workflow 步驟。

有關定義自訂評分邏輯的詳細資料，請參閱 createScorer 參考。