hf-mem 是 Hugging Face 提供的命令行工具，用于估算从 Hugging Face Hub 加载 Safetensors 或 GGUF 模型权重进行推理时所需的内存。它使用 HTTP Range 请求读取所需信息，因此无需在本地下载或加载任何权重。
用途
当用户询问运行某个模型需要多少显存或内存时，可使用该工具。它也适合判断某个模型是否能放入用户的 GPU 或给定实例。当用户提供 Hugging Face 模型 ID 或 URL 并询问推理需求时同样适用。
主要能力
该工具可对 Hugging Face Hub 仓库中的 Safetensors 与 GGUF 模型权重进行内存估算，包括模型权重本身，并在开启实验性选项时包含可选的 KV 缓存。
对于 Safetensors，工具会检查仓库是否包含 model.safetensors、分片时的 model.safetensors.index.json，或用于 Diffusers 的 model_index.json。
如果仓库包含多种精度或量化的 GGUF 模型权重，估算将按文件逐个进行；而推理时通常只加载单个精度，因此对于 GGUF 可能需要通过 --gguf-file 指定想要运行的特定文件（或分片路径）。
--experimental 标志还会计算 KV 缓存的内存需求，适用于大语言模型，即 LLM（...ForCausalLM）、VLM（...ForConditionalGeneration）以及 GGUF 模型。上下文窗口默认读取模型默认值，也可通过 --max-model-len 覆盖（用法与 vLLM 类似）；KV 缓存精度默认与模型精度一致，也可通过 --kv-cache-dtype 手动设置（同样与 vLLM 类似）。
使用方式
运行要求：已安装 uv（用于 uvx）；访问受限或私有模型时需要 HF_TOKEN 环境变量或 --hf-token 参数。
基本命令： uvx hf-mem --model-id <model-id> --json-output
GGUF 指定文件： uvx hf-mem --model-id <model-id> --gguf-file <file-or-path> --json-output
Safetensors 配合 KV 缓存估算： 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 配合 KV 缓存估算： uvx hf-mem --model-id <model-id> --gguf-file <file-or-path> --experimental [--max-model-len N] [--batch-size N] --kv-cache-dtype <dtype> --json-output 其中 GGUF 的 --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。
示例
Transformers 与 Safetensors 权重： uvx hf-mem --model-id MiniMaxAI/MiniMax-M2 --json-output
Diffusers 与 Safetensors 权重： uvx hf-mem --model-id Qwen/Qwen-Image --json-output
Sentence Transformers 与 Safetensors 权重： uvx hf-mem --model-id google/embeddinggemma-300m --json-output
为 LLM 和 VLM 加入 KV 缓存估算： uvx hf-mem --model-id mistralai/Mistral-7B-v0.1 --experimental --json-output
LLM 或 VLM 的 GGUF 权重： uvx hf-mem --model-id unsloth/Qwen3.5-397B-A17B-GGUF --gguf-file Q4_K_M --experimental --json-output
适用场景与限制
该工具适合在部署或运行模型之前快速评估显存和内存需求，支持 Transformers、Diffusers、Sentence Transformers 等形式的 Safetensors 权重以及 GGUF 权重。限制方面：访问受限或私有模型需要认证；GGUF 多精度仓库的估算是按文件进行的，推理时通常只需其中之一，因此可能需要用 --gguf-file 指定具体文件；KV 缓存估算目前为实验性功能。