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

# 득점자 개요

기존 소프트웨어 테스트에는 명확한 통과/실패 조건이 있지만 AI 출력은 비결정적이며 동일한 입력에 따라 달라질 수 있습니다.**Scorers**Agent 품질 측정을 위한 수량화 가능한 지표를 제공하여 이러한 격차를 해소하는 데 도움을 줍니다.

채점자는 Model 기반 판정, 규칙 기반 및 통계적 방법을 사용하여 Agent 출력을 평가하는 자동화된 테스트입니다. 채점자는 출력이 평가 기준을 얼마나 잘 충족하는지 수치화한 **점수**(일반적으로 0과 1 사이의 값)를 반환합니다. 이러한 점수를 통해 AI 시스템의 성능을 객관적으로 추적하고 다양한 접근 방식을 비교하며 개선할 영역을 식별할 수 있습니다. 자체 Prompt와 채점 함수를 사용해 채점자를 커스터마이즈할 수도 있습니다. 채점자는 클라우드에서 실행되어 실시간 결과를 캡처할 수 있습니다. 그러나 채점자는 CI/CD 파이프라인의 일부일 수도 있으므로 시간이 지남에 따라 Agent를 테스트하고 모니터링할 수 있습니다.

:::tip\[📹 보기]

Evals 소개와 Agent 품질을 판단하는 방법은 [Mastra Evals 개요](https://www.youtube.com/watch?v=12WN6u2DrBk)를 참조하세요. :::

## 득점자의 유형

Mastra는 각각 특정 목적을 수행하는 다양한 종류의 득점자를 제공합니다. 다음은 몇 가지 일반적인 유형입니다.

1. **텍스트 득점자**: Agent 응답의 정확성, 신뢰성, 상황 이해도를 평가합니다.
2. **분류 채점자**: 미리 정의된 카테고리를 기반으로 데이터 분류의 정확성을 측정합니다.
3. **신속한 엔지니어링 득점자**: 다양한 명령어와 입력 형식의 영향을 살펴보세요.

## 설치

Mastra의 득점자 기능에 액세스하려면 다음을 설치하십시오.`@mastra/evals` package.

**npm**:

```bash
npm install @mastra/evals@latest
```

**pnpm**:

```bash
pnpm add @mastra/evals@latest
```

**Yarn**:

```bash
yarn add @mastra/evals@latest
```

**Bun**:

```bash
bun add @mastra/evals@latest
```

## 실시간 평가

**실시간 평가**Agent와 Workflow가 작동할 때 실시간으로 AI 출력의 점수를 자동으로 매길 수 있습니다. 평가를 수동으로 또는 일괄적으로 실행하는 대신 채점자는 AI 시스템과 함께 비동기식으로 실행되어 지속적인 품질 모니터링을 제공합니다.

### Agent에 득점자 추가

Agent에 기본 제공 채점자를 추가하여 출력을 자동으로 평가할 수 있습니다. 사용 가능한 모든 옵션은 [기본 제공 채점자 전체 목록](https://mastra.zisheng.pro/ko/docs/evals/built-in-scorers)을 참조하세요.

```typescript
import { Agent } from '@mastra/core/agent'
import { createAnswerRelevancyScorer, createToxicityScorer } from '@mastra/evals/scorers/prebuilt'

export const evaluatedAgent = new Agent({
  id: 'evaluated-agent',
  scorers: {
    relevancy: {
      scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
      sampling: { type: 'ratio', rate: 0.5 },
    },
    safety: {
      scorer: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
      sampling: { type: 'ratio', rate: 1 },
    },
  },
})
```

### Workflow 단계에 채점자 추가

또한 개별 Workflow 단계에 채점자를 추가하여 프로세스의 특정 지점에서 출력을 평가할 수도 있습니다. 각 채점자는 해당 단계의 자체 입력 및 출력을 수신하므로 최종 답변에만 점수를 매기는 대신 각 단계의 품질을 측정할 수 있습니다.

```typescript
import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";
import { customStepScorer } from "../scorers/custom-step-scorer";

const contentStep = createStep({
  id: "content-step",
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ content: z.string() }),
  scorers: {
    customStepScorer: {
      scorer: customStepScorer(),
      sampling: {
        type: "ratio",
        rate: 1, // Score every step execution
      },
    },
  },
  execute: async ({ inputData }) => {
    return { content: await generateContent(inputData.topic) };
  },
});

export const contentWorkflow = createWorkflow({
  id: "content-workflow",
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ content: z.string() }),
})
  .then(contentStep)
  .commit();
```

단계 수준의 `scorers` API는 [Step 클래스 레퍼런스](https://mastra.zisheng.pro/ko/reference/workflows/step)를 참조하세요.

### 실시간 평가 작동 방식

**비동기 실행**: 실시간 평가는 Agent 응답이나 Workflow 실행을 차단하지 않고 백그라운드에서 실행됩니다. 이를 통해 AI 시스템이 모니터링되는 동안에도 성능을 유지할 수 있습니다.

**샘플링 제어**: `sampling.rate` 매개변수(0-1)는 채점할 출력의 비율을 제어합니다.

- `1.0`: 모든 응답에 점수를 매깁니다(100%).
- `0.5`: 전체 응답의 절반 점수(50%)
- `0.1`: 응답의 10% 점수
- `0.0`: 채점 비활성화

**자동 저장**: 모든 채점 결과는 구성된 데이터베이스의 `mastra_scorers` 테이블에 자동으로 저장되므로 시간 경과에 따른 성능 추세를 분석할 수 있습니다.

## 추적 평가

실시간 평가 외에도 채점자를 사용하여 Agent 상호 작용 및 Workflow의 기록 추적을 평가할 수 있습니다.

이는 과거 성능을 분석하거나 문제를 디버깅하거나 일괄 평가를 실행하는 데 특히 유용합니다.

:::참고\[관찰성이 필요함]

Trace를 채점하려면 먼저 Trace 데이터를 수집하도록 Mastra 인스턴스에 Observability을 구성해야 합니다. 설정 방법은 [Tracing 문서](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)를 참조하세요. :::

## 사진관

추적을 기록하려면 먼저 기록자를 Mastra 인스턴스에 등록해야 합니다.

```typescript
const mastra = new Mastra({
  scorers: {
    answerRelevancy: myAnswerRelevancyScorer,
    responseQuality: myResponseQualityScorer,
  },
})
```

등록한 후에는 Studio의 **Observability** 섹션에서 대화형으로 Trace를 채점할 수 있습니다. Studio를 열어 채점자를 관리하고 점수를 검토하며 실험을 실행하세요.

- **득점자 목록**: 등록된 모든 득점자를 설명과 함께 찾아보고, 각 득점자가 연결된 Agent 및 Workflow 수를 찾아보세요.
- **점수 결과**: 득점자를 선택하면 해당 득점자가 생성한 모든 점수의 페이지가 매겨진 목록을 볼 수 있습니다. 행을 클릭하면 점수 값, 사유, 입력, 출력 및 심사위원이 사용하는 Prompt가 표시되는 세부 패널이 열립니다. 이 패널에서 결과를 향후 실험을 위한 데이터세트 항목으로 저장합니다.
- **Agent 평가 탭**: 득점자 및 데이터 세트를 관리하려면 Agent에서 평가 탭을 엽니다. 거기에서 실험을 실행할 수도 있습니다. 실험 결과에는 통과/실패 상태 및 버전 태그와 함께 항목별 점수가 표시됩니다.
- **추적 점수**: Observability 섹션에서 기록 추적 또는 범위에 대해 채점기를 실행하여 과거 상호 작용을 평가합니다. Agent 또는 Workflow별로 점수를 필터링합니다.

## 다음 단계

- 텍스트와 Tool 사용을 빠르고 결정적으로 검증하려면 [빠른 검사](https://mastra.zisheng.pro/ko/docs/evals/quick-checks)를 사용하세요.
- 엄격한 요구 사항과 품질 임계값을 적용하려면 [게이트 및 판정](https://mastra.zisheng.pro/ko/docs/evals/gates-and-verdicts)을 추가하세요.
- 여러 순차적 턴에 걸쳐 동작이 나타나는 [멀티 턴 대화](https://mastra.zisheng.pro/ko/docs/evals/multi-turn)를 테스트하세요.
- 자체 채점자를 만드는 방법은 [커스텀 채점자 만들기](https://mastra.zisheng.pro/ko/docs/evals/custom-scorers) 가이드에서 알아보세요.
- [기본 제공 채점자](https://mastra.zisheng.pro/ko/docs/evals/built-in-scorers) 섹션을 살펴보세요.
- [Studio](https://mastra.zisheng.pro/ko/docs/studio/overview)에서 채점자를 테스트하세요.
- 📹 [Mastra Evals 워크숍](https://www.youtube.com/watch?v=OHOZ5PgPj5M\&t=3578s)