득점자 개요

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

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

:::tip[📹 보기]

Evals 소개와 Agent 품질을 판단하는 방법은 Mastra Evals 개요를 참조하세요. :::

득점자의 유형

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

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

설치

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

npm

npm install @mastra/evals@latest

pnpm

pnpm add @mastra/evals@latest

Yarn

yarn add @mastra/evals@latest

Bun

bun add @mastra/evals@latest

실시간 평가

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

Agent에 득점자 추가

Agent에 기본 제공 채점자를 추가하여 출력을 자동으로 평가할 수 있습니다. 사용 가능한 모든 옵션은 기본 제공 채점자 전체 목록을 참조하세요.

src/mastra/agents/evaluated-agent.ts

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

src/mastra/workflows/content-generation.ts

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 클래스 레퍼런스를 참조하세요.

실시간 평가 작동 방식

비동기 실행: 실시간 평가는 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 문서를 참조하세요. :::

사진관

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

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

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

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

다음 단계

• 텍스트와 Tool 사용을 빠르고 결정적으로 검증하려면 빠른 검사를 사용하세요.
• 엄격한 요구 사항과 품질 임계값을 적용하려면 게이트 및 판정을 추가하세요.
• 여러 순차적 턴에 걸쳐 동작이 나타나는 멀티 턴 대화를 테스트하세요.
• 자체 채점자를 만드는 방법은 커스텀 채점자 만들기 가이드에서 알아보세요.
• 기본 제공 채점자 섹션을 살펴보세요.
• Studio에서 채점자를 테스트하세요.
• 📹 Mastra Evals 워크숍