게이트 및 평결

게이트와 판정은 심각도 의미를 추가합니다.runEvals. 게이츠는 득점을 막는 엄격한 요구 사항인 1.0을 획득해야 하는 득점자입니다. 임계값은 추적된 측정항목에서 허용되는 최소 점수입니다. 판결은 결과를 다음과 같이 요약합니다.passed, scored, 또는failed.

게이트와 평결을 사용해야 하는 경우

• CI에서 엄격한 요구 사항을 적용합니다(예: "Agent는 올바른 Tool을 호출해야 합니다").
• 최소 임계값으로 품질 지표를 추적합니다(예: "충실도 0.7 이상").
• 커스텀 어설션 로직을 작성하지 않고 평가 실행에서 단일 판정 신호(passed, scored 또는 failed)를 얻습니다.
• "반드시 통과해야 하는" 게이트와 "있으면 좋은" 추적 지표를 분리합니다.

빠른 시작

src/evals/weather-eval.ts

import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'
import { weatherAgent } from '../agents'
import { faithfulnessScorer } from '../scorers'

const result = await runEvals({
  data: [{ input: 'What is the weather in Brooklyn?' }],
  target: weatherAgent,

  // Gates: must all score 1.0 or the run fails
  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],

  // Scorers: tracked with optional thresholds
  scorers: [
    { scorer: faithfulnessScorer, threshold: 0.7 },
    checks.includes('Brooklyn'), // no threshold = tracked only
  ],
})

console.log(result.verdict) // 'passed' | 'scored' | 'failed'

평결의 작동 방식

모든 데이터 항목이 처리된 후 게이트와 임계값에서 판정이 계산됩니다.

• failed: 데이터 항목 전체에서 평균이 1.0 미만인 게이트가 하나 이상 있습니다.
• scored: 모든 관문을 통과했지만 최소 한 명의 기준점 득점자가 기준점을 통과하지 못했습니다.
• passed: 모든 게이트 점수가 1.0이고 모든 임계값이 충족되었습니다.

게이트 또는 임계값이 있는 채점자를 제공하지 않으면 판정 필드가 생략되고 runEvals는 이전과 똑같이 동작합니다.

게이츠

게이트는 gates 필드에 전달하는 채점자입니다. 각 데이터 항목에서 일반 채점자보다 먼저 실행됩니다. 게이트를 통과하려면 모든 데이터 항목의 평균 점수가 1.0이어야 합니다.

src/evals/tool-gate.ts

import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'

const result = await runEvals({
  data: [{ input: 'What is the weather?' }],
  target: weatherAgent,
  gates: [checks.calledTool('get_weather')],
  scorers: [qualityScorer],
})

// result.gateResults: [{ id: 'check-called-tool', passed: true, score: 1 }]

모든 채점자를 게이트로 사용할 수 있습니다. 빠른 검사는 이진 1/0 점수를 반환하므로 게이트에 자연스럽게 적합합니다. 전체 매개변수와 반환 유형 문서는 runEvals() 레퍼런스를 참조하세요.

게이트 전용 실행

scorers게이트가 하나 이상 제공되는 경우 선택 사항입니다. 이는 합격/실패 게이트에만 관심이 있고 품질 측정항목을 추적할 필요가 없는 결정적 CI 검사에 유용합니다.

src/evals/gate-only.ts

import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'

const result = await runEvals({
  data: [{ input: 'What is the weather in Brooklyn?' }],
  target: weatherAgent,
  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
})

최소한 한 명의 득점원이나 게이트를 제공해야 하며, 둘 다 실행하지 않으면 오류가 발생합니다.

임계값

통과/실패 경계를 설정하려면 채점자를 { scorer, threshold }로 감싸세요. 임계값은 모든 데이터 항목에 대한 채점자의 평균 점수와 비교됩니다. threshold에는 다음 값을 사용할 수 있습니다.

• 숫자: 최솟값을 의미합니다(이 점수 이상이면 통과). { scorer, threshold: 0.7 }
• min 및/또는 max를 가진 객체: 범위 기반 검사에 사용합니다. { scorer, threshold: { max: 0.3 } } 높은 점수가 좋지 않은 채점자(예: 환각, 유해성)에는 max를 사용하세요. 점수가 특정 범위 안에 있어야 한다면 { min, max }를 사용하세요.

src/evals/threshold-example.ts

import { runEvals } from '@mastra/core/evals'

const result = await runEvals({
  data: [{ input: 'Explain quantum computing' }],
  target: myAgent,
  scorers: [
    { scorer: faithfulnessScorer, threshold: 0.7 }, // min threshold (number shorthand)
    { scorer: hallucinationScorer, threshold: { max: 0.3 } }, // max threshold — high score = bad
    { scorer: verbosityScorer, threshold: { min: 0.3, max: 0.8 } }, // range threshold
    toneScorer, // bare scorer, no threshold — tracked only
  ],
})

// result.thresholdResults:
// [
//   { id: 'faithfulness', passed: true, averageScore: 0.85, threshold: 0.7 },
//   { id: 'hallucination', passed: true, averageScore: 0.1, threshold: { max: 0.3 } },
//   { id: 'verbosity', passed: false, averageScore: 0.9, threshold: { min: 0.3, max: 0.8 } },
// ]

임계값이 없는 일반 채점자도 result.scores에 표시되지만 판정에는 영향을 주지 않습니다.

CI에서 판정 사용

이번 판결은 CI 파이프라인에 대한 단일 신호를 제공합니다.

src/evals/ci-check.ts

import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'

const result = await runEvals({
  data: testDataset,
  target: myAgent,
  gates: [checks.calledTool('search'), checks.noToolErrors()],
  scorers: [{ scorer: faithfulnessScorer, threshold: 0.7 }],
})

if (result.verdict === 'failed') {
  console.error(
    'Gate failures:',
    result.gateResults?.filter(g => !g.passed),
  )
  process.exit(1)
}

if (result.verdict === 'scored') {
  console.warn(
    'Threshold misses:',
    result.thresholdResults?.filter(t => !t.passed),
  )
}

관련된

• 빠른 점검: 게이트 역할을 하는 Zero-LLM 마이크로 스코어러
• runEvals() 참조: 전체 API 문서
• 내장 득점자: LLM 기반 및 코드 기반 채점자
• CI에서 평가 실행: CI 통합 패턴