Pydantic Evals 빠른 시작

Pydantic Evals 빠른 시작 (Quickstart)

Pydantic Evals는 간단한 LLM 호출부터 복잡한 멀티 에이전트 애플리케이션까지, AI 시스템을 체계적으로 테스트하고 평가하기 위한 강력한 평가 프레임워크예요.

Pydantic Evals란 무엇인가요?

Pydantic Evals는 다음을 도와줘요.

  • 타입 안전한 구조적 입력과 예상 출력으로 테스트 데이터셋 생성
  • 자동 동시성으로 AI 시스템에 대해 평가 실행
  • 결정적 검사, LLM judge 또는 사용자 정의 평가자로 결과 채점
  • 상세 지표, 어서션, 성능 데이터가 있는 보고서 생성
  • 시간에 따른 평가 실행을 비교해 변화 추적
  • 시각화와 공동 분석을 위한 Logfire 연동

출처: 문서

본문

설치 (Installation)

Terminal

pip install pydantic-evals

OpenTelemetry 트레이싱과 Logfire 연동을 위해서는:

Terminal

pip install 'pydantic-evals[logfire]'

빠른 시작 (Quick Start)

평가는 일반적으로 AI 시스템을 테스트하는 데 쓰이지만, Pydantic Evals 프레임워크는 어떤 함수 호출과도 작동해요. 핵심 기능을 보여주기 위해 간단한 결정적 예제부터 시작할게요.

단순한 텍스트 변환 함수를 평가하는 완전한 예제예요.

from pydantic_evals import Case, Dataset
from pydantic_evals.evaluators import Contains, EqualsExpected

# Create a dataset with test cases
dataset = Dataset(
    name='uppercase_tests',
    cases=[
        Case(
            name='uppercase_basic',
            inputs='hello world',
            expected_output='HELLO WORLD',
        ),
        Case(
            name='uppercase_with_numbers',
            inputs='hello 123',
            expected_output='HELLO 123',
        ),
    ],
    evaluators=[
        EqualsExpected(),  # Check exact match with expected_output
        Contains(value='HELLO', case_sensitive=True),  # Check contains "HELLO"
    ],
)


# Define the function to evaluate
def uppercase_text(text: str) -> str:
    return text.upper()


# Run the evaluation
report = dataset.evaluate_sync(uppercase_text)

# Print the results
report.print()
"""
        Evaluation Summary: uppercase_text
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID                ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ uppercase_basic        │ ✔✔         │     10ms │
├────────────────────────┼────────────┼──────────┤
│ uppercase_with_numbers │ ✔✔         │     10ms │
├────────────────────────┼────────────┼──────────┤
│ Averages               │ 100.0% ✔   │     10ms │
└────────────────────────┴────────────┴──────────┘
"""

출력:

                  Evaluation Summary: uppercase_text
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID                 ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ uppercase_basic         │ ✔✔         │     10ms │
├─────────────────────────┼────────────┼──────────┤
│ uppercase_with_numbers  │ ✔✔         │     10ms │
├─────────────────────────┼────────────┼──────────┤
│ Averages                │ 100.0% ✔   │     10ms │
└─────────────────────────┴────────────┴──────────┘

핵심 개념 (Key Concepts)

몇 가지 핵심 개념을 이해하면 Pydantic Evals를 최대한 활용할 수 있어요.

  • Dataset — 테스트 케이스와 (선택적) 평가자의 모음
  • Case — 입력과 선택적 예상 출력 및 케이스별 평가자를 가진 단일 테스트 시나리오
  • Evaluator — 작업 출력을 채점하거나 검증하는 함수
  • EvaluationReport — 평가 실행의 결과

더 깊이 알아보려면 핵심 개념을 참고하세요.

일반적인 사용 사례 (Common Use Cases)

결정적 검증 (Deterministic Validation)

AI 시스템이 올바르게 구조화된 출력을 생성하는지 테스트:

from pydantic_evals import Case, Dataset
from pydantic_evals.evaluators import Contains, IsInstance

dataset = Dataset(
    name='dict_validation',
    cases=[
        Case(inputs={'data': 'required_key present'}, expected_output={'result': 'success'}),
    ],
    evaluators=[
        IsInstance(type_name='dict'),
        Contains(value='required_key'),
    ],
)

LLM-as-a-Judge 평가

정확성이나 도움됨 같은 주관적 품질을 평가하기 위해 LLM 사용:

from pydantic_evals import Case, Dataset
from pydantic_evals.evaluators import LLMJudge

dataset = Dataset(
    name='llm_judge_test',
    cases=[
        Case(inputs='What is the capital of France?', expected_output='Paris'),
    ],
    evaluators=[
        LLMJudge(
            rubric='Response is accurate and helpful',
            include_input=True,
            model='anthropic:claude-sonnet-4-6',
        )
    ],
)

성능 테스트 (Performance Testing)

시스템이 성능 요구사항을 충족하는지 확인:

from pydantic_evals import Case, Dataset
from pydantic_evals.evaluators import MaxDuration

dataset = Dataset(
    name='performance_test',
    cases=[
        Case(inputs='test input', expected_output='test output'),
    ],
    evaluators=[
        MaxDuration(seconds=2.0),
    ],
)

다음 단계 (Next Steps)

더 알아보기 위해 문서를 탐색하세요.

더 알아보기 (Learn more)