MastraScorer
MastraScorer 類別是 Mastra 中所有評分器的基礎類別。它提供標準的 .run() 方法來評估輸入／輸出組合，並支援依照 preprocess → analyze → generateScore → generateReason 流程執行的多步驟評分 Workflow。
大多數使用者應透過 createScorer 建立評分器執行個體。不建議直接具現化 MastraScorer。
如何取得 MastraScorer 執行個體「how-to-get-a-mastrascorer-instance」的直接連結
使用 createScorer factory 函式，它會傳回 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-method」的直接連結
.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() 輸入「run-input」的直接連結
input:
output:
runId:
requestContext:
groundTruth:
.run() 傳回值「run-returns」的直接連結
runId:
score:
reason:
preprocessStepResult:
analyzeStepResult:
preprocessPrompt:
analyzePrompt:
generateScorePrompt:
generateReasonPrompt:
judge:
裁判結果「裁判結果」的直接連結
選填的 judge 記錄包含以提示詞為基礎的評分器步驟呼叫裁判模型的詳細資訊。已知的 key 為 preprocess、analyze、generateScore 與 generateReason。每個 key 都包含依順序排列的 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[] }
>
>
使用步驟 key 來存取其裁判執行詳情：
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 值描述的是提示詞邏輯步驟的執行結果，而非受評估回應的品質。結構化輸出的後援機制若最終成功，會建立一筆 success 執行記錄，且其 attemptCount 大於一。若用盡所有嘗試，則會建立一筆 failed 執行記錄。
成功的執行需要經過驗證的 output 與標準化的 usage。失敗的執行需要 error 摘要，且只會包含 runtime 收到的證據。只有在後續 callback 或協調作業失敗前已驗證輸出時，失敗的執行才會包含 output。Mastra 不會剖析 rawOutput 來建立 output。
attemptCount 計算裁判呼叫次數，其中包括結構化輸出的後援嘗試。modelCallCount 計算這些嘗試中已完成的模型步驟數。durationMs 涵蓋完整的提示詞步驟執行時間。
函式步驟不會建立 judge 項目。此記錄中的用量屬於評分器的裁判模型，而非受評估的 Agent 或 Workflow。彙總成功執行時，請依 status 篩選。彙總所有已完成的 Provider 用量時，請包含兩種狀態。選填的 cost 欄位只會出現在直接回報具權威性之成本、來源與單位的成功執行記錄上。
使用 Mastra metrics 查詢多次評分器執行的彙總用量、延遲與估計成本。judge 記錄只描述一次評分器執行，不會查詢 metrics 或 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:
completedSteps:
result:
result 快照包含已完成階段的輸出與裁判執行證據。例如，若 generateReason 在 generateScore 傳回 0 後失敗，error.result.score 會是 0，generateScore 執行的 status: 'success'，而 generateReason 執行的 status: 'failed'。此次執行仍視為失敗。
提示詞失敗時可能建立 error.result，其中只包含執行識別資訊、輸入與一筆失敗的 judge 項目。若函式階段在產生評分器欄位前失敗，則不會建立結果。
JSON.stringify(error) 會使用標準 MastraError 序列化方式，並省略 result，包括成功與失敗的裁判證據。如需評分器成品或失敗時的原始輸出，請明確讀取 result。
記憶體內的實驗結果可保留評分器失敗前已完成的分數或理由，以及 error、failedStep 與 completedSteps。該評分器仍會視為失敗，復原的分數也不會寫入舊版的成功分數儲存空間。
步驟執行流程「步驟執行流程」的直接連結
呼叫 .run() 時，MastraScorer 會依下列順序執行已定義的步驟：
- preprocess（選填）：擷取或轉換資料
- analyze（選填）：處理輸入／輸出與預先處理過的資料
- generateScore（必要）：計算數值分數
- generateReason（選填）：提供分數的說明
每個步驟都會收到先前步驟的結果，因此你可以建立複雜的評估 pipeline。
使用範例「使用範例」的直接連結
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 參考文件。