createScorer
Mastra는 통합된createScorer입력/출력 쌍을 평가하기 위해 사용자 정의 채점자를 정의할 수 있는 팩토리입니다. 각 평가 단계에 기본 JavaScript 함수 또는 LLM 기반 Prompt 개체를 사용할 수 있습니다. 사용자 정의 채점자를 Agent 및 Workflow 단계에 추가할 수 있습니다.
맞춤 채점자를 만드는 방법맞춤 채점자를 만드는 방법에 대한 직접 링크
createScorer 팩터리를 사용해 이름, 설명, 선택적 심판 구성을 포함하는 채점기를 정의합니다. 그런 다음 단계 메서드를 연결하여 평가 파이프라인을 구축합니다. 최소한 generateScore 단계는 제공해야 합니다.
Prompt 객체 단계는 description + createPrompt로 표현되는 단계 구성입니다(preprocess/analyze의 경우 outputSchema도 포함). 이러한 단계는 심판 LLM을 호출합니다. 함수 단계는 일반 함수이며 심판을 호출하지 않습니다.
import { createScorer } from '@mastra/core/evals'
const scorer = createScorer({
id: 'my-custom-scorer',
name: 'My Custom Scorer', // Optional, defaults to id
description: 'Evaluates responses based on custom criteria',
type: 'agent', // Optional: for agent evaluation with automatic typing
judge: {
model: myModel,
instructions: 'You are an expert evaluator...',
},
})
.preprocess({/* step config */})
.analyze({/* step config */})
.generateScore(({ run, results }) => {
// Return a number
})
.generateReason({/* step config */})
createScorer옵션createscorer-options에 대한 직접 링크
id:
name을 제공하지 않으면 이름으로 사용됩니다.name?:
id를 사용합니다.description:
judge?:
model:
instructions:
jsonPromptInjection?:
inputProcessors?:
outputProcessors?:
errorProcessors?:
processAPIError를 구현하며 LLM API 거부를 검사하고 재시도를 지시할 수 있습니다(예: StreamErrorRetryProcessor). 레거시 Model 어댑터는 generateLegacy()를 사용하므로 오류 프로세서를 실행하지 않습니다.maxProcessorRetries?:
type?:
prepareRun?:
이 함수는 단계 메서드를 연결할 수 있는 채점기 빌더를 반환합니다. .run() 메서드와 해당 입력/출력에 대한 자세한 내용은 MastraScorer 참조를 확인하세요.
심판은 Prompt 객체로 정의된 단계(Prompt 모드의 preprocess, analyze, generateScore, generateReason)에서만 실행됩니다. 함수 단계만 사용하면 심판이 호출되지 않으며 검사할 LLM 출력도 없습니다. 이 경우 점수와 이유는 함수에서 생성해야 합니다.
Prompt 객체 단계가 실행되면 구조화된 LLM 출력이 해당 결과 필드(preprocessStepResult, analyzeStepResult 또는 generateScore의 calculateScore가 사용하는 값)에 저장됩니다.
심사위원 요청 재시도심사위원 요청 재시도에 대한 직접 링크
심판의 errorProcessors 구성을 사용하여 실패한 심판 요청 내의 일시적 오류를 재시도하세요. 이 구성은 채점기 Workflow, Trace 대상, 배치 항목, 점수 쓰기 또는 완료된 채점기 단계를 재시도하지 않습니다.
@mastra/core 1.49.0에는 채점기 오류 프로세서 구성이 포함되어 있지 않습니다. 이 구성을 사용하기 전에 채점기 프로세서를 지원하는 버전으로 업그레이드하거나 해당 변경 사항만 백포트하세요.
다음 예에서는 하나의 제한된 재시도 예산을 사용합니다. 프로세서의 maxRetries와 judge.maxProcessorRetries를 같은 값으로 설정합니다. Model 재시도가 프로세서 시도 횟수를 배가하지 않도록 내부 심판 Agent의 Model 재시도는 기본값 0으로 유지하세요.
import { createScorer } from '@mastra/core/evals'
import { StreamErrorRetryProcessor } from '@mastra/core/processors'
const isTransientNetworkError = (error: unknown) =>
error instanceof Error && /ECONNRESET|ETIMEDOUT|socket hang up/i.test(error.message)
const retryProcessor = new StreamErrorRetryProcessor({
maxRetries: 2,
maxRetryAfterMs: 30_000,
delayMs: ({ retryCount }) => Math.min(1_000 * 2 ** retryCount, 30_000),
matchers: [isTransientNetworkError],
retryUnknownErrors: false,
})
export const responseQuality = createScorer({
id: 'response-quality',
description: 'Scores response quality',
judge: {
model: myModel,
instructions: 'Return a score and concise reason.',
errorProcessors: [retryProcessor],
maxProcessorRetries: 2,
},
})
.generateScore({
description: 'Score the response quality.',
createPrompt: ({ run }) => `Score: ${run.output}`,
})
.generateReason({
description: 'Explain the score.',
createPrompt: () => 'Explain the score.',
})
이 구성을 사용하면 실패한 요청에 최대 3번의 Provider 시도(초기 요청과 프로세서 재시도 2회)가 이루어집니다. generateScore가 완료된 후 generateReason에서 재시도 가능한 오류가 발생하면 generateReason만 재시도됩니다.
StreamErrorRetryProcessor는 재시도 가능한 Provider 메타데이터와 범위가 좁은 사용자 정의 매처를 따릅니다. retryUnknownErrors는 기본적으로 비활성화되어 있으므로 인증, 잘못된 요청 및 컨텍스트 길이 오류는 명시적으로 일치시키지 않는 한 즉시 실패합니다. 기본적으로 Retry-After 값을 30_000밀리초로 제한합니다. 이 상한을 변경하려면 maxRetryAfterMs를 사용하세요.
외부 채점자나 Workflow 재시도를 추가하지 마세요. 의도적으로 추가 시도를 허용하지 않는 한 0이 아닌 Model 재시도 설정을 이 프로세서와 결합하지 마십시오.
한 단계에 대한 재시도 재정의한 단계에 대한 재시도 재정의에 대한 직접 링크
단계의 judge 구성은 채점기 수준의 심판 필드를 재정의합니다. 프로세서 배열은 채점기 수준의 배열을 대체합니다. 채점기 수준의 숫자 상한을 상속하려면 단계 구성에서 maxProcessorRetries를 생략하세요.
조정된 프로세서 재시도에는 Mastra의 현재 생성 API를 사용하는 심판 Model이 필요합니다. 레거시 Model 어댑터는 generateLegacy()를 호출하고 오류 프로세서를 우회하며, 해당 API의 별도 AI SDK maxRetries 기본값인 2를 사용합니다.
유형 안전유형 안전에 대한 직접 링크
더 나은 유형 추론 및 IntelliSense 지원을 위해 채점자를 만들 때 입력/출력 유형을 지정할 수 있습니다.
Agent 유형 바로가기Agent 유형 바로가기에 대한 직접 링크
Agent를 평가하려면 type: 'agent'를 사용하여 Agent 입력/출력에 맞는 타입을 자동으로 가져오세요.
import { createScorer } from '@mastra/core/evals'
// Agent scorer with automatic typing
const agentScorer = createScorer({
id: 'agent-response-quality',
description: 'Evaluates agent responses',
type: 'agent', // Automatically provides ScorerRunInputForAgent/ScorerRunOutputForAgent
})
.preprocess(({ run }) => {
// run.input is automatically typed as ScorerRunInputForAgent
const userMessage = run.inputData.inputMessages[0]?.content
return { userMessage }
})
.generateScore(({ run, results }) => {
// run.output is automatically typed as ScorerRunOutputForAgent
const response = run.output[0]?.content
return response.length > 10 ? 1.0 : 0.5
})
제네릭을 사용한 사용자 정의 유형제네릭을 사용한 사용자 정의 유형에 대한 직접 링크
사용자 정의 입력/출력 유형의 경우 일반적인 접근 방식을 사용하십시오.
import { createScorer } from '@mastra/core/evals'
type CustomInput = { query: string; context: string[] }
type CustomOutput = { answer: string; confidence: number }
const customScorer = createScorer<CustomInput, CustomOutput>({
id: 'custom-scorer',
description: 'Evaluates custom data',
}).generateScore(({ run }) => {
// run.input is typed as CustomInput
// run.output is typed as CustomOutput
return run.output.confidence
})
내장 Agent 유형내장 Agent 유형에 대한 직접 링크
ScorerRunInputForAgent- Agent 평가를 위한inputMessages,rememberedMessages,systemMessages,taggedSystemMessages포함ScorerRunOutputForAgent- Agent 응답 메시지 배열 이러한 유형을 사용하면 자동 완성, 컴파일 시간 유효성 검사 및 채점 논리에 대한 더 나은 문서가 제공됩니다.
Agent 유형을 통한 추적 점수 매기기Agent 유형을 통한 추적 점수 매기기에 대한 직접 링크
type: 'agent'를 사용하면 채점기를 Agent에 직접 추가하거나 Agent 상호 작용의 Trace를 채점하는 데 모두 사용할 수 있습니다. 채점기는 Trace 데이터를 적절한 Agent 입력/출력 형식으로 자동 변환합니다.
const agentTraceScorer = createScorer({
id: 'agent-trace-length',
description: 'Evaluates agent response length',
type: 'agent',
}).generateScore(({ run }) => {
// Trace data is automatically transformed to agent format
const userMessages = run.inputData.inputMessages
const agentResponse = run.output[0]?.content
// Score based on response length
return agentResponse?.length > 50 ? 0 : 1
})
// Register with Mastra for trace scoring
const mastra = new Mastra({
scorers: {
agentTraceScorer,
},
})
단계 메서드 서명단계 메서드 서명에 대한 직접 링크
전처리전처리에 대한 직접 링크
분석 전에 데이터를 추출하거나 변환할 수 있는 선택적 전처리 단계입니다.
기능 모드:기능:({ run, results }) => any
run.input:
[{ role: 'user', content: 'hello world' }]). 채점기가 Workflow에서 사용되는 경우 Workflow의 입력입니다.run.output:
run.runId:
run.requestContext?:
results:
반환값: any
이 메서드는 모든 값을 반환할 수 있습니다. 반환된 값은 후속 단계에서 preprocessStepResult로 사용할 수 있습니다.
Prompt 개체 모드:
description:
outputSchema:
createPrompt:
judge?:
분석하다분석하다에 대한 직접 링크
입력/출력 및 전처리된 데이터를 처리하는 선택적 분석 단계입니다.
기능 모드:기능:({ run, results }) => any
run.input:
[{ role: 'user', content: 'hello world' }]). 채점기가 Workflow에서 사용되는 경우 Workflow의 입력입니다.run.output:
run.runId:
run.requestContext?:
results.preprocessStepResult?:
반환값: any
이 메서드는 모든 값을 반환할 수 있습니다. 반환된 값은 후속 단계에서 analyzeStepResult로 사용할 수 있습니다.
Prompt 개체 모드:
description:
outputSchema:
createPrompt:
judge?:
generateScoregeneratescore에 대한 직접 링크
필수의최종 수치 점수를 계산하는 단계입니다.
기능 모드:기능:({ run, results }) => number
run.input:
[{ role: 'user', content: 'hello world' }]). 채점기가 Workflow에서 사용되는 경우 Workflow의 입력입니다.run.output:
run.runId:
run.requestContext?:
results.preprocessStepResult?:
results.analyzeStepResult?:
반환값: number
이 메서드는 숫자 점수를 반환해야 합니다.
Prompt 개체 모드:
description:
outputSchema:
createPrompt:
judge?:
Prompt 객체 모드를 사용하는 경우 LLM 출력을 숫자 점수로 변환하는 calculateScore 함수도 제공해야 합니다.
calculateScore:
generateReasongeneratereason에 대한 직접 링크
점수에 대한 설명을 제공하는 선택적 단계입니다.
기능 모드:기능:({ run, results, score }) => string
run.input:
[{ role: 'user', content: 'hello world' }]). 채점기가 Workflow에서 사용되는 경우 Workflow의 입력입니다.run.output:
run.runId:
run.requestContext?:
results.preprocessStepResult?:
results.analyzeStepResult?:
score:
반환값: string
이 메서드는 점수를 설명하는 문자열을 반환해야 합니다.
Prompt 개체 모드:
description:
createPrompt:
judge?:
모든 단계 기능은 비동기식일 수 있습니다.