llama-cpp

llama.cpp -- C/C++ LLM 推論フレームワークガイド

公式ドキュメント

出典	URL
GitHub リポジトリ	https://github.com/ggml-org/llama.cpp
C API ヘッダー（llama.h）	https://github.com/ggml-org/llama.cpp/blob/master/include/llama.h
C++ RAII ラッパー	https://github.com/ggml-org/llama.cpp/blob/master/include/llama-cpp.h
ビルド手順	https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md
サーバーのドキュメント	https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md
量子化ツール	https://github.com/ggml-org/llama.cpp/blob/master/tools/quantize/README.md
GGUF 仕様	https://github.com/ggml-org/ggml/blob/master/docs/gguf.md
関数呼び出しのドキュメント	https://github.com/ggml-org/llama.cpp/blob/master/docs/function-calling.md
マルチモーダルのドキュメント	https://github.com/ggml-org/llama.cpp/blob/master/docs/multimodal.md
サンプルディレクトリ	https://github.com/ggml-org/llama.cpp/tree/master/examples
HuggingFace GGUF Hub	https://huggingface.co/docs/hub/gguf-llamacpp
Llama-Unreal プラグイン	https://github.com/getnamo/Llama-Unreal

llama.cpp とは？

llama.cpp は、依存関係を最小限に抑え、CPU と GPU での高性能なローカル推論を目的に設計された、純粋な C/C++ の LLM 推論エンジンです。主な特長は次のとおりです。

• MIT ライセンスで、開発が非常に活発です（ほぼ毎日リリースされ、現在は b8766 以降）
• 幅広いハードウェアに対応：NVIDIA（CUDA）、AMD（ROCm/Vulkan）、Apple（Metal）、Intel（SYCL/Vulkan）、Qualcomm（OpenCL）、ARM、WebGPU
• GGUF モデル形式：単一ファイルで、mmap に対応し、1.5 ビットから 16 ビットまで 40 種類以上の量子化タイプをサポート
• 組み込み HTTP サーバー：OpenAI 互換 API、Anthropic Messages API、ストリーミング、関数呼び出し、マルチモーダルに対応
• 言語バインディング：Python（llama-cpp-python）、Go、Rust、C#、Node.js、Java、Swift など

クイックスタート

サーバー経由でモデルを実行する（最も手早い方法）

# Install
brew install llama.cpp    # macOS/Linux
winget install llama.cpp  # Windows

# Start server with a HuggingFace model
llama-server -hf bartowski/Llama-3.3-70B-Instruct-GGUF:Q4_K_M -ngl 99

# Query via curl
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"temperature":0.8}'

C++ プロジェクトに組み込む（ライブラリとして使用）

#include "llama.h"

// 1. Init backends and load model
ggml_backend_load_all();
auto params = llama_model_default_params();
params.n_gpu_layers = 99;
llama_model * model = llama_model_load_from_file("model.gguf", params);

// 2. Create context
auto ctx_params = llama_context_default_params();
ctx_params.n_ctx = 4096;
llama_context * ctx = llama_init_from_model(model, ctx_params);

// 3. Tokenize, decode, sample (see C API reference for full pattern)

GPU 対応でソースからビルドする

git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
cmake -B build -DGGML_CUDA=ON      # or GGML_VULKAN=ON, GGML_METAL=ON
cmake --build build --config Release -j

コアアーキテクチャ

llama.cpp/
  include/
    llama.h          # C API (primary interface)
    llama-cpp.h      # C++ RAII wrappers (unique_ptr aliases)
    ggml.h           # Tensor computation library
  common/
    common.h         # High-level convenience layer
  tools/
    server/          # HTTP server (llama-server)
    quantize/        # Model quantization tool
  examples/
    simple/          # Minimal inference example
    simple-chat/     # Multi-turn chat example

推論パイプライン：

Model (GGUF file)
  -> llama_model_load_from_file()  [load + mmap weights]
  -> llama_init_from_model()       [create context with KV cache]
  -> llama_tokenize()              [text -> tokens]
  -> llama_decode()                [run transformer, fill KV cache]
  -> llama_get_logits()            [get output probabilities]
  -> llama_sampler_sample()        [select next token]
  -> llama_token_to_piece()        [token -> text]
  -> repeat decode/sample loop until EOS

量子化クイックリファレンス

タイプ	ビット数	品質	推奨用途
Q4_K_M	~4.5	良好	標準の選択肢 -- 品質とサイズのバランスが最適
Q5_K_M	~5.5	非常に良好	約 20% の容量増加を許容できる場合
Q8_0	8	ほぼロスレス	検証、品質が特に重要なタスク
IQ4_XS	~4.25	4 ビットで最高	imatrix を使用する場合。Q4_K_M よりわずかに小さい
Q3_K_M	~3.5	許容可能	RAM に制約がある環境
IQ2_XS	~2.3	低下	極端な圧縮（imatrix が必要）
F16	16	参照用	全精度の基準

# Quantize a model
llama-quantize model-f16.gguf model-q4km.gguf Q4_K_M

# Convert from HuggingFace
python convert_hf_to_gguf.py /path/to/hf_model --outfile model.gguf

GPU バックエンド

バックエンド	フラグ	ハードウェア
CUDA	GGML_CUDA=ON	NVIDIA GPU
Metal	macOS で自動	Apple Silicon
Vulkan	GGML_VULKAN=ON	クロスプラットフォーム（NVIDIA/AMD/Intel）
HIP	GGML_HIP=ON	AMD GPU（ROCm）
SYCL	GGML_SYCL=ON	Intel GPU

GPU オフロード（-ngl 99）は、パフォーマンスに最も大きな影響を与える設定です。

サーバー API

組み込みサーバーは、OpenAI 互換のエンドポイントを提供します。

エンドポイント	用途
POST /v1/chat/completions	チャット（ストリーミングに対応）
POST /v1/completions	テキスト補完
POST /v1/embeddings	埋め込み
POST /v1/messages	Anthropic Messages API
POST /completion	すべてのパラメーターを制御できるネイティブ API
GET /health	ヘルスチェック
GET /metrics	Prometheus メトリクス

機能：関数呼び出し（--jinja）、文法制約（--grammar/--json-schema）、マルチモーダル（画像＋音声）、並列デコード、投機的デコード、ルーターモード、LoRA のホットスワップ、組み込み Web UI。

CMake 統合

# Method 1: Subdirectory (embedding)
add_subdirectory(vendor/llama.cpp)
target_link_libraries(myapp PRIVATE llama ggml)

# Method 2: Installed package
find_package(llama REQUIRED)
target_link_libraries(myapp PRIVATE llama)

詳細なリファレンスドキュメント

• C/C++ API リファレンス：llama.h の関数シグネチャ、型、列挙型、構造体、サンプリングチェーン API、および完全な動作例については、references/c-api-reference.md を参照してください
• ビルドシステムと統合：すべての CMake オプション、GPU バックエンドのビルド、ライブラリのリンク方法、Docker、パッケージマネージャーについては、references/build-and-integration.md を参照してください
• サーバー REST API：すべての HTTP エンドポイント、CLI フラグ、環境変数、curl の例、関数呼び出し、文法制約、Python クライアントの使用方法については、references/server-api.md を参照してください
• GGUF と量子化：GGUF 形式の仕様、40 種類以上の量子化タイプ、imatrix の生成、モデル変換、ハードウェア要件、対応アーキテクチャについては、references/quantization-guide.md を参照してください
• パフォーマンスと GPU バックエンド：バックエンドの比較、CUDA/Vulkan/Metal の最適化、メモリ管理、投機的デコード、ハードウェアの推奨事項については、references/performance-and-backends.md を参照してください
• Unreal Engine との統合：Llama-Unreal プラグイン、Build.cs を使用したカスタム C++ 統合、HTTP サーバー方式、ゲーム内のパフォーマンス、UE でよくある落とし穴については、references/unreal-engine-integration.md を参照してください