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

# createScorer

Mastra는 통합된`createScorer`입력/출력 쌍을 평가하기 위해 사용자 정의 채점자를 정의할 수 있는 팩토리입니다. 각 평가 단계에 기본 JavaScript 함수 또는 LLM 기반 Prompt 개체를 사용할 수 있습니다. 사용자 정의 채점자를 Agent 및 Workflow 단계에 추가할 수 있습니다.

## 맞춤 채점자를 만드는 방법

`createScorer` 팩터리를 사용해 이름, 설명, 선택적 심판 구성을 포함하는 채점기를 정의합니다. 그런 다음 단계 메서드를 연결하여 평가 파이프라인을 구축합니다. 최소한 `generateScore` 단계는 제공해야 합니다. **Prompt 객체 단계**는 `description` + `createPrompt`로 표현되는 단계 구성입니다(`preprocess`/`analyze`의 경우 `outputSchema`도 포함). 이러한 단계는 심판 LLM을 호출합니다. **함수 단계**는 일반 함수이며 심판을 호출하지 않습니다.

```typescript
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`옵션

**id** (`string`): 채점기의 고유 식별자입니다. name을 제공하지 않으면 이름으로 사용됩니다.

**name** (`string`): 채점기의 이름입니다. 제공하지 않으면 기본값으로 id를 사용합니다.

**description** (`string`): 채점기가 수행하는 작업에 대한 설명입니다.

**judge** (`object`): LLM 기반 단계를 위한 선택적 심판 구성입니다.

**judge.model** (`LanguageModel`): 평가에 사용할 LLM Model 인스턴스입니다.

**judge.instructions** (`string`): LLM을 위한 시스템 Prompt/지침입니다.

**judge.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): 심판의 구조화된 출력 스키마가 Model에 전달되는 방식을 제어합니다. 기본값은 'auto'이며, 지원되는 경우 네이티브 구조화 출력을 사용하고 그렇지 않으면 인라인 Prompt 삽입을 사용합니다. 명시적 값은 자동 라우팅을 재정의합니다.

**judge.inputProcessors** (`Processor[]`): 내부 심판 Agent의 메시지가 Model에 도달하기 전에 적용되는 입력 프로세서입니다(예: 수정, 검증).

**judge.outputProcessors** (`Processor[]`): 내부 심판 Agent의 출력이 반환되기 전에 적용되는 출력 프로세서입니다(예: 조정, 변환).

**judge.errorProcessors** (`Processor[]`): Mastra의 현재 생성 API를 사용하는 심판 Model용 오류 프로세서입니다. 이 프로세서는 processAPIError를 구현하며 LLM API 거부를 검사하고 재시도를 지시할 수 있습니다(예: StreamErrorRetryProcessor). 레거시 Model 어댑터는 generateLegacy()를 사용하므로 오류 프로세서를 실행하지 않습니다.

**judge.maxProcessorRetries** (`number`): 오류 프로세서가 한 번의 심판 생성을 재시도할 수 있는 최대 횟수입니다. 이 값을 지정하지 않고 errorProcessors를 구성하면 런타임 기본값은 10입니다. 재시도 예산을 제한하려면 명시적으로 설정하세요.

**type** (`string`): 입력/출력의 타입 지정입니다. 자동 Agent 타입에는 'agent'를 사용합니다. 사용자 정의 타입에는 제네릭 방식을 사용하세요.

**prepareRun** (`(run: ScorerRun) => ScorerRun | Promise<ScorerRun>`): 파이프라인을 실행하기 전에 채점기 실행 데이터를 변환합니다. 메시지를 필터링하거나, 컨텍스트 크기를 제한하거나, 채점기에 필요하지 않은 필드를 제거할 때 사용합니다. \`filterRun()\` 유틸리티는 선언적 옵션으로 이 함수를 생성합니다. 비동기일 수 있습니다.

이 함수는 단계 메서드를 연결할 수 있는 채점기 빌더를 반환합니다. `.run()` 메서드와 해당 입력/출력에 대한 자세한 내용은 [MastraScorer 참조](https://mastra.zisheng.pro/ko/reference/evals/mastra-scorer)를 확인하세요. 심판은 **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`으로 유지하세요.

```typescript
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()`](https://mastra.zisheng.pro/ko/reference/agents/generateLegacy)를 호출하고 오류 프로세서를 우회하며, 해당 API의 별도 AI SDK `maxRetries` 기본값인 `2`를 사용합니다.

## 유형 안전

더 나은 유형 추론 및 IntelliSense 지원을 위해 채점자를 만들 때 입력/출력 유형을 지정할 수 있습니다.

### Agent 유형 바로가기

Agent를 평가하려면 `type: 'agent'`를 사용하여 Agent 입력/출력에 맞는 타입을 자동으로 가져오세요.

```typescript
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
  })
```

### 제네릭을 사용한 사용자 정의 유형

사용자 정의 입력/출력 유형의 경우 일반적인 접근 방식을 사용하십시오.

```typescript
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 유형

- **`ScorerRunInputForAgent`** - Agent 평가를 위한 `inputMessages`, `rememberedMessages`, `systemMessages`, `taggedSystemMessages` 포함
- **`ScorerRunOutputForAgent`** - Agent 응답 메시지 배열 이러한 유형을 사용하면 자동 완성, 컴파일 시간 유효성 검사 및 채점 논리에 대한 더 나은 문서가 제공됩니다.

## Agent 유형을 통한 추적 점수 매기기

`type: 'agent'`를 사용하면 채점기를 Agent에 직접 추가하거나 Agent 상호 작용의 Trace를 채점하는 데 모두 사용할 수 있습니다. 채점기는 Trace 데이터를 적절한 Agent 입력/출력 형식으로 자동 변환합니다.

```typescript
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,
  },
})
```

## 단계 메서드 서명

### 전처리

분석 전에 데이터를 추출하거나 변환할 수 있는 선택적 전처리 단계입니다.

**기능 모드:**&#xAE30;능:`({ run, results }) => any`

**run.input** (`any`): 채점기에 제공되는 입력 레코드입니다. 채점기가 Agent에 추가된 경우 사용자 메시지 배열입니다(예: \[{ role: 'user', content: 'hello world' }]). 채점기가 Workflow에서 사용되는 경우 Workflow의 입력입니다.

**run.output** (`any`): 채점기에 제공되는 출력 레코드입니다. Agent의 경우 일반적으로 Agent의 응답입니다. Workflow의 경우 Workflow의 출력입니다.

**run.runId** (`string`): 이 채점 실행의 고유 식별자입니다.

**run.requestContext** (`object`): 평가 중인 Agent 또는 Workflow 단계의 요청 컨텍스트입니다(선택 사항).

**results** (`object`): 빈 객체입니다(이전 단계 없음).

반환값: `any`\
이 메서드는 모든 값을 반환할 수 있습니다. 반환된 값은 후속 단계에서 `preprocessStepResult`로 사용할 수 있습니다. **Prompt 개체 모드:**

**description** (`string`): 이 전처리 단계가 수행하는 작업에 대한 설명입니다.

**outputSchema** (`StandardJSONSchemaV1`): 전처리 단계의 예상 출력에 대한 표준 JSON Schema입니다.

**createPrompt** (`function`): 함수: ({ run, results }) => string. LLM용 Prompt를 반환합니다.

**judge** (`object`): (선택 사항) 이 단계의 LLM 심판입니다(주 심판을 재정의할 수 있음). 심판 객체 섹션을 참조하세요.

### 분석하다

입력/출력 및 전처리된 데이터를 처리하는 선택적 분석 단계입니다.

**기능 모드:**&#xAE30;능:`({ run, results }) => any`

**run.input** (`any`): 채점기에 제공되는 입력 레코드입니다. 채점기가 Agent에 추가된 경우 사용자 메시지 배열입니다(예: \[{ role: 'user', content: 'hello world' }]). 채점기가 Workflow에서 사용되는 경우 Workflow의 입력입니다.

**run.output** (`any`): 채점기에 제공되는 출력 레코드입니다. Agent의 경우 일반적으로 Agent의 응답입니다. Workflow의 경우 Workflow의 출력입니다.

**run.runId** (`string`): 이 채점 실행의 고유 식별자입니다.

**run.requestContext** (`object`): 평가 중인 Agent 또는 Workflow 단계의 요청 컨텍스트입니다(선택 사항).

**results.preprocessStepResult** (`any`): 정의된 경우 전처리 단계의 결과입니다(선택 사항).

반환값: `any`\
이 메서드는 모든 값을 반환할 수 있습니다. 반환된 값은 후속 단계에서 `analyzeStepResult`로 사용할 수 있습니다. **Prompt 개체 모드:**

**description** (`string`): 이 분석 단계가 수행하는 작업에 대한 설명입니다.

**outputSchema** (`StandardJSONSchemaV1`): 분석 단계의 예상 출력에 대한 표준 JSON Schema입니다.

**createPrompt** (`function`): 함수: ({ run, results }) => string. LLM용 Prompt를 반환합니다.

**judge** (`object`): (선택 사항) 이 단계의 LLM 심판입니다(주 심판을 재정의할 수 있음). 심판 객체 섹션을 참조하세요.

### `generateScore`

**필수의**최종 수치 점수를 계산하는 단계입니다.

**기능 모드:**&#xAE30;능:`({ run, results }) => number`

**run.input** (`any`): 채점기에 제공되는 입력 레코드입니다. 채점기가 Agent에 추가된 경우 사용자 메시지 배열입니다(예: \[{ role: 'user', content: 'hello world' }]). 채점기가 Workflow에서 사용되는 경우 Workflow의 입력입니다.

**run.output** (`any`): 채점기에 제공되는 출력 레코드입니다. Agent의 경우 일반적으로 Agent의 응답입니다. Workflow의 경우 Workflow의 출력입니다.

**run.runId** (`string`): 이 채점 실행의 고유 식별자입니다.

**run.requestContext** (`object`): 평가 중인 Agent 또는 Workflow 단계의 요청 컨텍스트입니다(선택 사항).

**results.preprocessStepResult** (`any`): 정의된 경우 전처리 단계의 결과입니다(선택 사항).

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

반환값: `number`\
이 메서드는 숫자 점수를 반환해야 합니다. **Prompt 개체 모드:**

**description** (`string`): 이 채점 단계가 수행하는 작업에 대한 설명입니다.

**outputSchema** (`StandardJSONSchemaV1`): generateScore 단계의 예상 출력에 대한 표준 JSON Schema입니다.

**createPrompt** (`function`): 함수: ({ run, results }) => string. LLM용 Prompt를 반환합니다.

**judge** (`object`): (선택 사항) 이 단계의 LLM 심판입니다(주 심판을 재정의할 수 있음). 심판 객체 섹션을 참조하세요.

Prompt 객체 모드를 사용하는 경우 LLM 출력을 숫자 점수로 변환하는 `calculateScore` 함수도 제공해야 합니다.

**calculateScore** (`function`): 함수: ({ run, results, analyzeStepResult }) => number. LLM의 구조화된 출력을 숫자 점수로 변환합니다.

### `generateReason`

점수에 대한 설명을 제공하는 선택적 단계입니다.

**기능 모드:**&#xAE30;능:`({ run, results, score }) => string`

**run.input** (`any`): 채점기에 제공되는 입력 레코드입니다. 채점기가 Agent에 추가된 경우 사용자 메시지 배열입니다(예: \[{ role: 'user', content: 'hello world' }]). 채점기가 Workflow에서 사용되는 경우 Workflow의 입력입니다.

**run.output** (`any`): 채점기에 제공되는 출력 레코드입니다. Agent의 경우 일반적으로 Agent의 응답입니다. Workflow의 경우 Workflow의 출력입니다.

**run.runId** (`string`): 이 채점 실행의 고유 식별자입니다.

**run.requestContext** (`object`): 평가 중인 Agent 또는 Workflow 단계의 요청 컨텍스트입니다(선택 사항).

**results.preprocessStepResult** (`any`): 정의된 경우 전처리 단계의 결과입니다(선택 사항).

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

**score** (`number`): generateScore 단계에서 계산된 점수입니다.

반환값: `string`\
이 메서드는 점수를 설명하는 문자열을 반환해야 합니다. **Prompt 개체 모드:**

**description** (`string`): 이 근거 생성 단계가 수행하는 작업에 대한 설명입니다.

**createPrompt** (`function`): 함수: ({ run, results, score }) => string. LLM용 Prompt를 반환합니다.

**judge** (`object`): (선택 사항) 이 단계의 LLM 심판입니다(주 심판을 재정의할 수 있음). 심판 객체 섹션을 참조하세요.

모든 단계 기능은 비동기식일 수 있습니다.