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. 02KVキャッシュの任意見積もり
  3. 03SafetensorsとGGUFに対応
  4. 04GGUFファイルの指定
  5. 05JSON出力

活用シーン

  1. 01モデルが利用可能なVRAMに収まるか確認
  2. 02Hubモデルのデプロイ前にメモリを見積もり
  3. 03GGUFの量子化ファイルを比較

インストール

コマンドをコピーしてターミナルで実行します。

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

インストール後、Claude Code で/hf-memを入力して読み込まれたか確認します。

詳細

hf_mem は、Hugging Face Hub 上のモデルについて、Safetensors と GGUF の推論に必要なメモリ量を推定します。モデルの重みと、任意の KV キャッシュが対象です。HTTP Range リクエストを使用するため、重みをローカルにダウンロードしたり読み込んだりする必要はありません。

いつ使いますか？

  • モデルの実行に必要な 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 モデルに適用されます。

コンテキストウィンドウは、デフォルト値が読み込まれます。vLLM と同様に、--max-model-len で上書きできます。また、KV キャッシュの精度も同様に、手動で --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

LLM と VLM の KV キャッシュの推定値を含める場合は、--experimental を指定します。

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 対応