> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 마스트라스코어러

그만큼`MastraScorer`클래스는 마스트라의 모든 득점자의 기본 클래스입니다. 표준을 제공합니다`.run()`입력/출력 쌍을 평가하는 방법이며 전처리 → 분석 → generateScore → generateReason 실행 흐름을 통해 다단계 채점 Workflow를 지원합니다.

대부분의 사용자는 [`createScorer`](https://mastra.zisheng.pro/ko/reference/evals/create-scorer)를 사용하여 채점기 인스턴스를 생성합니다. `MastraScorer`를 직접 인스턴스화하는 것은 권장하지 않습니다.

## 얻는 방법`MastraScorer` instance

`MastraScorer` 인스턴스를 반환하는 `createScorer` 팩터리 함수를 사용하세요.

```typescript
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()` 메서드는 채점기를 실행하고 입력/출력 쌍을 평가하는 기본 방법입니다. 정의한 단계(전처리 → 분석 → generateScore → generateReason)를 통해 데이터를 처리하고 점수, 근거, 중간 결과가 포함된 상세 결과 객체를 반환합니다.

```typescript
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`): 정의된 경우 전처리 단계의 결과입니다(선택 사항).

**analyzeStepResult** (`any`): 정의된 경우 분석 단계의 결과입니다(선택 사항).

**preprocessPrompt** (`string`): 정의된 경우 전처리 Prompt입니다(선택 사항).

**analyzePrompt** (`string`): 정의된 경우 분석 Prompt입니다(선택 사항).

**generateScorePrompt** (`string`): 정의된 경우 점수 생성 Prompt입니다(선택 사항).

**generateReasonPrompt** (`string`): 정의된 경우 근거 생성 Prompt입니다(선택 사항).

**judge** (`ScorerJudgeResults`): Prompt 기반 채점기 단계의 실행 세부 정보입니다(있는 경우, 선택 사항).

### 심사위원 결과

선택적 `judge` 레코드에는 Prompt 기반 채점기 단계에서 수행된 심판 Model 호출의 세부 정보가 포함됩니다. 알려진 키는 `preprocess`, `analyze`, `generateScore`, `generateReason`입니다. 각 키에는 순서가 지정된 `executions` 배열이 포함됩니다.

```typescript
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[] }
  >
>
```

심사위원 실행 세부정보에 액세스하려면 단계 키를 사용하세요.

```typescript
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`를 포착하세요.

```typescript
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`): 완료된 채점기 단계의 출력과 시도한 Prompt 단계의 심판 실행 증거입니다. 둘 다 사용할 수 없으면 이 속성은 생략됩니다.

그만큼`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가 정의된 단계를 다음 순서로 실행합니다.

1. **전처리**(선택): 데이터를 추출하거나 변환합니다.
2. **분석하다**(선택): 입력/출력 및 전처리된 데이터를 처리합니다.
3. **생성점수**(필수): 숫자 점수를 계산합니다.
4. **생성 이유**(선택): 점수에 대한 설명을 제공합니다.

각 단계는 이전 단계의 결과를 수신하므로 복잡한 평가 파이프라인을 구축할 수 있습니다.

## 사용예

```typescript
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 참조](https://mastra.zisheng.pro/ko/reference/evals/create-scorer)를 확인하세요.