> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# llama.cpp を速度とメモリの観点で最適化する

> llama.cpp のパフォーマンスを最大化するためのチューニングです。flash attention、mmap と mlock の比較、スレッドの調整、GPU オフロード戦略、バッチサイズ、KV キャッシュの精度、MoE エキスパートの配置を解説します。

llama.cppは最もポータブルなローカル推論ランタイムだ。CPU、NVIDIA GPU、AMD GPU、Apple Siliconで動作し、多くの場合同じバイナリから実行できる。その柔軟性は長いフラグリストと引き換えであり、デフォルトがあなたのハードウェアに最適とは限らない。このガイドでは最も重要なフラグと、それぞれのトレードオフを解説する。

> [!NOTE]
>
> Last verified: 2026-10-14 — llama.cpp build b11609.

> [!NOTE]
>
> このガイドのフラグは、llama.cppビルド`llama-server`および`llama-cli`（ビルド**b11609**、14 October 2026）に適用される。フラグ名はビルド間で変更される可能性がある — `llama-server --help`を実行して、あなたのバイナリがサポートするものを確認してほしい。

## Flash attention

Flash attentionの有効化には`-fa`または`--flash-attn on`を使用する。ほとんどのベンチマークで、これはllama.cppが提供するほぼフリーのパフォーマンス向上だ — 同じまたはより少ないメモリ使用量で高速な推論が得られ、品質への影響は無視できる。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf -fa
```

Flash attentionはトークン間のアテンションスコアの計算方法を見直す。完全なアテンション行列をメモリに展開する代わりに、高速なSRAMに収まるタイル状のチャンクでアテンションを計算する。結果は以下の通りだ：

* **KVキャッシュの低いメモリ使用量** — ロングコンテキスト長で最大の効果がある。
* **高速な推論** — 特にGPU上で効果的であり、タイル計算がテンソルコアにうまくマッピングされる。
* **同じ出力品質** — flash attentionは標準アテンションと数学的に等価であり、近似ではない。

> [!TIP]
>
> **常に`-fa`から始めるべきだ。** 特定のモデルやプラットフォームで互換性の問題に遭遇しない限り、オフにする理由はない。このガイドで最も影響の大きいフラグだ。

## mmap vs mlock

llama.cppは2つの戦略のいずれかでモデルウェイトをメモリにロードする。デフォルトは`--mmap`で、モデルファイルをプロセスの仮想アドレス空間に直接マップする。代替は`--mlock`で、モデル全体を物理RAMにピン留めする。

| Flag | What it does | Best for |
| - | - | - |
| `--mmap` (default) | Maps the file; the OS pages data in and out as needed | One-shot runs, memory-constrained machines, quick experiments |
| `--mlock` | Pins every byte in physical RAM; nothing pages out | Repeated inference, dedicated inference servers, models you run all day |

### mmapが優れる場面

`--mmap`がデフォルトなのは、ほとんどのインタラクティブな使用でうまく動作するからだ。OSは要求に応じてモデルページをロードするため、起動が速く、モデルファイルが実際にページに触れられるまでRAMに対して二重カウントされない。モデルのテストや短いセッションの実行であれば、デフォルトで問題ない。

### mlockが優れる場面

`--mlock`はOSがモデルページをスワップに追い出すのを防ぐ。以下の場合に重要だ：

* 同じモデルを終日実行し、一貫したレイテンシを望む場合 — ページフォルトによるコールドスタートペナルティがない。
* システムが他のプロセスからのメモリ圧迫下にあり、モデルウェイトがページアウトされる可能性がある場合。
* スワップが遅い（またはスワップがない）マシンを使用しており、ページフォルトが推論を数秒間停止させる可能性がある場合。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf -fa --mlock
```

> [!WARNING]
>
> `--mlock`はモデル全体が利用可能な物理RAMに収まることを要求する。収まらない場合、プロセスの起動に失敗する。有効化する前に、Linuxでは`free -h`で、macOSではActivity Monitorで利用可能なメモリを確認してほしい。

## スレッドチューニング

推論スレッド数の設定には`-t`フラグを使用する。適切な値はCPUが実際にどのくらいの作業を行うかに依存する。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf -t 8
```

| Scenario | Thread guidance |
| - | - |
| Full GPU offload (all layers on GPU) | `-t 2` to `-t 4` — the CPU handles orchestration and tokenization, not math |
| Partial GPU offload (some layers on CPU) | Set `-t` to the number of physical cores on your CPU — not hyperthreads |
| CPU-only (no GPU) | Set `-t` to the number of physical cores |

> [!TIP]
>
> スレッド数は多ければ多いほど速いわけではない。物理コア数を超えると、スレッドがキャッシュとメモリバンド幅を競合し、推論が遅くなる可能性がある。迷った場合は物理コア数から始めてベンチマークを取ってほしい。

Apple Siliconでは、GPUとCPUが統一メモリを共有し、Metalバックエンドがスケジューリングを処理するため、スレッドチューニングの影響は小さい。デフォルトは通常うまく動作する。

## GPUオフロード戦略

GPUオフロードには`-ngl`フラグを使用する。GPU上のレイヤーが多いほど推論は速くなるが、各レイヤーがVRAMを消費する。

### パーシャルオフロード

オフロード数の設定には`-ngl`をGPUメモリに収まるレイヤー数に設定する。残りのレイヤーはCPU上で実行される。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf -ngl 20 -fa
```

モデル全体がVRAMに収まらない場合はパーシャルオフロードを使用する。高い値から始めて、サーバーがメモリ不足なしで起動するまで減らしていく。

### フルオフロード

全レイヤーのオフロードには`-ngl 999`を設定する。llama.cppは999を「残りのすべてのレイヤー」として扱う — 文字通り999レイヤーをオフロードしようとするわけではない。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf -ngl 999 -fa
```

フルオフロードはすべてのフォワードパスがGPU上で実行されるため、最良の推論速度を提供する。モデルウェイトとKVキャッシュの両方がVRAMに収まる必要がある。

### レイヤーごとのメモリ見積もり

オフロードされた各レイヤーはウェイトとKVキャッシュの両方のためにVRAMを消費する。大まかな見積もり：

```
VRAM per layer ≈ (parameter_count_per_layer × bytes_per_weight) + KV_cache_per_layer
```

7Bモデル（Q4\_K\_M、ウェイトあたり約4.5ビット、約40レイヤー）の場合：

| Component | Per layer | 40 layers total |
| - | - | - |
| Weights | \~0.15 GB | \~6 GB |
| KV cache (f16, 4K ctx) | \~0.05 GB | \~2 GB |
| **Total** | | **\~8 GB** |

CUDAコンテキストとオーバーヘッドのために1-2 GBのVRAMヘッドルームを残すこと。

## バッチサイズチューニング

プリフィルフェーズでllama.cppが一度に処理するトークン数を制御するフラグがある。

| Flag | What it controls |
| - | - |
| `-b` (batch size) | Total tokens processed in one batch during prompt ingestion |
| `-ub` (UBatch size) | Maximum tokens per micro-batch within a single batch |

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf -b 512 -ub 512 -fa
```

### 相互作用

* **`-b`** は外側の制限を設定する。プロンプトのトークン数が`-b`を超える場合、llama.cppは複数のバッチに分割する。
* **`-ub`** は内側のチャンクサイズを設定する。llama.cppはバッチを最大`-ub`トークンのマイクロバッチで処理する。
* `-ub`は`-b`以下でなければならない。

### トレードオフ

| Setting | Effect |
| - | - |
| Larger `-b` (512-2048) | Faster prefill for long prompts — more tokens processed per forward pass |
| Larger `-b` | More VRAM/RAM consumed during prompt ingestion |
| Smaller `-b` (128-256) | Lower memory usage, slower prefill |
| `-ub` equal to `-b` | Simplest configuration; one micro-batch covers the full batch |
| `-ub` smaller than `-b` | Caps per-micro-batch memory; useful when `-b` is large but VRAM is tight |

> [!TIP]
>
> 短いプロンプト（1Kトークン未満）のインタラクティブチャットの場合、デフォルトの`-b 512`で問題ない。長いドキュメントを定期的に読み込み、time-to-first-tokenを高速化したい場合にのみ増加させること。

## KVキャッシュ精度

KVキャッシュはすべてのアクティブなシーケンスの各トークンのキーテンソルとバリューテンソルを格納する。デフォルトでは、llama.cppはキーとバリューの両方にf16（16ビット浮動小数点）を使用する。量子化精度に切り替えることで、わずかな品質コストでメモリ使用量を削減できる。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf -fa \
  --cache-type-k q8_0 --cache-type-v q8_0
```

| Precision | Memory per element | Quality | When to use |
| - | - | - | - |
| `f16` (default) | 2 bytes | Baseline | Maximum quality; you have plenty of memory |
| `q8_0` | 1 byte | Near-identical to f16 | Best balance — halves KV cache memory with negligible quality loss |
| `q4_0` | 0.5 bytes | Slight degradation | Tight memory; long context or many concurrent sequences |

キーとバリューは独立して設定できる。一般的なパターンは両方に`q8_0`を使用することで、ほとんどのベンチマークで1%未満の品質差でKVキャッシュフットプリントを半減する。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Aggressive: quarter the KV cache memory
llama-server -m model.gguf -fa \
  --cache-type-k q4_0 --cache-type-v q4_0
```

> [!WARNING]
>
> `q4_0`KVキャッシュはロングコンテキストにわたる正確なアテンションに依存するタスク — ニードルインヘイスタック検索、マルチドキュメント要約、長い会話 — で測定可能な品質低下を引き起こす。`q4_0`にコミットする前に、特定のワークロードをテストしてほしい。

## MoE最適化

Qwen3.5-35B-A3BやMixtralのようなMixture-of-expertsモデルは各レイヤーに多数のエキスパートサブネットワークを格納するが、トークンごとに少数のみをアクティブにする。エキスパートウェイトは非アクティブ時でもメモリ上に残るため、MoEモデルはアクティブパラメータ数の割に不釣り合いに大きい。

マルチGPUシステムでは、GPUメモリが逼迫している場合、エキスパートレイヤーをCPUに配置できる。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf -ngl 999 --n-cpu-moe 4 -fa
```

`--n-cpu-moe <num>`は指定された数のエキスパートサブレイヤーをCPU上に保持し、モデルの残りはGPU上で実行する。これはわずかなレイテンシ増加と引き換えに、より大きなモデルをVRAMに収める。

| Scenario | Configuration |
| - | - |
| MoE fits entirely in VRAM | `-ngl 999` — no CPU experts needed |
| MoE almost fits, a few experts overflow | `--n-cpu-moe 2` to `--n-cpu-moe 8` |
| MoE is too large for any reasonable GPU setup | Combine `--n-cpu-moe` with partial `-ngl` |

> [!TIP]
>
> 開始には`--n-cpu-moe 0`（すべてのエキスパートをGPU上）を使用し、VRAMが不足した場合にのみ増加させること。CPUに移動された各エキスパートはフォワードパス中にデータをPCIeバス経由で渡す必要があるため、レイテンシが追加される。

## 設定例

### Apple Silicon — MシリーズMacに最適化

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf \
  -fa \
  --mlock \
  -b 512 \
  -ub 512 \
  --cache-type-k q8_0 \
  --cache-type-v q8_0 \
  -ngl 999 \
  --port 8080
```

これはモデルを統一メモリにピン留めし、flash attentionを有効化し、KVキャッシュを量子化してメモリ予算を最大化する。Apple Siliconの統一メモリはGPUが全RAMプールにアクセスできるため、モデルとKVキャッシュが収まる限りフルオフロード（`-ngl 999`）が機能する。

> [!NOTE]
>
> llama.cppはApple Siliconでうまく動作するが、Mac専用のデプロイの場合は[MLX](https://github.com/ml-explore/mlx)がAppleのMetalバックエンドに最適化されており、同じモデルでもより高速な推論を提供できる。クロスプラットフォームのポータビリティやOpenAI互換サーバーが必要な場合はllama.cppを使用すること。

### GPUオフロード — NVIDIAまたはAMDディスクリートGPU

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf \
  -fa \
  -ngl 999 \
  -b 512 \
  -ub 512 \
  --cache-type-k q8_0 \
  --cache-type-v q8_0 \
  -t 4 \
  --port 8080
```

Flash attentionと量子化KVキャッシュによるフルGPUオフロード。4つのCPUスレッドがオーケストレーションとトークン化を処理する。モデルが収まらない場合は`-ngl`を減らすこと — 総レイヤー数から始めて5ずつ減らしてロードされるか確認する。

### CPUのみ — GPUなし

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
llama-server -m model.gguf \
  -t 8 \
  -b 256 \
  -ub 256 \
  --cache-type-k q8_0 \
  --cache-type-v q8_0 \
  --port 8080
```

GPUオフロードなしのため、CPUがすべての作業を行う。スレッド数は物理コア数に一致させる。小さいバッチサイズがメモリ使用量を抑える。モデルウェイトにはQ4\_K\_MまたはQ5\_K\_M量子化を使用してフットプリントを小さく保つこと。

## 次のステップ

> **[llama.cpp remote access](/ja/guides/llama-cpp-remote-access.md)**
>
> Expose your llama.cpp server to teammates and agents through Tokios — without opening ports.

> **[Speculative decoding](/ja/guides/speculative-decoding.md)**
>
> Speed up decode with draft models, n-grams, and EAGLE — works with llama.cpp backends.

> **[Test your deployment](/ja/guides/benchmark-your-deployment.md)**
>
> Measure latency and throughput after tuning to confirm the improvement.

> **[KV cache and context](/ja/concepts/kv-cache-and-context.md)**
>
> Deeper explanation of how KV cache works across model architectures and runtimes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.