alvarobartt/hf-mem

A CLI to estimate inference memory requirements for Hugging Face models, written in Python.

📦 Project: hf‑mem – Hugging Face 모델을 위한 메모리 사용량 추정기

무엇인가요

추론 시 모델이 얼마나 많은 RAM(및 KV‑cache)을 필요로 하는지 알려주는 아주 작은 Python‑only 명령줄 도구입니다.
Safetensors 또는 GGUF 파일로 가중치를 저장하는 Hugging Face Hub의 모든 모델에 대해 작동합니다. 여기에는 Transformers, Diffusers, Sentence‑Transformers 및 커스텀 GGUF 모델이 포함됩니다.
가벼운 설계: 유일한 런타임 의존성은 httpx2이며, HTTP Range 요청을 통해 모델 메타데이터만 가져오므로 전체 가중치 파일을 다운로드하지 않습니다.

왜 중요한가요

수 기가바이트의 모델을 장치(CPU, GPU 또는 엣지 하드웨어)로 가져오기 전에, 사용 가능한 메모리가 충분한지 빠르게 확인할 수 있습니다.
선택 사항인 실험적 모드는 LLM/VLM을 위한 KV‑cache 추정치를 추가하고, Mixture‑of‑Experts 모델의 메모리를 세분화하여 배치 크기, 컨텍스트 길이 및 데이터 유형 선택을 돕습니다.

🚀 Quick start (CLI)

# 권장 사항: 빠른, 격리된 실행을 위해 uv로 실행하세요
uvx hf-mem --model-id MiniMaxAI/MiniMax-M2          # Transformers model
uvx hf-mem --model-id Qwen/Qwen-Image               # Diffusers model
uvx hf-mem --model-id google/embeddinggemma-300m    # Sentence‑Transformers model

명령어는 모델 ID, 추정된 모델 가중치 메모리, KV‑cache 메모리(if --experimental), 그리고 필요한 총 RAM을 포함하는 표를 출력합니다.

🐍 Using it from Python

from hf_mem import run, arun

# Synchronous call
result = run(model_id="MiniMaxAI/MiniMax-M2", experimental=True)
print(result)

# Asynchronous call (inside an async app)
# result = await arun(model_id="MiniMaxAI/MiniMax-M2", experimental=True)

The returned Result object contains fields such as memory, kv_cache, and total_memory (all in bytes).

⚙️ Experimental extensions

--experimental enables:
- KV‑cache size estimation for causal LM and conditional‑generation models (you can tweak --max-model-len, --batch-size, --kv-cache-dtype).
- A breakdown of base‑model vs. expert weights for Mixture‑of‑Experts architectures.
GGUF support:
- 만약 리포지토리가 GGUF 파일만 포함하고 있다면, 각 파일이 나열되고 그 메모리가 추정됩니다.
- --gguf-file <filename>를 사용하여 단일 GGUF 파일을 대상으로 지정할 수 있습니다.

🛠️ Installation & integration

Standalone – 패키지는 PyPI(또는 리포지토리에서 직접)에서 설치할 수 있으며 uvx hf-mem …를 통해 실행할 수 있습니다.
Hugging Face CLI extension – 일반적인 hf CLI를 설치한 후, 도구를 확장 프로그램으로 추가합니다:
```
hf extensions add alvarobartt/hf-mem
```
그 다음 다른 HF 확장 프로그램과 함께 hf mem …로 호출합니다.
Agent skill – SKILL.md가 제공되어 코딩 에이전트(예: Anthropic Claude)가 hf‑mem을 자동으로 발견하고 호출할 수 있습니다.

📚 What it does not do

모델을 다운로드하거나 실행하지 않습니다; 가중치 파일 헤더만 검사합니다.
벤치마크 방식의 지연 시간(latency) 또는 처리량(throughput) 측정을 수행하지 않습니다.
실험적 KV‑cache 계산은 근사치이며 1.0 릴리스 전까지 변경될 수 있습니다.

📖 Further reading

Short‑form blog post (Jan 2026) – https://alvarobartt.com/hf-mem (약간 구식일 수 있습니다).
Safetensors metadata spec, GGUF file format, 및 Hugging Face Hub documentation은 더 깊은 기술적 세부 사항을 위해 README에 링크되어 있습니다.

Bottom line: hf‑mem은 개발자가 모델을 것을 가져오기 전에 Hugging Face의 모든 모델에 대한 필요한 RAM을 크기 조정하는 빠르고 의존성 없는 방법을 제공하여, 로컬 머신, 서버 또는 엣지 디바이스의 메모리 부족(out-of-memory) 문제를 방지하는 데 도움을 줍니다.