3.3.3 하네스 실전 활용

도구 선택부터 코드 예제, CI/CD 통합, 에이전트 품질 보증 체크리스트까지 — Harness Engineering을 실제 프로젝트에 적용하는 방법을 단계별로 정리한다. 업데이트: 2026-03-16

---

핵심 요약

구분	내용
📖 정의	평가 하네스·운영 하네스 도구를 실제 프로젝트에 통합하는 실전 가이드
💡 핵심	”측정하지 않으면 개선할 수 없다” — 어떤 도구든 CI/CD에 연결해야 의미가 있다
🎯 대상	LLM 앱·에이전트 시스템을 처음 평가하거나, 평가를 자동화하려는 엔지니어
⚠️ 주의	도구를 여러 개 한꺼번에 도입하지 않는다. 하나를 완전히 익힌 뒤 확장하는 것이 효과적이다

---

문서 탐색

이전	다음
3.3.2 하네스 아키텍처	—

---

목차

1. 주요 도구 목록
2. 도구 선택 가이드
3. lm-evaluation-harness — 모델 벤치마킹
4. DeepEval — pytest 스타일 LLM 유닛 테스트
5. PromptFoo — 선언형 프롬프트 테스트 + CI/CD
6. Langfuse — 관찰 가능성 통합
7. 에이전트 품질 보증 체크리스트
8. 단계별 학습 경로

---

1. 주요 도구 목록

도구	카테고리	GitHub	라이선스	특징
lm-evaluation-harness	모델 벤치마크	EleutherAI/lm-evaluation-harness	MIT	HF Leaderboard 백엔드, 60+ 벤치마크
OpenAI Evals	모델 평가	openai/evals	MIT	커뮤니티 기여 eval 스크립트
DeepEval	LLM 유닛 테스트	confident-ai/deepeval	Apache 2.0	pytest 호환, 30+ 메트릭
RAGAS	RAG 평가	explodinggradients/ragas	Apache 2.0	에이전트 도구 호출 메트릭 포함
PromptFoo	프롬프트 테스트	promptfoo/promptfoo	MIT	YAML 선언형, 레드팀, CI/CD 통합
Langfuse	관찰 가능성	langfuse/langfuse	MIT	자체 호스팅, OpenTelemetry
Weave (W&B)	실험 추적	wandb/weave	Apache 2.0	Stripe Minions 채택
LightEval	HF 네이티브 평가	huggingface/lighteval	MIT	HuggingFace 생태계 통합
Braintrust	SaaS 평가 플랫폼	— (SaaS)	유료	프롬프트 플레이그라운드 + 평가 통합

---

2. 도구 선택 가이드

graph TD
    A["평가 목적 선택"]
    B{"모델 자체 성능<br/>벤치마킹?"}
    C["lm-evaluation-harness<br/>OpenAI Evals"]
    D{"RAG 파이프라인<br/>평가?"}
    E["DeepEval + RAGAS"]
    F{"보안·레드팀<br/>포함?"}
    G["PromptFoo"]
    H{"자체 호스팅<br/>필요?"}
    I["Langfuse"]
    J["Braintrust"]

    A --> B
    B -->|Yes| C
    B -->|No| D
    D -->|Yes| E
    D -->|No| F
    F -->|Yes| G
    F -->|No| H
    H -->|Yes| I
    H -->|No| J

시나리오	추천 도구
오픈소스 모델의 학술 벤치마크 성능 측정	lm-evaluation-harness
LLM 앱의 RAG 품질 측정 (충실도, 관련성 등)	DeepEval + RAGAS
프롬프트 변경 전후 품질 비교, PR 품질 게이트	PromptFoo
프로덕션 LLM 앱 추적·디버깅·인간 평가	Langfuse
에이전트 도구 호출 정확성 단위 테스트	DeepEval (ToolCorrectnessMetric)
보안 취약점·프롬프트 인젝션 탐지	PromptFoo (레드팀 기능)

---

3. lm-evaluation-harness — 모델 벤치마킹

EleutherAI의 lm-evaluation-harness는 Hugging Face Open LLM Leaderboard의 공식 백엔드로, 학술 벤치마크 평가의 표준 도구다.

설치 및 기본 실행

# 설치
pip install lm-eval
 
# HuggingFace 모델 평가 (MMLU + HellaSwag, 5-shot)
lm_eval \
  --model hf \
  --model_args pretrained=meta-llama/Llama-3.1-8B-Instruct \
  --tasks mmlu,hellaswag \
  --num_fewshot 5 \
  --batch_size 8 \
  --output_path ./results/llama3
 
# OpenAI API 모델 평가
lm_eval \
  --model openai-chat-completions \
  --model_args model=gpt-4o \
  --tasks mmlu \
  --num_fewshot 0 \
  --output_path ./results/gpt4o

커스텀 태스크 YAML 작성

# my_tasks/custom_qa/custom_qa.yaml
task: custom_qa
dataset_path: json
dataset_kwargs:
  data_files:
    test: my_data/test.json
test_split: test
 
doc_to_text: "Q: {{question}}\nA:"
doc_to_target: "{{answer}}"
 
output_type: generate_until
generation_kwargs:
  until:
    - "\n"
  max_gen_toks: 128
 
metric_list:
  - metric: exact_match
    aggregation: mean
    higher_is_better: true
 
num_fewshot: 0

# 커스텀 태스크 실행
lm_eval \
  --model openai-chat-completions \
  --model_args model=gpt-4o-mini \
  --tasks custom_qa \
  --include_path ./my_tasks \
  --output_path ./results/custom

---

4. DeepEval — pytest 스타일 LLM 유닛 테스트

DeepEval은 기존 pytest 워크플로우와 완전히 호환되며, 30개 이상의 내장 메트릭으로 LLM 앱과 에이전트를 평가한다.

설치

pip install deepeval
deepeval login  # Confident AI 클라우드 연결 (선택)

기본 RAG 평가 테스트

# test_rag_app.py
import pytest
from deepeval import assert_test
from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric
from deepeval.test_case import LLMTestCase
from my_app import generate_answer  # 평가 대상 함수
 
@pytest.mark.parametrize("test_case", [
    LLMTestCase(
        input="환불 정책이 어떻게 되나요?",
        actual_output=generate_answer("환불 정책이 어떻게 되나요?"),
        expected_output="30일 이내 전액 환불 가능합니다.",
        retrieval_context=[
            "모든 고객은 구매 후 30일 이내에 추가 비용 없이 전액 환불을 받을 수 있습니다."
        ],
    )
])
def test_answer_quality(test_case):
    relevancy = AnswerRelevancyMetric(threshold=0.7, model="gpt-4o-mini")
    faithfulness = FaithfulnessMetric(threshold=0.8, model="gpt-4o-mini")
    assert_test(test_case, [relevancy, faithfulness])

# pytest로 실행
deepeval test run test_rag_app.py

에이전트 도구 호출 정확성 평가

from deepeval.metrics import ToolCorrectnessMetric
from deepeval.test_case import LLMTestCase, ToolCall
 
# 에이전트가 올바른 도구를 올바른 순서로 호출했는지 평가
test_case = LLMTestCase(
    input="서울 날씨를 알려주고, 우산이 필요한지 판단해줘.",
    actual_output="현재 서울은 흐리고 비가 예상됩니다. 우산을 준비하세요.",
    tools_called=[
        ToolCall(name="get_weather", input={"location": "Seoul"}),
        ToolCall(name="check_rain_probability", input={"location": "Seoul"}),
    ],
    expected_tools=[
        ToolCall(name="get_weather", input={"location": "Seoul"}),
    ],
)
 
metric = ToolCorrectnessMetric(threshold=0.8)
metric.measure(test_case)
print(f"점수: {metric.score}, 이유: {metric.reason}")

주요 메트릭 목록

메트릭	용도	판단 기준
AnswerRelevancyMetric	답변이 질문과 관련 있는가	0.0 ~ 1.0
FaithfulnessMetric	답변이 검색된 컨텍스트에 충실한가	0.0 ~ 1.0
ContextualRecallMetric	검색된 컨텍스트가 정답 생성에 기여했는가	0.0 ~ 1.0
ToolCorrectnessMetric	에이전트가 올바른 도구를 올바른 순서로 호출했는가	0.0 ~ 1.0
GEval	커스텀 기준으로 LLM-Judge 평가	사용자 정의

---

5. PromptFoo — 선언형 프롬프트 테스트 + CI/CD

PromptFoo는 YAML 기반 선언형 설정으로 여러 모델을 비교하고, 프롬프트 변경의 영향을 CI/CD에서 자동으로 검증한다.

설치

npm install -g promptfoo
# 또는 npx로 실행

기본 설정 파일

# promptfooconfig.yaml
description: "고객 서비스 챗봇 품질 테스트"
 
prompts:
  - "당신은 친절한 고객 서비스 담당자입니다. 다음 질문에 답해주세요: {{question}}"
 
providers:
  - id: openai:gpt-4o-mini
    config:
      temperature: 0.3
  - id: anthropic:claude-3-5-haiku-20241022
    config:
      temperature: 0.3
 
tests:
  - vars:
      question: "환불은 며칠 이내에 가능한가요?"
    assert:
      - type: contains
        value: "30"
      - type: llm-rubric
        value: "답변이 환불 정책에 대해 명확하고 친절하게 설명하는가?"
        threshold: 0.8
 
  - vars:
      question: "제품이 파손되어 도착했습니다."
    assert:
      - type: llm-rubric
        value: "답변이 공감을 표현하고 명확한 해결 단계를 제시하는가?"
        threshold: 0.85
      - type: not-contains
        value: "죄송합니다만 저는 AI라서"

# 평가 실행
npx promptfoo@latest eval
 
# 결과 UI 열기
npx promptfoo@latest view

GitHub Actions CI/CD 통합

# .github/workflows/llm-eval.yml
name: LLM Quality Gate
 
on:
  pull_request:
    paths:
      - 'prompts/**'
      - 'promptfooconfig.yaml'
 
jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run PromptFoo Evaluation
        uses: promptfoo/promptfoo-action@v1
        with:
          config: promptfooconfig.yaml
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          fail-on-error: true
          github-token: ${{ secrets.GITHUB_TOKEN }}

PR마다 평가 결과가 댓글로 자동 첨부된다. 성공률이 기준치 미만이면 빌드가 실패한다.

레드팀 설정 (보안 취약점 탐지)

# promptfooconfig-redteam.yaml
redteam:
  plugins:
    - prompt-injection     # 프롬프트 인젝션
    - pii                  # 개인정보 유출
    - jailbreak            # 안전 지침 우회 시도
    - harmful:hate         # 혐오 발언 유도
  strategies:
    - jailbreak            # 자동 우회 전략 생성

npx promptfoo@latest redteam run

---

6. Langfuse — 관찰 가능성 통합

Langfuse는 프로덕션 LLM 앱의 모든 호출을 추적하고, 평가 점수를 기록하며, 인간 어노테이션 큐를 제공한다. 자체 호스팅이 가능해 데이터 주권이 중요한 환경에 적합하다.

설치

pip install langfuse

Python SDK — 자동 추적

from langfuse import Langfuse
from langfuse.decorators import observe, langfuse_context
 
langfuse = Langfuse(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="https://cloud.langfuse.com"  # 또는 자체 호스팅 URL
)
 
@observe()  # 자동으로 추적 생성
def run_rag_pipeline(user_query: str) -> str:
    # 검색 단계 추적
    with langfuse_context.update_current_observation(
        name="retrieval",
        input=user_query,
    ):
        docs = vector_db.search(user_query, k=5)
 
    # 생성 단계 추적
    response = llm.generate(user_query, context=docs)
 
    # 인라인 평가 점수 기록
    langfuse_context.score_current_trace(
        name="relevance",
        value=evaluate_relevance(user_query, response),
        comment="자동 관련성 평가"
    )
    return response

자체 호스팅 (Docker Compose)

# docker-compose.yml (간략 버전)
services:
  langfuse-server:
    image: ghcr.io/langfuse/langfuse:latest
    environment:
      DATABASE_URL: postgresql://postgres:password@db/langfuse
      NEXTAUTH_SECRET: your-secret
      SALT: your-salt
    ports:
      - "3000:3000"
 
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: langfuse

---

7. 에이전트 품질 보증 체크리스트

프로덕션 에이전트를 출시하기 전 검토해야 할 항목이다.

기능 평가

항목	도구	기준
Pass@1 (단일 시도 성공률) 측정	DeepEval, 자체 스크립트	태스크 유형별 기준선 설정
Pass@k (k번 시도 중 1회 이상 성공) 측정	자체 스크립트	k=3 ~ 5 권장
도구 호출 정확성 (올바른 도구·순서·인자)	DeepEval ToolCorrectnessMetric	≥ 0.8
목표 달성 완료율 (Goal Completion Rate)	DeepEval, RAGAS	≥ 0.75

안전성 평가

항목	도구	기준
레드팀: 적대적 입력 응답 테스트	PromptFoo 레드팀	0건 실패 (크리티컬 카테고리)
권한 범위 초과 시도 감지	로그 분석, Langfuse	0건 허용
프롬프트 인젝션 저항성	PromptFoo prompt-injection 플러그인	100% 차단

운영 안정성

항목	도구	기준
타임아웃·에러 핸들링 검증	부하 테스트	타임아웃 시 안전 종료
샌드박스 격리 확인	Docker, 네트워크 정책	컨테이너 외부 접근 불가
실행 추적 로깅 완비	Langfuse, LangSmith	모든 도구 호출 기록
결정론적 게이트 통과	CI/CD 린터·테스트	100% 통과 후 배포

회귀 방지

항목	도구	기준
CI/CD 파이프라인 평가 단계 통합	PromptFoo Actions, GitHub Actions	PR마다 자동 실행
기준선 대비 회귀 자동 감지	Braintrust, PromptFoo	5% 이상 저하 시 블록
모델 업데이트 시 자동 재평가 트리거	GitHub Actions (스케줄)	주 1회 이상

---

8. 단계별 학습 경로

초급 — 평가의 기초 이해

목표: LLM 평가가 왜 필요한지 이해하고, 기본 도구를 실행할 수 있는 수준

graph TD
    S1["1. 개념 읽기<br/>Martin Fowler: Harness Engineering<br/>Anthropic: Demystifying evals"]
    S2["2. PromptFoo 입문<br/>설치 → YAML 설정 → 두 모델 비교 실행"]
    S3["3. DeepEval 입문<br/>설치 → pytest 테스트 케이스 1개 작성 → 실행"]
    S4["4. Langfuse 입문<br/>무료 계정 → @observe 데코레이터 추가 → UI 확인"]

    S1 --> S2
    S2 --> S3
    S3 --> S4

중급 — 체계적 평가 파이프라인 구축

목표: CI/CD에 통합된 자동화 평가 시스템 운영

1. lm-evaluation-harness로 로컬 모델 MMLU·HellaSwag 평가 실행
2. DeepEval + RAGAS로 RAG 파이프라인 평가 (충실도, 문맥 재현율)
3. GitHub Actions에 PromptFoo 평가 단계 추가 (품질 게이트 설정)
4. Langfuse로 프로덕션 추적 대시보드 구축

고급 — Harness Engineering 설계

목표: 프로덕션 에이전트 시스템의 하네스 아키텍처 설계

1. Stripe Minions 패턴 학습

   • 6레이어 아키텍처 직접 설계 (샌드박스→컨텍스트→도구→게이트→라이프사이클→관찰)
   • Docker 샌드박스 + GitHub Actions 결정론적 게이트 구현

2. OpenAI Harness Engineering 사례 연구

   • 컨텍스트 엔지니어링, 아키텍처 경계, 엔트로피 관리 기법 적용

3. 멀티에이전트 평가 시스템 구축

   • Claude Agent Teams 패턴 구현 (리드 에이전트 + 팀원 에이전트)
   • METR 스타일 자율 능력 평가 설계

4. LangGraph 하네스 패턴

   • LangChain Blog: Improving Deep Agents with Harness Engineering 학습
   • 상태 머신 기반 에이전트 + 평가 루프 통합

학습 자료 로드맵

단계	자료	유형
초급	Martin Fowler: Harness Engineering	아티클
초급	Anthropic: Demystifying evals	블로그
중급	lm-eval-harness GitHub	문서
중급	DeepEval 에이전트 평가 가이드	가이드
중급	PromptFoo CI/CD 문서	문서
고급	Stripe Minions Part 2	블로그
고급	OpenAI: Harness Engineering	블로그
고급	LangChain: The Anatomy of an Agent Harness	블로그
고급	METR 에이전트 벤치마크	연구 기관

---

문서 탐색

이전	다음
3.3.2 하네스 아키텍처	—

---

참고 자료

• EleutherAI lm-evaluation-harness GitHub
• confident-ai/deepeval GitHub
• promptfoo/promptfoo GitHub
• langfuse/langfuse GitHub
• Anthropic Engineering: Demystifying evals for AI agents
• LangChain Blog: The Anatomy of an Agent Harness
• LangChain Blog: Improving Deep Agents with Harness Engineering
• OpenAI: Harness Engineering
• Stripe Dev Blog: Minions Part 2
• METR — AI Autonomous Capability Evaluations