EleutherAI/lm-evaluation-harness

• [2025/12]
  **CLI 리팩토링 (refactored)**이 수행되어 서브커맨드 (run, ls, validate)와 --config를 통한 YAML 설정 파일 지원이 추가되었습니다. CLI 레퍼런스 및 설정 가이드를 참조하세요. - [2025/12]
  더 가벼워진 설치: 기본 패키지에 더 이상 transformers / torch가 포함되지 않습니다. 모델 백엔드를 별도로 설치하세요: pip install lm_eval[hf], lm_eval[vllm] 등. - [2025/07] 이를 지원하는 모델에서 CoT (Chain of Thought) 추론 흔적을 제거하기 위해 hf (token/str), vllm 및 sglang (str)에 think_end_token 인자를 추가했습니다. - [2025/03] HF 모델을 스티어링 (steering) 할 수 있는 지원 기능이 추가되었습니다! - [2025/02] SGLang 지원이 추가되었습니다! - [2024/09] LM Evaluation Harness 사용자가 텍스트+이미지 멀티모달 (multimodal) 입력, 텍스트 출력 태스크를 생성하고 평가할 수 있도록 프로토타이핑 중이며, 프로토타입 기능으로 hf-multimodal 및 vllm-vlm 모델 타입과 mmmu 태스크를 방금 추가했습니다. 진행 중인 이 기능을 사용해 보고 직접 스트레스 테스트를 해보시길 권장하며, 더 넓은 범위의 멀티모달 태스크, 모델 및 기능을 원하신다면 원래 lm-evaluation-harness를 포크하여 만들어진 훌륭한 프로젝트인 lmms-eval을 확인해 보실 것을 제안합니다. - [2024/07] API 모델 지원이 업데이트 및 리팩토링되어 배치 (batched) 및 비동기 (async) 요청 지원이 도입되었으며, 사용자의 목적에 맞게 커스터마이징하고 사용하기가 훨씬 쉬워졌습니다.
  Llama 405B를 실행하려면, VLLM의 OpenAI 호환 API를 사용하여 모델을 호스팅하고, local-completions 모델 타입을 사용하여 모델을 평가하는 것을 권장합니다. - [2024/07] 새로운 Open LLM Leaderboard 태스크들이 추가되었습니다! 리더보드 태스크 그룹 아래에서 확인하실 수 있습니다.

lm-evaluation-harness의 새로운 v0.4.0 릴리스가 사용 가능합니다!

새로운 업데이트 및 기능은 다음과 같습니다:

새로운 Open LLM Leaderboard 태스크가 추가되었습니다! Leaderboard 태스크 그룹에서 확인하실 수 있습니다.

• 내부 리팩토링 (Internal refactoring)
• 설정 기반 (Config-based) 태스크 생성 및 구성
• 외부에서 정의된 태스크 설정 YAML 파일의 더 쉬운 임포트 및 공유
• Jinja2 프롬프트 설계 지원, 프롬프트의 쉬운 수정 + Promptsource로부터의 프롬프트 임포트
• 출력 후처리 (output post-processing), 정답 추출 (answer extraction), 문서당 다중 언어 모델 (LM) 생성, 설정 가능한 퓨샷 (fewshot) 설정 등을 포함한 더 발전된 구성 옵션
• 속도 향상 및 새로운 모델링 라이브러리 지원: 더 빠른 데이터 병렬 (data-parallel) HF 모델 사용, vLLM 지원, HuggingFace를 통한 MPS 지원 등
• 로깅 (Logging) 및 사용성 변경
• CoT BIG-Bench-Hard, Belebele, 사용자 정의 태스크 그룹화 등을 포함한 새로운 태스크

자세한 내용은 docs/에 있는 업데이트된 문서 페이지를 참조하십시오.

개발은 main 브랜치에서 계속 진행될 예정이며, GitHub의 이슈(issues)나 PR, 또는 EleutherAI 디스코드에서 어떤 기능이 필요한지, 라이브러리를 어떻게 더 개선할 수 있을지에 대한 피드백을 주시거나 질문을 남겨주시길 권장합니다!

이 프로젝트는 수많은 다양한 평가 태스크에서 생성형 언어 모델 (generative language models)을 테스트할 수 있는 통합 프레임워크를 제공합니다.

주요 기능:

• 수백 개의 하위 태스크와 변형이 구현된 60개 이상의 LLM 표준 학술 벤치마크 (benchmarks).
• transformers를 통해 로드된 모델 (GPTQModel 및 AutoGPTQ를 통한 양자화 포함), GPT-NeoX, Megatron-DeepSpeed 지원 및 유연한 토큰화 불가지론적 (tokenization-agnostic) 인터페이스.
• vLLM을 통한 빠르고 메모리 효율적인 추론 지원.
• OpenAI 및 TextSynth를 포함한 상용 API 지원.
• HuggingFace의 PEFT 라이브러리에서 지원하는 어댑터 (예: LoRA)에 대한 평가 지원.
• 로컬 모델 및 벤치마크 지원.
• 공개적으로 사용 가능한 프롬프트를 사용한 평가를 통해 논문 간의 재현성 (reproducibility) 및 비교 가능성 보장.
• 커스텀 프롬프트 및 평가 지표 (evaluation metrics)에 대한 간편한 지원.

Language Model Evaluation Harness는 🤗 Hugging Face의 인기 있는 Open LLM Leaderboard의 백엔드(backend)이며, 수백 편의 논문에서 사용되었고, NVIDIA, Cohere, BigScience, BigCode, Nous Research, Mosaic ML을 포함한 수십 개의 조직에서 내부적으로 사용되고 있습니다.

GitHub 저장소에서 lm-eval 패키지를 설치하려면 다음을 실행하세요:

git clone --depth 1 https://github.com/EleutherAI/lm-evaluation-harness
cd lm-evaluation-harness
pip install -e .

기본 설치는 핵심 평가 프레임워크를 제공합니다. 모델 백엔드(Model backends)는 선택적 추가 기능(optional extras)을 사용하여 별도로 설치해야 합니다.

HuggingFace transformers 모델의 경우:

pip install "lm_eval[hf]"

vLLM 추론(inference)의 경우:

pip install "lm_eval[vllm]"

API 기반 모델 (OpenAI, Anthropic 등)의 경우:

pip install "lm_eval[api]"

여러 백엔드를 함께 설치할 수 있습니다:

pip install "lm_eval[hf,vllm,api]"

모든 선택적 추가 기능에 대한 자세한 표는 이 문서의 끝에서 확인할 수 있습니다.

가이드	설명
CLI Reference	명령줄 인자(Command-line arguments) 및 서브커맨드
...

사용 가능한 옵션을 보려면 lm-eval -h를, 평가 옵션을 보려면 lm-eval run -h를 사용하세요.

다음 명령으로 사용 가능한 태스크(tasks) 목록을 나열할 수 있습니다:

lm-eval ls tasks

중요

HuggingFace 백엔드를 사용하려면 먼저 다음을 설치하세요: pip install "lm_eval[hf]"

HuggingFace Hub에 호스팅된 모델(예: GPT-J-6B)을 hellaswag에서 평가하려면 다음 명령을 사용할 수 있습니다 (이 명령은 CUDA 호환 GPU를 사용한다고 가정합니다):

lm_eval --model hf \
--model_args pretrained=EleutherAI/gpt-j-6B \
--tasks hellaswag \
...

--model_args 플래그를 사용하여 모델 생성자(constructor)에 추가 인자를 제공할 수 있습니다. 특히, 이는 부분적으로 학습된 체크포인트를 저장하기 위해 Hub의 revisions 기능을 사용하거나, 모델 실행을 위한 데이터 타입(datatype)을 지정하는 일반적인 관행을 지원합니다:

lm_eval --model hf \
--model_args pretrained=EleutherAI/pythia-160m,revision=step100000,dtype="float" \
--tasks lambada_openai,hellaswag \
...

Huggingface에서 transformers.AutoModelForCausalLM (자기회귀적 (autoregressive), 디코더 전용 (decoder-only) GPT 스타일 모델) 및 transformers.AutoModelForSeq2SeqLM (T5와 같은 인코더-디코더 (encoder-decoder) 모델)을 통해 로드되는 모델들이 지원됩니다.

배치 크기 (Batch size) 선택은 --batch_size 플래그를 auto로 설정하여 자동화할 수 있습니다. 이렇게 하면 사용자의 장치에 적합한 가장 큰 배치 크기를 자동으로 감지합니다. 가장 긴 예시와 가장 짧은 예시 사이에 큰 차이가 있는 태스크의 경우, 추가적인 속도 향상을 위해 주기적으로 가장 큰 배치 크기를 재계산하는 것이 도움이 될 수 있습니다. 이를 위해 위 플래그 뒤에 :N을 추가하면 가장 큰 배치 크기를 N번 자동으로 재계산합니다. 예를 들어, 배치 크기를 4번 재계산하려면 명령어는 다음과 같습니다:

lm_eval --model hf \
--model_args pretrained=EleutherAI/pythia-160m,revision=step100000,dtype="float" \
--tasks lambada_openai,hellaswag \
...

참고

transformers.AutoModel에 로컬 경로를 제공할 수 있는 것과 마찬가지로, --model_args pretrained=/path/to/model을 통해 lm_eval에 로컬 경로를 제공할 수 있습니다.

lm-eval은 Hugging Face (hf) 백엔드를 사용하여 GGUF 형식의 모델을 평가하는 것을 지원합니다. 이를 통해 transformers, AutoModel 및 llama.cpp 변환과 호환되는 양자화된 (quantized) 모델을 사용할 수 있습니다.

GGUF 모델을 평가하려면 --model_args 플래그를 사용하여 모델 가중치가 포함된 디렉토리 경로, gguf_file, 그리고 선택적으로 별도의 tokenizer 경로를 전달하십시오.

🚨 중요 참고 사항:

별도의 토크나이저 (tokenizer)를 제공하지 않으면, Hugging Face는 GGUF 파일로부터 토크나이저를 재구성하려고 시도합니다. 이 과정은 몇 시간이 걸리거나 심지어 무한히 중단될 수 있습니다. 별도의 토크나이저를 전달하면 이 문제를 방지할 수 있으며, 토크나이저 로딩 시간을 몇 시간에서 몇 초로 단축할 수 있습니다.

✅ 권장 사용법:

lm_eval --model hf \
--model_args pretrained=/path/to/gguf_folder,gguf_file=model-name.gguf,tokenizer=/path/to/tokenizer \
--tasks hellaswag \
...

팁

tokenizer 경로가 유효한 Hugging Face tokenizer 디렉터리(예: tokenizer_config.json, vocab.json 등이 포함된 디렉터리)를 가리키고 있는지 확인하십시오.

우리는 멀티 GPU 평가를 위해 Hugging Face의 accelerate 🚀 라이브러리를 사용하는 세 가지 주요 방법을 지원합니다.

데이터 병렬 평가 (data-parallel evaluation) (각 GPU가 모델의 별도 전체 복사본을 로드하는 방식)를 수행하려면, 다음과 같이 accelerate 런처를 활용합니다:

accelerate launch -m lm_eval --model hf \
--tasks lambada_openai,arc_easy \
--batch_size 16

(또는 accelerate launch --no-python lm_eval을 통해 수행할 수 있습니다).

모델이 단일 GPU에 들어갈 수 있는 경우, 이 방식을 사용하면 K개의 GPU에서 평가할 때 1개의 GPU에서 할 때보다 K배 더 빠르게 평가할 수 있습니다.

경고 (WARNING): 이 설정은 FSDP 모델 샤딩 (model sharding)과 함께 작동하지 않으므로, accelerate config에서 FSDP를 비활성화하거나 NO_SHARD FSDP 옵션을 사용해야 합니다.

멀티 GPU 평가를 위해 accelerate를 사용하는 두 번째 방법은 모델이 단일 GPU에 담기기에 너무 큰 경우입니다.

이 설정에서는 라이브러리를 accelerate 런처 외부에서 실행하되, 다음과 같이 --model_args에 parallelize=True를 전달합니다:

lm_eval --model hf \
--tasks lambada_openai,arc_easy \
--model_args parallelize=True \
...

이는 모델의 가중치 (weights)가 사용 가능한 모든 GPU에 분산되어 배치됨을 의미합니다.

숙련된 사용자나 훨씬 더 큰 모델을 위해, parallelize=True일 때 다음과 같은 인자들도 사용할 수 있도록 허용합니다:

device_map_option: 사용 가능한 GPU에 모델 가중치를 분할하는 방법. 기본값은 "auto"입니다.
max_memory_per_gpu: 모델을 로드할 때 GPU당 사용할 최대 GPU 메모리.
max_cpu_memory: 모델 가중치를 RAM으로 오프로딩 (offloading)할 때 사용할 최대 CPU 메모리 양.
offload_folder: 필요한 경우 모델 가중치를 디스크로 오프로딩할 폴더.

세 번째 옵션은 두 가지를 동시에 사용하는 것입니다. 이를 통해 데이터 병렬성 (data parallelism)과 모델 샤딩 (model sharding)의 이점을 모두 누릴 수 있으며, 특히 단일 GPU에 담기에는 너무 큰 모델에 유용합니다.

accelerate launch --multi_gpu --num_processes {nb_of_copies_of_your_model} \
-m lm_eval --model hf \
--tasks lambada_openai,arc_easy \
...

모델 병렬화 (model parallelism)와 accelerate 라이브러리를 사용하여 이를 사용하는 방법에 대해 더 자세히 알아보려면, accelerate 문서를 참조하십시오.

경고: 저희는 hf 모델 타입을 사용하여 멀티 노드 (multi-node) 평가를 기본적으로 지원하지 않습니다! 커스텀 멀티 머신 (multi-machine) 평가 스크립트가 작성된 코드 예시로 저희의 GPT-NeoX 라이브러리 통합 사례를 참조해 주세요.

참고: 현재 멀티 노드 평가를 기본적으로 지원하지 않으며, 추론 (inference) 요청을 보낼 외부 호스팅 서버를 사용하거나, GPT-NeoX 라이브러리에서 수행하는 것과 같이 분산 프레임워크 (distributed framework)를 사용하여 커스텀 통합을 생성하는 것을 권장합니다.

PyTorch의 네이티브 텐서 병렬화 (Tensor Parallelism, DTensor를 통해)를 지원하는 모델의 경우, --model_args에 tp_plan=auto를 전달함으로써 accelerate의 디바이스 맵 (device-map) 없이도 GPU 간에 모델 가중치를 샤딩 (shard)할 수 있습니다. torchrun 또는 accelerate launch로 실행하십시오:

torchrun --nproc-per-node=4 -m lm_eval \
--model hf \
--model_args pretrained=google/gemma-4-31B-it,tp_plan=auto \
...

제약 사항:

• tp_plan과 parallelize=True는 상호 배타적입니다. 둘 중 하나만 사용하십시오.
• 모델의 키-값 헤드 (key-value heads) 수는 --nproc-per-node (TP 차수)로 나누어떨어져야 합니다.
• PyTorch >= 2.4 및 해당 모델에 대한 TP 플랜 (TP plan)을 노출하는 transformers 버전 (v4.47+)이 필요합니다.

스티어링 벡터 (steering vectors)가 적용된 Hugging Face transformers 모델을 평가하려면, 모델 타입을 steered로 지정하고 미리 정의된 스티어링 벡터가 포함된 PyTorch 파일 경로 또는 사전 학습된 sparsify나 sae_lens 모델로부터 스티어링 벡터를 도출하는 방법을 지정하는 CSV 파일 경로를 제공하십시오 (이 방법을 사용하려면 해당 선택적 의존성 (optional dependency)을 설치해야 합니다).

미리 정의된 스티어링 벡터 지정:

import torch
steer_config = {
"layers.3": {
...

도출된 스티어링 벡터 지정:

import pandas as pd
pd.DataFrame({
"loader": ["sparsify"],
...

스티어링 벡터 (steering vectors)를 적용하여 evaluation harness를 실행합니다:

lm_eval --model steered \
--model_args pretrained=EleutherAI/pythia-160m,steer_path=steer_config.pt \
--tasks lambada_openai,hellaswag \
...

NVIDIA NeMo Framework는 언어 모델 (language models)을 연구하는 연구자 및 PyTorch 개발자를 위해 구축된 생성형 AI (generative AI) 프레임워크입니다.

nemo 모델을 평가하려면, 먼저 문서를 따라 NeMo를 설치하십시오. 특히 Apex 또는 기타 종속성 (dependencies) 설치에 문제가 있는 경우, NVIDIA PyTorch 또는 NeMo 컨테이너를 사용하는 것을 강력히 권장합니다 (최신 출시된 컨테이너를 참조하십시오). 또한 Install 섹션의 지침에 따라 lm evaluation harness 라이브러리를 설치해 주세요.

NeMo 모델은 NVIDIA NGC Catalog 또는 NVIDIA의 Hugging Face 페이지를 통해 얻을 수 있습니다. NVIDIA NeMo Framework에는 llama, falcon, mixtral 또는 mpt와 같은 인기 있는 모델의 hf 체크포인트를 nemo로 변환하는 변환 스크립트 (conversion scripts)가 포함되어 있습니다.

nemo를 실행합니다