클라이언트 측 평가 SDK (Client-Side Evals)

Phoenix Evals SDK는 Python이나 TypeScript로 평가를 작성·실행하기 위한 조립 가능한 빌딩 블록을 제공해요. 이 문서에서는 핵심 개념 — 평가자가 무엇인지, 두 가지 평가자 유형, 입력 매핑이 어떻게 동작하는지 — 를 정리해요. 평가를 사전 구성해 두는 바인드(bind) 패턴과 동기·비동기 실행 선택 기준도 살펴볼게요.

출처: Phoenix - Client-Side Evals (SDK)

평가자란 무엇인가요?

평가자는 입력을 받아 Score를 반환하는 어떤 것이든 돼요. Score 객체는 모든 평가자의 공통 출력이에요.

속성	필수	설명
`name`	✓	평가자의 사람이 읽을 수 있는 이름
`kind`	✓	신호의 출처: `llm`, `code`, `human`
`direction`	✓	점수가 높을수록 좋은지 나쁜지
`label`	선택	범주형 결과(예: `"correct"`, `"hallucinated"`)
`explanation`	선택	결과에 대한 근거
`metadata`	선택	임의의 추가 컨텍스트

모든 평가자는 단일 레코드 실행용 evaluate·async_evaluate 메서드를 노출하고, 필요한 필드를 설명하는 input_schema를 가져요.

두 가지 평가자 유형

LLM 기반 평가자: 판정 모델로 충실성·독성·관련성처럼 '정답이 주관적인' 정성적 기준을 평가해요. 판정 모델이 프롬프트 템플릿을 읽고 설명과 함께 라벨 점수를 생성하죠.
코드 평가자: 정확 매치, regex, Levenshtein 거리처럼 '정답이 객관적인' 기준을 결정적 로직·휴리스틱으로 평가해요. LLM 호출 없이 실행되어 빠르고 저렴해요.

입력 매핑(Input Mapping)

평가자 필드 이름을 데이터 안의 경로로 매핑해요. 점 표기법(dot notation)으로 중첩 키를, 호출 가능 객체(callable)로 변환을 지정할 수 있어요.

input_mapping = {
    "input": "input.query",        # 점 표기법: 중첩 키
    "context": lambda x: " ".join(x["input"]["documents"]),  # 호출 가능 객체: 변환
    "output": "output.response",
}

TypeScript로는 bindEvaluator와 createFaithfulnessEvaluator를 조합해 사용해요.

import { bindEvaluator, createFaithfulnessEvaluator } from "@arizeai/phoenix-evals";
import { openai } from "@ai-sdk/openai";

const evaluator = bindEvaluator(
  createFaithfulnessEvaluator({ model: openai("gpt-4o") }),
  { inputMapping: { input: "input.query", context: (data) => data.input.documents.join(" "), output: "output.response" } }
);
const scores = await evaluator.evaluate(evalInput);

바인드 패턴(Bind Pattern)

bind_evaluator(Python) / bindEvaluator(TypeScript)로 매핑을 미리 박아 두면 평가자를 사전 구성할 수 있어요. 이후에는 데이터만 넘겨 점수를 얻으면 되죠.

from phoenix.evals import bind_evaluator

bound = bind_evaluator(faithfulness_evaluator, {
    "input": "input.query",
    "context": lambda x: " ".join(x["input"]["documents"]),
    "output": "output.response",
})

# 이제 데이터만 넘기면 매핑이 적용돼요
scores = bound(eval_input)

동기 vs 비동기

evaluate: 간단한 스크립트·노트북용이에요.
async_evaluate: 많은 평가를 동시에 실행할 때 써요. 실행기(executor)가 rate limit 처리·재시도·동적 동시성을 자동으로 관리해요.
전체 dataframe에 평가를 돌릴 땐 async_evaluate_dataframe을 사용해요.

더 알아보기

커스텀 LLM 평가자: 프롬프트 템플릿으로 분류·점수 평가자 만들기
코드 평가자: 함수로 결정적 평가자 만들기
배치 평가: dataframe에 대해 효율적으로 평가 실행하기
사전 빌드 메트릭: 충실성·관련성 등 미리 테스트된 평가자 사용하기