Ollama 上下文长度

上下文长度（Context Length）是模型在内存里能同时"看到"的最大 token 数。它不是模型能力里最显眼的参数，但几乎决定了所有体验边界：能读多长的文档、能做几轮对话、Agent 会不会"忘事"，以及你的显存够不够用。

调大它，效果好但吃显存；调小它，省资源但容易丢上下文。这一篇把默认值怎么定、在哪儿改、以及怎么判断改得对不对讲清楚。

版本基线 v0.40.12，官方 docs.ollama.com/context-length。

一、默认值不是固定的，按显存自动分档

这一点很多人不知道：Ollama 会根据你的显存大小自动选择默认上下文长度。

所以同一份代码在 8G 显卡的笔记本上和在 80G 的服务器上跑，能"记住"的内容差两个数量级。这也解释了为什么有人抱怨"模型读不了长文档"——不是模型不行，是默认值按他的显存被压到了 4k。

云端模型不受此限，默认就跑在最大上下文长度上。这是云端在长上下文场景更省心的原因。

官方还给了一条明确建议：需要大上下文的任务（网络搜索、Agent、编码工具）至少设到 64000 token。因为这类任务里，搜索结果、文件内容、工具返回值都是成块塞进上下文的，4k 根本撑不住。

二、三种改法

方式一：应用里拉滑块

桌面应用（macOS / Windows）的设置面板里有一个上下文长度的滑块，直接拖到想要的值即可。适合日常使用，改完对全局生效。

方式二：启动服务时设环境变量

不想动应用设置，或者跑在无界面的服务器上，就用环境变量：

## 把默认上下文长度提到 64000（适合检索与 Agent 场景）
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

这个变量影响的是服务端的默认值——所有没显式指定上下文的请求都会用它。

方式三：Modelfile 里写 num_ctx

想把某个模型的上下文长度固化成它自己的属性，写进 Modelfile：

FROM gemma4
## 这个模型默认就用 8K 上下文
PARAMETER num_ctx 8192

ollama create my-model -f Modelfile

这三者的优先级是：请求里的 options.num_ctx > Modelfile 的 PARAMETER num_ctx > 服务端 OLLAMA_CONTEXT_LENGTH > 按显存自动分档的默认值。排查"为什么没生效"时，按这个顺序从高到低找。

如果只是临时试用，还可以在交互会话里直接改：

>>> /set parameter num_ctx 8192

会话结束就失效，不会影响其他调用。

三、用 API 指定：num_ctx 选项

写代码时最常见的方式是在请求的 options 里传：

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "为什么天空是蓝色的？",
  "options": {
    "num_ctx": 32768
  }
}'

Python SDK 一样：

import ollama

response = ollama.chat(
    model='gemma4',
    messages=[{'role': 'user', 'content': '总结这份长文档的要点…'}],
    options={'num_ctx': 32768},   # 显式指定，覆盖服务端默认
)
print(response.message.content)

长文档处理的正确姿势：先估算文档 token 数，把 num_ctx 设成"文档长度 + 提示词 + 预留输出空间"以上。一个粗略的换算：中文约 1 字 ≈ 1 token，英文约 4 字符 ≈ 1 token。留 2k–4k 给输出比较稳妥。

四、调大不是免费的：显存按比例涨

官方原文就一句提醒：调大上下文会显著增加运行模型所需的内存。原因在 K/V 缓存——每一层注意力都需要缓存历史 token 的键值对，上下文翻倍，缓存基本也翻倍。

而且叠加了一个容易忽略的放大因素：并行请求数会成倍放大上下文占用。OLLAMA_NUM_PARALLEL=4 配 2K 上下文，实际相当于 8K 的缓存开销（详见 4.1 Ollama CLI 参考）。

所以调大之前先想清楚显存预算。两个省显存的手段可以叠加用：

• OLLAMA_KV_CACHE_TYPE=q8_0：把 K/V 缓存压到 f16 的一半左右，精度损失通常感知不到（需 Flash Attention 已启用）。
• OLLAMA_NUM_PARALLEL=1：单用户场景没必要并行，这是默认值，别乱调大。

五、验证：ollama ps 看真实分配值

设完之后必须验证——设了不等于生效。官方给的方法就是 ollama ps：

ollama ps

NAME             ID              SIZE      PROCESSOR    CONTEXT    UNTIL
gemma4:latest    c6eb396dbd59    9.6 GB    100% GPU     131072     2 minutes from now

三列信息各有用途：

官方特别强调：为获得最佳性能，应使用模型支持的最大上下文，并避免模型被卸载到 CPU。后半句比前半句更关键——一旦模型部分跑到 CPU 上，生成速度可能掉到原来的几分之一，这比上下文不够更影响体验。

所以调大上下文的正确判断标准不是"越大越好"，而是：调大后 PROCESSOR 仍然是 100% GPU。如果因为调大而出现 CPU 卸载，那就该往回调，或者先启用 K/V 缓存量化。

六、超出窗口会发生什么

上下文是有限资源，超出的部分必须被丢弃。实际表现通常是早期的内容被挤出窗口——最早的系统消息、最早的几轮对话会逐渐"看不见"，模型开始答非所问。

典型的故障信号：

• 聊到十几轮后，模型忘记最初设定的角色
• 塞入长文档后，模型只回答了文档末尾的内容
• 网络搜索 Agent 明明抓到了结果，回答却像没看见（原因就是结果把上下文挤爆了，见 3.9 Ollama 网络搜索（Web search））

诊断方法很简单：把 num_ctx 调到明显大于你实际需要的值再试一次。如果问题消失，就确认是上下文不够，而不是提示词或逻辑写错了。

对症的解决手段按优先级排：

1. 调大 num_ctx（前提是显存撑得住，ollama ps 验证仍 100% GPU）
2. 压缩输入——检索结果只取前几条、工具返回只保留必要字段
3. 做摘要——长对话定期让模型总结前文，用摘要替换原始历史

第 3 条是长对话场景最实用的思路：与其无限扩大窗口，不如主动控制历史长度。

七、一张决策表

最终以 ollama ps 的 CONTEXT 与 PROCESSOR 两列为准来定值——理论值只是起点，实测分配值和是否掉到 CPU 才是真实结论。

上下文受显存约束，下一篇 7.1 Ollama Linux 安装与部署 起会讲各平台的部署方式，其中也包括如何配置 GPU 加速。