alvarobartt/hf-mem

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

📦 Project: hf‑mem – Hugging Face モデルのメモリ使用量見積もりツール

概要

Python のみの軽量なコマンドラインツールで、推論時にモデルがどれだけの RAM (および KV‑cache) を必要とするかを教えてくれます。
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

# 同期的な呼び出し
result = run(model_id="MiniMaxAI/MiniMax-M2", experimental=True)
print(result)

# 非同期的な呼び出し (async app 内)
# result = await arun(model_id="MiniMaxAI/MiniMax-M2", experimental=True)

返される Result オブジェクトには、memory, kv_cache, および total_memory (すべて bytes) といったフィールドが含まれています。

⚙️ Experimental extensions

--experimental を有効にすると:
- Causal LM および conditional‑generation モデルの KV‑cache サイズ見積もりが可能になります ( --max-model-len, --batch-size, --kv-cache-dtype を調整できます)。
- Mixture‑of‑Experts アーキテクチャにおけるベースモデル対エキスパート重みの内訳を表示します。
GGUF サポート:
- リポジトリが GGUF ファイルのみを含む場合、各ファイルがリストアップされ、そのメモリが見積もりされます。
- --gguf-file <filename> を使用して、単一の GGUF ファイルを対象にできます。

🛠️ Installation & integration

Standalone – パッケージは PyPI (またはリポジトリから直接) インストール可能で、uvx hf-mem … を介して実行できます。
Hugging Face CLI extension – 通常の hf CLI をインストールした後、、hf CLI の拡張機能としてツールを追加します:
```
hf extensions add alvarobartt/hf-mem
```
その後、他の HF 拡張機能と同様に hf mem … として呼び出します。
Agent skill – SKILL.md が提供されているため、コーディングエージェント (例: Anthropic Claude) が hf‑mem を自動的に発見し、呼び出すことができます。

📚 What it does not do

モデルをダウンロードしたり実行したりすることは ありません。重みファイルのヘッダーのみを検査します。
ベンチマーク形式のレイテンシやスループットの測定は行いません。
実験的な KV‑cache 計算は近似値であり、1.0 リリース前には変更される可能性があります。

📖 Further reading

短い形式のブログ記事 (Jan 2026) – https://alvarobartt.com/hf-mem (少し古い可能性があります)。
Safetensors メタデータ仕様、GGUF ファイル形式、および Hugging Face Hub ドキュメントは、より詳細な技術的詳細については README にリンクされています。

Bottom line: hf‑mem は、開発者がモデルをプルする前に、あらゆる Hugging Face モデルに対して必要な RAM を見積もりするための、高速で依存関係の少ない方法を提供し、ローカルマシン、サーバー、またはエッジデバイスでのメモリ不足 (out-of-memory) の驚きを防ぐのに役立ちます。