llama.cpp クイックスタート：CLIとサーバーの使い方

llama.cpp は GGUF モデル向け C/C++ 推論エンジンです。対話型チャット用の llama-cli、スクリプトによるプロンプト処理用の llama-completion、OpenAI 互換 HTTP API 用の llama-server が含まれます。

ローカル、セルフホスト、クラウドの各アプローチ間でまだ迷っている場合は、まず基盤ガイドの LLM ホスティング 2026：ローカル、セルフホスト & クラウドインフラの比較 を参照してください。

なぜ 2026 年に llama.cpp なのか

llama.cpp は軽量な推論エンジンで、以下への偏りを持っています：

• CPU と複数の GPU バックエンド間のポータビリティ、
• 単一マシンでの予測可能なレイテンシ、
• ラップトップからオンプレミスノードまで、柔軟なデプロイ。

プライバシーとオフライン動作が求められる場合、ランタイムフラグに対する決定的な制御が必要な場合、また Python 中心の重いスタックを動かさずに推論をより大きなシステムに組み込みたい場合に威力を発揮します。

後でよりスループットの高いサーバーランタイムを選んでも、llama.cpp を理解しておくことは有用です。例えば、GPU での最大サービングスループットが目標であれば、vLLM との比較も検討することをお勧めします： vLLM クイックスタート：高性能 LLM サービング また、ツールの選択をベンチマークするには： Ollama vs vLLM vs LM Studio：2026 年にローカルで LLM を実行する最善の方法は？

もし Ollama 特が llama-server と比較検討している代替案であるなら、llama.cpp vs Ollama in 2026 が専用の対比比較であり、Ollama を維持すべき時期と直接 llama.cpp へ移行すべき時期の具体的なトリガーを示しています。

Windows、macOS、Linux での llama.cpp インストール

以下のコマンドは llama.cpp v0.6.0（2026年10月5日）と一致します。同じランタイム（CPU とアクセラレーターバックエンドでの GGUF 推論、ビルドコミットでバージョン管理）のカタログ項目は LLM Systems の llama.cpp ランタイムリファレンス にあります。利便性、ポータビリティ、または最大のパフォーマンスを重視するかによって、4つの実用的なインストールパスがあります。

パッケージマネージャーでのインストール

これが「すぐに動かす」ための最速オプションです。

# macOS or Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS or Linux (Nix)
nix profile install nixpkgs#llama-cpp

# Ubuntu (universe). This package lags upstream by a long way:
# 8681+dfsg against current build b11433 / v0.6.0, so newer flags will be missing.
sudo apt install llama.cpp-tools

ヒント：インストール後、ツールが存在することを確認してください：

llama-cli --version
llama-completion --version
llama-server --version

プリビルトバイナリでのインストール

コンパイラなしでクリーンなインストールを行いたい場合は、llama.cpp GitHub リリースに公開されている公式プリビルトバイナリを使用してください。通常、複数の OS ターゲットと複数のバックエンド（CPU のみ、および GPU 有効バリアント）をカバーしています。

一般的なワークフロー：

# 1) Download the right archive for your OS and backend
# 2) Extract it
# 3) Run from the extracted folder

./llama-cli --help
./llama-server --help

公式コンテナの実行

プロジェクトは GitHub Container Registry にサーバーイメージを公開しています。CPU イメージは ghcr.io/ggml-org/llama.cpp:server、CUDA イメージは :server-cuda です。デフォルトのバインドが 127.0.0.1 のため、コンテナはすべてのインターフェースでリッスンする必要があります：

docker run --gpus all -p 8080:8080 \
  -v /path/to/models:/models \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/my-model.gguf -c 4096 --host 0.0.0.0 -ngl all

正確なハードウェア用にソースからビルド

CPU/GPU バックエンドから最高のパフォーマンスを引き出したい場合は、CMake を使用してソースからビルドしてください。

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

# CPU build
cmake -B build
cmake --build build --config Release

ビルド後、バイナリは通常ここにあります：

ls -la ./build/bin/

1コマンドで GPU ビルド

ハードウェアに一致するバックエンドを有効にしてください（CUDA と Vulkan の例）：

# NVIDIA CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Vulkan
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Ubuntu 24.04 + NVIDIA GPU：完全なビルド手順

NVIDIA GPU 搭載の Ubuntu 24.04 では、ビルド前に CUDA ツールキットと OpenSSL が必要です。テスト済みのシーケンスは以下の通りです：

1. CUDA ツールキット 13.1 をインストール。 この手順では 13.1.1 ローカルインストーラーを固定しています。NVIDIA の Ubuntu 24.04 リポジトリからの新しいツールキットでも、ファイル名を更新すれば同じピンファイルおよびローカル deb ステップに従います。

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

2. CUDA を環境に追加（~/.bashrc に追記）：

# cuda toolkit
export PATH=/usr/local/cuda-13.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64:$LD_LIBRARY_PATH

その後、source ~/.bashrc を実行するか、新しいターミナルを開いてください。

3. OpenSSL 開発ヘッダーをインストール（クリーンなビルドに必要）：

sudo apt update
sudo apt install libssl-dev

4. llama.cpp をビルド（llama.cpp のクローンを含むディレクトリから、CUDA を有効にして）：

cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

これにより llama-cli、llama-mtmd-cli、llama-server、llama-embedding、llama-gguf-split が llama.cpp ディレクトリに生成されます。

また、複数のバックエンドをコンパイルし、ランタイムでデバイスを選択することも可能です。これは、同一のビルドを異なる構成のマシンにデプロイする場合に有用です。

GGUF モデルと量子化の選択

推論を実行するには、GGUF モデルファイル（*.gguf）が必要です。GGUF は、モデルの重みと llama.cpp のようなエンジンに必要な標準化されたメタデータを含む単一ファイル形式です。

モデルを手に入れる 2 つの方法

オプション A：ローカル GGUF ファイルを使用

GGUF をダウンロードまたはコピーして ./models/ に配置します：

mkdir -p models
# Place your GGUF at models/my-model.gguf

次にパスで実行します：

llama-cli -m models/my-model.gguf -p "Hello! Explain what llama.cpp is." -n 128 -st

オプション B：llama.cpp に Hugging Face からダウンロードさせる

モダンな llama.cpp ビルドでは、Hugging Face からダウンロードし、ファイルをローカルキャッシュに保持できます。これはクイック実験のための最も簡単なワークフローであることが多いです。

# Download a model from HF and run a prompt
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Once upon a time," \
  -n 200 \
  -st

また、リポジトリセレクタで量子化を指定し、ツールに一致するファイルを選択させることもできます：

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Summarize the concept of quantization in one paragraph." \
  -n 160 \
  -st

後に完全なオフラインワークフローが必要な場合、--offline はキャッシュの使用を強制し、ネットワークアクセスを防ぎます。

ローカル推論のための量子化の選択

量子化は、「ローカル推論にはどの GGUF 量子化を選ぶべきか」という質問に対する実践的な答えであり、品質、モデルサイズ、速度のトレードオフに直接影響します。

実践的な出発点：

• CPU 中心のマシンでは Q4 または Q5 バリアントから始める、
• RAM や VRAM を確保できる場合、より高い精度（または攻撃的な量子化でないもの）に移行する、
• タスクに対してモデルが「愚かに感じる」場合、修正は多くの場合、より良いモデルまたは攻撃的な量子化でないものであり、サンプリングの調整だけではない。

また、コンテキストウィンドウの重要性を覚えておいてください：GGUF ファイル自体が収まる場合でも、より大きなコンテキストサイズはメモリ使用量（場合によっては劇的に）を増やします。

llama-cli クイックスタートと主なパラメータ

llama-cli は、モデルがロードされ、バックエンドが動作し、プロンプトが意図通りに動作することを確認する最速の方法です。

llama-cli は 2025 年 12 月の書き換え以来、対話型チャットクライアントです。モデルにチャットテンプレートが同梱されている場合、会話モードはデフォルトでオンになり、--no-conversation は llama-completion へのポインターを伴って拒否されます。この 2 番目のバイナリは古い llama-cli であり、1 つのプロンプトを入力し、1 つの補完を出力し、スクリプトやパイプに適しています。新しいクライアントでは、--single-turn (-st) が 1 つの返信を生成して終了します。

1 つの返信で終了

llama-cli \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -n 200 \
  -st

非対話型バイナリ経由での同じプロンプト：

llama-completion \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -n 200 \
  --no-conversation

対話型チャットの実行

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "You are a concise systems engineering assistant." \
  --ctx-size 4096

--conversation はもう必要ありません。モデルが特定のシーケンスを表示したときに生成を終了するには、逆プロンプトを使用してください。

重要な主な llama-cli フラグ

200 のフラグを覚えるのではなく、正確性、レイテンシ、メモリを支配するものに焦点を当てます。

モデルとダウンロード

コンテキストとスループット

GPU オフロードとハードウェア選択

サンプリングと出力品質

llama-cli での例示ワークロード

プロンプトだけでなくファイルの要約

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "You summarize technical documents. Output five bullets max." \
  --file ./docs/incident-report.txt \
  -n 300 \
  -st

結果をより再現可能にする

プロンプトのデバッグ中、シードを固定し、ランダム性を減らします：

llama-cli \
  -m models/my-model.gguf \
  -p "Extract key risks from this design note." \
  -n 200 \
  --seed 42 \
  --temp 0.2 \
  -st

OpenAI 互換 API を備えた llama-server クイックスタート

llama-server は組み込み HTTP サーバーで、以下を公開できます：

• チャット、補完、エンベディング、レスポンス用の OpenAI 互換エンドポイント、
• 対話型テスト用の Web UI、
• 本番環境での可視性のための任意のモニタリングエンドポイント。

ローカルモデルでサーバーを開始

llama-server \
  -m models/my-model.gguf \
  -c 4096

デフォルトでは、127.0.0.1:8080 でリッスンします。

外部にバインドする場合（例えば Docker の内側や LAN 内）、ホストとポートを指定します：

llama-server \
  -m models/my-model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

任意だが重要なサーバーフラグ

コンテナで実行する場合、多くの設定は LLAMA_ARG_* 環境変数経由でも制御できます。

API 呼び出しの例

curl によるチャット補完

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me a quick llama.cpp checklist." }
    ],
    "temperature": 0.7
  }'

本番デプロイのためのヒント：--api-key を設定した場合、x-api-key ヘッダー（またはゲートウェイに応じて Authorization ヘッダーを継続して使用）で送信できます。

llama-server をターゲットとする OpenAI Python クライアント

OpenAI 互換サーバーでは、base_url を変更するだけで多くのクライアントが動作します。これは、lukeswade/deep-research のような研究エージェントが、別途アダプタ層なしに直接 llama-server と通信する方法でもあります。セルフホスト型 Deep Research システム：12 ツールの比較 は、OpenAI 互換ローカルエンドポイントを指すそのプロジェクトや他をカバーしています。

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required",
)

resp = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain threads vs batch size in llama.cpp."},
    ],
)

print(resp.choices[0].message.content)

エンベディング

OpenAI 互換エンベディングは /v1/embeddings で公開されますが、モデルは none でないエンベディングプーリングモードをサポートする必要があります。

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["hello", "world"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

専用のエンベディングモデルを実行する場合、エンベディング専用モードでサーバーを起動することを検討してください：

llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

または、CPU でエンベディングモデルを llama-cpp で実行したい場合：

CUDA_VISIBLE_DEVICES="" llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

以下のように試してください：

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "your text here" \
  --pooling last \
  --verbose-prompt

1 プロセスからの複数モデルのサービング

上記の例は、起動時に llama-server を単一のモデルにバインドします。プロセスを再起動せずに、リクエストごとにモデルを切り替える必要がある場合、それがルーターモードの目的です。 llama-server ルーターモード：再起動なしでの動的モデル切り替え を参照してください。ルーターを再起動せずに VRAM を解放するためのスクリプト可能なアンロードオールフローについては、再起動なしで llama.cpp ルーターモデルをすべてアンロードする を参照してください。

パフォーマンス、モニタリング、本番環境の強化

「速度とメモリにとって最も重要な llama.cpp コマンドラインオプションは何か」という FAQ の質問は、推論をシステムとして扱うことでmuch容易になります：

• メモリ上限は通常最初の制約（CPU では RAM、GPU では VRAM）。
• コンテキストサイズはメモリの大きな乗数。
• GPU レイヤーオフロードは多くの場合、より高いトークン/秒への最速経路。
• バッチサイズとスレッドはスループットを改善できるが、メモリ圧力も増大させる可能性がある。

より深い、エンジニアリングファーストの視点については： LLM パフォーマンス 2026：ベンチマーク、ボトルネック & 最適化 を参照してください。

16 GB クラスの GPU での測定された llama-cli スタイルの成果（秒あたりトークン数、VRAM、コンテキストを 19K / 32K / 64K にスウィープしながらの GPU 負荷、デンスおよび MoE GGUF 全体で）を閲覧するには、16 GB VRAM LLM ベンチマーク with llama.cpp (速度とコンテキスト) を参照してください。

Qwen 3.6 について、llama.cpp は組み込みのマルチトークン予測スペキュラティブデコーディングをサポートしています。--spec-type draft-mtp でオンにします；--spec-draft-n-max はドラフトヘッドが提案するトークン数を設定します（デフォルト 3）。v0.6.0 は同じ MTP パスを Qwen4Exp に拡張します。手法の比較については スペキュラティブデコーディング を、16 GB での測定された Qwen 3.6 の数値については 16GB GPU での Qwen 3.6 MTP vs 標準 を参照してください。

Prometheus と Grafana による llama-server のモニタリング

llama-server は --metrics が有効な場合のみ、/metrics で Prometheus 互換メトリクスを公開します。そのパスに Prometheus スクレープジョブを指向してください。llama.cpp、vLLM、TGI のダッシュボードとアラートしきい値は、本番環境での LLM 推論モニタリング (2026)：vLLM、TGI、llama.cpp 用の Prometheus & Grafana にあります。

基本的な強化チェックリスト

llama-server が localhost を超えて到達可能になった場合：

• リクエストを認証するために --api-key（または --api-key-file）を使用、
• 必要ない限り 0.0.0.0 へのバインドを避ける、
• サーバーの SSL フラグによる TLS またはリバースプロキシでの TLS 終端を検討、
• 負荷下でのレイテンシを保護するために --parallel で並行性を制限、
• --tools と --agent はオフのままにしておく。両方とも実験的であり、API 経由でファイルおよびシェル操作を公開する；どちらかを有効にすると CORS も localhost に制限される。

トラブルシューティングのクイックウイン

モデルはロードされるがチャットでの答えがおかしい

チャットエンドポイントは、モデルがサポートされるチャットテンプレートを持っている場合に最良です。出力が非構造に見える場合は、以下のことを試してください：

• 明示的な --system-prompt を渡す（会話モードは llama-cli では既にデフォルトでオン）、
• モデルが指示またはチャットチューニングされたバリアントであることを確認、
• アプリに組み込む前にサーバーの Web UI を使用してテスト。v0.6.0 は Hugging Face Hub ブラウザを備えた UI を再構築したため、モデルは CLI だけでなくページからダウンロードできます。

思考モデルは答えを推論トレースでラップします。--reasoning off はそれを抑制し、--reasoning-format deepseek はトレースを content ではなく reasoning_content に移動します。

メモリ不足に遭遇

コンテキストを減らすか、より小さな量子化を選択してください：

• --ctx-size を下げる、
• VRAM が問題の場合 --n-gpu-layers を減らす、または MoE モデルのエキスパート重みを RAM に留めるために --cpu-moe を設定、
• より小さいモデルまたはより圧縮された量子化に切り替える、
• --cache-type-k q8_0 --cache-type-v q8_0 で KV キャッシュを量子化。

コンテキストまたは GPU スplitが意図したものと異なる

--fit はデフォルトでオンであり、設定しなかったメモリ設定を書き換えて、各デバイスで 1024 MiB の空き（--fit-target）を残そうとします。コンテキストを縮小しますが、-c を渡さない限り --fit-ctx (4096) を下にはしません。-ngl を渡すとレイヤー配置には触れません。--fit off はこのメカニズムを無効にします。ログに n_gpu_layers already set by user と表示された場合、明示的な -ngl がロードされており、fit はそれによるメモリ不足を救済しません。

CPU 上で遅い

以下から始めてください：

• 物理コア数と同じ --threads、
• 適度なバッチサイズ、
• マシンに一致するビルド（CPU 機能とバックエンド）がインストールされたことを確認。

参考文献

• 公式 llama.cpp リポジトリとドキュメント
• 公式 CLI フラグドキュメント
• 公式 llama-server ドキュメントと API 詳細