> ## 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-.

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

> Ollama の速度を最大化するためのチューニングです。コンテキストウィンドウ、GPU オフロード、flash attention、KV キャッシュの量子化、並列リクエストを解説します。これらの設定でレイテンシを 2-5x 削減できます。

Ollamaはローカルモデルを最も速く起動する方法だ — `ollama run llama3`でサービングを開始できる。内部ではllama.cpp（およびApple SiliconではMLX）をラップし、ハードウェアの使用方法を制御する環境変数とモデルパラメータを公開している。デフォルトはカジュアルな使用には機能するが、重要なパフォーマンスを逃している。このガイドでは重要なすべての設定項目と、ワークロードに応じた設定方法を解説する。

> [!NOTE]
>
> Last verified: 2026-10-14 — Ollama v0.33.2.

> [!NOTE]
>
> **Apple SiliconはMLXを使用する。** Ollama 0.19以降、Apple Siliconのデフォルトバックエンドはllama.cppではなくAppleのMLXフレームワークだ。MLXはMシリーズチップで大幅に高速な推論を提供する（[Apple SiliconとMLXの最適化](#apple-silicon-and-mlx-optimization)を参照）。このガイドのほとんどの環境変数は両方のバックエンドに適用される。動作が異なる場合は明示的に説明する。

## コンテキストウィンドウのチューニング

コンテキストウィンドウ（`num_ctx`）は単一リクエストでモデルが処理できるトークン数を制御する — プロンプトと生成されるレスポンスの合計だ。モデルウェイト自体に次ぐメモリ使用量の最大のドライバーだ。

### Ollamaのコンテキストウィンドウを増やす方法

Ollamaのデフォルトは2048トークンのコンテキストウィンドウだ。ほとんどの最新モデルは8K、32K、または128Kトークンをサポートするが、Ollamaはデフォルトでモデルの最大値を使用しない — メモリ使用量を抑えるために2048を使用する。

3つの方法で設定できる。最も具体的なものから最もグローバルなものまで：

**リクエストごと（API）：**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [{"role": "user", "content": "Summarize this document..."}],
    "options": {
      "num_ctx": 32768
    }
  }'
```

**Modelfile内（モデルごとの永続設定）：**

```dockerfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3
PARAMETER num_ctx 32768
```

次にカスタムモデルをビルドして実行する：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
ollama create llama3-32k -f Modelfile
ollama run llama3-32k
```

**グローバル（全モデル、全リクエスト）：**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Linux (systemd)
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_CONTEXT_LENGTH=32768"
sudo systemctl daemon-reload && systemctl restart ollama
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
[System.Environment]::SetEnvironmentVariable("OLLAMA_CONTEXT_LENGTH", "32768", "User")
# Restart Ollama
```

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
launchctl setenv OLLAMA_CONTEXT_LENGTH 32768
# Restart Ollama
```

### コンテキストウィンドウのメモリコスト

KVキャッシュはコンテキスト長に比例して増加する。計算式：

```
KV cache memory = 2 × num_layers × hidden_dim × num_ctx × precision_bytes
```

7Bモデル（32レイヤー、4096 hidden dimension）のf16精度の場合：

| Context length | KV cache memory |
| - | - |
| 2,048 (default) | \~1 GB |
| 8,192 | \~4 GB |
| 32,768 | \~16 GB |
| 128,000 | \~64 GB |

> [!TIP]
>
> 設定は`num_ctx`をワークロードが実際に必要とする値だけにすべきだ。2Kプロンプトを送信するコーディングエージェントは128Kコンテキストウィンドウから利益を得ない — 他のリクエストをサービスするかより大きなモデルを収めるために使用できた64 GBのKVキャッシュスペースを無駄にするだけだ。

## Flash attention

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

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

### Ollamaでflash attentionを有効にする方法

環境変数を設定する：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Linux (systemd)
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_FLASH_ATTENTION=1"
sudo systemctl daemon-reload && systemctl restart ollama
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
[System.Environment]::SetEnvironmentVariable("OLLAMA_FLASH_ATTENTION", "1", "User")
# Restart Ollama
```

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
launchctl setenv OLLAMA_FLASH_ATTENTION 1
# Restart Ollama
```

> [!TIP]
>
> **常にflash attentionを有効にすること。** 特定のモデルやプラットフォームで互換性の問題に遭遇しない限り、オフにする理由はない。このガイドで最も影響の大きい設定だ。

> [!NOTE]
>
> MLXバックエンドを使用するApple Siliconでは、flash attentionはデフォルトで有効化されており、`OLLAMA_FLASH_ATTENTION`変数は効果を持たない — MLXは常に最適化されたアテンションカーネルを使用する。

## GPUオフロード戦略

OllamaはモデルレイヤーをGPUに自動的にオフロードする。モデル全体がVRAMに収まる場合、すべてのレイヤーが最大速度でGPU上で実行される。VRAMが逼迫している場合、OllamaはレイヤーをGPUとCPUに分割する — GPUが可能な限りを実行し、残りはシステムRAMにフォールバックする。

### OllamaがGPUレイヤーを決定する方法

OllamaのGPUスケジューリングは以下の順序で動作する：

1. **フルオフロード** — モデルウェイト + KVキャッシュがVRAMに収まる場合、すべてのレイヤーがGPUに送られる。これが最速の設定だ。
2. **パーシャルオフロード** — モデル全体が収まらない場合、OllamaはVRAMが許す限りのレイヤーをGPUに配置し、残りをCPUで実行する。CPU常駐レイヤーのために各フォワードパスがPCIeバスを渡る必要があるため、パフォーマンスが低下する。
3. **CPUのみ** — GPUが利用できないか、VRAMが数レイヤーすら収めるには小さすぎる場合、モデル全体がCPU上で実行される。

### GPUレイヤーの制御: `num_gpu`

GPUオフロードの`num_gpu`パラメータはGPUにオフロードするレイヤー数を設定する。Modelfileまたはリクエストごとに設定する：

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3
PARAMETER num_gpu 35
```

```bash API theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [{"role": "user", "content": "Hello"}],
    "options": {
      "num_gpu": 35
    }
  }'
```

| `num_gpu` value | Behavior |
| - | - |
| `-1` | All layers on GPU (same as setting it to the total layer count) |
| `0` | No GPU offload — CPU only |
| `1` to `N` | Exactly that many layers on GPU, rest on CPU |
| Not set (default) | Ollama auto-detects based on available VRAM |

> [!TIP]
>
> ほとんどの場合、`num_gpu`は未設定のままOllamaに自動検出させること。特定の分割を強制する必要がある場合にのみ手動で設定する — 例えば、より大きなコンテキストウィンドウのためにVRAMを確保する場合や、ぎりぎりで収まるモデルの一部のレイヤーをCPUに保持する場合。

### VRAM見積もり

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

```
VRAM per layer ≈ (parameters_per_layer × bytes_per_weight) + (KV_cache_per_layer × num_ctx)
```

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

| Component | Per layer | 32 layers total |
| - | - | - |
| Weights | \~0.19 GB | \~6 GB |
| KV cache (f16, 8K ctx) | \~0.13 GB | \~4 GB |
| **Total** | | **\~10 GB** |

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

> [!WARNING]
>
> 警告：`num_ctx`を増加させると、KVキャッシュが成長してレイヤーがVRAMから追い出される可能性がある。`num_ctx 32768`を設定した後にOllamaが突然レイヤーの半分をCPUにオフロードし始めた場合、KVキャッシュがVRAM予算を消費したことになる。`num_ctx`を減らすか、小さい量子化を使用するか、flash attentionを有効化してKVキャッシュを縮小すること。

## KVキャッシュ精度

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

キャッシュタイプは`OLLAMA_KV_CACHE_TYPE`環境変数で設定する：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Linux (systemd)
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_KV_CACHE_TYPE=q8_0"
sudo systemctl daemon-reload && systemctl restart ollama
```

| Cache type | 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 |

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Halve KV cache memory
OLLAMA_KV_CACHE_TYPE=q8_0

# Quarter KV cache memory
OLLAMA_KV_CACHE_TYPE=q4_0
```

> [!TIP]
>
> 組み合わせると最大：`OLLAMA_KV_CACHE_TYPE=q8_0`と`OLLAMA_FLASH_ATTENTION=1`を共に設定すること。Flash attentionはKVキャッシュフットプリントを30-50%削減し、q8\_0がさらに半減する — 組み合わせるとデフォルトと比較してKVキャッシュメモリを60-75%削減できる。

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

## スレッド設定

CPUスレッド数の`num_thread`パラメータはOllamaが推論に使用するCPUスレッド数を制御する。適切な値はCPUが実際にどのくらいの作業を行うかに依存する。

Modelfileまたはリクエストごとに設定する：

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3
PARAMETER num_thread 8
```

```bash API theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3",
    "messages": [{"role": "user", "content": "Hello"}],
    "options": {
      "num_thread": 8
    }
  }'
```

グローバル設定は`OLLAMA_NUM_THREADS`でグローバルに設定することもできる：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Linux (systemd)
sudo systemctl edit ollama.service
# Add: Environment="OLLAMA_NUM_THREADS=8"
sudo systemctl daemon-reload && systemctl restart ollama
```

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

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

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

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

バッチサイズの`num_batch`パラメータはOllamaがプリフィルフェーズ（プロンプト読み込み）で一度に処理するトークン数を制御する。デフォルトは512だ。

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3
PARAMETER num_batch 1024
```

| Setting | Effect |
| - | - |
| `num_batch 512` (default) | Balanced for interactive chat with short prompts |
| `num_batch 1024` | Faster prefill for long prompts — roughly 50-100% faster time-to-first-token |
| `num_batch 2048` | Maximum throughput for document ingestion — up to 150% faster prefill |
| `num_batch 2048+` | Diminishing returns; higher memory usage without proportional speed gains |

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

> [!WARNING]
>
> 大きなバッチサイズはプロンプト読み込み中にVRAMをより多く消費する。`num_batch`を増加させてメモリ不足エラーに遭遇した場合は、減らすか`num_ctx`を下げること。

## 並列リクエスト

`OLLAMA_NUM_PARALLEL`は単一のモデルが同時に処理するリクエスト数を制御する。デフォルトは1だ。Ollamaはロード済みモデルごとに同時に単一のリクエストを処理する。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Allow 4 parallel requests per model
OLLAMA_NUM_PARALLEL=4
```

| Value | Behavior |
| - | - |
| `1` (default) | One request at a time — lowest latency per request |
| `2` to `4` | Multiple requests share the GPU — higher throughput, slightly higher per-request latency |
| `8+` | Maximum throughput for batch workloads — requires significant VRAM for KV cache |

> [!NOTE]
>
> RAMとVRAMは`OLLAMA_NUM_PARALLEL`に比例して増加する。各並列リクエストは独自のKVキャッシュを必要とする。`num_ctx 8192`で4つの並列リクエストをサービスする場合、単一リクエストの4倍のKVキャッシュメモリが必要だ。

### 並列リクエストを増やすべき場合

以下の場合に`OLLAMA_NUM_PARALLEL`を増加させる：

* 同じモデルから複数のユーザーやエージェントにサービスする場合。
* 個別リクエストのレイテンシより全体のスループットが重要なバッチワークロードを実行する場合。
* VRAMに余裕があり、単一リクエストではGPUが十分に活用されていない場合。

以下の場合には1のままにする：

* 単一のユーザーやエージェントにサービスする場合。
* スループットより低レイテンシを優先する場合。
* VRAMが逼迫している場合。

## モデルメモリ管理

### モデルのロード状態保持: `OLLAMA_KEEP_ALIVE`

デフォルトでは、Ollamaは5分間非アクティブになるとメモリからモデルをアンロードする。次のリクエストはディスクからモデルを再ロードする必要があり、モデルサイズとディスク速度に応じて数秒から数分かかる。

ロード状態の制御は`OLLAMA_KEEP_ALIVE`を設定してモデルのロード状態を制御する：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Keep models loaded indefinitely
OLLAMA_KEEP_ALIVE=-1

# Keep models loaded for 1 hour
OLLAMA_KEEP_ALIVE=1h

# Unload models immediately after each request
OLLAMA_KEEP_ALIVE=0
```

| Value | Behavior |
| - | - |
| `5m` (default) | Unload after 5 minutes of inactivity |
| `-1` | Keep loaded indefinitely — no reload penalty |
| `0` | Unload immediately after each request |
| Duration (`1h`, `30m`, `24h`) | Keep loaded for that duration after the last request |

> [!TIP]
>
> 終日同じモデルを実行する専用推論サーバーの場合、`OLLAMA_KEEP_ALIVE=-1`を設定すること。モデルがメモリに保持され、すべてのリクエストがコールドスタートペナルティなしで即座に応答する。

### ロード済みモデル数の制限: `OLLAMA_MAX_LOADED_MODELS`

Ollamaは複数のモデルを同時にロード状態に保てる。デフォルトは3 ×（GPU数）またはCPUのみの場合は3だ。多数のモデルをサービスし、メモリ使用量を制限したい場合は下げる：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Only keep 1 model loaded at a time
OLLAMA_MAX_LOADED_MODELS=1
```

制限に達した状態で新しいモデルがリクエストされると、Ollamaは最も最近使用されていないモデルをアンロードして空きを作る。

## Apple SiliconとMLXの最適化

Ollama 0.19以降、Apple SiliconのデフォルトバックエンドはAppleのMLXフレームワークだ。MLXはAppleの統一メモリアーキテクチャに最適化されており、Mシリーズチップでllama.cppよりも大幅に高速な推論を提供する。

### パフォーマンス向上

Ollamaの2026年MLX最適化アップデートからのベンチマーク：

| Model | Quantization | Tokens/sec (MLX) |
| - | - | - |
| Gemma 4 12B | NVFP4 | \~55 tok/s |
| Gemma 4 12B | Q4\_K\_M | \~46 tok/s |
| Llama 3.1 8B | Q4\_K\_M | \~70-80 tok/s |

MLXはApple SiliconでNVFP4量子化もサポートし、BF16に近い品質を4ビットメモリフットプリントで実現し、Q4量子化の半分の品質劣化となる。

### Apple Silicon最適化のヒント

1. **MLX最適化モデルを使用する。** Apple Siliconでモデルをプルすると、Ollamaは自動的にMLXバックエンドを使用する。設定は不要。
2. **Flash attentionは常にオン。** MLXはデフォルトで最適化されたアテンションカーネルを使用する。`OLLAMA_FLASH_ATTENTION`変数は効果を持たない。
3. **統一メモリによりフルGPUオフロード。** Apple SiliconのGPUは全RAMプールにアクセスできるため、`-ngl 999`（すべてのレイヤーをGPUに）がモデルとKVキャッシュが統一メモリに収まる限り機能する。
4. **使用には`OLLAMA_KV_CACHE_TYPE=q8_0`** でメモリ予算を最大化する。KVキャッシュを半減することで、より大きなモデルやより長いコンテキストを実行できる。
5. **設定には`OLLAMA_KEEP_ALIVE=-1`** を使用して常時稼働の推論を実現する。モデルは統一メモリに保持され、リロードペナルティなし。

> [!NOTE]
>
> クロスプラットフォームのポータビリティが必要か、NVIDIA GPUとMacで同じ設定を実行したい場合は、Apple Siliconでllama.cppバックエンドを使用するようOllamaを強制できる。バックエンド選択をオーバーライドする環境変数については、Ollamaサポートに問い合わせるかドキュメントを確認してほしい。

## 設定例

### Mac Studio M2 Ultra — 128 GB統一メモリ

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=4
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:70b-q4_K_M
PARAMETER num_ctx 32768
PARAMETER num_batch 1024
```

この設定は70B Q4モデルを32Kコンテキストウィンドウで実行する。128 GBの統一メモリプールは約40 GBのモデルウェイト、約16 GBのKVキャッシュ（q8\_0）を処理し、4つの並列リクエストのヘッドルームを残す。MLXはApple Siliconで最大のスループットを提供する。

### NVIDIA RTX 4090 — 24 GB VRAM

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=2
OLLAMA_NUM_THREADS=4
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:8b-q4_K_M
PARAMETER num_ctx 16384
PARAMETER num_batch 1024
```

この設定は8B Q4モデルを16Kコンテキストウィンドウで実行する。24 GBのVRAMは約5 GBのモデルウェイト、flash attention付きの約4 GBのKVキャッシュ（q8\_0）を処理し、2つの並列リクエストのヘッドルームを残す。4つのCPUスレッドがオーケストレーションとトークン化を処理する。

### マルチGPUサーバー — 4× RTX 4090（合計96 GB VRAM）

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=8
OLLAMA_NUM_THREADS=8
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:70b-q4_K_M
PARAMETER num_ctx 8192
PARAMETER num_batch 2048
```

この設定は70B Q4モデルを4つのGPUで実行する。Ollamaは利用可能なすべてのGPUにレイヤーを自動的に分散する。合計96 GBのVRAMは約40 GBのモデルウェイト、約16 GBのKVキャッシュを処理し、8つの並列リクエストのヘッドルームを残す。大きなバッチサイズがバッチワークロードのスループットを最大化する。

### CPU専用サーバー — 64 GB RAM、GPUなし

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=1
OLLAMA_NUM_THREADS=16
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:8b-q4_K_M
PARAMETER num_ctx 8192
PARAMETER num_batch 512
PARAMETER num_gpu 0
```

この設定は8B Q4モデルを完全にCPU上で実行する。16スレッドが物理コア数に一致する。小さいバッチサイズと単一の並列リクエストがメモリ使用量を抑える。5-10 tok/sが期待できる — インタラクティブチャットには使用可能だが、バッチワークロードには不向き。

### 高スループットバッチ処理 — RTX 4090

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q4_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=8
OLLAMA_NUM_THREADS=4
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:8b-q4_K_M
PARAMETER num_ctx 4096
PARAMETER num_batch 2048
```

この設定はオフラインバッチワークロードのスループットを最大化する。q4\_0 KVキャッシュがメモリ使用量を大きく削減し、8つの並列リクエストを24 GBのVRAMで可能にする。大きなバッチサイズがプロンプト読み込みを高速化する。短い4KコンテキストがKVキャッシュを小さく保つ。全並列リクエストで合計200-300トークン/秒が期待できる。

### 低レイテンシインタラクティブサービング — RTX 4090

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Environment variables
OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=1
OLLAMA_NUM_THREADS=4
```

```dockerfile Modelfile theme={"theme":{"light":"github-light","dark":"css-variables"}}
FROM llama3.1:8b-q4_K_M
PARAMETER num_ctx 8192
PARAMETER num_batch 512
```

この設定はインタラクティブチャットのレイテンシを最小化する。単一の並列リクエスト、品質のためのq8\_0 KVキャッシュ、適度なバッチサイズ。500ms以下のtime-to-first-tokenと50-70 tok/sのデコード速度が期待できる。

## よくある間違いと回避方法

### 間違い1：num\_ctxを高く設定しすぎる

**問題：** 「念のため」`num_ctx 128000`を設定したが、プロンプトは2Kトークン未満。64 GBのKVキャッシュメモリを無駄にした。

**修正：** 実際のワークロードに合わせて`num_ctx`を設定すること。プロンプトが4Kトークン未満なら、`num_ctx 4096`または`num_ctx 8192`を使用する。後でAPIを通じて特定のリクエスト用に増やすことができる。

### 間違い2：flash attentionを忘れる

**問題：** flash attentionが有効になっていないため、必要より30-50%多いVRAMを使用している。

**修正：** 常に`OLLAMA_FLASH_ATTENTION=1`を設定すること。サポートされたハードウェアでデメリットはない。

### 間違い3：モデルのアンロードを制御しない

**問題：** 10分の休憩後にリクエストを再開すると、Ollamaがディスクからモデルを再ロードしたため最初のリクエストに30秒かかる。

**修正：** 常時稼働の推論には`OLLAMA_KEEP_ALIVE=-1`を設定すること。モデルがメモリに保持され、すべてのリクエストが即座に応答する。

### 間違い4：GPU上でスレッドを使いすぎる

**問題：** 32スレッドのCPUで`num_thread 32`を設定したが、すべてのレイヤーがGPU上にある。余分なスレッドがキャッシュを競合し、オーケストレーションを遅くする。

**修正：** すべてのレイヤーがGPU上にある場合、`num_thread 2`から`num_thread 4`を使用すること。CPUは推論の計算ではなくオーケストレーションとトークン化のみを処理する。

### 間違い5：KVキャッシュ精度を無視する

**問題：** VRAMが不足しOllamaがレイヤーをCPUにオフロードしているが、KVキャッシュが必要の2倍のメモリを使用していることを考慮していない。

**修正：** `OLLAMA_KV_CACHE_TYPE=q8_0`を設定してKVキャッシュメモリを半減すること。品質とメモリ節約の最適なバランスだ。

### 間違い6：OLLAMA\_NUM\_PARALLELを高く設定しすぎる

**問題：** 24 GBのGPUで`OLLAMA_NUM_PARALLEL=16`を設定し、各リクエストのKVキャッシュが1.5 GBしかない。リクエストが失敗するか品質が低下する。

**修正：** KVキャッシュ予算を計算する：`(VRAM - model_weights) / num_parallel`。これがリクエストあたり1 GB未満になる場合は、`num_parallel`を減らすか`num_ctx`を下げること。

## トラブルシューティング

### 起動後にOllamaが遅い

**原因：** モデルがアンロードされており、ディスクから再ロードする必要があった。

**修正：** `OLLAMA_KEEP_ALIVE=-1`を設定してモデルを無期限にロード状態に保つこと。

### メモリ不足エラー

**原因：** モデル + KVキャッシュが利用可能なVRAMまたはRAMを超えている。

**修正：** `num_ctx`を減らす、`OLLAMA_FLASH_ATTENTION=1`を有効化する、`OLLAMA_KV_CACHE_TYPE=q8_0`を設定する、または小さい量子化を使用すること。

### GPUが使用されていない

**原因：** OllamaがGPUを検出しなかったか、VRAMが数レイヤーすら収めるには小さすぎる。

**修正：** `ollama ps`でレイヤーがGPU上にあるか確認すること。NVIDIA GPUの場合、NVIDIAドライバーとCUDAツールキットがインストールされていることを確認すること。AMD GPUの場合、ROCmがインストールされていることを確認すること。

### 遅いCPU推論

**原因：** スレッド数が多すぎる、またはレイヤーがGPUとCPUに分割されている。

**修正：** `num_thread`を物理コア数に設定すること。可能であれば、`num_gpu`でより多くのレイヤーをGPUにオフロードすること。小さい量子化（Q4\_K\_MまたはQ5\_K\_M）を使用してより多くのレイヤーをGPUに収めること。

## 次のステップ

> **[Ollama remote access](/ja/guides/ollama-remote-access.md)**
>
> Expose your Ollama model to teammates and agents through Tokios — without opening ports or setting OLLAMA\_HOST=0.0.0.0.

> **[Hardware reference](/ja/guides/hardware-reference.md)**
>
> Compare hardware platforms for local LLM inference — specs, model capacity, and recommendations.

> **[Model fit finder](/ja/guides/model-fit.md)**
>
> Find which models run on your hardware, or which hardware can run your target model.

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

## よくある質問

> **What is the best Ollama configuration for fast inference?**
>
> Enable flash attention (`OLLAMA_FLASH_ATTENTION=1`), set the context window to what your task actually needs (not the model maximum), use quantized KV cache (`OLLAMA_KV_CACHE_TYPE=q8_0` or `q4_0`) for long contexts, and make sure your model is fully GPU-offloaded. See the sections above for the exact commands.

> **How do I reduce Ollama memory usage?**
>
> The 3 biggest levers: (1) lower `num_ctx` — memory scales linearly with context length, (2) quantize the KV cache with `OLLAMA_KV_CACHE_TYPE=q4_0` for up to 75% KV savings, (3) use a smaller quantization of the model weights (e.g., Q4\_0 instead of Q8\_0). Flash attention also saves 30-50% on attention memory.

> **Does Ollama use MLX on Mac?**
>
> Yes — starting with Ollama 0.19, the default backend on Apple Silicon is Apple's MLX framework, not llama.cpp. MLX delivers substantially faster inference on M-series chips (55-80 tok/s on M2 Ultra vs 25-40 tok/s with llama.cpp). The `OLLAMA_FLASH_ATTENTION` variable has no effect on MLX because MLX always uses optimized attention kernels.

> **How many parallel requests can Ollama handle?**
>
> Set `OLLAMA_NUM_PARALLEL` (default 1). Each parallel slot adds roughly 20-30% memory overhead for KV cache. For a 7B model at Q4 with 8K context, 4 parallel slots fit comfortably in 8 GB of VRAM. For larger models or longer contexts, start with 2 and measure.

> **Why is Ollama slow to load my model?**
>
> Model load time is dominated by reading weights from disk and moving them to GPU. Use an NVMe SSD (not HDD), set `OLLAMA_KEEP_ALIVE` to keep the model warm between requests, and set `OLLAMA_MAX_LOADED_MODELS` to avoid evicting and reloading. On Apple Silicon, NVFP4 models load faster because the weights are smaller.

> **What GPU offload settings should I use?**
>
> By default, Ollama auto-selects how many layers to offload to GPU. For maximum speed, set `num_gpu` to the model's total layer count (fully offload). If you run out of VRAM, reduce `num_ctx` before reducing `num_gpu` — keeping the model fully on GPU is almost always faster than partial offload.

## ソース

* [Ollama FAQ](https://docs.ollama.com/faq) — official documentation on environment variables and configuration
* [Ollama Modelfile reference](https://docs.ollama.com/modelfile) — parameter syntax and valid values
* [Ollama MLX performance update](https://ollama.com/blog/mlx-performance) — June 2026 benchmarks and optimizations for Apple Silicon
* [Ollama GPU scheduling deep dive](https://eastondev.com/blog/en/posts/ai/ollama-gpu-scheduling/) — VRAM management and multi-GPU behavior
* [Ollama performance tuning: batching, KV cache, and OOM](https://eastondev.com/blog/en/posts/ai/20260410-ollama-performance-optimization/) — num\_batch benchmarks and memory calculations
* [Ollama environment variables: complete reference](https://modelpiper.com/blog/ollama-environment-variables) — audited against v0.32.5 source

> [!NOTE]
>
> Ollamaの設定を変更した後、Tokiosデプロイメントを再登録してコネクターが新しいアップストリームエンドポイントを取得するようにすること。[Register Model](/ja/setup/register-model.md)を参照。


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