CLIとサーバーによるllama.cppクイックスタート

ローカル推論には、llama.cpp を使い続けています。Ollama や他のツールが抽象化している部分を自分で制御できるためであり、単に「動く」だけでなく、GGUF モデルを llama-cli で対話的に実行したり、llama-server で OpenAI 互換の HTTP API を公開したりするのが簡単だからです。

ローカル、セルフホスト、クラウドのアプローチのいずれを選ぶべきか迷っているなら、以下の柱となるガイドから始めましょう。 LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared.

2026年における llama.cpp の理由

llama.cpp は、以下の点に重点を置いた軽量な推論エンジンです。

• CPU および複数の GPU バックエンドへのポータビリティ
• 単一マシンでの予測可能なレイテンシ
• ノートパソコンからオンプレミスのノードまで、デプロイの柔軟性

プライバシーとオフライン動作を重視する場合、ランタイムフラグに対する決定論的な制御が必要な場合、あるいは Python 依存の重いスタックを実行せずに推論をより大きなシステムに埋め込みたい場合に、その真価を発揮します。

また、後に高いスループットのサーバーランタイムを選択する場合でも、llama.cpp の理解は役立ちます。例えば、GPU での最大サービングスループットが目標である場合、vLLM と比較することも検討してください。 vLLM Quickstart: High-Performance LLM Serving また、以下の記事でツール選択のベンチマークを行うことができます。 Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

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

利便性、ポータビリティ、または最大のパフォーマンスを求めているかによって、実用的なインストール方法が3つあります。

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

最も迅速に「動作させる」ためのオプションです。

# macOS または Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS または Linux (Nix)
nix profile install nixpkgs#llama-cpp

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

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

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

コンパイラなしでクリーンなインストールを希望する場合、llama.cpp GitHub リリースで公開されている公式のプリビルトバイナリを使用します。これらは通常、複数のOSターゲットと複数のバックエンド（CPUのみとGPU対応のバリエーション）をカバーしています。

一般的なワークフロー：

# 1) OSとバックエンドに合ったアーカイブをダウンロード
# 2) 展開
# 3) 展開したフォルダから実行

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

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

CPU/GPU バックエンドから最高のパフォーマンスを引き出すことが重要であれば、CMake を使用してソースからビルドします。

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

# CPU ビルド
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 toolkit 13.1 のインストール

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.cpp ディレクトリに llama-cli、llama-mtmd-cli、llama-server、llama-embedding、llama-gguf-split が生成されます。

複数のバックエンドをコンパイルし、ランタイムでデバイスを選択することもできます。これは、同じビルドを異種なマシンにデプロイする場合に役立ちます。

GGUF モデルと量子化の選択

推論を実行するには、GGUF モデルファイル（*.gguf）が必要です。GGUF は、モデルの重みと llama.cpp などのエンジンに必要な標準化されたメタデータをバンドルする単一ファイルフォーマットです。

モデルを取得する2つの方法

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

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

mkdir -p models
# GGUFを models/my-model.gguf に配置

その後、パスを指定して実行します：

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

オプション B: Hugging Face から llama.cpp でダウンロード

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

# HFからモデルをダウンロードし、プロンプトを実行
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Once upon a time," \
  -n 200

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

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

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

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

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

実用的な出発点：

• CPU 優先のマシンでは Q4 または Q5 バリアントから始める
• RAM または VRAM に余裕がある場合は、より高い精度（またはより緩やかな量子化）に切り替える
• モデルがタスクに対して「愚か」に感じられる場合、修正は通常、より良いモデルまたはより緩やかな量子化であり、サンプリングの調整のみではありません

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

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

llama-cli は、モデルがロードされ、バックエンドが動作し、プロンプトが適切に動作することを検証する最も速い方法です。

ミニマルな実行

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

インタラクティブなチャット実行

会話モードはチャットテンプレート用に設計されています。対話的な動作を有効にし、モデルのテンプレートに従ってプロンプトをフォーマットします。

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

モデルが特定のシーケンスを出力したときに生成を終了するには、リバースプロンプトを使用します。これは特にインタラクティブモードで役立ちます。

重要な 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

結果をより再現的に

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

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

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 を変更するだけで多くのクライアントが動作します。

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 router mode: dynamic model switching without restarts. ルーターを再起動せずに VRAM を解放するスクリプト可能なアンロードオールフローについては、Unload All llama.cpp Router Models Without Restarting. を参照してください。

パフォーマンス、監視、および本番環境の強化

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

• メモリ上限 は通常、最初の制約です（CPU の RAM、GPU の VRAM）。
• コンテキストサイズ は主要なメモリ倍率です。
• GPU レイヤオフロード は、より高いトークン毎秒数への最も速いパスです。
• バッチサイズとスレッド はスループットを改善できますが、メモリ圧力も増加させる可能性があります。

より深い、エンジニアリングファーストの視点については、以下を参照してください： LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

16 GB クラスの GPU での測定された llama-cli 様式の成果（トークン毎秒、VRAM、およびコンテキストをスイープした際の GPU 負荷）について興味がある場合、16 GB VRAM LLM benchmarks with llama.cpp (speed and context). を参照してください。

Qwen 3.6 に特化したもので、llama.cpp は現在、生成スループットを大幅に向上させる可能性のある組み込みのマルチトークン予測（MTP）投機的デコーディングをサポートしています。測定された生成速度、VRAM オーバーヘッド、推奨される --spec-draft-n-max 値については、Qwen 3.6 27B and 35B MTP vs Standard on 16GB GPU を参照してください。

Prometheus と Grafana による llama-server の監視

llama-server は、--metrics が有効な場合、/metrics で Prometheus 互換のメトリクスを公開できます。これは Prometheus スクレープ設定と Grafana ダッシュボードと自然に組み合わされます。

llama.cpp（および vLLM、TGI）固有のダッシュボードとアラートについては：Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp. より広範なガイド：Observability: Monitoring, Metrics, Prometheus & Grafana Guide および Observability for LLM Systems.

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

llama-server が localhost 以外から到達可能になる場合：

• --api-key（または --api-key-file）を使用して、リクエストが認証されるようにする
• 必要がない限り 0.0.0.0 へのバインドを避ける
• サーバーの SSL フラグまたはリバースプロキシで TLS を終端することを検討する
• 負荷下でのレイテンシを保護するために --parallel で並行性を制限する

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

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

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

• llama-cli --conversation と明示的な --system-prompt を使用する
• モデルが指示またはチャットチューニングされたバリアントであることを確認する
• アプリに組み込む前にサーバー Web UI をテストする

メモリ不足に到達した

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

• --ctx-size を下げる
• VRAM が問題の場合は --n-gpu-layers を減らす
• より小さいモデルまたはより圧縮された量子化に切り替える

CPU で遅い

以下から始めます：

• 物理コア数に等しい --threads
• 適度なバッチサイズ
• マシン（CPU機能とバックエンド）に合ったビルドをインストールしたことを検証する

参考文献

• Official llama.cpp repository and docs
• Official CLI flags documentation
• Official llama-server documentation and API details