마스트라스코어러
그만큼MastraScorer클래스는 마스트라의 모든 득점자의 기본 클래스입니다. 표준을 제공합니다.run()입력/출력 쌍을 평가하는 방법이며 전처리 → 분석 → generateScore → generateReason 실행 흐름을 통해 다단계 채점 Workflow를 지원합니다.
대부분의 사용자는 createScorer를 사용하여 채점기 인스턴스를 생성합니다. MastraScorer를 직접 인스턴스화하는 것은 권장하지 않습니다.
얻는 방법MastraScorer instancehow-to-get-a-mastrascorer-instance에 대한 직접 링크
MastraScorer 인스턴스를 반환하는 createScorer 팩터리 함수를 사용하세요.
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() 메서드는 채점기를 실행하고 입력/출력 쌍을 평가하는 기본 방법입니다. 정의한 단계(전처리 → 분석 → 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 레코드에는 Prompt 기반 채점기 단계에서 수행된 심판 Model 호출의 세부 정보가 포함됩니다. 알려진 키는 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[] }
>
>
심사위원 실행 세부정보에 액세스하려면 단계 키를 사용하세요.
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 값은 평가된 응답의 품질이 아니라 논리적 Prompt 단계 실행의 결과를 설명합니다. 최종적으로 성공한 구조화 출력 폴백은 attemptCount가 1보다 큰 하나의 success 실행을 생성합니다. 모든 시도가 소진되면 하나의 failed 실행이 생성됩니다.
성공한 실행에는 검증된 output과 정규화된 usage가 필요합니다. 실패한 실행에는 error 요약이 필요하며 런타임이 수신한 증거만 포함합니다. 이후 콜백 또는 오케스트레이션 오류가 발생하기 전에 출력이 검증된 경우에만 실패한 실행에 output이 포함됩니다. Mastra는 rawOutput을 파싱하여 output을 생성하지 않습니다.
attemptCount는 구조화 출력 폴백을 포함한 심판 호출 횟수를 계산합니다. modelCallCount는 이러한 시도에서 완료된 Model 단계 수를 계산합니다. durationMs는 전체 Prompt 단계 실행 시간을 포함합니다.
함수 단계는 judge 항목을 생성하지 않습니다. 이 레코드의 사용량은 평가 중인 Agent나 Workflow가 아니라 채점기의 심판 Model에 속합니다. 성공한 실행을 집계할 때는 status로 필터링하세요. 완료된 모든 Provider 사용량을 집계할 때는 두 상태를 모두 포함하세요. 선택적 cost 필드는 신뢰할 수 있는 비용, 출처, 단위를 직접 보고하는 성공한 실행에만 존재합니다.
Mastra 메트릭을 사용하여 채점기 실행 전반의 집계 사용량, 지연 시간, 예상 비용을 쿼리합니다. judge 레코드는 한 번의 채점기 실행을 설명하며 메트릭이나 Trace를 쿼리하지 않습니다.
실패한 실행실패한 실행에 대한 직접 링크
채점기 단계가 실패하면 .run() 프로미스도 실패합니다. 완료된 단계와 해당 단계가 생성한 결과를 검사하려면 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 fails after generateScore returns 0, error.result.score is 0, the generateScore execution has status: 'success', and the generateReason execution has status: 'failed'. The run remains failed.
초기 Prompt 단계가 실패하면 실행 ID, 입력, 실패한 judge 항목만 포함된 error.result가 생성될 수 있습니다. 채점기 필드를 생성하기 전에 실패한 함수 단계는 결과를 생성하지 않습니다.
JSON.stringify(error)는 표준 MastraError 직렬화를 사용하며 성공 및 실패한 심판 증거를 포함한 result를 생략합니다. 채점기 산출물이나 실패한 원시 출력이 필요하면 result를 명시적으로 읽으세요.
인메모리 실험 결과는 실패한 채점기의 완료된 점수나 이유를 error, failedStep, completedSteps와 함께 저장할 수 있습니다. 채점기는 여전히 실패한 것으로 처리되며 복구된 점수는 레거시 성공 점수 저장소에 기록되지 않습니다.
단계 실행 흐름단계 실행 흐름에 대한 직접 링크
.run()을 호출하면 MastraScorer가 정의된 단계를 다음 순서로 실행합니다.
- 전처리(선택): 데이터를 추출하거나 변환합니다.
- 분석하다(선택): 입력/출력 및 전처리된 데이터를 처리합니다.
- 생성점수(필수): 숫자 점수를 계산합니다.
- 생성 이유(선택): 점수에 대한 설명을 제공합니다.
각 단계는 이전 단계의 결과를 수신하므로 복잡한 평가 파이프라인을 구축할 수 있습니다.
사용예사용예에 대한 직접 링크
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 참조를 확인하세요.