2026.10.23

技術 💻

llama.cppとは｜使い方・ビルド・GGUF量子化とllama-server

RJC Techチーム

結論

llama.cppは、GGUF形式のLLMをCPUやGPUで動かすC/C++製の推論エンジンです。対話は llama-cli、API は llama-server（OpenAI 互換）で使います。

この記事でわかること

導入5通りとcmakeビルド・GPU別の手順の早見表
SDKが送ったリクエストとGGUFの中身23項目の実物
量子化8種の大きさ・誤差の実測とエラー12種の直し方

2026年10月23日更新｜llama.cpp b11835・v0.7.0のソースで確認

llama.cpp は、量子化して小さくしたモデルのファイル（GGUF）を読み込み、層ごとに GPU と CPU へ振り分けて計算します。使う人は、対話用の llama-cli か、API サーバーの llama-server を起動します。

flowchart TD
    M[GGUF ファイル<br>量子化した重みと設定] --> E[llama.cpp<br>ggml で計算]
    E --> G[GPU<br>-ngl で指定した層]
    E --> C[CPU<br>残りの層]
    G --> O[llama-cli で対話<br>llama-server で API]
    C --> O

急いでいる人向けに、よく調べられることの答えを先にまとめます。

知りたいこと	答え	詳しい節
llama.cppとは	ローカルで LLM を動かす C/C++ の推論エンジン	とは
インストール	Win は winget、Mac は brew、配布バイナリも可	インストール
モデルを動かす	`llama-cli -hf ユーザー/リポジトリ`	llama-cli
API にする	`llama-server -m model.gguf` → `:9931/v1`	llama-server
既定のポート	v0.7.0 から 9931（以前は 8080）	llama-server
GPU を使う	CUDA 版などを使い、`-ngl` で層の数を指定	仕組み
どの量子化を選ぶ	迷ったら Q4_K_M（8B で約4.6GiB）	量子化
Ollama との違い	Ollama は llama.cpp を土台にした常駐アプリ	違い
ソースから入れる	`cmake -B build` → `cmake --build build`	ビルド

確認環境：llama.cpp は GitHub の ggml-org/llama.cpp の nightly b11835（コミット f64a498、2026年10月23日）を対象に、ソース（common/arg.cpp・tools/server・app・ggml/src/gguf.cpp など）と同梱ドキュメント（README・docs/build.md・docs/install.md・docs/docker.md・tools/server/README.md・tools/quantize/README.md）で、コマンド・オプションの既定値・エラー文の原文を確かめました。既定のポートの変化は v0.1.0・v0.5.0・v0.6.0・v0.7.0 のタグのソースで比べています。GGUF の中身と量子化は、同じリポジトリの gguf-py 0.19.0（Python 3.11.15・NumPy 2.4.4）で実際にファイルを書き・読み、行列を量子化して測りました。llama-server の API は、ソースが組み立てる応答の形をまねた擬似サーバーを立て、OpenAI の Python SDK 3.24.0 と curl 8.5.0 から送られたリクエストを記録しています。配布バイナリの名前は GitHub の Releases、Ollama・vLLM・LM Studio・llama-cpp-python・Hugging Face の値は各公式ドキュメントで確かめました（確認日 2026年10月23日）。

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

（記載例）出典：株式会社RJC「llama.cppとは｜使い方・ビルド・GGUF量子化とllama-server」

llama.cppとは（できること・特徴）

この節では、llama.cpp が何をするソフトで、どんな場面で使われるのかが分かります。

llama.cpp は、大規模言語モデル（LLM）を手元のパソコンやサーバーで動かすための、C/C++ で書かれた推論エンジンです。 推論とは、学習済みのモデルに文章を入れて続きを生成させることです。公式の README は、目的を「少ない準備で、ローカルでもクラウドでも、幅広いハードウェアで LLM（と画像も読める VLM）を最高水準の性能で動かすこと」と説明しています。ライセンスは MIT です。

名前の llama は Meta の LLaMA モデルを動かすために始まったことに由来しますが、今は Qwen・Gemma・Mistral・gpt-oss など多くのモデルを扱います。計算の部分は、同じ開発者たちの行列計算ライブラリ ggml の上に作られています。

1依存の少ない C/C++

Python や PyTorch が無くても動く。1つの実行ファイルで、組み込み機器や Android でも使われる

2量子化で小さくして動かす

1.5〜8 ビットの整数で重みを表す。8B のモデルが 16 ビットの約15GiB から 4.6GiB になる

3CPU と GPU を混ぜて使う

VRAM に入りきらないモデルも、入る分の層だけ GPU に載せ、残りを CPU で計算できる

README が挙げている対応のハードウェアは次のとおりです（2026年10月23日時点）。

種類	対応（README の記載）
CPU（x86）	AVX・AVX2・AVX512・AMX
CPU（Arm・Apple シリコン）	ARM NEON・Accelerate。Apple シリコンは「first-class citizen」
NVIDIA GPU	CUDA（独自のカーネル）
AMD GPU	HIP（ROCm）
どの GPU でも	Vulkan・WebGPU
Apple の GPU	Metal（Mac では既定で有効）
Intel GPU	SYCL・OpenVINO
複数台のマシン	RPC（ネットワーク越しに分担）

llama.cppでできること・使われる場面

やりたいこと	llama.cpp の部品	この記事の節
ターミナルでモデルと対話する	llama-cli	llama-cli
自作アプリ・RAG から呼ぶ	llama-server（OpenAI 互換 API）	llama-server
ブラウザでチャットする	llama-server の組み込み Web UI	llama-server
社外にデータを出さずに使う	すべて手元のマシンで計算	とは
モデルを小さくする	convert_hf_to_gguf.py・llama-quantize	量子化
速さを測る	llama-bench	オプション
Python から直接使う	llama-cpp-python（別のプロジェクト）	FAQ

文章をクラウドの API に送らずに済むので、社内文書を扱う RAG（検索して答える仕組み）や、ネットにつながらない環境のチャットに使われます。API の料金はかかりませんが、計算するマシンの電気代と、モデルが入るメモリ（RAM・VRAM）が要ります。

llama.cppの仕組み（GGUF・量子化・CPUとGPUの分担）

この節では、llama.cpp がモデルをどんな形で読み、どこで計算しているのかが図で分かります。

GGUF とは（モデルのファイル形式）

GGUF は、llama.cpp が読むモデルのファイル形式で、重み（テンソル）と、モデルの設定・トークナイザーなどのメタデータを1つのファイルにまとめたものです。 Hugging Face のドキュメントは、safetensors のようにテンソルだけを持つ形式と違い、「テンソルと標準化されたメタデータの両方を持つ」と説明しています。1ファイルで動くので、配るのも置くのも簡単です。

flowchart TD
    H[ヘッダー<br>GGUF の4文字と版 3] --> K[メタデータ<br>キーと値の組]
    K --> T[テンソルの情報<br>名前・形・量子化の種類]
    T --> D[テンソルのデータ<br>量子化した重み]

ファイルの先頭は、必ず GGUF の4文字（16進で 47 47 55 46）と版の番号です。リポジトリに入っている Qwen2 のトークナイザー用の GGUF の先頭を xxd で見ました。

$ xxd -l 16 models/ggml-vocab-qwen2.gguf
00000000: 4747 5546 0300 0000 0000 0000 0000 0000  GGUF............

0300 0000 はリトルエンディアンの 3 で、GGUF の版 3 を表します。中身は後の「GGUFファイルの中身を見る」の節で全部出します。

量子化とは

量子化（りょうしか）は、16 ビットの小数で持っている重みを、4 ビットなどの少ないビット数で表してファイルとメモリを小さくすることです。 小さくなるほど速く・軽くなりますが、元の値との差（誤差）が増え、答えの質が下がることがあります。llama.cpp の量子化は、32 個や 256 個の重みを1つのブロックにして、ブロックごとの倍率（スケール）と小さな整数で表します。種類と大きさは後の「量子化の種類と大きさ」の節で比べます。

CPU と GPU の分担（-ngl）

LLM は、同じ形の層（Transformer のブロック）を何十段も重ねた作りです。llama.cpp は、-ngl（--n-gpu-layers）で指定した数の層を GPU の VRAM に載せ、残りの層を CPU で計算します。 全部が VRAM に入ればいちばん速く、入らなければ一部だけ載せて動かせるのが特徴です。

GPU に載せた層

VRAM に重みと KV キャッシュを置く

並列の計算が速い

VRAM の大きさが上限

CPU に残した層

メインメモリ（RAM）に置く

GPU より遅いが、RAM は増やしやすい

GPU が無ければ全部がここ

-ngl の既定は auto で、ソースでは数字・auto・all のどれかを受け付けます。さらに --fit（既定で on）が、指定していない値（層の数やコンテキスト長）を、各デバイスに 1024MiB の余裕を残して入るように調整します。docs/build.md には「-ngl 0 でも計算の一部に GPU が使われることがあり、完全に止めるには --device none」と書かれています。

llama.cppのインストール方法（Windows・Mac・Linux）

この節では、自分の OS と GPU に合った入れ方を選べます。

llama.cpp には5つの入れ方があります。ビルドしたことがなければ、パッケージマネージャーか配布バイナリがいちばん早い方法です。

入れ方	Windows	Mac	Linux
パッケージマネージャー	`winget install llama.cpp`	`brew install llama.cpp`	`brew install llama.cpp`・Nix・conda-forge
公式のインストーラー（llama.app）	PowerShell で install.ps1（下記）	アプリ版あり	install.sh（下記）
GitHub Releases の配布バイナリ	zip（CPU・CUDA・Vulkan など）	tar.gz（arm64・x64）	tar.gz（CPU・CUDA・Vulkan・ROCm など）
ソースからビルド	Visual Studio 2022＋CMake	Xcode のツール＋CMake	gcc か clang＋CMake
Docker	可	可	`ghcr.io/ggml-org/llama.cpp:server` など

# Linux・Mac（README の Quick start）
curl -LsSf https://llama.app/install.sh | sh

# Windows の PowerShell
irm https://llama.app/install.ps1 | iex

llama.app は README の Quick start の最初に載っている、llama.cpp チームと Hugging Face のアプリです。サイトの説明では、Mac と Windows ではメニューバー・タスクトレイのアプリ、Linux ではコマンドラインの版で、モデルは Hugging Face のキャッシュに置かれます。

配布バイナリの選び方（GitHub Releases）

GitHub の Releases には、nightly ビルド（b と番号のタグ）ごとに OS と GPU 別のファイルが並びます。2026年10月23日時点の最新（b11829）の名前の例です。

自分の環境	選ぶファイル（b11829 の例）
Windows・GPU なし	llama-b11829-bin-win-cpu-x64.zip
Windows・NVIDIA GPU	llama-b11829-bin-win-cuda-13.4-x64.zip と cudart-llama-bin-win-cuda-13.4-x64.zip
Windows・AMD や Intel の GPU	llama-b11829-bin-win-vulkan-x64.zip
Mac（Apple シリコン）	llama-b11829-bin-macos-arm64.tar.gz
Ubuntu・GPU なし	llama-b11829-bin-ubuntu-x64.tar.gz
Ubuntu・NVIDIA GPU	llama-b11829-bin-ubuntu-cuda-13.4-x64.tar.gz
Ubuntu・AMD GPU	llama-b11829-bin-ubuntu-rocm-10.0-x64.tar.gz か vulkan

CUDA 版は CUDA 12.4（Windows）・12.8（Ubuntu）と 13.4 の2系統があり、cudart- で始まるファイルは CUDA のランタイムの DLL・ライブラリです。CUDA Toolkit を入れていないパソコンでは、本体と同じフォルダに展開します。

版の番号（nightly と v0.x.y）

llama.cpp には2種類の版があります。docs/release.md によると、毎日のビルドは b11835 のような通し番号、リリースは semver の v0.7.0 のタグです。git のタグで見ると、v0.1.0 が 2026年8月17日、v0.7.0 が 2026年10月15日でした。

$ git ls-remote --tags origin 'v*'
… refs/tags/v0.1.0  refs/tags/v0.1.1  refs/tags/v0.1.2  refs/tags/v0.2.0  refs/tags/v0.3.0
  refs/tags/v0.4.0  refs/tags/v0.4.1  refs/tags/v0.5.0  refs/tags/v0.6.0  refs/tags/v0.7.0

--version は、ソースの llama_print_build_info で次の2行の形で表示されます。

version: <版>（ソースから作ると 0.7.0-dev のように -dev が付く） (build <番号>, commit <コミット>)
built with <コンパイラ> for <OS と CPU>

build の番号は、ビルド時に git rev-list --count HEAD で数えたコミットの数です。git clone --depth 1 で取ったソースでは、手元で数えると 1 でした。正しい番号を出したいときは、深さを指定せずに clone します。

llama.cppのビルド方法（cmake・CUDA・Metal・Vulkan）

この節では、ソースから CPU 版・GPU 版を作る手順と、GPU ごとの cmake の指定が分かります。

docs/build.md の CPU 版の手順は、clone と2つの cmake だけです。

道具をそろえる

Linux は gcc・g++・cmake・git。Mac は Xcode のコマンドラインツールと cmake。Windows は Visual Studio 2022 の「C++ によるデスクトップ開発」と CMake・Git。

ソースを取る

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

構成する

cmake -B build。GPU 版はここに -DGGML_CUDA=ON などを足す。

ビルドする

cmake --build build --config Release -j 8。-j は同時に動かすジョブの数。

できたものを確かめる

実行ファイルは build/bin/ にできる。./build/bin/llama-server --version で版を見る。

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

# llama-server だけを作るとき（tools/server/README.md の手順）
cmake --build build --config Release -t llama-server

GPU を使うときは、構成（cmake -B build）のときにバックエンドを指定します。

GPU	cmake に足す指定	前もって要るもの
NVIDIA	`-DGGML_CUDA=ON`	CUDA Toolkit
Apple シリコン	指定なし（Metal が既定で有効）	Xcode のコマンドラインツール
AMD	`-DGGML_HIP=ON -DGPU_TARGETS=gfx1030`（GPU の型）	ROCm
どのメーカーでも	`-DGGML_VULKAN=ON`	Vulkan SDK
Intel GPU	SYCL（docs/backend/SYCL.md）	oneAPI
CPU だけで速くしたい	`-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS`	OpenBLAS

docs/build.md の注意点です。

CUDA 版の既定は「ビルドしたマシンの GPU 向け」です。別の GPU のマシンでも使うなら -DGGML_NATIVE=OFF か、-DCMAKE_CUDA_ARCHITECTURES="86;89" のように Compute Capability を並べます。
-DGGML_CUDA=ON -DGGML_VULKAN=ON のように複数のバックエンドを同時に入れられ、実行時に --device で選びます。使えるデバイスは --list-devices で表示します。
BLAS は、512 を超える大きなバッチのプロンプト処理を速くすることがあり、生成（1トークンずつ出す部分）の速さは変わらないと書かれています。
HTTPS でモデルを取るには OpenSSL の開発用ライブラリが要ります（Ubuntu は libssl-dev）。無くてもビルドはでき、SSL 無しで動きます。

できる実行ファイル

ビルドすると、目的ごとの実行ファイルと、それらを1つにまとめた llama ができます。app/llama.cpp のソースにあるサブコマンドの一覧です。

llama のサブコマンド	単体の実行ファイル	役割
`llama serve`（別名 server）	llama-server	HTTP の API サーバー
`llama cli`（別名 client）	llama-cli	ターミナルで対話
`llama download`（別名 get）	―	モデルをダウンロードするだけ
`llama completion`	llama-completion	会話でない文章の続きの生成
`llama bench`	llama-bench	速さの計測
`llama quantize`	llama-quantize	量子化
`llama perplexity`	llama-perplexity	パープレキシティ（質の指標）の計測
`llama help all`	―	隠れたコマンドも含めて一覧を出す

README の Quick start は llama cli -hf …・llama serve -hf … の形で書かれています。この記事では、配布物にもある単体の名前（llama-cli・llama-server）で書きます。どちらも同じ引数を受け付けます。

Hugging FaceでGGUFモデルを入手する

この節では、モデルをどこから取り、どこに保存されるのかが分かります。

llama.cpp で動かすモデルは、Hugging Face の GGUF 形式のリポジトリから取るのが基本です。 Hugging Face のモデル一覧は https://huggingface.co/models?library=gguf で GGUF に絞り込めます。llama.cpp の開発元の ggml-org や、各モデルの開発元（Qwen・google など）が公開しているリポジトリを選ぶと、作り手がはっきりしています。モデルごとにライセンス（商用利用の条件など）が違うので、モデルカードで確かめます。

-hf でダウンロードして起動する

-hf ユーザー/リポジトリ[:量子化] を付けると、llama.cpp がダウンロードしてから起動します。

# README の例。量子化を省くと Q4_K_M、無ければリポジトリの最初のファイル
llama-cli -hf ggml-org/Qwen3.5-0.8B-GGUF

# 量子化を指定する
llama-server -hf ggml-org/gemma-3-4b-it-qat-GGUF:Q4_K_M

# ダウンロードだけ（保存先のパスが表示される）
llama download -hf ggml-org/gemma-3-4b-it-qat-GGUF:Q4_K_M

引数・環境変数	意味
`-hf`（`--hf-repo`）	リポジトリ。`:Q8_0` などで量子化を選ぶ
`-hff`（`--hf-file`）	ファイル名を直接指定する（`-hf` の量子化より優先）
`-hft` か環境変数 `HF_TOKEN`	利用の承認が要るモデルを取るためのトークン
`-cl`（`--cache-list`）	ダウンロード済みのモデルの一覧
`--offline`	ネットに接続せず、キャッシュだけを使う
環境変数 `LLAMA_CACHE`	保存先を変える

画像も読めるモデルは、画像を処理する部品（mmproj）のファイルも自動で一緒に取られます（--no-mmproj で止める）。

モデルの保存先

common/hf-cache.cpp のソースでは、-hf で取ったモデルの保存先は次の順で決まります。指定が無ければ Hugging Face の共通のキャッシュ（~/.cache/huggingface/hub）で、Python の huggingface_hub などと同じ場所を使います。

優先順	環境変数	保存先
1	`LLAMA_CACHE`	そのフォルダ
2	`HF_HUB_CACHE`・`HUGGINGFACE_HUB_CACHE`	そのフォルダ
3	`HF_HOME`	その下の hub
4	`XDG_CACHE_HOME`	その下の huggingface/hub
5	（何も無いとき）	ホームの .cache/huggingface/hub

社内のプロキシを通る環境では、tools/server/README.md のとおり HTTPS_PROXY を設定してからダウンロードします。

自分で GGUF に変換する

GGUF が配られていないモデルは、Hugging Face 形式（safetensors）から自分で変換します。tools/quantize/README.md の手順は2段階です。

flowchart TD
    A[Hugging Face 形式<br>safetensors] --> B[convert_hf_to_gguf.py]
    B --> C[GGUF<br>BF16 か F16]
    C --> D[llama-quantize]
    D --> E[GGUF<br>Q4_K_M など]

python3 -m pip install -r requirements.txt
python3 convert_hf_to_gguf.py --outfile model-bf16.gguf --outtype bf16 ./モデルのフォルダ
./build/bin/llama-quantize model-bf16.gguf model-Q4_K_M.gguf Q4_K_M

README には、ブラウザだけで変換と量子化ができる Hugging Face の Space「GGUF-my-repo」も紹介されています。

llama-cliの使い方（ターミナルで対話）

この節では、モデルとターミナルで会話する基本の使い方が分かります。

llama-cli -m モデル.gguf で起動すると、そのまま対話が始まります。 今の llama-cli は、内部で llama-server を起動し、そこへつなぐクライアントとして動く作りです（tools/cli のソース）。すでに動いている llama-server へは --server-base http://localhost:9931 でつなげます。

# 手元のファイルで対話する
llama-cli -m ./models/model-Q4_K_M.gguf

# システムプロンプトを付ける
llama-cli -m ./models/model-Q4_K_M.gguf -sys "日本語で短く答えてください"

# 1回だけ答えて終わる（スクリプトから使う）
llama-cli -m ./models/model-Q4_K_M.gguf -p "GGUFとは何ですか" -st

# GPU に全部の層を載せ、コンテキストを 8192 にする
llama-cli -m ./models/model-Q4_K_M.gguf -ngl all -c 8192

オプション	意味	既定
`-sys`・`-sysf`	システムプロンプト（文字・ファイル）	なし
`-p`	最初のプロンプト	なし
`-st`（`--single-turn`）	1往復で終わる	無効
`-mli`	複数行をそのまま貼り付けられる	無効
`--image` など	画像・音声・動画を渡す（対応モデル）	なし
`--reasoning off`	考える過程（thinking）を止める	auto
`--show-timings`	1回ごとの速さを表示する	有効

以前の解説によく出てくる -cnv（会話モード）・-no-cnv は、今のソースでは llama-completion だけの引数です。llama-cli に付けると、引数の解析で error: invalid argument: -cnv になります。会話でなく「文章の続き」を生成したいときは llama-completion を使います。

llama-serverの使い方（OpenAI互換API）

この節では、llama-server を API サーバーとして起動し、curl や OpenAI の SDK から呼ぶ方法が分かります。

llama-server -m モデル.gguf で起動すると、http://127.0.0.1:9931 に OpenAI 互換の API と、ブラウザで使えるチャット画面（Web UI）が立ち上がります。

llama-server -m ./models/model-Q4_K_M.gguf -c 8192 -ngl all
# → http://127.0.0.1:9931/ をブラウザで開くとチャット画面

既定のポートは 9931（v0.7.0 から）

既定のポートは、v0.7.0（2026年10月15日のタグ）から 8080 ではなく 9931 になりました。 タグごとの common/common.h の値を比べた結果です。

v0.1.0: int32_t port = 8080;
v0.5.0: int32_t port = 8080;
v0.6.0: int32_t port = 8080;
v0.7.0: int32_t port = 9931;          // server listens on this network port

以前の解説や、8080 を前提に設定したアプリ・Open WebUI などから「つながらない」ときは、まずポートを確かめます。8080 で動かし続けたいときは --port 8080 を付けます。Docker の README の例は、今も --port 8080 を明示しています。

主なエンドポイント

エンドポイント	役割	互換
`POST /v1/chat/completions`	チャット（ストリーミング可）	OpenAI
`POST /v1/completions`	文章の続き	OpenAI
`POST /v1/responses`	Responses API	OpenAI
`POST /v1/embeddings`	埋め込み（`--embedding` で起動）	OpenAI
`GET /v1/models`	読み込んだモデルの情報	OpenAI
`POST /v1/messages`	Messages API	Anthropic
`GET /health`	準備ができたか（200 か 503）	独自
`POST /completion`・`/tokenize`・`/infill`	llama.cpp 独自の API	独自
`GET /metrics`	Prometheus 形式の指標（`--metrics`）	独自

curl・Python から呼ぶ

curl から呼ぶ例です。

curl http://localhost:9931/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"local","messages":[{"role":"user","content":"llama.cppとは？"}]}'

OpenAI の Python SDK は、base_url を llama-server に向けるだけで使えます。

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:9931/v1", api_key="sk-no-key-required")
r = client.chat.completions.create(
    model="local",
    messages=[{"role": "system", "content": "日本語で短く答えて"},
              {"role": "user", "content": "llama.cppとは？"}],
    temperature=0.7, max_tokens=64)
print(r.choices[0].message.content)
print(r.usage)
print("timings:", list(r.model_extra["timings"]))   # llama.cpp 独自の項目

このコードを、llama-server の応答の形（tools/server の server-task.cpp・server-http.cpp）をまねた擬似サーバーに向けて動かし、SDK が実際に送ったリクエストを記録しました。

POST /v1/chat/completions
authorization: Bearer sk-no-key-required
content-type: application/json
user-agent: OpenAI/Python 3.24.0
x-stainless-lang: python
x-stainless-package-version: 3.24.0
x-stainless-retry-count: 0
x-stainless-read-timeout: 600
Content-Length: 169
{"model":"local","messages":[{"role":"system","content":"日本語で短く答えて"},{"role":"user","content":"llama.cppとは？"}],"max_tokens":64,"temperature":0.7}

（Host・Accept-Encoding などの一般的なヘッダーと、x-stainless-os などの残りは省いています。）SDK の側の出力です。

llama.cpp は GGUF の モデル を 動かす 推論 エンジン です。
CompletionUsage(completion_tokens=11, prompt_tokens=21, total_tokens=32, completion_tokens_details=None, prompt_tokens_details=PromptTokensDetails(audio_tokens=None, cache_write_tokens=None, cached_tokens=0, image_tokens=None, text_tokens=None))
timings: ['cache_n', 'prompt_n', 'prompt_ms', 'prompt_per_token_ms', 'prompt_per_second', 'predicted_n', 'predicted_ms', 'predicted_per_token_ms', 'predicted_per_second']

返答の文章とトークン数は擬似サーバーが返した仮のものです。読み取れることは次のとおりです。

API キーを設定していない llama-server でも、SDK は api_key に何かの文字列を求めます。 README の例と同じ sk-no-key-required のような値を入れておくと、Authorization: Bearer … として送られます。
llama-server は OpenAI の項目に加えて timings（プロンプトの処理と生成の、トークン数・ミリ秒・1秒あたりのトークン数）を返します。SDK では r.model_extra["timings"] で読めます。predicted_per_second が生成の速さです。
system_fingerprint には b11835-f64a498 のようなビルドの番号とコミットが入ります（ソースの llama_build_info）。

ストリーミング（stream=True）では、Server-Sent Events の data: 行が1トークン分ずつ届き、最後が data: [DONE] です。擬似サーバーから curl で受けた最初の2行です（長い行の後ろは省いています）。

data: {"choices": [{"finish_reason": null, "index": 0, "delta": {"role": "assistant", "content": null}}], "created": 1792738077, "id": "chatcmpl-WNonPWrfi8Kw7rwLGzLlZOIEWQUUPcKP", "model": "my-model-Q4_K_M.gguf", "system_fingerprint": "b11835-f64a498", "object": …

data: {"choices": [{"finish_reason": null, "index": 0, "delta": {"content": "llama.cpp"}}], …

最初のかたまりが role だけで content が null なのは、ソースのコメントにあるとおり「OpenAI の動きに合わせるため」です。SDK でストリーミングを読むコードです。

stream = client.chat.completions.create(model="local", stream=True,
    messages=[{"role": "user", "content": "llama.cppとは？"}])
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

API キーと外部への公開

llama-server は既定で 127.0.0.1（同じマシンからだけ）で待ち受けます。ほかのマシンから使うときは --host 0.0.0.0 にし、必ず --api-key も付けます。

llama-server -m ./models/model-Q4_K_M.gguf --host 0.0.0.0 --port 9931 --api-key s358-secret

擬似サーバーにソースと同じ API キーの確かめ方（Authorization: Bearer か X-Api-Key、/health は確かめない）を入れて、curl で送った結果です。

[ヘッダーなし]                        {"error": {"code": 401, "message": "Invalid API Key", "type": "authentication_error"}}  -> HTTP 401
[Authorization: Bearer wrong]         {"error": {"code": 401, "message": "Invalid API Key", "type": "authentication_error"}}  -> HTTP 401
[Authorization: Bearer s358-secret]   {"object": "list", "data": [{"id": "my-model-Q4_K_M.gguf", "object": "model", … -> HTTP 200
[X-Api-Key: s358-secret]              {"object": "list", "data": [{"id": "my-model-Q4_K_M.gguf", "object": "model", … -> HTTP 200
[/health をキーなしで]                 {"status": "ok"}  -> HTTP 200

OpenAI SDK で違うキーを送ると、AuthenticationError Error code: 401 - {'error': {'code': 401, 'message': 'Invalid API Key', 'type': 'authentication_error'}} になりました。

tools/server/README.md の CORS の節は、公開の仕方ごとの設定を次のように勧めています。

置き場所	README の推奨
インターネットに公開	API キーを設定し、リバースプロキシの後ろに置く
社内のネットワーク	`--cors-origins` に画面（フロントエンド）のオリジンを指定
同じマシンだけ	`--cors-origins localhost`

--tools・--agent（ファイルの読み書きやコマンドの実行を API から行える試験的な機能）は、README で「信頼できない環境では有効にしない」とされています。

複数のモデルを切り替える（ルーターモード）

モデルを指定せずに llama-server を起動すると、ルーターモードになります。キャッシュ（-hf で取ったもの）や --models-dir のフォルダの GGUF を一覧にし、リクエストの model の値で読み込むモデルを切り替えます。同時に読み込むのは既定で4つまで（--models-max）です。

llama.cppの主なオプション早見表

この節では、よく使うオプションと既定値を1つの表で引けます。値は llama-cli と llama-server の README（自動生成のヘルプ）で確かめた 2026年10月23日時点のものです。

オプション	意味	既定
`-m`・`--model`	モデルのファイル	なし
`-hf`・`--hf-repo`	Hugging Face から取る	なし（量子化は Q4_K_M）
`-c`・`--ctx-size`	コンテキスト長（トークン）	0＝モデルの値
`-ngl`・`--n-gpu-layers`	GPU に載せる層の数・auto・all	auto
`--fit`	入りきるよう未指定の値を調整	on
`-t`・`--threads`	CPU のスレッド数	-1（自動）
`-fa`・`--flash-attn`	Flash Attention	auto
`-ctk`・`-ctv`	KV キャッシュの型（q8_0 で約半分）	f16
`-n`・`--n-predict`	生成するトークン数の上限	-1（無制限）
`--temp`	温度（大きいほどばらつく）	0.80
`--top-k`・`--top-p`・`--min-p`	候補の絞り込み	40・0.95・0.05
`-b`・`-ub`	論理・物理のバッチの大きさ	2048・512
`--host`・`--port`	待ち受けるアドレスとポート（server）	127.0.0.1・9931
`-np`・`--parallel`	同時に処理する枠（スロット）の数（server）	-1（自動）
`-cb`・`--cont-batching`	連続バッチング（server）	有効
`--api-key`	API キー（server）	なし
`-a`・`--alias`	API に見せるモデル名（server）	ファイルのパス
`--no-webui`	Web UI を出さない（server）	出す
`-dev`・`--list-devices`	使うデバイス・一覧	自動
`-ts`・`-sm`	複数 GPU への分け方	―・layer

ほとんどのオプションは環境変数でも指定できます（例：-c は LLAMA_ARG_CTX_SIZE、-ngl は LLAMA_ARG_N_GPU_LAYERS、--port は LLAMA_ARG_PORT）。両方あるときはコマンドラインの引数が優先されます。Docker Compose で使うときに便利です。

量子化の種類と大きさ（Q4_K_M・Q8_0の選び方）

この節では、GGUF のファイル名に付く Q4_K_M などの意味と、どれを選べばよいかが数値で分かります。

量子化の名前の読み方

名前の部分	意味
Q の後の数字	1つの重みのおおよそのビット数（Q4 は約4ビット）
`_0`・`_1`	最初期の方式。`_1` は倍率に加えて最小値も持つ
`_K`	k-quants。256 個のスーパーブロックで倍率を細かく持つ
`_S`・`_M`・`_L`	同じ方式の中の小・中・大（大きいほど一部の層を高い精度にする）
`IQ` で始まる	i-quants。重要度の行列（imatrix）を使って低いビットでも誤差を抑える
F16・BF16	量子化していない16ビット

Llama 3.1 8B での大きさ（公式の表）

tools/quantize/README.md には、Llama 3.1 8B を各方式で量子化したときの「1重みあたりのビット数」と大きさの表があります。その値をグラフにしました。

Llama 3.1 8B の GGUF の大きさtools/quantize/README.md の表（GiB）

Q2_K2.95

Q3_K_M3.74

Q4_K_M4.58

Q5_K_M5.33

Q6_K6.14

Q8_07.95

F1614.96

量子化	ビット/重み	大きさ（GiB）	生成の速さ（t/s、README の表）
IQ2_XS	2.5882	2.42	78.04
Q3_K_M	3.9960	3.74	71.68
IQ4_XS	4.4597	4.17	77.51
Q4_K_M	4.8944	4.58	71.93
Q5_K_M	5.7036	5.33	67.23
Q6_K	6.5633	6.14	58.67
Q8_0	8.5008	7.95	50.93
F16	16.0005	14.96	29.17

同じ表で、生成の速さ（text generation、128トークン）は F16 の 29.17 トークン/秒に対して Q4_K_M が 71.93 トークン/秒でした。生成は重みを読み出す量で速さが決まりやすいため、小さい量子化ほど速くなる傾向が出ています（計測した機材は表に書かれていません）。

手元で量子化して誤差を測る

llama.cpp に同梱の gguf-py（Python 版の GGUF ライブラリ）で、4096×4096 の行列（正規分布、標準偏差 0.02）を各方式で量子化し、元に戻したときの誤差を測りました。

import time, numpy as np
from gguf import GGMLQuantizationType as T, quantize, dequantize

rng = np.random.default_rng(0)
w = rng.normal(0, 0.02, size=(4096, 4096)).astype(np.float32)
for name in ["Q8_0", "Q5_1", "Q5_0", "Q4_1", "Q4_0"]:
    qt = getattr(T, name)
    q = quantize(w, qt); back = dequantize(q, qt)
    rel = np.sqrt(np.mean((back - w) ** 2)) / np.sqrt(np.mean(w ** 2)) * 100
    print(f"{name} {q.nbytes/1024/1024:.2f} MiB  {q.nbytes*8/w.size:.3f} bit/重み  相対誤差 {rel:.3f}%")

元の行列: 4096x4096 = 16,777,216 個の重み
F32     64.00 MiB  32.000 bit/重み  相対誤差  0.000%  (0.00秒)
F16     32.00 MiB  16.000 bit/重み  相対誤差  0.021%  (0.09秒)
BF16    32.00 MiB  16.000 bit/重み  相対誤差  0.166%  (0.20秒)
Q8_0    17.00 MiB   8.500 bit/重み  相対誤差  0.535%  (0.28秒)
Q5_1    12.00 MiB   6.000 bit/重み  相対誤差  3.784%  (0.31秒)
Q5_0    11.00 MiB   5.500 bit/重み  相対誤差  4.268%  (0.29秒)
Q4_1    10.00 MiB   5.000 bit/重み  相対誤差  7.821%  (0.30秒)
Q4_0     9.00 MiB   4.500 bit/重み  相対誤差  8.592%  (0.17秒)

（F32・F16・BF16 の行は、同じスクリプトで型を変えて測った値です。）

Q8_0 が 8 ビットなのに 8.500 ビット/重みになるのは、32 個の重みごとに 16 ビットの倍率を1つ持つためです（(32×8＋16)÷32＝8.5）。Q4_0 も同じ理由で 4.5 ビットです。公式の表の Q8_0 の 8.5008 とも合います。誤差は Q8_0 で 0.5％ほど、4 ビットで 8％ほどでした。ただし、これは重みの値の誤差で、答えの質の下がり方はモデルや言語で変わります。質の比較には llama-perplexity（パープレキシティ・KL ダイバージェンス）を使います。K 系（Q4_K など）は gguf-py に量子化する関数が無い（元に戻す関数だけ）ため、K 系の数値は公式の表で比べています。

必要なメモリを計算する

動かすのに要るメモリは、おおよそ「重みの大きさ＋KV キャッシュ＋作業領域」です。KV キャッシュは、読んだ文章（コンテキスト）を覚えておく場所で、「2（K と V）×層の数×コンテキスト長×KV ヘッドの数×ヘッドの次元×1要素のバイト数」で増えます。Llama 3 系の GGUF に入っている値を読んで計算しました。

import sys, gguf
r = gguf.GGUFReader(sys.argv[1])            # Llama 3 系のメタデータ
g = lambda k: int(r.fields[k].contents())
L, kvh = g("llama.block_count"), g("llama.attention.head_count_kv")
hd = g("llama.embedding_length") // g("llama.attention.head_count")
N_PARAMS = 8_030_261_312                    # Llama 3.1 8B（llama-server README の例の n_params）
BPW = {"Q4_K_M": 4.8944, "Q5_K_M": 5.7036, "Q6_K": 6.5633, "Q8_0": 8.5008, "F16": 16.0005}
GiB = 1024**3
print(f"層 {L}・KVヘッド {kvh}・ヘッドの次元 {hd}")
for q, b in BPW.items():
    print(f"重み {q:7s}: {N_PARAMS * b / 8 / GiB:5.2f} GiB")
for ctx in (4096, 32768, 131072):
    for name, bytes_per in (("f16", 2), ("q8_0", 34 / 32)):
        print(f"KVキャッシュ ctx={ctx:6d} {name:4s}: {2*L*ctx*kvh*hd*bytes_per / GiB:5.2f} GiB")

層 32・KVヘッド 8・ヘッドの次元 128
重み Q4_K_M :  4.58 GiB
重み Q5_K_M :  5.33 GiB
重み Q6_K   :  6.14 GiB
重み Q8_0   :  7.95 GiB
重み F16    : 14.96 GiB
KVキャッシュ ctx=  4096 f16 :  0.50 GiB
KVキャッシュ ctx=  4096 q8_0:  0.27 GiB
KVキャッシュ ctx= 32768 f16 :  4.00 GiB
KVキャッシュ ctx= 32768 q8_0:  2.12 GiB
KVキャッシュ ctx=131072 f16 : 16.00 GiB
KVキャッシュ ctx=131072 q8_0:  8.50 GiB

計算した重みの大きさは、公式の表（4.58・5.33・6.14・7.95・14.96 GiB）と一致しました。

4.58GiB8B の Q4_K_M の重みF16 の約3割

0.50GiBKV キャッシュ（4096）f16、Llama 3.1 8B

16.0GiBKV キャッシュ（131072）重みより大きくなる

長いコンテキストでは、KV キャッシュが重みより大きくなります。 -c を必要な長さにする、-ctk q8_0 -ctv q8_0 で KV キャッシュを約半分にする、が効く対策です。GPU 別の目安と、ほかのモデルでの計算は、関連記事「VRAMとは｜確認方法・必要量の目安とLLMの計算式をPythonで解説」で扱っています。

どの量子化を選ぶか（判断表）

状況	選ぶもの	理由
迷ったとき	Q4_K_M	`-hf` の既定。大きさと質の釣り合いがよい
メモリに余裕があり質を優先	Q5_K_M・Q6_K	4 ビットより誤差が小さい
量子化の影響をほぼ避けたい	Q8_0	誤差が小さく、F16 の約半分
メモリが足りない	IQ4_XS・Q3_K_M	4 ビット前後より下で小さくする
とにかく小さく	IQ2・Q2_K	質の低下が大きくなりやすい
自分でさらに量子化する元	BF16・F16	量子化済みを再び量子化すると質が落ちる

量子化済みのモデルをもう一度量子化するには --allow-requantize が要り、README には「16 ビットや 32 ビットから量子化するより質がかなり下がることがある」と警告があります。

GGUFファイルの中身を見る（実物）

この節では、GGUF の中に何が入っているのかを、実際のファイルで確かめます。

llama.cpp のリポジトリの models/ には、トークナイザーの試験用の GGUF（重みは入っていない）が入っています。Llama 3 系の ggml-vocab-llama-bpe.gguf（7,818,140 バイト）を、gguf-py の gguf-dump で開いたメタデータの全部です。

$ python3 -m gguf.scripts.gguf_dump --no-tensors models/ggml-vocab-llama-bpe.gguf
* File is LITTLE endian, script is running on a LITTLE endian host.
* Dumping 23 key/value pair(s)
      1: UINT32     |        1 | GGUF.version = 3
      2: UINT64     |        1 | GGUF.tensor_count = 0
      3: UINT64     |        1 | GGUF.kv_count = 20
      4: STRING     |        1 | general.architecture = 'llama'
      5: STRING     |        1 | general.name = 'llama-bpe'
      6: UINT32     |        1 | llama.block_count = 32
      7: UINT32     |        1 | llama.context_length = 8192
      8: UINT32     |        1 | llama.embedding_length = 4096
      9: UINT32     |        1 | llama.feed_forward_length = 14336
     10: UINT32     |        1 | llama.attention.head_count = 32
     11: UINT32     |        1 | llama.attention.head_count_kv = 8
     12: FLOAT32    |        1 | llama.rope.freq_base = 500000.0
     13: FLOAT32    |        1 | llama.attention.layer_norm_rms_epsilon = 9.999999747378752e-06
     14: UINT32     |        1 | general.file_type = 1
     15: UINT32     |        1 | llama.vocab_size = 128256
     16: UINT32     |        1 | llama.rope.dimension_count = 128
     17: STRING     |        1 | tokenizer.ggml.model = 'gpt2'
     18: STRING     |        1 | tokenizer.ggml.pre = 'llama-bpe'
     19: [STRING]   |   128256 | tokenizer.ggml.tokens = ['!', '"', '#', '$', '%', '&', ...]
     20: [INT32]    |   128256 | tokenizer.ggml.token_type = [1, 1, 1, 1, 1, 1, ...]
     21: [STRING]   |   280147 | tokenizer.ggml.merges = ['Ġ Ġ', 'Ġ ĠĠĠ', 'ĠĠ ĠĠ', 'ĠĠĠ Ġ', 'i n', 'Ġ t', ...]
     22: UINT32     |        1 | tokenizer.ggml.bos_token_id = 128000
     23: UINT32     |        1 | tokenizer.ggml.eos_token_id = 128001

キー	何の値か
`general.architecture`	モデルの種類。llama.cpp はこれで計算の組み方を決める
`llama.block_count`	層の数（-ngl で数える単位）
`llama.context_length`	学習したコンテキスト長
`llama.attention.head_count_kv`	KV ヘッドの数（KV キャッシュの大きさに効く）
`general.file_type`	量子化の種類（1 は F16、7 は Q8_0 など）
`tokenizer.ggml.*`	トークナイザーの語彙・結合規則・特別なトークン

モデルの設定とトークナイザーがファイルの中にあるので、llama.cpp は GGUF 1つだけで動きます。 新しい種類のモデルで unknown model architecture が出るのは、この general.architecture の値を、使っている llama.cpp がまだ知らないときです。

自分でも小さな GGUF を書いて、読み戻しました。

import sys, numpy as np, gguf
w = gguf.GGUFWriter(sys.argv[1], arch="llama")
w.add_name("tiny-demo"); w.add_context_length(4096); w.add_block_count(2)
w.add_embedding_length(64); w.add_file_type(gguf.LlamaFileType.MOSTLY_Q8_0)
x = np.random.default_rng(0).normal(0, 0.02, (64, 64)).astype(np.float32)
w.add_tensor("blk.0.attn_q.weight", gguf.quantize(x, gguf.GGMLQuantizationType.Q8_0),
             raw_dtype=gguf.GGMLQuantizationType.Q8_0)
w.write_header_to_file(); w.write_kv_data_to_file(); w.write_tensors_to_file(); w.close()

r = gguf.GGUFReader(sys.argv[1])
for k, f in r.fields.items():
    if not k.startswith("GGUF."):
        print(f"  {k} = {f.contents()}")
for t in r.tensors:
    print(f"  tensor {t.name} shape={[int(s) for s in t.shape]} type={t.tensor_type.name} bytes={t.n_bytes}")

GGUF version: 3
  general.architecture = llama
  general.name = tiny-demo
  llama.context_length = 4096
  llama.block_count = 2
  llama.embedding_length = 64
  general.file_type = 7
  tensor blk.0.attn_q.weight shape=[64, 64] type=Q8_0 bytes=4352
$ xxd -l 64 tiny.gguf
00000000: 4747 5546 0300 0000 0100 0000 0000 0000  GGUF............
00000010: 0600 0000 0000 0000 1400 0000 0000 0000  ................
00000020: 6765 6e65 7261 6c2e 6172 6368 6974 6563  general.architec
00000030: 7475 7265 0800 0000 0500 0000 0000 0000  ture............

先頭から「GGUF」「版 3」「テンソルの数 1」「メタデータの数 6」、続いて最初のキーの長さ 20（0x14）と general.architecture の文字が並んでいます。64×64＝4,096 個の重みの Q8_0 は 4,352 バイトで、4,096÷32＝128 ブロック×34 バイト（倍率2バイト＋重み32バイト）と一致します。

llama.cppとOllama・vLLMの違い

この節では、似た目的のツールとの違いと、どれを選ぶかが分かります。

各公式ドキュメント・README の記載をもとにした比較です（2026年10月23日時点）。

項目	llama.cpp	Ollama	vLLM	LM Studio
形	C/C++ のエンジンと CLI・サーバー	常駐するアプリと CLI	Python のライブラリとサーバー	デスクトップアプリ
モデルの形式	GGUF	ライブラリから pull。GGUF も取り込める	Hugging Face 形式。GGUF は試験的	GGUF（llama.cpp）・MLX
主に動く場所	CPU・CUDA・Metal・Vulkan・ROCm など	Windows・Mac・Linux	Linux＋GPU	Mac・Windows・Linux
既定のポート	9931（v0.7.0 から）	11434	8000	―
同時の依頼	連続バッチング（既定で有効）	`OLLAMA_NUM_PARALLEL` 既定1	連続バッチング・PagedAttention	―
細かい調整	全部のオプションを直接指定	Modelfile で一部	多くのオプション	画面から設定

Ollama は llama.cpp を土台にした「モデルの管理と常駐サーバー」を足したアプリ、vLLM は GPU のサーバーで多くの依頼を同時にさばくための別の作りのエンジンです。 Ollama の README は「Supported backends」に llama.cpp を挙げています。LM Studio のドキュメントは、GGUF のモデルを llama.cpp で、Apple シリコンでは MLX でも動かすと説明しています。vLLM のドキュメントは、GGUF の対応を「highly experimental and under-optimized」としています。

状況	選ぶもの	理由
コマンド1つで手軽に始めたい	Ollama	モデルの取得と常駐を受け持つ
画面で操作したい	LM Studio・llama.app	GUI でモデルを選べる
オプションを細かく決めたい・最新のモデルを早く試したい	llama.cpp	エンジンそのものを直接使う
VRAM に入らないモデルを CPU と分けて動かしたい	llama.cpp・Ollama	層ごとに CPU と GPU に分けられる
GPU サーバーで多くの人が同時に使う	vLLM	同時の依頼に強い作り
組み込み機器・Android で動かしたい	llama.cpp	依存が少なく、Android 向けの手順がある

どれも OpenAI 互換の API を持つので、アプリ側は base_url を変えるだけで行き来できます。Ollama のコマンドと API は関連記事「Ollamaの使い方｜ローカルLLMのコマンド一覧とAPIの呼び方」、vLLM の仕組みとオプションは関連記事「vLLMとは｜使い方・インストール・OpenAI互換APIとOllamaとの違い」で扱っています。llama-server にブラウザのチャット画面と RAG を足すなら、関連記事「Open WebUIとは｜インストール・使い方・Ollama接続とRAG設定」で扱っています。

llama.cppのよくあるエラーと直し方

この節では、エラーの原文から原因と直し方を引けます。原文はソースの文字列で確かめたものです。

エラー原文	原因	直し方
`error: invalid argument: -cnv`	llama-cli に無い引数（以前の書き方）	llama-cli は引数なしで対話。続きの生成は llama-completion
`failed to open GGUF file '…' (No such file or directory)`	`-m` のパスが違う	パスと拡張子を確かめる
`invalid magic characters: '…', expected 'GGUF'`	GGUF でないファイル	下の「GGUF でないファイル」を参照
`unknown model architecture: '…'`	llama.cpp がそのモデルの種類を知らない	llama.cpp を新しい版にする
`cudaMalloc failed: out of memory`	VRAM が足りない	`-ngl` を減らす・`-c` を小さく・小さい量子化
`warning: no usable GPU found, --gpu-layers option will be ignored`	GPU を使わない版（CPU 版）	CUDA・Vulkan 版を入れるかビルドし直す
`couldn't bind HTTP server socket, hostname: …, port: 9931`	ポートが使われている	`--port` を変えるか、使っているプロセスを止める
`{"code": 401, "message": "Invalid API Key"}`	`--api-key` と違うキー	`Authorization: Bearer キー` を送る
`{"code": 503, "message": "Loading model"}`	モデルを読み込み中	`/health` が 200 になるまで待つ
`request (… tokens) exceeds the available context size (… tokens), try increasing it`	入力がコンテキスト長を超えた	`-c` を大きく・入力を短く
Connection refused（8080）	v0.7.0 から既定が 9931	`:9931` に向けるか `--port 8080`
別のマシンからつながらない	既定は 127.0.0.1 で待ち受け	`--host 0.0.0.0` と `--api-key`

GGUF でないファイルを読んだとき

Hugging Face のファイルのページ（/blob/ の URL）をそのまま保存すると、中身は GGUF ではなく HTML になります。先頭を xxd で見ると違いがすぐ分かります。

$ xxd -l 16 page.html
00000000: 3c21 646f 6374 7970 6520 6874 6d6c 3e0a  <!doctype html>.
$ xxd -l 16 model.gguf
00000000: 4747 5546 0300 0000 0000 0000 0000 0000  GGUF............

ggml/src/gguf.cpp は先頭の4文字を invalid magic characters: '%c%c%c%c', expected 'GGUF' の形で表示するので、HTML なら '<!do' と出ます。gguf-py で同じように GGUF でないファイル（safetensors の形）を開くと ValueError: GGUF magic invalid になりました。ダウンロードには /resolve/ の URL か -hf を使います。

VRAM が足りないとき（out of memory）

1-c を必要な長さにした（131072 だと 8B でも KV キャッシュが 16GiB）

2-ctk q8_0 -ctv q8_0 で KV キャッシュを約半分にした

3-ngl を減らして、入りきらない層を CPU に回した

4MoE のモデルは --cpu-moe・--n-cpu-moe でエキスパートの重みを CPU に置いた

51 段小さい量子化（Q5_K_M → Q4_K_M など）にした

--fit（既定で on）は、指定していない値を入るように調整します。自分で -c や -ngl を指定すると、その値はそのまま使われます。

ポートが使われている

couldn't bind HTTP server socket は、同じポートで別の llama-server や別のアプリが動いているときに出ます。Linux なら ss -tlnp 'sport = :9931'、Mac なら lsof -nP -iTCP:9931 -sTCP:LISTEN で探します。Windows も含めた探し方と止め方は、関連記事「Address already in useの解決方法【Windows・Mac・Linux】」で扱っています。

よくある質問

Q. llama.cppとは簡単に言うと何ですか？ A. 量子化した LLM（GGUF 形式）を、パソコンやサーバーの CPU・GPU で動かすための C/C++ のソフトです。ターミナルの対話（llama-cli）と、OpenAI 互換の API サーバー（llama-server）が付いています。

Q. llama.cppは無料ですか？商用利用できますか？ A. llama.cpp は MIT ライセンスで、無料で使えます。ただし動かすモデルには別のライセンスがあるので、商用で使えるかはモデルカードで確かめます。

Q. GPUがなくても動きますか？ A. 動きます。CPU 版は AVX2・AVX512・Arm NEON などを使って計算します。GPU より遅くなるので、小さいモデルと 4 ビット前後の量子化から試すと、必要なメモリも少なく済みます。

Q. Windowsで使うにはどうしますか？ A. winget install llama.cpp か、GitHub Releases の zip（GPU なしは win-cpu-x64、NVIDIA は win-cuda と cudart の2つ、AMD・Intel は win-vulkan）を展開します。ソースからビルドするなら Visual Studio 2022 と CMake を使います。

Q. Macで使えますか？ A. 使えます。brew install llama.cpp で入り、Apple シリコンでは Metal（GPU）が既定で有効です。README は Apple シリコンを「first-class citizen」としています。

Q. llama-serverのポートは8080ではないのですか？ A. v0.7.0（2026年10月15日のタグ）から既定が 9931 になりました。v0.6.0 までは 8080 です。以前の設定のまま使うときは --port 8080 を付けます。

Q. Ollamaとllama.cppの違いは何ですか？ A. llama.cpp は推論のエンジンとそのツール、Ollama は llama.cpp を土台に、モデルの取得（ollama pull）と常駐サーバー（既定 11434）を足したアプリです。オプションを細かく決めたいときや、新しいモデルを早く試したいときは llama.cpp を直接使います。

Q. llama-cpp-pythonとの違いは何ですか？ A. llama-cpp-python は、llama.cpp を Python から呼ぶための別のプロジェクトのバインディングです（PyPI の最新は 0.3.36、2026年10月1日公開）。pip install llama-cpp-python で入り、GPU 版は CMAKE_ARGS="-DGGML_CUDA=on" を付けてビルドします。llama-server を立てて OpenAI SDK から呼ぶ方法なら、Python 側に追加のライブラリは要りません。

Q. 日本語で使えますか？ A. llama.cpp は UTF-8 の文章をそのまま扱います。日本語の答えの質はモデルで決まるので、日本語に対応したモデル（モデルカードで確認）を選びます。量子化による質の違いは、llama-perplexity で自分の文章を使って比べられます。

Q. どれくらいのメモリが必要ですか？ A. 8B のモデルの Q4_K_M なら重みが 4.58GiB、これに KV キャッシュ（コンテキスト 4096 で約 0.5GiB）と作業領域が加わります。計算式と実行結果は「必要なメモリを計算する」の節にあります。

Q. ダウンロードしたモデルはどこに保存されますか？ A. -hf で取ったモデルは、既定で Hugging Face の共通のキャッシュ（ホームの .cache/huggingface/hub）に入ります。LLAMA_CACHE で変えられ、-cl で一覧を見られます。

Q. Dockerで動かせますか？ A. 公式のイメージ ghcr.io/ggml-org/llama.cpp:server（CPU）・server-cuda・server-vulkan・server-rocm などがあります。docs/docker.md によると、GPU 版のイメージは CI ではビルドだけが確かめられています。

まとめ

llama.cpp は、GGUF 形式の LLM を CPU・GPU で動かす C/C++ の推論エンジン（MIT）。対話は llama-cli、API は llama-server。
入れ方は winget・brew・llama.app・GitHub Releases の配布バイナリ・ソースのビルド（cmake -B build → cmake --build build --config Release）。GPU は -DGGML_CUDA=ON などを足す。
モデルは Hugging Face の GGUF を -hf ユーザー/リポジトリ:量子化 で取る。保存先は Hugging Face の共通のキャッシュ。
llama-server の既定は 127.0.0.1:9931（v0.7.0 から。以前は 8080）。OpenAI SDK は base_url を向けるだけで使え、外に出すなら --host 0.0.0.0 と --api-key。
迷ったら Q4_K_M。8B で 4.58GiB、F16 の約3割。長いコンテキストでは KV キャッシュが重みより大きくなるので、-c と -ctk/-ctv q8_0 で調整する。
GGUF の中にはモデルの設定とトークナイザーが入っていて、1ファイルで動く。先頭は必ず GGUF。
手軽さは Ollama、GPU サーバーで多くの依頼をさばくなら vLLM、細かい調整と幅広い機材は llama.cpp。

参考・出典

確認日はいずれも 2026年10月23日です。

llama.cpp「GitHub リポジトリ（README・b11835 のソース）」：https://github.com/ggml-org/llama.cpp
llama.cpp「Releases」：https://github.com/ggml-org/llama.cpp/releases
llama.cpp「Build llama.cpp locally」（docs/build.md）：https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md
llama.cpp「Install pre-built version of llama.cpp」（docs/install.md）：https://github.com/ggml-org/llama.cpp/blob/master/docs/install.md
llama.cpp「Docker」（docs/docker.md）：https://github.com/ggml-org/llama.cpp/blob/master/docs/docker.md
llama.cpp「Release process」（docs/release.md）：https://github.com/ggml-org/llama.cpp/blob/master/docs/release.md
llama.cpp「LLaMA.cpp HTTP Server」（tools/server/README.md）：https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md
llama.cpp「llama.cpp/tools/cli」（tools/cli/README.md）：https://github.com/ggml-org/llama.cpp/blob/master/tools/cli/README.md
llama.cpp「quantize」（tools/quantize/README.md）：https://github.com/ggml-org/llama.cpp/blob/master/tools/quantize/README.md
llama.cpp「gguf-py」：https://github.com/ggml-org/llama.cpp/tree/master/gguf-py
Llama（llama.app）：https://llama.app
Hugging Face「GGUF」：https://huggingface.co/docs/hub/gguf
Hugging Face「Models（library=gguf）」：https://huggingface.co/models?library=gguf
Ollama「FAQ」：https://docs.ollama.com/faq
vLLM ドキュメント「GGUF」：https://docs.vllm.ai/en/stable/features/quantization/gguf/
LM Studio「Docs」：https://lmstudio.ai/docs/app
PyPI「llama-cpp-python」：https://pypi.org/project/llama-cpp-python/