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）。
适用于任何托管在 Hugging Face Hub 上并将权重存储为 Safetensors 或 GGUF 文件的模型 —— 这包括 Transformers、Diffusers、Sentence-Transformers 甚至自定义 GGUF 模型。
设计理念是 轻量化：唯一的运行时依赖是 httpx2，它仅通过 HTTP Range 请求获取模型元数据，因此永远不会下载完整的权重文件。

为什么重要

在将数 GB 的模型拉取到设备（CPU、GPU 或边缘硬件）之前，您可以快速检查可用内存是否充足。
可选的 实验性 模式可以为 LLM/VLM 添加 KV-cache 估算，并可以分解 Mixture-of-Experts 模型的内存，帮助您确定 batch size、context length 和数据类型选择。

🚀 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)

The returned Result object 包含诸如 memory、kv_cache 和 total_memory（均为 bytes）等字段。

⚙️ Experimental extensions

--experimental 启用：
- 因果 LM 和条件生成模型的 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 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）的意外情况。