huggingface-local-models

Hugging Face ローカルモデル

Hugging Face Hub で llama.cpp 互換の GGUF リポジトリを検索し、適切な量子化を選んで、llama-cli または llama-server でモデルを起動します。

デフォルトのワークフロー

1. apps=llama.cpp を指定して Hub を検索します。
2. https://huggingface.co/<repo>?local-app=llama.cpp を開きます。
3. 表示されている場合は、HF ローカルアプリの正確なスニペットと推奨量子化を優先します。
4. https://huggingface.co/api/models/<repo>/tree/main?recursive=true で正確な .gguf ファイル名を確認します。
5. llama-cli -hf <repo>:<QUANT> または llama-server -hf <repo>:<QUANT> で起動します。
6. リポジトリで独自のファイル名が使われている場合は、--hf-repo と --hf-file を使います。
7. リポジトリに GGUF ファイルがない場合に限り、Transformers の重みから変換します。

クイックスタート

llama.cpp をインストールする

brew install llama.cpp
winget install llama.cpp

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
make

アクセス制限付きリポジトリ用に認証する

hf auth login

Hub を検索する

https://huggingface.co/models?apps=llama.cpp&sort=trending
https://huggingface.co/models?search=Qwen3.6&apps=llama.cpp&sort=trending
https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending

Hub から直接実行する

llama-cli -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M
llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M

正確な GGUF ファイルを指定して実行する

llama-server \
    --hf-repo unsloth/Qwen3.6-35B-A3B-GGUF \
    --hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf \
    -c 4096

GGUF がない場合に限り変換する

hf download <repo-without-gguf> --local-dir ./model-src
python convert_hf_to_gguf.py ./model-src \
    --outfile model-f16.gguf \
    --outtype f16
llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M

ローカルサーバーのスモークテストを行う

llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "messages": [
      {"role": "user", "content": "Write a limerick about exception handling"}
    ]
  }'

量子化の選択

• ?local-app=llama.cpp ページで HF が互換性ありと示す正確な量子化を優先します。
• UD-Q4_K_M など、リポジトリ固有のラベルは標準化せず、そのまま使用します。
• リポジトリのページやハードウェアの構成から別の選択が適切と判断できない場合は、Q4_K_M をデフォルトにします。
• メモリに余裕がある場合、コードや技術系のワークロードには Q5_K_M または Q6_K を優先します。
• RAM や VRAM の予算が限られている場合は、Q3_K_M、Q4_K_S、またはリポジトリ固有の IQ／UD-* バリアントを検討します。
• mmproj-*.gguf ファイルはプロジェクターの重みであり、メインのチェックポイントではありません。

参考資料の読み込み

• URL を優先するワークフロー、モデル検索、ツリー API からの情報抽出、コマンドの組み立てについては、hub-discovery.md を読んでください。
• 形式の表、モデルのスケーリング、品質のトレードオフ、imatrix については、quantization.md を読んでください。
• Metal、CUDA、ROCm、CPU でのビルドやアクセラレーションの詳細については、hardware.md を読んでください。

リソース

• llama.cpp：https://github.com/ggml-org/llama.cpp
• Hugging Face GGUF と llama.cpp のドキュメント：https://huggingface.co/docs/hub/gguf-llamacpp
• Hugging Face ローカルアプリのドキュメント：https://huggingface.co/docs/hub/main/local-apps
• Hugging Face ローカルエージェントのドキュメント：https://huggingface.co/docs/hub/agents-local
• GGUF コンバーター Space：https://huggingface.co/spaces/ggml-org/gguf-my-repo