mcpField
H
hf-mem

hf-mem

github.com/huggingface开发11.2k865 次安装5 天前更新
代码仓库

关于 hf-mem

hf-mem 用于估算 Hugging Face Hub 模型的推理内存需求。它通过 HTTP Range 请求读取 Safetensors 或 GGUF 信息，无需下载权重。

主要功能

  1. 01估算权重内存
  2. 02可选 KV cache 估算
  3. 03支持 Safetensors 和 GGUF
  4. 04指定 GGUF 文件
  5. 05输出 JSON

适用场景

  1. 01检查模型是否适配可用显存
  2. 02部署 Hub 模型前估算内存
  3. 03比较 GGUF 量化文件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/huggingface/skills --skill hf-mem

安装后在 Claude Code 中输入/hf-mem确认已加载。

详细介绍

hf_mem 使用 HTTP Range 请求估算推理所需的内存，包括模型权重和可选的 KV 缓存，适用于 Hugging Face Hub 上采用 Safetensors 和 GGUF 格式的模型，无需在本地下载或加载任何权重。

何时使用？

  • 用户询问运行某个模型需要多少 VRAM 或内存
  • 用户想知道某个模型是否能在自己的 GPU 或指定实例上运行
  • 用户提到 Hugging Face 模型 ID 或 URL，并询问推理要求

有什么要求？

  • 已安装 uv（用于 uvx）
  • HF_TOKEN 环境变量或 --hf-token 标志（仅适用于受限或私有模型）

如何运行？

使用 --model-id 指定 Hugging Face Hub 仓库。工具会检查仓库是否包含 Safetensors（通过 model.safetensors、分片情况下的 model.safetensors.index.json，或 Diffusers 的 model_index.json）或 GGUF 模型权重。

uvx hf-mem --model-id <model-id> --json-output

如果仓库包含多种精度或量化格式的 GGUF 模型权重，估算结果会按文件分别给出；而推理时不会加载所有这些权重，只会加载一种精度的权重。也就是说，对于 GGUF，你可能还需要提供 --gguf-file，以指定要运行的文件（若为分片，则指定路径）。

uvx hf-mem --model-id <model-id> --gguf-file <file-or-path> --json-output

此外，hf-mem 还提供 --experimental 标志，用于计算 KV 缓存所需的内存，这对大语言模型很有用，适用于 LLM（...ForCausalLM）、VLM（...ForConditionalGeneration）和 GGUF 模型。

上下文窗口长度将读取模型默认值，或使用 --max-model-len 覆盖，方式与 vLLM 类似。KV 缓存精度也是如此：默认使用模型精度，也可以像 vLLM 一样通过 --kv-cache-dtype 手动设置。

Safetensors 的用法：

uvx hf-mem --model-id <model-id> --experimental [--max-model-len N] [--batch-size N] [--kv-cache-dtype auto|bfloat16|fp8|fp8_ds_mla|fp8_e4m3|fp8_e5m2|fp8_inc] --json-output

GGUF 的用法：

uvx hf-mem --model-id <model-id> --gguf-file <file-or-path> --experimental [--max-model-len N] [--batch-size N] [--kv-cache-dtype auto|F32|F16|Q4_0|Q4_1|Q5_0|Q5_1|Q8_0|Q8_1|Q2_K|Q3_K|Q4_K|Q5_K|Q6_K|Q8_K|IQ2_XXS|IQ2_XS|IQ3_XXS|IQ1_S|IQ4_NL|IQ3_S|IQ2_S|IQ4_XS|I8|I16|I32|I64|F64|IQ1_M|BF16|TQ1_0|TQ2_0|MXFP4] --json-output

示例

使用 Safetensors 权重的 Transformers：

uvx hf-mem --model-id MiniMaxAI/MiniMax-M2 --json-output

使用 Safetensors 权重的 Diffusers：

uvx hf-mem --model-id Qwen/Qwen-Image --json-output

使用 Safetensors 权重的 Sentence Transformers：

uvx hf-mem --model-id google/embeddinggemma-300m --json-output

添加 --experimental，以包含 LLM 和 VLM 的 KV 缓存估算：

uvx hf-mem --model-id mistralai/Mistral-7B-v0.1 --experimental --json-output

使用 GGUF 权重的 LLM 或 VLM：

uvx hf-mem --model-id unsloth/Qwen3.5-397B-A17B-GGUF --gguf-file Q4_K_M --experimental --json-output

评论

支持 Markdown