第26章 OpenCode 中的缓存预热机制
Warming(缓存预热)
WarmingSession(预热会话)会周期性地向模型发送请求,以维护服务端的提示词缓存或短暂状态,防止在你暂停输入期间缓存过期。此功能默认处于关闭状态。
你可以在任意 OpenCode 配置文件中启用预热:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"warming": true,
}
启用后,OpenCode 会在提示词缓存即将过期前自动预热最近活跃的会话。触发时机为模型 cache.ttl 达到 90%,或者当模型未设置缓存时,每 4 分钟预热一次。该过程会持续进行,直到距离最后一次非预热请求的时间超过 30 分钟为止。
若需自定义预热提示词、空闲间隔或活跃窗口,请使用对象形式配置:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"warming": {
"prompt": "请勿执行任何操作。仅回复:OK",
"interval": "5 minutes",
"duration": "1 hour",
},
}
各字段默认值及用途如下:
- prompt(默认:保活指令):附加在每次预热请求中的临时用户消息。默认提示词要求模型不执行任何任务、不使用工具,并回复 "OK"。
- interval(默认:"auto"):发出下次预热请求前的空闲时间。"auto" 模式下,若模型设置了
cache.ttl,则取该值的 90%;若未设置,则为 4 分钟。 - duration(默认:"30 minutes"):预热窗口时长,计时起点为最后一次非预热的模型请求。
对象配置中省略的字段将沿用默认值。例如,以下配置仅修改了间隔时间:
opencode.jsonc
{
"warming": {
"interval": "2 minutes",
},
}
interval 默认值为 "auto",旨在紧贴模型提示词缓存的过期时间进行预热。OpenCode 采用模型 cache.ttl 设置的 90% 作为间隔,例如 "5m" 的缓存将在 4.5 分钟后触发预热。对于未设置 cache.ttl 的模型,则每 4 分钟预热一次。
opencode.jsonc
{
"warming": { "duration": "2 hours" },
"providers": {
"anthropic": { "settings": { "cache": { "ttl": "1h" } } },
},
}
如果缓存有效期(如 "1h")长于 duration(如默认的 30 分钟),系统将不会执行预热,因为缓存本身在窗口结束前不会失效。OpenCode 会在每个会话中记录一次此日志。若需预热此类长缓存,请增大 duration 的值。
你可以通过在提供商(provider)或模型(model)级别设置 settings.cache.warming,来仅为特定会话启用预热或设置独立的时间参数。该配置项接受与顶层 warming 相同的值(prompt 除外),并会覆盖顶层设置。模型级设置优先级高于提供商级设置。
opencode.jsonc
{
"providers": {
"anthropic": {
"settings": { "cache": { "ttl": "5m", "warming": true } },
"models": {
"claude-haiku-5-5": { "settings": { "cache": { "warming": false } } },
},
},
},
}
在上述示例中,Anthropic 的会话每 4.5 分钟预热一次,但 Claude Haiku 5.5 除外(其预热被禁用)。其他提供商不进行预热。对象配置中省略的字段将依次回退到顶层 warming 配置或默认值。无效的设置会记录警告并回退到顶层配置。
interval 和 duration 接受持续时间字符串。两者必须解析为大于零的有限数值,且 interval 必须短于 duration;否则 OpenCode 将跳过预热并记录警告。
opencode.jsonc
{
"warming": {
"interval": "30 seconds",
"duration": "1 hour",
},
}
预热仅在顶层会话发生非预热模型请求后启动。子智能体(Subagent)会话不进行预热。每个间隔时间的计数起点是上一次请求或预热请求的发送时间,而非响应完成时间,因为服务端缓存的生命周期始于请求抵达时。预热请求不会延长活跃窗口。
00:00 发送正常模型请求
00:01 响应完成
00:04 预热请求
00:08 预热请求
00:30 停止预热
任何新的非预热模型活动(包括压缩操作)都会重置这两个计时器。若显式设置的 interval 大于或等于 duration,系统将拒绝并记录警告;若 "auto" 间隔过长导致缓存寿命超过窗口期,则会跳过预热。
00:00 正常模型请求
00:20 正常模型请求;窗口重启
00:24 预热请求
00:50 停止预热
当模型请求(包括压缩操作)正在运行时,OpenCode 绝不会发送预热请求。若计时到达时请求仍在执行,预热将等待其完成并立即发送(前提是该请求产生的缓存尚未过期)。若缓存已过期,则停止预热,直到下一次正常请求发生。
00:00 发送正常模型请求
00:04 间隔到期;请求仍在运行
00:04:30 响应完成;发送预热请求
00:08:30 预热请求
预热请求复用当前会话的模型、智能体、指令和对话上下文。OpenCode 会临时附加配置的提示词,执行一次模型调用,随后丢弃响应结果。
[当前会话上下文]
[临时用户消息:保活提示词]
→ 生成一次模型响应(随后丢弃)
该请求不接受输入、不添加消息到历史记录,也不变更持久化的会话状态。OpenCode 不会分发本地工具调用或继续工具循环;默认提示词也明确指示模型不要使用工具。
预热失败仅记录日志,不会导致会话失败或状态变更。OpenCode 会等待至下一个间隔再尝试,而原始的活跃窗口计时继续向下计数。
00:04 预热请求失败;会话状态不变
00:08 尝试下一次预热
如果预热请求未命中缓存(即从缓存读取的数据少于写入的数据),系统将为该会话停止预热,直到下一次非预热请求发生。不报告缓存使用量的提供商永远不会被视为未命中。
00:04 预热请求未命中缓存;停止预热
00:10 正常模型请求;恢复预热
00:14 预热请求
预热请求是真实的提供商请求。它们可能消耗令牌、产生费用、计入速率限制,并可能像其他模型请求一样失败。
- 更短的
interval会增加请求量。 - 更长的
duration允许更多的预热请求。 - 仅当服务端缓存收益足以抵消增加的用量成本时,才启用预热。
例如,对于未设置 cache.ttl 的模型,默认设置下,在一个不间断的 30 分钟窗口内最多允许 7 次预热尝试:分别发生在第 4、8、12、16、20、24 和 28 分钟。
将 warming 显式设置为 false 可关闭该功能。省略该字段同样保持关闭状态。
opencode.jsonc
{
"warming": false,
}