HF 推理显存估算

要解决什么问题

在选型 GPU 或云实例时，常见问题是：不先把整份权重拉下来，能否知道推理要占多少显存/内存？ 对 Hugging Face Hub 上的 Safetensors 或 GGUF，传统做法是本地下载或 from_pretrained 加载，成本高且慢。hf-mem（hf_mem）通过 HTTP Range 只读取元数据与必要字节，估算 模型权重 占用，并在开启实验模式时一并估算 KV 缓存。

如何工作

• 用 --model-id 指向 Hub 仓库；自动识别 Safetensors（含分片 model.safetensors.index.json、Diffusers 的 model_index.json）或 GGUF 权重。
• Safetensors：按文件结构汇总各张量 dtype/shape，得到权重显存；Diffusers、Sentence Transformers 等路径与 Transformers 类似。
• GGUF：按单个文件估算；若仓库里有多档量化，推理通常只加载其中一个文件，需用 --gguf-file 指定目标文件（或分片路径），否则多文件并列估算会偏大。
• --experimental：在 LLM（...ForCausalLM）、VLM（...ForConditionalGeneration）及 GGUF 上额外算 KV 缓存；上下文长度默认来自模型配置，可用 --max-model-len 覆盖；KV 精度默认同模型，可用 --kv-cache-dtype 调整（语义接近 vLLM）。

边界与注意

• 私有或 gated 模型需 HF_TOKEN 或 --hf-token；本地需已装 uv 以便通过 uvx 运行。
• 估算是静态结构 + 配置推导，不含框架开销、激活峰值、批大小、并行策略等；GGUF 多文件场景务必选对 --gguf-file。
• KV 缓存估算属实验能力，长上下文对总显存影响大，部署前仍建议结合真实 batch 与引擎做压测。