homebench

사용자가 이미 보유한 로컬 LLMs의 속도, 메모리, 그리고 품질을 라이브 터미널 리더보드로 벤치마킹합니다.

PyPI

Python

License

homebench는 로컬 러너(local runner)에 설치된 모델(Ollama, LM Studio, llama.cpp, vLLM, 또는 모든 OpenAI-compatible 서버)를 검색하고, 선별된 품질 테스트 스위트(curated quality suite)를 실행하며, 실제 사용자의 기기에서 tokens/sec, time-to-first-token, 그리고 memory footprint을 측정하여 라이브 비교 리더보드를 렌더링하는 단일 명령어 TUI입니다.

pip install homebench
homebench

그게 전부입니다. 설정(config)도, API 키도, 클라우드 연결도 필요 없습니다.

왜 필요한가 (Why)

이 문제의 절반에 대해서는 훌륭한 도구들이 있지만, 둘 다를 처리하는 로컬 우선(local-first) 도구는 없습니다:

• llama-bench (llama.cpp 내부): 속도만 측정합니다.
• lm-evaluation-harness: 품질을 측정하지만, 세련된 노트북 UX가 부족하고 대부분의 사용자가 로컬에서 실제로 사용하는 모델 러너를 중심으로 구축되지 않았습니다.

homebench는 이 간극을 메웁니다: 로컬 우선(local-first), 제로 설정(zero-config), UX 중심. 클론하여 실행하기만 하면, 이미 다운로드한 모델들을 지정하고 *

homebench # fast default: 3 smallest models, quick suite (TUI)
homebench --all # benchmark every discovered model
homebench --full # run the full quality suite (not just the fast subset)
...

전체 플래그 목록은 homebench --help를 실행하세요.

예시 출력

Apple M1 (16 GB)에서 Ollama를 통해 실행한 실제 빠른 테스트 결과:

                               Final leaderboard
┏━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
┃ # ┃ Model                ┃ Params ┃ Quality ┃ Pass ┃ tok/s ┃   TTFT ┃ Memory ┃
...

(숫자는 그 노트북에서 그 순간의 수치입니다 — 제한 사항 참조.)

제공자 (Providers)

최소한 하나의 로컬 모델 러너가 연결되어 있어야 합니다:

품질 채점 방식 (How quality grading works)

이 테스트 스위트는 의도적으로 작습니다 — 모델을 구분하기에 충분한 카테고리별 작업들을 포함하며, 모든 모델이 노트북에서 몇 분 안에 실행될 만큼 적절합니다. 각 작업은 결정론적으로 채점됩니다(정확한 숫자 일치, 객관식 문자, 부분 문자열, 유효 JSON, 정규 표현식). 재현성을 위해 Temperature는 0으로 설정하고 고정된 시드(seed)를 사용합니다. 목록은 homebench tasks에서 확인하세요.

선택적 --judge MODEL 플래그는 LLM-as-judge (어떤 로컬 모델이든 가능)를 활성화하여 개방형 작업에 대해 참조 답변을 기준으로 1~5점으로 점수를 매깁니다. 이는 신호일 뿐, 절대적인 진리는 아닙니다.

기본적으로 빠름 (Fast by default)

전체 스위트의 모든 모델을 벤치마킹하는 것은 노트북에서 시간이 걸리므로, 기본 설정은 빠른 첫 확인에 맞게 조정되었습니다:

• 기본적으로 가장 작은 3개 모델 (가장 작은 것부터 순서대로 표시되어 결과가 빠르게 나옴) — 모든 것을 사용하려면 --all, 선택하려면 -m을 사용합니다.
• 빠른 품질 서브셋 (~모든 카테고리에서 8가지 작업) — 모두 사용하려면 --full을 사용합니다.
• 응답 캐싱: 품질 테스트는 온도(temperature) 0과 고정 시드(fixed seed)를 사용하므로 응답이 결정론적이며 ~/.homebench 아래에 캐시됩니다. 재실행할 때는 새로운 모델/작업만 재생성하고 (변경되지 않은 것은 밀리초 단위로 캐시에서 재평가됨); --refresh-cache는 강제 재계산을 수행하며, --no-cache는 이를 비활성화합니다.

실제로는 이 기능 덕분에 첫 실행 시간이 ~15–25분 (모든 모델, 전체 스위트)에서 ~1–2분으로 단축되며, 재실행은 몇 초 만에 완료됩니다. 철저한 테스트(CI, 최종 수치)를 위해서는 homebench --all --full을 사용하세요.

사용자 지정 작업 팩 (Custom task packs)

JSON 또는 YAML 팩으로 자체 평가 세트를 가져오세요 — Python이 필요 없습니다. --tasks는 내장 스위트를 대체하고, --add-tasks는 여기에 추가합니다. YAML은 선택적 확장(`pip install

Gate CI에 통합하기. --fail-on-regression은 공유 모델의 품질이나 속도가 임계값 이하로 떨어지면 diff가 0이 아닌 값으로 종료되게 하여, 모델을 조용히 성능 저하시키는 프롬프트/설정 변경도 빌드 실패를 유발합니다:**

homebench diff --fail-on-regression --quality-threshold 5 --speed-threshold 10
# quality tolerance는 포인트 단위, speed는 기본 tok/s 대비 퍼센트입니다.
``` 모든 실행은 **환경** (OS, CPU, RAM, GPU, homebench + Python 버전)을 기록하므로 보고서가 재현 가능하며, `diff`는 두 실행이 다른 장치에서 온 경우 경고합니다.

### 공유 가능한 보고서

실행 결과를 **독립적인 HTML 페이지**로 내보낼 수 있습니다 (인라인 스타일, CSS 바, 테마 인식 — 외부 에셋 불필요, 이메일이나 gist에 안전하게 첨부 가능):

```bash
homebench --html report.html          # 새로운 실행에서
homebench report latest --html run.html   # 또는 저장된 모든 실행 렌더링 (또한 --md도 가능)

배치 처리량 (Batch throughput)

주요 리더보드는 단일 스트림(single-stream) tok/s를 측정합니다. 요청을 배치로 처리하는 서버(vLLM, llama.cpp continuous batching, Ollama와 OLLAMA_NUM_PARALLEL>1 사용)는 동시성 하에서 훨씬 더 많은 총 작업을 수행할 수 있으며, homebench throughput가 이를 측정합니다:

homebench throughput -m my-model --concurrency 1,2,4,8

이 명령어는 각 동시성 수준에서 N개의 요청을 전송하며 (N은 기본적으로 3×동시성), 총합(aggregate) tok/s (총 출력 ÷ 벽시계 시간), 동시성 1 대비 속도 향상률(speedup), 평균 요청당 속도, 그리고 지연 시간(mean / p95)을 보고합니다:

             Batch throughput — my-model (vllm)
┏━━━━━━┳━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
┃ Conc ┃ Reqs ┃ Agg tok/s ┃ Speedup ┃ Req tok/s ┃ Mean lat ┃ p95 lat ┃ Errors ┃
...

배치 처리를 하지 않는 환경에서는 총합 처리량이 평평하게 유지되는 반면 지연 시간이 상승하는데, 이는 그 자체로 유용한 관찰점입니다. --json FILE을 추가하여 내보낼 수 있습니다.

제 장비는 무엇을 실행할 수 있나요?

벤치마킹을 수행하기 전에, homebench fit은 사용자의 하드웨어(RAM, CPU, GPU/VRAM, Apple 통합 메모리)를 파악하고 약 50개의 인기 모델 카탈로그—SmolLM2, Qwen2.5, Llama 3.x, Gemma 2, Phi-3.5/4, Mistral/Mixtral, DeepSeek-R1, CodeLlama, Yi, Command-R 등 135M부터 141B까지의 모델—를 메모리 예산과 비교하여 어떤 모델이 적합하며 어느 정도 양자화(quantization)로 가능한지 보여줍니다:

homebench fit                    # 적합한 모델, 최적의 양자화 수준 확인
homebench fit --all              # 적합하지 않은 모델도 포함
homebench fit --context 8192     # 더 큰 KV 캐시를 위한 예산 할당
...

HuggingFace에서 실시간 목록 가져오기

내장 카탈로그 대신, 현재 가장 인기 있는 모델을 HuggingFace Hub에서 직접 불러와—이들의 파라미터 수(safetensors 메타데이터 기준)를 사용자의 하드웨어에 실시간으로 맞춰봅니다:

homebench fit --online              # 다운로드 기준으로 상위 50개 텍스트 생성 모델
homebench fit --online --top 100    # 더 넓은 범위의 모델 탐색
homebench fit --online --sort trending   # 또는: 좋아요(likes) 기준
...

결과는 $HOMEBENCH_HOME (~/.homebench)에 캐시되므로, 반복 실행이 빠르고 오프라인에서도 작동합니다. 만약 Hub에 접속할 수 없다면, homebench는 캐시(또는 내장 카탈로그)로 대체됩니다.

내장 카탈로그에는 각 모델의 Ollama 태그 (ollama pull …)와 HuggingFace 저장소 (LM Studio 및 vLLM이 가져오는 곳)도 함께 제공됩니다. JSON 카탈로그를 사용하여 직접 모델을 추가할 수 있습니다(여기 참조: examples/models.example.json): {name, params_b, family?, ollama?, hf?} 형식의 목록입니다. 크기는 추정치이므로(

• 품질은 기록용 리더보드가 아니라 신호입니다. 이 테스트 스위트는 작고 영어 전용입니다(기본 빠른 모드에서 8개 작업, --full 사용 시 31개). 모델들을 분리하는 데 초점을 맞추었지, 권위적으로 순위를 매기는 것이 아닙니다. 진지한 평가에는 lm-evaluation-harness를 사용하세요. 선택적인 LLM-as-judge는 특히 작은 로컬 judge의 경우 노이즈가 많습니다.

• 속도는 그 순간의 기기 성능입니다. tok/s와 TTFT(Time To First Token)는 현재 부하, 열 상태, 메모리 압력에 따라 달라집니다. 바쁜 노트북(또는 RAM 부족 시 스와핑하는 경우)은 더 느리게 작동할 것입니다. 이 수치들은 절대적인 모델 사양으로 보는 것이 아니라, 같은 실행 내에서 서로 상대적으로 의미가 있습니다.

• 메모리는 최선의 노력입니다. 노출된 경우 러너의 상주 크기(resident size)를 사용합니다(Ollama /api/ps, LM Studio /api/v0)에 RSS 샘플링을 더합니다. 통합 메모리 Mac에서는 근사치이며, OpenAI 호환 백엔드용으로는 클라이언트 측에서 시간을 측정합니다.

• fit 크기는 추정치입니다 (가중치 + KV 캐시 + 오버헤드) —

• PyPI 배포

• HTML / 공유 가능한 보고서 내보내기

• 비교 가능한 결과를 위한 실행별 환경 캡처 (OS, RAM, GPU)

• 종합적인 '노트북에 가장 적합한 모델' 값 점수

• homebench doctor — 제공자 / 모델 / 설정 진단

• MLX 제공자 (Apple-Silicon 네이티브)

• CI용 회귀 방지 장치 (diff --fail-on-regression)

• 커뮤니티 작업 팩 공유

라이선스

MIT