DeepEval 평가 스킬

DeepEval 평가 스킬 (DeepEval Evals Skill)

에이전트에게 DeepEval로 pytest 평가 스위트를 만들고, 데이터셋을 생성하고, 실패를 반복 개선하는 법을 가르치는 스킬 문서예요. 이 문서에서는 스킬이 언제 발동하는지, 설치 방법, 그리고 코드베이스에서 바뀌는 것을 설명할게요.

출처: 문서

본문

개요 (Overview)

deepeval Agent Skill은 코딩 에이전트에게 AI 애플리케이션에 완전한 평가 루프를 추가하는 법을 가르쳐요: 앱을 분류하고(에이전트, RAG 파이프라인, 또는 다중 턴 챗봇), 데이터셋을 생성하거나 재사용하고, 커밋된 pytest 평가 스위트를 작성하고, deepeval test run으로 실행하며, 실패를 반복 개선해요. confident-ai/deepeval 저장소에 배포되는 세 스킬 중 메인 스킬이에요.

스킬이 없으면 에이전트는 일회용 평가 스크립트를 손으로 쓰고, 골든을 지어내고, raw pytest를 호출하곤 해요. 스킬이 있으면 에이전트는 우리 문서가 권장하는 것과 같은 워크플로를 따라요 — 합성 데이터는 deepeval generate, 지표는 별도 metrics.py 모듈에, 가능하면 추적되는 단일 턴 평가, 그리고 에이전트 없이도 다시 실행할 수 있는 스위트.

언제 발동하나요?

이 스킬은 다음과 같은 프롬프트에서 활성화돼요:

Add evals to my customer support agent.
Generate a dataset of goldens from our docs folder.
Why is my RAG pipeline hallucinating? Set up metrics to catch it.
Run the eval suite and fix the failures.

계측이나 원시 원격 측정은 의도적으로 다루지 않아요 — confident-trace 통합이나 커스텀 스팬 추가는 confident-tracing, 원시 OpenTelemetry / OTLP 내보내기는 confident-otel의 몫이에요.

설치 (Installation)

Skills CLI

Cursor, Claude Code, Codex, Windsurf, OpenCode 등 Skills 호환 어시스턴트에서 작동해요:

npx skills add confident-ai/deepeval --skill "deepeval"

Claude Code (플러그인)

플러그인은 세 가지 deepeval-* 스킬을 모두 번들해요:

/plugin marketplace add confident-ai/deepeval
/plugin install deepeval@deepeval-plugins
/reload-plugins

수동 복사

스킬 폴더를 에이전트의 스킬 디렉토리에 복사해요:

git clone https://github.com/confident-ai/deepeval
cp -r deepeval/skills/deepeval .claude/skills/

사전 조건 (Prerequisites)

pip install deepeval을 포함한 Python 3.9+
지표용 모델 자격 증명 (예: OPENAI_API_KEY)
호스팅 보고서와 트레이스용 CONFIDENT_API_KEY

코드베이스에서 바뀌는 것

평가 요청하기

무엇을 평가할지 설명해요. 에이전트가 코드베이스를 검사하고, 사용 사례(다중 턴 챗봇, 에이전트, RAG)를 고르며, 짧은 일련의 인테이크 질문 — 평가 모델, 데이터셋 소스, 트레이싱, 몇 라운드 개선할지 — 을 물어요.

Add evals to my customer support agent and iterate until they pass.

데이터셋 생성하게 하기

이미 데이터셋이 없다면 — 로컬이든 Confident AI에서 가져온 것이든 — 에이전트는 손으로 쓰는 대신 여러분의 문서나 지식 베이스에서 대략 30–50개의 골든을 생성해요. 직접 요청할 수도 있어요:

Generate a dataset of goldens from the ./docs folder.

에이전트가 무엇을 실행하는지 보기

deepeval generate --method docs --variation single-turn \
  --documents ./docs --output-dir ./tests/evals --file-name .dataset

커밋된 평가 스위트 검토

에이전트는 스킬의 템플릿에서 시작해, 에이전트 없이도 다시 실행할 수 있는 pytest 스위트를 커밋해요. 지표 인스턴스는 공유 metrics.py 모듈에 유지돼요.

에이전트가 무엇을 커밋하는지 보기

import pytest
from deepeval import assert_test
from deepeval.dataset import EvaluationDataset, Golden

from metrics import SINGLE_TURN_TRACE_METRICS
import ai_app

dataset = EvaluationDataset()
dataset.add_goldens_from_json_file(file_path="tests/evals/.dataset.json")


@pytest.mark.parametrize("golden", dataset.goldens)
def test_single_turn_tracing(golden: Golden):
    ai_app.run_traced_ai_app(golden.input)
    assert_test(golden=golden, metrics=SINGLE_TURN_TRACE_METRICS)

실행과 반복

평가는 deepeval test run(raw pytest가 아님)으로 실행돼요. 에이전트는 실패를 — 트레이싱이 켜져 있으면 트레이스도 — 검사하고 프롬프트, 도구, 검색에 목표 조정을 가한 뒤 합의된 라운드 수만큼(기본 5회) 다시 실행해요:

Run the eval suite and fix the failures until every metric passes.

에이전트가 무엇을 실행하는지 보기

deepeval test run tests/evals/test_ai_app.py \
  --num-processes 5 --identifier "iterating-round-1"

Confident AI가 활성화되면 각 실행이 프로젝트의 테스트 실행으로 기록되고, deepeval view가 최신 호스팅 보고서를 엽니다.

앱을 계측할 수 있다면, 이 스킬은 계측 자체는 confident-tracing에 맡기고 그 위에 추적되는 평가를 만드는데, 그게 개별 스팬의 구성 요소 수준 지표를 여는 열쇠예요.

자주 묻는 질문 (FAQs)

이 스킬을 쓰려면 Confident AI 계정이 필요한가요?

아니요. 평가는 pip install deepeval과 모델 자격 증명만으로 로컬에서 실행돼요. CONFIDENT_API_KEY(또는 deepeval login)가 그 위에 호스팅 보고서, 트레이스, 프로덕션 모니터링, 온라인 평가를 추가해요.

이미 가진 데이터셋을 사용할 수 있나요?

네. 기존 데이터셋 — 로컬 파일 또는 Confident AI에서 가져온 데이터셋 — 은 있는 그대로 재사용되고, 기존 지표와 임계값은 바꾸지 않는 한 유지돼요. 이 스킬은 데이터셋이 없을 때만 deepeval generate를 쓰고, 골든을 손으로 쓰지 않아요.

왜 pytest 대신 'deepeval test run'을 실행하나요?

스위트는 내부적으로는 표준 pytest지만, deepeval test run 명령이 평가에 필요한 것 — --num-processes를 통한 병렬 실행, 반복 추적용 실행 식별자, 활성화 시 Confident AI로의 자동 보고 — 을 추가해요.

어떤 모델이 지표를 채점하나요?

여러분이 정해요. 평가 모델은 스킬이 아무것도 쓰기 전에 물어보는 인테이크 질문 중 하나이고, 기본값을 가정하지 않고 여러분의 모델 자격 증명(예: OPENAI_API_KEY)을 사용해요.

DeepEval 평가 스킬