huggingface/optimum-benchmark

🏋️ A unified multi-backend utility for benchmarking Transformers, Timm, PEFT, Diffusers and Sentence-Transformers with full support of Optimum's hardware optimizations & quantization schemes.

What is Optimum‑Benchmark?

Optimum‑Benchmark 는 다양한 하드웨어 백엔드에서 Hugging Face 모델의 실행 속도와 효율성을 측정할 수 있는 Python 라이브러리입니다. 주요 모델 패밀리(Transformer, Diffusers, PEFT, TIMM 등)와 넓은 범위의 런타임(PyTorch, ONNX Runtime, OpenVINO, vLLM, TensorRT‑LLM, IPEX, Llama‑Cpp, Py‑TXI 등)을 지원하며, CPU, GPU, AMD ROCm, Intel XPU, Habana Gaudi 등 다양한 물리적 하드웨어에서 작동합니다.

이 도구는 추론(지연 시간, 처리량, 메모리, 에너지)과 학습(동일한 메트릭에 더해 데이터셋 형상 제어)을 모두 벤치마킹할 수 있습니다. 단일 프로세스 모드, torchrun 을 통한 분산 실행, 또는 간단한 Hydra 기반 CLI 로 작동합니다. 결과는 JSON, Markdown, 일반 텍스트 파일로 저장되며, 공유를 위해 Hugging Face Hub 에 푸시할 수 있습니다.

누구에게 유용한가요?

동일한 모델로 경쟁 제품과 자신의 칩을 비교하고 싶은 하드웨어 제조사.
배포 전 특정 백엔드에서 모델의 지연 시간, 메모리 사용량 또는 에너지 비용을 알고 싶은 모델 개발자 / 연구자.
Optimum 생태계에서 제공하는 양자화, 프루닝, 기타 최적화의 영향을 평가하고 싶은 ML 엔지니어.
재현 가능하고 구성 가능한 실행을 원하며, 장치, 백엔드, 모델 변형을 스위프할 수 있는 벤치마킹 애호가.

핵심 개념

개념	의미
Launcher	벤치마크 프로세스의 시작 방식 – `process` (격리), `torchrun` (분산), `inline` (디버그 전용).
Scenario	측정 대상 – `inference` (포워드 / 생성) 또는 `training` (트레이너 루프).
Backend	실제로 모델을 실행하는 런타임 – 예: `pytorch`, `onnxruntime`, `vllm`, `openvino`, `tensorrt‑llm` 등.
Device	물리적 하드웨어 타겟 – `cpu`, `cuda`, `rocm`, `gpu`, `xpu`, `hpu` 등.
Config	Hydra 호환 YAML 파일(또는 Python 객체)로 세 가지 요소를 연결하고 배치 크기, 입력 형상, 워밍업 실행, 에너지 추적 등과 같은 설정을 조정할 수 있습니다.

시작하기

설치 – 라이브러리는 PyPI 에 있습니다. 가장 간단한 방법은 pip install optimum-benchmark 또는, 빠른 uv 매니저를 선호한다면 uv add optimum-benchmark 입니다.
백엔드 선택 – 필요로 하는 런타임용 선택적 확장 기능을 설치합니다. 예: pip install optimum-benchmark[onnxruntime] 또는 uv add optimum-benchmark --extra vllm.
벤치마크 실행 – 다음 중 하나로 실행합니다:
- Python API – BenchmarkConfig 를 생성하고, TorchrunConfig, InferenceConfig (또는 TrainingConfig) 및 백엔드 설정(예: PyTorchConfig(model="gpt2", device="cuda"))을 지정합니다. Benchmark.launch(config) 를 호출하고 반환된 BenchmarkReport 를 확인합니다.
- CLI – optimum-benchmark --config-dir examples/ --config-name cuda_pytorch_bert. --multirun 을 사용해 값 스위프(예: backend.device=cpu,cuda)가 가능합니다.
결과 확인 – 실행 결과 여러 파일(benchmark_report.json, .md, .txt 등)이 생성되며, 필요 시 Hugging Face Hub 에 푸시할 수 있습니다.

왜 유용한가요?

수십 개의 백엔드와 장치에서 통합된 인터페이스를 제공하여, 각 런타임용 별도 스크립트를 작성할 필요가 없습니다.
정확한 메트릭 – 지연 시간, 처리량, 메모리 사용량 및 codecarbon 통합을 통한 선택적 에너지 추적.
재현 가능성 – Hydra 설정, Docker 이미지(cpu, cuda, rocm), CI 테스트로 동일한 벤치마크를 어디서든 재실행할 수 있습니다.
확장성 – 제공된 설정 클래스를 확장해 새로운 백엔드, 런처, 사용자 정의 메트릭을 추가할 수 있습니다.

더 알아보기

위에 표시된 README 는 빠른 시작 명령어와 지원되는 백엔드의 전체 목록을 포함합니다.
예제 설정 파일은 리포지토리의 examples/ 디렉터리에 있습니다.
라이브러리의 API 문서 는 optimum_benchmark 패키지에서 생성되며, 설치 후 확인할 수 있습니다.
커뮤니티 주도의 성능 비교는 Hugging Face Hub 에 호스팅된 LLM‑Perf Leaderboard 를 참조하세요.

TL;DR

Optimum‑Benchmark 는 Hugging Face 유지보수의, 트랜스포머 스타일 모델을 위한 다중 백엔드 벤치마크 툴킷입니다. 설치하고 백엔드/디바이스를 선택한 후, Hydra 설정을 정의하거나 Python API를 사용해 벤치마크를 실행하면, 공개적으로 공유할 수 있는 상세한 지연 시간/메모리/에너지 리포트를 얻을 수 있습니다. 빠르게 변화하는 AI 하드웨어 환경에서 신뢰할 수 있고 재현 가능한 성능 수치가 필요한 모든 사람들을 위한 도구입니다.