> ## 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]
>
> 最后验证时间：2026-10-14 — Ollama v0.33.2。

> [!NOTE]
>
> **Apple Silicon 使用 MLX。** 从 Ollama 0.19 开始，Apple Silicon 上的默认后端是 Apple 的 MLX 框架，而非 llama.cpp。MLX 在 M 系列芯片上提供了更快的推理速度（请参阅 [Apple Silicon 和 MLX 优化](#apple-silicon-and-mlx-optimization)）。本指南中的大多数环境变量同时适用于两个后端；行为不同的地方会明确说明。

## 上下文窗口调优

上下文窗口（`num_ctx`）控制模型在单个请求中可以处理的 token 数量——包括您的提示词和生成的响应。它是仅次于模型权重本身的最大内存消耗因素。

### 如何增加 Ollama 上下文窗口

Ollama 默认使用 2048 token 的上下文窗口。大多数现代模型支持 8K、32K 甚至 128K token，但 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 隐藏维度），f16 精度：

| 上下文长度 | KV 缓存内存 |
| - | - |
| 2,048（默认） | \~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 提供的最接近免费性能提升的优化。它重新设计了模型计算 token 之间注意力的方式——不再在内存中实例化完整的注意力矩阵，而是以适合快速 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 运行它能处理的部分，其余回退到系统内存。

### Ollama 如何决定 GPU 层数

Ollama 的 GPU 调度按以下顺序工作：

1. **完全卸载**——如果模型权重 + KV 缓存可以放入 VRAM，所有层都放到 GPU。这是最快的配置。
2. **部分卸载**——如果模型无法完全放入，Ollama 将尽可能多的层放在 GPU 上，其余在 CPU 上运行。性能会下降，因为每次前向传播都必须通过 PCIe 总线访问 CPU 侧的层。
3. **仅 CPU**——如果没有可用的 GPU 或 VRAM 太小连几层都放不下，整个模型在 CPU 上运行。

### GPU 层数控制：`num_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` 值 | 行为 |
| - | - |
| `-1` | 所有层在 GPU 上（与设置为总层数相同） |
| `0` | 不使用 GPU 卸载——仅 CPU |
| `1` 到 `N` | 恰好该数量的层在 GPU 上，其余在 CPU 上 |
| 未设置（默认） | Ollama 根据可用 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 层）：

| 组件 | 每层 | 32 层总计 |
| - | - | - |
| 权重 | \~0.19 GB | \~6 GB |
| KV 缓存（f16，8K 上下文） | \~0.13 GB | \~4 GB |
| **总计** | | **\~10 GB** |

预留 1-2 GB VRAM 余量用于 CUDA 上下文和开销。

> [!WARNING]
>
> 当您增加 `num_ctx` 时，KV 缓存会增长，可能将层挤出 VRAM。如果您设置了 `num_ctx 32768`，Ollama 突然将一半的层卸载到 CPU，说明 KV 缓存占用了您的 VRAM 预算。要么减少 `num_ctx`，使用更小的量化，要么启用 flash attention 来缩小 KV 缓存。

## KV 缓存精度

KV 缓存存储每个活跃序列中每个 token 的键和值张量。默认情况下，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
```

| 缓存类型 | 每元素内存 | 质量 | 使用时机 |
| - | - | - | - |
| `f16`（默认） | 2 字节 | 基准 | 最高质量；内存充足 |
| `q8_0` | 1 字节 | 与 f16 几乎相同 | 最佳平衡——KV 缓存内存减半，质量损失可忽略 |
| `q4_0` | 0.5 字节 | 轻微下降 | 内存紧张；长上下文或多个并发序列 |

```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` 之前，请先在您的具体工作负载上进行测试。

## 线程配置

参数 `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
```

| 场景 | 线程建议 |
| - | - |
| 完全 GPU 卸载（所有层在 GPU 上） | `num_thread 2` 到 `num_thread 4`——CPU 处理调度和分词，不做数学运算 |
| 部分 GPU 卸载（部分层在 CPU 上） | 将 `num_thread` 设置为 CPU 的物理核心数——不是超线程数 |
| 仅 CPU（无 GPU） | 将 `num_thread` 设置为物理核心数 |

> [!WARNING]
>
> 线程数并非越多越好。超过物理核心数后，线程会争抢缓存和内存带宽，反而会拖慢推理。不确定时，从物理核心数开始，然后进行基准测试。

在 Apple Silicon 上，线程调优的重要性较低，因为 GPU 和 CPU 共享统一内存，MLX 后端负责调度。默认值通常效果良好。

## 批处理大小调优

参数 `num_batch` 控制 Ollama 在预填充阶段（提示词摄取）一次处理多少 token。默认值为 512。

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

| 设置 | 效果 |
| - | - |
| `num_batch 512`（默认） | 适合短提示词的交互式聊天 |
| `num_batch 1024` | 长提示词的预填充更快——首个 token 的生成时间大约快 50-100% |
| `num_batch 2048` | 文档摄取的最大吞吐量——预填充最快可达 150% |
| `num_batch 2048+` | 收益递减；内存使用增加但没有相应的速度提升 |

> [!TIP]
>
> 对于短提示词（1K token 以下）的交互式聊天，默认的 `num_batch 512` 即可。仅在您经常摄取长文档并希望更快获得首个 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
```

| 值 | 行为 |
| - | - |
| `1`（默认） | 一次一个请求——每个请求延迟最低 |
| `2` 到 `4` | 多个请求共享 GPU——更高吞吐量，每个请求延迟略高 |
| `8+` | 批处理工作负载的最大吞吐量——需要大量 VRAM 用于 KV 缓存 |

> [!NOTE]
>
> 内存和 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
```

| 值 | 行为 |
| - | - |
| `5m`（默认） | 5 分钟不活动后卸载 |
| `-1` | 无限期保持加载——无重新加载开销 |
| `0` | 每次请求后立即卸载 |
| 时长（`1h`、`30m`、`24h`） | 在最后一次请求后保持加载该时长 |

> [!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 优化更新的基准测试：

| 模型 | 量化 | 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 上运行相同的配置，可以强制 Ollama 在 Apple Silicon 上使用 llama.cpp 后端。请联系 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 q8\_0 KV 缓存，并为 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 模型权重、约 4 GB q8\_0 KV 缓存（配合 flash attention），并为 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
```

此配置完全在 CPU 上运行 8B Q4 模型。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 token/s。

### 低延迟交互式服务 — 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 缓存保证质量，适中的批处理大小。预计首个 token 时间在 500ms 以内，解码速度 50-70 tok/s。

## 常见错误及如何避免

### 错误 1：将 num\_ctx 设置过高

**问题：** 您将 `num_ctx 128000` 设为"以防万一"，但您的提示词不到 2K token。您刚刚浪费了 64 GB 的 KV 缓存内存。

**修复：** 将 `num_ctx` 设置为匹配您的实际工作负载。如果您的提示词不到 4K token，使用 `num_ctx 4096` 或 `num_ctx 8192`。您随时可以通过 API 为特定请求增加它。

### 错误 2：忘记 flash attention

**问题：** 您使用的 VRAM 比实际需要多 30-50%，因为没有启用 flash attention。

**修复：** 始终设置 `OLLAMA_FLASH_ATTENTION=1`。在支持的硬件上没有缺点。

### 错误 3：未控制模型卸载

**问题：** 休息 10 分钟后重新发起请求，第一个请求花了 30 秒，因为 Ollama 从磁盘重新加载了模型。

**修复：** 设置 `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`，现在每个请求只有 1.5 GB 的 KV 缓存。请求失败或质量下降。

**修复：** 计算您的 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 远程访问](/zh/guides/ollama-remote-access.md)**
>
> 通过 Tokios 向团队成员和智能体暴露您的 Ollama 模型——无需开放端口或设置 OLLAMA\_HOST=0.0.0.0。

> **[硬件参考](/zh/guides/hardware-reference.md)**
>
> 比较用于本地 LLM 推理的硬件平台——规格、模型容量和建议。

> **[模型适配查找](/zh/guides/model-fit.md)**
>
> 查找哪些模型可以在您的硬件上运行，或哪些硬件可以运行您的目标模型。

> **[测试您的部署](/zh/guides/benchmark-your-deployment.md)**
>
> 在调优后测量延迟和吞吐量以确认改进效果。

## 常见问题

> **Ollama 快速推理的最佳配置是什么？**
>
> 启用 flash attention（`OLLAMA_FLASH_ATTENTION=1`），将上下文窗口设置为任务实际所需的大小（而非模型最大值），对长上下文使用量化 KV 缓存（`OLLAMA_KV_CACHE_TYPE=q8_0` 或 `q4_0`），并确保模型完全卸载到 GPU。具体命令请参阅上述各节。

> **如何减少 Ollama 的内存使用？**
>
> 最大的 3 个调节手段：（1）降低 `num_ctx`——内存随上下文长度线性增长，（2）使用 `OLLAMA_KV_CACHE_TYPE=q4_0` 量化 KV 缓存，最高可节省 75% 的 KV 缓存，（3）使用更小的模型权重量化（例如 Q4\_0 而非 Q8\_0）。Flash attention 还可以节省 30-50% 的注意力内存。

> **Ollama 在 Mac 上使用 MLX 吗？**
>
> 是的——从 Ollama 0.19 开始，Apple Silicon 上的默认后端是 Apple 的 MLX 框架，而非 llama.cpp。MLX 在 M 系列芯片上提供更快的推理速度（55-80 tok/s，M2 Ultra，而 llama.cpp 为 25-40 tok/s）。`OLLAMA_FLASH_ATTENTION` 变量对 MLX 无效，因为 MLX 始终使用优化的注意力内核。

> **Ollama 可以处理多少并行请求？**
>
> 设置 `OLLAMA_NUM_PARALLEL`（默认 1）。每个并行槽位为 KV 缓存增加约 20-30% 的内存开销。对于 7B 模型 Q4 量化 8K 上下文，4 个并行槽位可以舒适地放入 8 GB VRAM。对于更大模型或更长上下文，从 2 开始测量。

> **为什么 Ollama 加载模型很慢？**
>
> 模型加载时间主要消耗在从磁盘读取权重并移至 GPU。使用 NVMe SSD（而非 HDD），设置 `OLLAMA_KEEP_ALIVE` 保持模型在请求之间处于热状态，设置 `OLLAMA_MAX_LOADED_MODELS` 以避免驱逐和重新加载。在 Apple Silicon 上，NVFP4 模型加载更快，因为权重更小。

> **应该使用什么 GPU 卸载设置？**
>
> 默认情况下，Ollama 自动选择卸载到 GPU 的层数。为了获得最快速度，将 `num_gpu` 设置为模型的总层数（完全卸载）。如果 VRAM 不足，先减少 `num_ctx`，再减少 `num_gpu`——保持模型完全在 GPU 上几乎总是比部分卸载更快。

## 来源

* [Ollama FAQ](https://docs.ollama.com/faq) — 关于环境变量和配置的官方文档
* [Ollama Modelfile reference](https://docs.ollama.com/modelfile) — 参数语法和有效值
* [Ollama MLX performance update](https://ollama.com/blog/mlx-performance) — 2026 年六月 Apple Silicon 基准测试和优化
* [Ollama GPU scheduling deep dive](https://eastondev.com/blog/en/posts/ai/ollama-gpu-scheduling/) — VRAM 管理和多 GPU 行为
* [Ollama performance tuning: batching, KV cache, and OOM](https://eastondev.com/blog/en/posts/ai/20260410-ollama-performance-optimization/) — num\_batch 基准测试和内存计算
* [Ollama environment variables: complete reference](https://modelpiper.com/blog/ollama-environment-variables) — 针对 v0.32.5 源码审计

> [!NOTE]
>
> 更改 Ollama 配置后，请重新注册您的 Tokios 部署，以便连接器获取新的上游端点。请参阅[注册模型](/zh/setup/register-model.md)。


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