LLM 평가 하네스(evaluation harness)란 무엇인가? lm-eval-harness 심층 분석

당신은 7B 모델을 파인튜닝(fine-tuned)했습니다. 스모크 테스트(smoke tests)를 통과했고, 동료는 몇 가지 프롬프트(prompts)를 실행해 본 뒤 만족스럽다는 듯 어깨를 으쓱했습니다. 이제 README 파일은 스크린샷에서 아주 멋져 보이는 체리피킹(cherry-picked)된 출력물들로 가득 차 있습니다. 그때 누군가 질문합니다. "정말로 얼마나 성능이 좋은가요?" — 그리고 당신은 제시할 수 있는 수치가 하나도 없다는 사실을 깨닫습니다. MMLU 점수도 없고, HellaSwag도 없습니다. 재현 가능하지도 않고, PR(Pull Request) 리뷰에서 방어할 수도 없으며, 지난주의 체크포인트(checkpoint)와 비교할 수도 있는 것이 아무것도 없습니다.

이것이 바로 평가 하네스(evaluation harness)가 메우는 간극입니다. 평가 하네스는 "느낌 기반 평가(vibes-based evaluation)"를 점수, stderr, 그리고 다음 주 화요일에 다시 실행할 수 있는 설정 파일(config file)이 있는 무언가로 바꿔줍니다.

왜 LLM을 평가해야 하는가?

실제로 중요한 두 가지 이유가 있습니다:

1. 비교 가능성 (Comparability). 모델에 수치를 부여할 수 없다면, 다른 어떤 것과도 비교할 수 없습니다. 이전 체크포인트도, 오픈 소스 베이스라인(open-source baseline)도, 당신이 대체하려는 상용 API(commercial API)도 비교할 수 없습니다. 리더보드(Leaderboards)는 노이즈가 많고 조작되기 쉽지만, 당신이 중요하게 생각하는 태스크(tasks)들로 구성된 로컬(local) 리더보드는 팀이 구축할 수 있는 가장 유용한 결과물 중 하나입니다.
2. 회귀 탐지 (Regression detection). 대부분의 모델 회귀(regressions)는 조용히 일어납니다. MMLU에서 0.3점 하락하는 것은 채팅 세션에서는 나타나지 않지만, CI(Continuous Integration)에서는 나타납니다. 모델을 전문적으로 배포하는 사람들은 백엔드 엔지니어가 유닛 테스트(unit tests)를 다루는 것처럼 평가(evals)를 다룹니다. 즉, 필수적이며, 모든 PR에서 실행되어야 하고, 회귀가 발생하면 차단(blocking)해야 하는 것입니다.

수백 개의 벤치마크(benchmarks)가 필요한 것은 아닙니다. 당신에게는 실제 사용 사례(use case)에 매핑되는 3~5개의 태스크와, 도메인에 맞춰 튜닝하는 동안 기본적인 추론 능력을 실수로 파괴하지 않았는지 확인하기 위한 한두 개의 일반적인 능력 앵커(general capability anchors, 예: MMLU, HellaSwag)가 필요할 뿐입니다.

"평가 하네스(evaluation harness)"란 무엇인가?

평가 하네스(evaluation harness)는 모델과 벤치마크(benchmark) 사이에 위치하는 소프트웨어입니다. 이는 지루하지만 매우 중요한 작업들을 처리합니다: 모델 가중치(model weights) 로드, 벤치마크가 기대하는 방식대로 프롬프트(prompt) 토큰화(tokenizing), 추론(inference) 실행, 긴 생성문에서 정답 추출, 정답 키(ground-truth key)를 기준으로 점수 산출, 예제 전반에 걸친 결과 집계, 그리고 지난주 실행 결과와 비교(diff)할 수 있는 JSON 또는 CSV 파일 작성 등이 이에 해당합니다.

핵심적인 통찰은 모델과 테스트의 분리에 있습니다. 벤치마크는 단순히 데이터셋(dataset)과 채점 규칙(scoring rule)일 뿐입니다. 하네스는 이를 연결하는 배관(plumbing) 역할을 합니다. 이 둘을 분리해 두었기에, 어느 한 쪽을 다시 구현할 필요 없이 동일한 모델을 여러 벤치마크에서 평가하거나, 여러 모델을 동일한 벤치마크에서 평가할 수 있는 것입니다.

전체 파이프라인(pipeline)의 흐름은 다음과 같습니다:

flowchart LR
    A[모델 로드<br/>HF / vLLM / API] --> B[프롬프트 형식 지정<br/>태스크 템플릿]
    B --> C[생성<br/>로그 확률(logprobs) 또는 텍스트]
...

위의 모든 단계는 lm-eval-harness에서 설정 가능합니다. 이것이 이 도구의 핵심입니다.

lm-eval-harness 상세 분석

EleutherAI는 2020년에 발표된 LLM 벤치마크 수치들을 재현하기 위한 통합된 방법론으로서 이 프로젝트를 시작했습니다. 현재 v0.4.12 (2026년 5월) 버전에 도달했으며, 추론(reasoning), 지식(knowledge), 코딩(coding), 수학(math), 다국어(multilingual), 그리고 롱 컨텍스트(long-context) 벤치마크를 아우르는 **200개 이상의 태스크(task)**를 제공합니다. 또한 Hugging Face transformers, vLLM, SGLang, GPT-NeoX, Megatron-DeepSpeed를 비롯하여 OpenAI, Anthropic 및 기타 몇몇 서비스의 API 엔드포인트(endpoint)까지 방대한 모델 백엔드(model backend) 목록을 지원합니다.

지난 1년 동안 알아둘 만한 몇 가지 변화가 있었습니다:

• CLI가 리팩토링되었습니다 (refactored) (v0.4.x). 기존의 평면적인 lm_eval --tasks ... 방식도 여전히 작동하지만, 새로운 스타일은 lm_eval run, lm_eval ls, lm_eval validate와 같은 서브커맨드(subcommands)를 사용합니다. 이제 --config를 통해 YAML 설정 파일(config file)로부터 전체 실행을 제어할 수 있으며, 이는 몇 가지 이상의 많은 태스크(tasks)를 관리할 수 있는 유일하고 합리적인 방법입니다.
• 설치가 더 가벼워졌습니다. 기본 패키지는 더 이상 transformers나 torch를 자동으로 불러오지 않습니다. 실제로 필요한 백엔드(backend)를 직접 설치하면 됩니다: pip install lm_eval[hf] 또는 lm_eval[vllm] 또는 lm_eval[api]. 4 GB 대신 30 MB 크기의 휠(wheel) 파일만 설치하게 됩니다.
• 멀티모달(Multimodal) 기능이 프로토타입(prototype) 단계로 포함되었습니다. hf-multimodal 및 vllm-vlm 모델 타입을 통해 지원되며, 첫 번째 실제 태스크로 mmmu가 포함되었습니다. 만약 시각-언어(vision-language) 작업을 수행 중이라면 lmms-eval을 살펴보세요. 이는 훨씬 더 광범위한 멀티모달 태스크 커버리지를 가진 포크(fork) 버전입니다.

태스크의 구조 (Anatomy of a task)

레지스트리(registry)에 있는 모든 벤치마크(benchmark)는 YAML 파일입니다. 저장소에서 가져온 실제 예시인 hellaswag.yaml을 살펴보겠습니다:

tag:
  - multiple_choice
task: hellaswag
...

가장 자주 접하게 될 필드들은 다음과 같습니다:

• task — 태스크의 등록된 이름으로, --tasks 인자에 전달하는 값입니다.
• dataset_path — Hugging Face 데이터셋 ID입니다. 대부분의 태스크는 공개 데이터셋을 가리키지만, 비공개 데이터셋의 경우 HF_TOKEN 환경 변수가 필요합니다.
• output_type — 전체 스코어링 파이프라인 (scoring pipeline)을 결정합니다. multiple_choice는 로그 확률 기반의 argmax (logprob-based argmax)를 사용합니다 (빠르며, 텍스트 생성이 필요 없음). generate는 모델이 실제로 텍스트를 생성해야 합니다. 또한 오래된 퍼플렉시티 (perplexity) 스타일의 태스크를 위한 loglikelihood 방식도 있습니다.
• doc_to_text / doc_to_target / doc_to_choice — 각 데이터셋 행에서 필드를 추출하는 Jinja2 템플릿입니다. {{query}}는 해당 행의 컬럼(column)을 의미합니다.
• metric_list — 계산할 지표입니다. acc는 원시 정확도 (raw accuracy)이며, acc_norm은 길이 정규화 (length normalization)를 거친 정확도입니다 (긴 선택지가 불공정하게 유리할 수 있는 HellaSwag 및 기타 몇몇 태스크에서 중요합니다).
• metadata.version — 태스크 정의가 변경될 때마다 업데이트되며, 이를 통해 오래된 결과 파일이 새로운 파일과 혼동되지 않도록 합니다. 태스크를 변경했다면 이 버전을 올려야 합니다.

디렉토리에 YAML 파일을 넣고 --include_path로 해당 파일을 지정하면 자신만의 태스크를 작성할 수 있습니다. 사람들은 도메인 특화 벤치마크 (domain-specific benchmarks)를 위해 이 방법을 끊임없이 사용합니다.

직접 실행해보기

Hugging Face 백엔드와 함께 설치합니다:

pip install lm_eval[hf]

작은 공개 모델로 HellaSwag를 실행합니다:

lm_eval run \
  --model hf \
  --model_args pretrained=meta-llama/Llama-3.2-1B,dtype=bfloat16 \
...

실행하면 results.json (기계 판독 가능) 파일과 샘플별 로그가 담긴 results/ 디렉토리가 생성됩니다. HellaSwag에 대한 1B 모델 실행은 단일 A100에서 몇 분 내에 완료됩니다. 첫 실행 시에는 데이터셋을 다운로드하므로 몇 초의 시간이 더 소요될 수 있습니다.

vLLM의 경우 (더 큰 모델에서 훨씬 빠릅니다):

pip install lm_eval[vllm]
lm_eval run --model vllm --model_args pretrained=mistralai/Mistral-7B-v0.3 --tasks mmlu,hellaswag,arc_easy

lm-eval-harness vs 대안들

Harness	강점	약점	관리 주체
lm-eval-harness	광범위한 범위, 오픈 소스 (OSS) 커뮤니티, YAML 정의 태스크, 멀티 백엔드 (multi-backend)	UI, 커스텀 메트릭 (custom metric) UX	EleutherAI
...

솔직한 요약: 대부분의 팀에게는 lm-eval-harness가 기본값입니다. 중국어 벤치마크 (benchmarks)가 중요하다면 OpenCompass를, Stanford 스타일의 다축 보고 (multi-axis reporting)를 원한다면 HELM을, 이미 Hugging Face (HF) 생태계에 깊이 발을 들이고 있으며 Hub와 통합되는 것을 원한다면 lighteval을 선택하세요.

흔한 함정들 (Common pitfalls)

처음 접하는 모든 이들이 빠지기 쉬운 몇 가지 함정입니다:

• 데이터 오염 (Data contamination). 모델이 사전 학습 (pretraining) 과정에서 테스트 세트를 이미 보았을 수 있습니다. 깔끔한 해결책은 없지만, 최소한 모델의 학습 중단 시점 (training cutoff)을 알고 있어야 하며, 가능하다면 그 시점 이후에 데이터가 공개된 벤치마크를 선택해야 합니다. MMLU는 현재 사실상 포화 상태입니다.
• 프롬프트 형식 민감도 (Prompt-format sensitivity). 퓨샷 (few-shot) 구분자, 정답 추출 정규식 (regex)

lm-eval-harness는 다음과 같은 경우에는 적절한 도구가 아닙니다:

• 프로덕션 트래픽 (production traffic)을 모니터링하는 경우. 그 용도로는 Langfuse / Phoenix / Helicone / Braintrust가 필요합니다. 온라인 평가 (Online eval)는 다른 범주의 문제입니다. HellaSwag가 아닌, 여러분의 데이터에 대한 암시적 피드백 (implicit feedback), 드리프트 탐지 (drift detection), 환각률 (hallucination rates)을 다뤄야 합니다.
• 도메인 특화 벤치마크 (domain-specific benchmark)가 필요한 경우. 만약 법률 계약 검토기를 출시한다면, "MMLU가 65.4이다"라는 정보는 거의 아무런 도움이 되지 않습니다. 실제 프로덕션 샘플로부터 수작업으로 채점하는 작은 (~200–500개 예시) 테스트 세트를 구축하고, 버전을 관리하며, 모든 PR (Pull Request)마다 실행하세요. lm-eval-harness의 --include_path 옵션을 사용하면 이를 쉽게 수행할 수 있습니다.
• 장난감 수준의 작업 (toy task)에서 아주 작은 커스텀 모델을 평가하는 경우. 감성 분류 (sentiment classification)를 위해 미세 조정 (fine-tuned)된 50M 파라미터 모델에는 HellaSwag가 필요하지 않습니다. 모델을 1,000번 호출하고 정확도 (accuracy)를 계산하는 파이썬 (Python) 스크립트를 작성하기만 하면 됩니다. 하네스 (harness)의 오버헤드는 실제로 존재합니다.

요약 (TL;DR)

• **LLM 평가 하네스 (LLM evaluation harness)**는 모델과 표준화된 벤치마크 사이를 연결하는 배관 (plumbing) 역할을 합니다. 모델을 로드하고, 프롬프트 (prompt) 형식을 지정하며, 추론 (inference)을 실행하고, 답변을 채점하며, 결과를 기록합니다.
• lm-eval-harness (EleutherAI)는 사실상의 오픈 소스 (OSS) 표준입니다. v0.4.12 버전 기준, 200개 이상의 태스크 (task)와 다양한 백엔드 (backend)를 지원합니다.
• **태스크 (task)**는 output_type, doc_to_text, metric_list와 같은 필드를 포함하는 YAML 파일입니다. 직접 작성할 수 있으며 --include_path를 통해 지정할 수 있습니다.
• 사용 사례에 매칭되는 작고 버전이 고정된 태스크 세트와 함께 1~2개의 일반적인 앵커 (anchor) 태스크를 실행하세요. 안정성 확인 없이 ~0.5점 미만의 차이 (delta)를 신뢰하지 마세요.
• 오프라인 평가 (offline eval) 및 회귀 탐지 (regression detection) 용도로 사용하세요. 프로덕션 모니터링에는 관측성 (observability) 도구를 사용하세요. 도메인 특화 평가를 위해서는 직접 작성하세요.

다음 포스트: 도메인 특화 평가 세트를 실제로 구축하는 방법 — 샘플링 전략 (sampling strategy), 평가자 간 일치도 (inter-rater agreement), 그리고 "나의 골든 세트 (golden set)가 여전히 골든 세트인가" 문제에 대해 다룹니다.

만약 모델을 구축 중이며 여러분의 평가 설정 (eval setup)에 대해 제2의 시각을 원하신다면, 다음 포스트를 위해 피드백을 수집하고 있습니다. 다루기를 원하는 작업 (tasks)의 종류를 댓글이나 DM으로 남겨주세요.