alvarobartt/hf-mem

📦 Project: hf‑mem – Hugging Face 模型記憶體使用量估算工具

是什麼

• 一個極小的純 Python 命令列工具，可告訴您在推論時模型需要多少 RAM（以及 KV‑cache）。
• 適用於任何託管在 Hugging Face Hub 上、並將權重儲存為 Safetensors 或 GGUF 檔案的模型 – 這包括 Transformers、Diffusers、Sentence‑Transformers 甚至自定義的 GGUF 模型。
• 設計為輕量化：唯一的執行時依賴項是 httpx2，且它僅透過 HTTP Range requests 獲取模型元數據（metadata），因此從不下載完整的權重檔案。

為什麼重要

• 在將數 GB 的模型拉取到裝置（CPU、GPU 或邊緣運算硬體）之前，您可以快速檢查可用記憶體是否充足。
• 選用的實驗性模式可為 LLMs/VLMs 增加 KV‑cache 估算，並能分解 Mixture‑of‑Experts 模型模型的記憶體，幫助您決定 batch size、context length 和 data‑type 的選擇。

---

🚀 Quick start (CLI)

# Recommended: run with uv for fast, isolated execution
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 記憶體（如果使用 --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)

回傳的 Result 物件包含 memory、kv_cache 和 total_memory 等欄位（皆為 bytes）。

---

⚙️ Experimental extensions

• --experimental 啟用：
  • 因果語言模型（causal LM）和條件生成模型的 KV‑cache 大小估算（您可以調整 --max-model-len、--batch-size、--kv-cache-dtype）。
  • Mixture‑of‑Experts 架構的基礎模型與專家權重分解。
• GGUF 支援：
  • 如果一個儲存庫（repo）僅包含 GGUF 檔案，則會列出每個檔案並估算其記憶體。
  • 您可以使用 --gguf-file <filename> 指定單一 GGUF 檔案。

---

🛠️ Installation & integration

1. Standalone – 此套件可以從 PyPI 安裝（或直接從 repo）並透過 uvx hf-mem … 執行。
2. Hugging Face CLI extension – 安裝一般的 hf CLI 後，將此工具作為擴充功能加入：

   hf extensions add alvarobartt/hf-mem
   

   然後可以像使用其他 HF 擴充功能一樣，使用 hf mem … 來呼叫它。
3. Agent skill – 提供 SKILL.md，因此編碼代理（例如 Anthropic Claude）可以自動發現並呼叫 hf‑mem。

---

📚 What it does not do

• 它不會下載或執行模型；它僅檢查權重檔案的標頭（headers）。
• 它不進行基準測試（benchmark）風格的延遲或吞吐量測量。
• 實驗性的 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）的意外。