llama-cpp

Name: llama-cpp
Author: nousresearch

github.com/nousresearch開発258.9k78 回インストール今日更新

リポジトリ

llama-cpp について

llama-cppは、llama.cppでGGUFモデルをローカル推論する人向けのスキルです。Hugging Faceでのモデル検索、量子化の選択、コマンド作成に加え、Pythonバインディングやサーバー利用も扱います。

主な機能

01llama.cpp対応モデルの検索
02リポジトリ内のGGUF一覧表示
03ハードウェアに応じた量子化選択
04llama-serverとllama-cliのコマンド作成
05ローカル推論とPythonバインディングの案内

活用シーン

01ハードウェアに合うGGUF量子化版の選択
02利用可能なGGUFファイルとサイズの確認
03Hugging Face Hubからモデルを実行
04ローカル推論やサーバー用コマンドの準備

インストール

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

$npx skills add https://github.com/nousresearch/hermes-agent --skill llama-cpp

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

advanced-usage.md

hub-discovery.md

optimization.md

quantization.md

server.md

troubleshooting.md

詳細

llama.cpp + GGUF

ローカルでの GGUF 推論、量子化の選択、または llama.cpp 用の Hugging Face リポジトリの検索には、このスキルを使用してください。

使用する場面

CPU、Apple Silicon、CUDA、ROCm、Intel GPU でローカルモデルを実行する
特定の Hugging Face リポジトリに適した GGUF を見つける
Hub の情報から llama-server または llama-cli のコマンドを作成する
llama.cpp に対応済みのモデルを Hub で検索する
リポジトリで利用できる .gguf ファイルとサイズを一覧表示する
ユーザーの RAM または VRAM に合わせて Q4/Q5/Q6/IQ の各バリアントを選ぶ

モデル検索のワークフロー

hf、Python、カスタムスクリプトを尋ねる前に、URL を使った方法を優先してください。

Hub で候補となるリポジトリを検索します。
- 基本 URL：https://huggingface.co/models?apps=llama.cpp&sort=trending
- モデルファミリーを指定するには search=<term> を追加します
- ユーザーがサイズを指定している場合は、num_parameters=min:0,max:24B などを追加します
llama.cpp のローカルアプリ表示でリポジトリを開きます。
- https://huggingface.co/<repo>?local-app=llama.cpp
ローカルアプリのスニペットが表示されている場合は、信頼できる情報源として扱います。
- llama-server または llama-cli のコマンドをそのままコピーします
- HF が表示する推奨量子化を正確に報告します
同じ ?local-app=llama.cpp の URL をページテキストまたは HTML として読み込み、Hardware compatibility の下にあるセクションを抽出します。
- 汎用的な表よりも、そこに記載された正確な量子化ラベルとサイズを優先します
- UD-Q4_K_M や IQ4_NL_XL など、リポジトリ固有のラベルはそのまま使います
- 取得したページソースにそのセクションが表示されない場合は、その旨を伝え、ツリー API と汎用的な量子化の指針に切り替えます
ツリー API を照会し、実際に存在するファイルを確認します。
- https://huggingface.co/api/models/<repo>/tree/main?recursive=true
- type が file で、path が .gguf で終わるエントリを対象にします
- ファイル名とバイト単位のサイズの情報源として path と size を使用します
- 量子化済みチェックポイントを mmproj-*.gguf プロジェクターファイルおよび BF16/ シャードファイルと区別します
- 人が確認するための代替手段としてのみ https://huggingface.co/<repo>/tree/main を使用します
ローカルアプリのスニペットがテキストで表示されない場合は、リポジトリと選択した量子化からコマンドを再構成します。
- 量子化を簡潔に指定する場合：llama-server -hf <repo>:<QUANT>
- 正確なファイル名を指定する場合：llama-server --hf-repo <repo> --hf-file <filename.gguf>
リポジトリで GGUF ファイルが公開されていない場合に限り、Transformers の重みからの変換を提案します。

クイックスタート

llama.cpp のインストール

# macOS / Linux (simplest)
brew install llama.cpp

winget install llama.cpp

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build
cmake --build build --config Release

Hugging Face Hub から直接実行する

llama-cli -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0

llama-server -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0

Hub から指定した GGUF ファイルを実行する

ツリー API にカスタムのファイル名が表示される場合、または HF の正確なスニペットがない場合に使用します。

llama-server \
    --hf-repo microsoft/Phi-3-mini-4k-instruct-gguf \
    --hf-file Phi-3-mini-4k-instruct-q4.gguf \
    -c 4096

OpenAI 互換サーバーの確認

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

Python バインディング（llama-cpp-python）

pip install llama-cpp-python（CUDA：CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --force-reinstall --no-cache-dir、Metal：CMAKE_ARGS="-DGGML_METAL=on" ...）。

基本的な生成

from llama_cpp import Llama

llm = Llama(
    model_path="./model-q4_k_m.gguf",
    n_ctx=4096,
    n_gpu_layers=35,     # 0 for CPU, 99 to offload everything
    n_threads=8,
)

out = llm("What is machine learning?", max_tokens=256, temperature=0.7)
print(out["choices"][0]["text"])

チャットとストリーミング

llm = Llama(
    model_path="./model-q4_k_m.gguf",
    n_ctx=4096,
    n_gpu_layers=35,
    chat_format="llama-3",   # or "chatml", "mistral", etc.
)

resp = llm.create_chat_completion(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Python?"},
    ],
    max_tokens=256,
)
print(resp["choices"][0]["message"]["content"])

# Streaming
for chunk in llm("Explain quantum computing:", max_tokens=256, stream=True):
    print(chunk["choices"][0]["text"], end="", flush=True)

埋め込み

llm = Llama(model_path="./model-q4_k_m.gguf", embedding=True, n_gpu_layers=35)
vec = llm.embed("This is a test sentence.")
print(f"Embedding dimension: {len(vec)}")

GGUF は Hub から直接読み込むこともできます。

llm = Llama.from_pretrained(
    repo_id="bartowski/Llama-3.2-3B-Instruct-GGUF",
    filename="*Q4_K_M.gguf",
    n_gpu_layers=35,
)

量子化の選び方

まず Hub のページを確認し、次に汎用的な目安を使います。

ユーザーのハードウェア構成に対応していると HF が示す量子化を優先してください。
一般的なチャットでは、まず Q4_K_M を試してください。
コード作業や技術的な作業では、メモリに余裕があれば Q5_K_M または Q6_K を優先してください。
RAM が非常に限られている場合は、品質よりもサイズを優先するとユーザーが明示した場合に限り、Q3_K_M、IQ バリアント、または Q2 バリアントを検討してください。
マルチモーダルのリポジトリでは、mmproj-*.gguf を別途案内してください。プロジェクターはメインのモデルファイルではありません。
リポジトリ固有のラベルを一般化しないでください。ページに UD-Q4_K_M と記載されている場合は、UD-Q4_K_M と報告します。

リポジトリから利用可能な GGUF を抽出する

ユーザーから存在する GGUF について尋ねられた場合は、次の情報を返します。

ファイル名
ファイルサイズ
量子化ラベル
メインモデルか補助プロジェクターか

依頼がない限り、次のものは無視します。

README
BF16 シャードファイル
imatrix のデータやキャリブレーション用アーティファクト

この手順ではツリー API を使用します。

https://huggingface.co/api/models/<repo>/tree/main?recursive=true

unsloth/Qwen3.6-35B-A3B-GGUF のようなリポジトリでは、ローカルアプリのページに UD-Q4_K_M、UD-Q5_K_M、UD-Q6_K、Q8_0 などの量子化チップが表示される一方、ツリー API には Qwen3.6-35B-A3B-UD-Q4_K_M.gguf や Qwen3.6-35B-A3B-Q8_0.gguf などの正確なファイルパスとバイト単位のサイズが表示されます。ツリー API を使って、量子化ラベルを正確なファイル名に対応付けてください。

検索パターン

これらの URL 形式をそのまま使用してください。

https://huggingface.co/models?apps=llama.cpp&sort=trending
https://huggingface.co/models?search=<term>&apps=llama.cpp&sort=trending
https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending
https://huggingface.co/<repo>?local-app=llama.cpp
https://huggingface.co/api/models/<repo>/tree/main?recursive=true
https://huggingface.co/<repo>/tree/main

出力形式

検索リクエストへの回答では、次のような簡潔で構造化された結果を優先してください。

Repo: <repo>
Recommended quant from HF: <label> (<size>)
llama-server: <command>
Other GGUFs:
- <filename> - <size>
- <filename> - <size>
Source URLs:
- <local-app URL>
- <tree API URL>

参考資料

hub-discovery.md - URL のみを使った Hugging Face のワークフロー、検索パターン、GGUF の抽出、コマンドの再構成
advanced-usage.md — 投機的デコーディング、バッチ推論、文法制約付き生成、LoRA、複数 GPU、カスタムビルド、ベンチマークスクリプト
quantization.md — 量子化による品質のトレードオフ、Q4／Q5／Q6／IQ の用途、モデルサイズの拡大、imatrix
server.md — Hub から直接サーバーを起動する方法、OpenAI API エンドポイント、Docker によるデプロイ、NGINX のロードバランシング、モニタリング
optimization.md — CPU スレッド処理、BLAS、GPU オフロードのヒューリスティクス、バッチの調整、ベンチマーク
troubleshooting.md — インストール／変換／量子化／推論／サーバーの問題、Apple Silicon、デバッグ

リソース

GitHub: https://github.com/ggml-org/llama.cpp
Hugging Face GGUF + llama.cpp のドキュメント: https://huggingface.co/docs/hub/gguf-llamacpp
Hugging Face Local Apps のドキュメント: https://huggingface.co/docs/hub/main/local-apps
Hugging Face Local Agents のドキュメント: https://huggingface.co/docs/hub/agents-local
ローカルアプリのページの例: https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF?local-app=llama.cpp
ツリー API の例: https://huggingface.co/api/models/unsloth/Qwen3.6-35B-A3B-GGUF/tree/main?recursive=true
llama.cpp の検索例: https://huggingface.co/models?num_parameters=min:0,max:24B&apps=llama.cpp&sort=trending
ライセンス: MIT

Markdown 対応

ログインしてコメント

基本情報

作者: nousresearch
リポジトリ: nousresearch/hermes-agent
カテゴリ: 開発
インストール数: 78
GitHub スター: 258,865

問題を報告